rcS(5) UTC option manpage documentation error

[Geoff Hager]

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