[Bug 1313024] Re: rcS(5) UTC option manpage documentation error

[Ken Sharp]

** Tags added: amd64 trusty

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to sysvinit in Ubuntu.
https://bugs.launchpad.net/bugs/1313024

Title:
  rcS(5) UTC option manpage documentation error

Status in sysvinit package in Ubuntu:
  New

Bug description:
  PROBLEM DESCRIPTION:

  Quoting from
  http://manpages.ubuntu.com/manpages/trusty/en/man5/rcS.5.html:

  "OPTIONS …  UTC    This  is  used  to  govern  how  the hardware real
  time clock is interpreted when it is read (e.g., at boot time, for the
  purpose of  setting  the  system clock) and when it is written (e.g.,
  at shutdown).  If this option is set to no then the system clock is
  assumed  to  be  set to local time.  If the option is set to yes then
  the  system  clock  is  assumed  to  be  set  to  something
  approximating  Coordinated Universal Time (UTC)."

  I discovered that the last two sentences describe the opposite of the
  actual behavior (which for me did in fact result in a good deal of
  confusion & problems & extra time configuring my system to use rtcwake
  with my HW clock set to UTC). These two sentences should refer to the
  ‘hardware real time clock’ instead of the ‘system clock’. The actual
  behavior is illustrated below (along with my pertinent system
  information).

  PROPOSED CORRECTION:

  These last two sentences should refer to the ‘hardware real time
  clock’ instead of the ‘system clock’, i.e.:

  "If this option is set to no then the hardware real time clock is
  assumed  to  be  set to local time.  If the option is set to yes then
  the  hardware real time clock is  assumed  to  be  set  to Coordinated
  Universal Time (UTC)."

  BACKGROUND:

  If “UTC=yes” is set in /etc/default/rcS:

    # assume that the BIOS clock is set to UTC time (recommended)
    UTC=yes

  … then the script in /etc/init/hwclock.conf calls:

   hwclock --rtc=/dev/rtc0 --systz --utc --noadjfile

  … and the script in /etc/init/hwclock-save.conf calls:

   hwclock --rtc=/dev/rtc0 --systohc --utc --noadjfile

  Otherwise (if ! $UTC=yes) then those respective hwclock calls are made
  with the ‘--localtime’ option instead of ‘--utc’.

  SUMMARY of the actual observed behavior:

  ‘hwclock --systohc --localtime’ writes the system time to the HW clock
  without any timezone translation (i.e., assumes that the HW clock is
  set to local time).

  ‘hwclock --systohc --utc’ translates the system time from local to UTC
  based on the system timezone configuration and writes the translated
  time (UTC) to the HW clock (i.e., assumes that the HW clock is set to
  UTC).

  ‘hwclock --systz --localtime’ writes the HW clock time to the system
  time without any timezone translation (i.e., assumes that the HW clock
  is set to local time).

  ‘hwclock --systz --utc’ translates the HW clock time from UTC to local
  based on the system timezone configuration and writes the translated
  time (local) to the system time (i.e., assumes that the HW clock is
  set to UTC).

  (Note that hwclock does behave consistently with its manpage.)

  MY SYSTEM INFORMATION:

  # lsb_release -a
  No LSB modules are available.
  Distributor ID: Ubuntu
  Description:    Ubuntu 14.04 LTS
  Release:        14.04
  Codename:       trusty

  # uname -srvmpio
  Linux 3.13.0-24-generic #46-Ubuntu SMP Thu Apr 10 19:11:08 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux

  HOW TO DEMONSTRATE THE ACTUAL BEHAVIOR:

  # date
  Sat Apr 26 01:47:22 EDT 2014

  # cat /proc/driver/rtc | grep rtc
  rtc_time        : 05:47:24
  rtc_date        : 2014-04-26

  # hwclock --rtc=/dev/rtc0 --systohc --localtime --noadjfile; cat /proc/driver/rtc | grep rtc
  rtc_time        : 01:47:37
  rtc_date        : 2014-04-26

  # hwclock --rtc=/dev/rtc0 --systohc --utc --noadjfile; cat /proc/driver/rtc | grep rtc
  rtc_time        : 05:47:45
  rtc_date        : 2014-04-26

  # cat /proc/driver/rtc | grep rtc; hwclock --rtc=/dev/rtc0 --systz --utc --noadjfile; date
  rtc_time        : 06:09:10
  rtc_date        : 2014-04-26
  Sat Apr 26 02:09:10 EDT 2014

  # cat /proc/driver/rtc | grep rtc; hwclock --rtc=/dev/rtc0 --systz --localtime --noadjfile; date
  rtc_time        : 06:09:36
  rtc_date        : 2014-04-26
  Sat Apr 26 06:09:36 EDT 2014

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/sysvinit/+bug/1313024/+subscriptions