* [PATCH 3/4] hwclock: update man page for v2.26 rc
2015-01-08 4:10 [PATCH 0/4] hwclock: x86_64 -- UTC Defaults -- v2.26 man updates JWP
2015-01-08 4:13 ` [PATCH 1/4] hwclock: enable --directisa for x86_64 JWP
2015-01-08 4:15 ` [PATCH 2/4] hwclock: Incorrect UTC defaults JWP
@ 2015-01-08 4:18 ` JWP
2015-01-10 12:44 ` Benno Schulenberg
2015-01-08 4:22 ` [PATCH 4/4] hwclock: man page 'Since v2.26' notes JWP
3 siblings, 1 reply; 11+ messages in thread
From: JWP @ 2015-01-08 4:18 UTC (permalink / raw)
To: Karel Zak; +Cc: util-linux
Authored new section: DATE-TIME CONFIGURATION.
Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
Errata and drop outdated language.
Updates for v2.26
Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
sys-utils/hwclock.8.in | 1132 ++++++++++++++++++++++++++++++++----------------
1 file changed, 751 insertions(+), 381 deletions(-)
diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 0c654a5..505ff65 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -1,30 +1,48 @@
-.TH HWCLOCK 8 "October 2014" "util-linux" "System Administration"
+.\" hwclock.8.in -- man page for util-linux' hwclock
+.\"
+.\" 2015-01-07 J William Piggott
+.\" Authored new section: DATE-TIME CONFIGURATION.
+.\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
+.\" Errata and drop outdated language.
+.\" Updates for v2.26
+.\"
+.\"
+.\" -------------------------------
+.\" Included for troff portability.
+.\" Continuation line for .TP header.
+.de TQ
+. br
+. ns
+. TP \\$1\" no doublequotes around argument!
+..
+.
+.\" -------------------------------
+.
+.TH HWCLOCK 8 "January 2015" "util-linux" "System Administration"
.SH NAME
-hwclock \- query or set the hardware clock (RTC)
+hwclock \- read or set the hardware clock (RTC)
.SH SYNOPSIS
.B hwclock
.RI [ function ]
.RI [ option ...]
-
+.
.SH DESCRIPTION
.B hwclock
-is a tool for accessing the Hardware Clock. You can display the
-current time, set the Hardware Clock to a specified time, set the
-Hardware Clock from the System Time, or set the System Time from the
-Hardware Clock.
+is a tool for accessing the Hardware Clock. It can: display the
+Hardware Clock time; set the Hardware Clock to a specified time; set the
+Hardware Clock from the System Clock; set the System Clock from the
+Hardware Clock; compensate for Hardware Clock drift; correct the System
+Clock timescale; set the kernel's timezone, NTP timescale, and epoch
+(Alpha only); compare the System and Hardware Clocks; and predict future
+Hardware Clock values based on its drift rate.
.PP
-You can also run
-.B hwclock
-periodically to add or subtract time from the Hardware Clock to
-compensate for systematic drift (where the clock consistently loses or
-gains time at a certain rate when left to run).
-
Since v2.26
.B hwclock
does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
\fB\-\-systohc\fR, to force drift factor updates.
-
+See the \fB\-\-update\-drift\fR option below for details.
+.PP
Since v2.26
.B hwclock \-\-hctosys
does a better job at setting the System Clock: it no longer simply copies
@@ -35,146 +53,228 @@ then sets the System Clock to the resulting value.)
Therefore it is no longer necessary to run \fBhwclock --adjust\fR before
doing \fBhwclock --hctosys\fR, and thus \fBhwclock\fR can be used very
early on in the boot process when the root filesystem is still read-only.
-
+See the \fB\-\-hctosys\fR function below for information on inhibiting
+this new behavior.
+.
.SH FUNCTIONS
-You need exactly one of the following options to tell
-.B hwclock
-what function to perform:
+The following functions are mutually exclusive, only one can be given at
+a time. If none are given the default is
+.BR \-\-show .
.TP
.B \-\-adjust
Add or subtract time from the Hardware Clock to account for systematic
drift since the last time the clock was set or adjusted. See the
-discussion below, under \fBThe Adjust Function\fR.
+discussion below, under
+.BR "The Adjust Function" .
+.
.TP
.BR \-c , \ \-\-compare
Periodically compare the Hardware Clock to the System Time and output
the difference every 10 seconds. This will also print the frequency
offset and tick.
+.
.TP
.B \-\-getepoch
-Print the kernel's Hardware Clock epoch value to standard output.
-This is the number of years into AD to which a zero year value in the
+.TQ
+.B \-\-setepoch
+These functions are for Alpha machines only.
+.sp
+Read and set the kernel's Hardware Clock epoch value.
+Epoch is the number of years into AD to which a zero year value in the
Hardware Clock refers. For example, if you are using the convention
that the year counter in your Hardware Clock contains the number of
full years since 1952, then the kernel's Hardware Clock epoch value
must be 1952.
.sp
+The set function requires using the
+.B \%\-\-epoch
+option.
+.sp
This epoch value is used whenever
-.B hwclock
+.B \%hwclock
reads or sets the Hardware Clock.
+.
.TP
-.BI \-\-predict
-Predict what the RTC will read at the time given by the
+.B \-\-predict
+Predict what the Hardware Clock will read in the future based upon the
+time given by the
.B \-\-date
-option, based on the adjtime file. This is useful for example if you
-need to set an RTC wakeup time to a distant future and want to account
-for the RTC drift.
+option and the information in
+.IR @ADJTIME_PATH@ .
+This is useful, for example, to account for drift when setting a
+Hardware Clock wakeup (aka alarm). See
+.BR \%rtcwake (8).
+.sp
+Do not use this function if the Hardware Clock is being modified by
+anything other than the current operating system's
+.B \%hwclock
+command, such as \%'11\ minute\ mode' or from dual-booting another OS.
+.
.TP
.BR \-r , \ \-\-show
+.TQ
+.B \-\-get
+.br
Read the Hardware Clock and print the time on standard output.
The time shown is always in local time, even if you keep your Hardware Clock
-in Coordinated Universal Time. See the
-.B \-\-utc
+in UTC. See the
+.B \%\-\-localtime
option.
+.sp
Showing the Hardware Clock time is the default when no function is specified.
-.TP
+.sp
+The
.B \-\-get
-Like
-.B --show
-only with drift correction applied to the time read. This is useful when the
-Hardware Clock is not being periodically updated by something such as NTP's
-11 minute mode or when not using
-.BR --adjust .
+function also applies drift correction to the time read, based upon the
+information in
+.IR @ADJTIME_PATH@ .
+Do not use this function if the Hardware Clock is being modified by
+anything other than the current operating system's
+.B \%hwclock
+command, such as \%'11\ minute\ mode' or from dual-booting another OS.
+.
.TP
.BR \-s , \ \-\-hctosys
-Set the System Time from the Hardware Clock. The time read from the Hardware
+Set the System Clock from the Hardware Clock. The time read from the Hardware
Clock is compensated to account for systematic drift before using it to set the
-System Clock. See the discussion below, under \fBThe Adjust Function\fR.
+System Clock. See the discussion below, under
+.BR "The Adjust Function" .
.sp
-Also set the kernel's timezone value to the local timezone
-as indicated by the TZ environment variable and/or
-.IR /usr/share/zoneinfo ,
-as
-.BR tzset (3)
+The System Clock must be kept in the UTC timescale for date-time
+applications to work correctly in conjunction with the timezone configured
+for the system. If the Hardware Clock is kept in local time then the time read
+from it must be shifted to the UTC timescale before using it to set the System
+Clock. The
+.B \%\-\-hctosys
+function does this based upon the information in the
+.I @ADJTIME_PATH@
+file or the command line arguments
+.BR \%\-\-localtime " and " \-\-utc .
+Note: no daylight saving adjustment is made. See the discussion below under
+.BR "LOCAL vs UTC" .
+.sp
+The kernel also keeps a timezone value, the
+.B \%\-\-hctosys
+function sets it to the timezone configured for the system. The system
+timezone is configured by the TZ environment variable or the
+.I \%/etc/localtime
+file, as
+.BR \%tzset (3)
would interpret them.
The obsolete tz_dsttime field of the kernel's timezone value is set
-to DST_NONE. (For details on what this field used to mean, see
-.BR settimeofday (2).)
+to zero. (For details on what this field used to mean, see
+.BR \%settimeofday (2).)
.sp
-When used in a startup script, making it the first caller of
-.BR settimeofday (2)
-from boot, it will set the NTP 11 minute mode time scale via the
-.I persistent_clock_is_local
-kernel variable. See the discussion below, under
+When used in a startup script, making the
+.B \%\-\-hctosys
+function the first caller of
+.BR \%settimeofday (2)
+from boot, it will set the NTP \%'11\ minute\ mode' timescale via the
+.I \%persistent_clock_is_local
+kernel variable. If the Hardware Clock's timescale configuration is
+changed then a reboot is required to inform the kernel. See the
+discussion below, under
.BR "Automatic Hardware Clock Synchronization by the Kernel" .
.sp
-This is a good option to use in one of the system startup scripts.
+This is a good function to use in one of the system startup scripts before the
+file systems are mounted read/write.
.sp
-This option should never be used on a running system. Jumping system time
-will cause problems, such as, corrupted file system timestamps.
-Also, if NTP 11 minute mode is active then
-.B --hctosys
-will set the time incorrectly by
-including drift compensation. Drift compensation can be inhibited by using the
-.B --noadjfile
-option.
+This function should never be used on a running system. Jumping system time
+will cause problems, such as, corrupted filesystem timestamps. Also, if
+something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then
+.B \%\-\-hctosys
+will set the time incorrectly by including drift compensation.
+.sp
+Drift compensation can be inhibited by setting the drift factor in
+.I @ADJTIME_PATH@
+to zero. This setting will be persistent as long as the
+.BR \%\-\-update\-drift " option is not used with " \%\-\-systohc
+at shutdown (or anywhere else). Another way to inhibit this is by using the
+.BR \%\-\-noadjfile " option when calling the " \%\-\-hctosys
+function. A third method is to delete the
+.IR @ADJTIME_PATH@ " file."
+.B Hwclock
+will then default to using the UTC timescale for the Hardware Clock. If
+the Hardware Clock is ticking local time it will need to be defined in
+the file. This can be done by calling
+.BR hwclock\ \-\-localtime\ \-\-adjust ;
+when the file is not present this command will not actually
+adjust the Clock, but it will create the file with local time
+configured, and a drift factor of zero.
+.sp
+A condition under which inhibiting
+.BR hwclock 's
+drift correction may be desired is when dual-booting multiple operating
+systems. If while this instance of Linux is stopped, another OS changes
+the Hardware Clock's value, then when this instance is started again the
+drift correction applied will be incorrect.
+.sp
+.RB "For " hwclock 's
+drift correction to work properly it is imperative that nothing changes
+the Hardware Clock while its Linux instance is not running.
+.
.TP
.B \-\-set
Set the Hardware Clock to the time given by the
-.B \-\-date
-option.
-.TP
-.B \-\-setepoch
-Set the kernel's Hardware Clock epoch value to the value specified by the
-.B \-\-epoch
-option. See the
-.B \-\-getepoch
-option for details.
+.BR \-\-date
+option, and update the timestamps in
+.IR @ADJTIME_PATH@ .
+With the
+.B --update-drift
+option (re)calculate the drift factor.
+.
.TP
.B \-\-systz
-Set the kernel's timezone and reset the System Time based on the current timezone.
+This is an alternate to the
+.B \%\-\-hctosys
+function that does not read the Hardware Clock nor set the System Clock;
+consequently there is not any drift correction. It is intended to be
+used in a startup script on systems with kernels above version 2.6 where
+you know the System Clock has been set from the Hardware Clock by the
+kernel during boot.
.sp
-The system time is only reset on the first call after boot.
-.sp
-The local timezone is taken to be what is
-indicated by the TZ environment variable and/or
-.IR /usr/share/zoneinfo ,
-as
-.BR tzset (3)
-would interpret them.
-The obsolete tz_dsttime field of the kernel's timezone value is set
-to DST_NONE. (For details on what this field used to mean, see
-.BR settimeofday (2).)
-.sp
-This is an alternate option to
-.B \-\-hctosys
-that does not read the hardware clock, and may be used in system startup
-scripts for recent 2.6 kernels where you know the System Time contains
-the Hardware Clock time. If the Hardware Clock is already in UTC, it is
-not reset.
+It does the following things that are detailed above in the
+.BR \%\-\-hctosys " function:"
+.RS
+.IP \(bu 2
+Corrects the System Clock timescale to UTC as needed. Only instead of
+accomplishing this by setting the System Clock,
+.B hwclock
+simply informs the kernel and it handles the change.
+.IP \(bu 2
+Sets the kernel's NTP \%'11\ minute\ mode' timescale.
+.IP \(bu 2
+Sets the kernel's timezone.
+.PP
+The first two are only available on the first call of
+.BR \%settimeofday (2)
+after boot. Consequently this option only makes sense when used in a
+startup script. If the Hardware Clocks timescale configuration is
+changed then a reboot would be required to inform the kernel.
+.RE
+.
.TP
.BR \-w , \ \-\-systohc
-Set the Hardware Clock to the current System Time.
+Set the Hardware Clock from the System Clock, and update the timestamps in
+.IR @ADJTIME_PATH@ .
+With the
+.B --update-drift
+option (re)calculate the drift factor.
+.
.TP
.BR \-V , \ \-\-version
Display version information and exit.
+.
.TP
.BR \-h , \ \-\-help
Display help text and exit.
-
+.
.SH OPTIONS
-
+.
.TP
.BI \-\-adjfile= filename
-Override the default @ADJTIME_PATH@.
-
-.TP
-.B \-\-arc
-This option is equivalent to
-.B \-\-epoch=1980
-and is used to specify the most common epoch on Alphas
-with ARC console (but Ruffians have epoch 1900).
-
+.RI "Override the default " @ADJTIME_PATH@ " file path."
+.
.TP
.B \-\-badyear
Indicate that the Hardware Clock is incapable of storing years outside
@@ -183,26 +283,26 @@ Award BIOSes made between 4/26/94 and 5/31/95) wherein they are unable
to deal with years after 1999. If one attempts to set the year-of-century
value to something less than 94 (or 95 in some cases), the value that
actually gets set is 94 (or 95). Thus, if you have one of these machines,
-.B hwclock
+.B \%hwclock
cannot set the year after 1999 and cannot use the value of the clock as
the true time in the normal way.
.sp
To compensate for this (without your getting a BIOS update, which would
definitely be preferable), always use
-.B \-\-badyear
+.B \%\-\-badyear
if you have one of these machines. When
-.B hwclock
+.B \%hwclock
knows it's working with a brain-damaged clock, it ignores the year part of
the Hardware Clock value and instead tries to guess the year based on the
last calibrated date in the adjtime file, by assuming that date is
within the past year. For this to work, you had better do a
-.B hwclock \-\-set
+.B \%hwclock\ \-\-set
or
-.B hwclock \-\-systohc
+.B \%hwclock\ \-\-systohc
at least once a year!
.sp
Though
-.B hwclock
+.B \%hwclock
ignores the year value when it reads the Hardware Clock, it sets the
year value when it sets the clock. It sets it to 1995, 1996, 1997, or
1998, whichever one has the same position in the leap year cycle as
@@ -211,405 +311,447 @@ they belong. Again, if you let the Hardware Clock run for more than a
year without setting it, this scheme could be defeated and you could
end up losing a day.
.sp
-.B hwclock
+.B \%hwclock
warns you that you probably need
-.B \-\-badyear
+.B \%\-\-badyear
whenever it finds your Hardware Clock set to 1994 or 1995.
-
+.
.TP
-.BI \-\-date= date_string
+.BI \%\-\-date= date_string
You need this option if you specify the
.B \-\-set
or
-.B \-\-predict
+.B \%\-\-predict
functions, otherwise it is ignored.
It specifies the time to which to set the Hardware Clock, or the
time for which to predict the Hardware Clock reading.
-The value of this option is an argument to the
-.BR date (1)
-program.
-For example:
-.sp
-.B " hwclock" --set --date="2011-08-14 16:45:05"
-.sp
+The value of this option is used as an argument to the
+.BR date "(1) program's " \-\-date
+option. For example:
+.RS
+.IP "" 4
+.BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 '
+.PP
The argument must be in local time, even if you keep your Hardware Clock in
-Coordinated Universal time. See the
-.B \-\-utc
-option.
-
+UTC. See the
+.B \%\-\-localtime
+option. The argument must not be a relative time like "+5 minutes", because
+.BR \%hwclock 's
+precision depends upon correlation between the argument's value and when
+the enter key is pressed.
+.RE
+.
.TP
.B \-\-debug
Display a lot of information about what
-.B hwclock
-is doing internally. Some of its function is complex and this output
+.B \%hwclock
+is doing internally. Some of its functions are complex and this output
can help you understand how the program works.
-
+.
.TP
.B \-\-directisa
-This option is meaningful only on an ISA machine or an Alpha (which implements
-enough of ISA to be, roughly speaking, an ISA machine for
-.BR hwclock 's
-purposes). For other machines, it has no effect. This option tells
-.B hwclock
+This option is meaningful for: ISA compatible machines including x86, and
+x86_64; and Alpha (which has a similar Hardware Clock interface). For other
+machines, it has no effect. This option tells
+.B \%hwclock
to use explicit I/O instructions to access the Hardware Clock.
Without this option,
-.B hwclock
-will try to use the /dev/rtc device (which it assumes to be driven by the
-RTC device driver). If it is unable to open the device (for reading), it will
-use the explicit I/O instructions anyway.
-
-.TP
-.BI \-\-epoch= year
-Specifies the year which is the beginning of the Hardware Clock's
-epoch, that is the number of years into AD to which a zero value in the
-Hardware Clock's year counter refers. It is used together with
-the \fB\-\-setepoch\fR option to set the kernel's idea of the epoch of the
-Hardware Clock, or otherwise to specify the epoch for use with
-direct ISA access.
-.sp
-For example, on a Digital Unix machine:
-.sp
-.B " hwclock" --setepoch --epoch=1952
-
+.B \%hwclock
+will try to use the rtc device, which it assumes to be driven by the RTC
+device driver. If it is unable to open the device for reading, it will
+use the explicit I/O instructions anyway. Direct hardware access from
+userspace should only be used for testing, troubleshooting, and as a
+last resort when all other methods fail. See the
+.BR \-\-rtc " option."
+.
.TP
-.BR \-f , \ \-\-rtc=\fIfilename\fB
-Overrides the default /dev file name, which is
-.IR /dev/rtc
-on many platforms but may be
-.IR /dev/rtc0 ,
-.IR /dev/rtc1 ,
-and so on.
-
-.TP
-.B \-\-funky\-toy
-.TP
-.B \-\-jensen
-These two options specify what kind of Alpha machine you have. They
-are invalid if you don't have an Alpha and are usually unnecessary
-if you do, because
-.B hwclock
-should be able to determine by itself what it's
-running on, at least when
-.I /proc
-is mounted.
-(If you find you need one of these options to make
-.B hwclock
-work, contact the maintainer to see if the program can be improved
-to detect your system automatically. Output of `hwclock --debug'
-and `cat /proc/cpuinfo' may be of interest.)
-.sp
-Option
-.B \-\-jensen
-means you are running on a Jensen model. And
-.B \-\-funky\-toy
-means that on your machine one has to use the UF bit instead
-of the UIP bit in the Hardware Clock to detect a time transition. "Toy"
-in the option name refers to the Time Of Year facility of the machine.
-
+.BR \-f , \ \-\-rtc=\fIfilename\fR
+.RB "Override " \%hwclock 's
+default rtc device file name. Otherwise it will
+use the first one found in this order:
+.in +4
+.br
+.I /dev/rtc
+.br
+.I /dev/rtc0
+.br
+.I /dev/misc/rtc
+.br
+.in
+.RB "For " IA-64:
+.in +4
+.br
+.I /dev/efirtc
+.br
+.I /dev/misc/efirtc
+.in
+.
.TP
.B \-\-localtime
-Indicate that the Hardware Clock is kept in local time.
+.TQ
+.BR \-u ", " \-\-utc
+Indicate which timescale the Hardware Clock is set to.
.sp
-It is your choice whether to keep
-your clock in UTC or in local time, but nothing in the clock itself
-says which alternative
-you've chosen. So with \fB\-\-localtime\fR or \fB\-\-utc\fR
-you give this information to
-.BR hwclock .
-If you specify the wrong one (or specify neither and take a wrong default),
-both setting and querying the Hardware Clock will be messed up.
+The Hardware Clock may be configured to use either the UTC or the local
+timescale, but nothing in the clock itself says which alternative is
+being used. The
+.BR \%\-\-localtime " or " \-\-utc
+options give this information to the
+.B \%hwclock
+command. If you specify the wrong one (or specify neither and take a
+wrong default), both setting and reading the Hardware Clock will be
+incorrect.
.sp
If you specify neither
-.B \-\-utc
-nor
-.BR \-\-localtime ,
-the default is whichever was specified the last time
-.B hwclock
-was used to set the clock (i.e.
-.B hwclock
-was successfully run with the
-.BR \-\-set ,
-.BR \-\-systohc ,
-or
-.B \-\-adjust
-options), as recorded in the adjtime file. If the adjtime file doesn't
-exist, the default is UTC time.
-
+.BR \-\-utc " nor " \%\-\-localtime
+then the one last given with a set function
+.RB ( \-\-set ", " \%\-\-systohc ", or " \%\-\-adjust ),
+as recorded in
+.IR @ADJTIME_PATH@ ,
+will be used. If the adjtime file doesn't exist, the default is UTC.
+.sp
+Note: daylight saving time changes may be inconsistent when the
+Hardware Clock is kept in local time. See the discussion below under
+.BR "LOCAL vs UTC" .
+.
.TP
.B \-\-noadjfile
Disable the facilities provided by
.IR @ADJTIME_PATH@ .
-.B hwclock
+.B \%hwclock
will not read nor write to that file with this option. Either
-.B \-\-utc
-or
-.B \-\-localtime
+.BR \-\-utc " or " \%\-\-localtime
must be specified when using this option.
-
-.TP
-.B \-\-srm
-This option is equivalent to
-.B \-\-epoch=1900
-and is used to specify the most common epoch on Alphas
-with SRM console.
-
+.
.TP
.B \-\-test
-Do everything except actually updating the Hardware Clock or anything
-else. This is useful, especially in conjunction with
-.BR \-\-debug ,
+Do not actually change anything on the system, i.e., the Clocks or
+adjtime file. This is useful, especially in conjunction with
+.BR \%\-\-debug ,
in learning about the internal operations of hwclock.
-
+.
.TP
-.B \-\-update-drift
+.B \-\-update\-drift
Update the Hardware Clock's drift factor in
.IR @ADJTIME_PATH@ .
It is used with
-.BR --set\ or \ --systohc ,
+.BR \-\-set " or " \%\-\-systohc ,
otherwise it is ignored.
-See the discussion below, under \fBThe Adjust Function\fR.
-
+.sp
+A minimum four hour period between settings is required. This is to
+avoid invalid calculations. The longer the period, the more precise the
+resulting drift factor will be.
+.sp
+This option was added in v2.26, because
+it is typical for systems to call
+.B \%hwclock\ \-\-systohc
+at shutdown; with the old behaviour this would automatically
+(re)calculate the drift factor which caused several problems:
+.RS
+.IP \(bu 2
+When using ntpd with an \%'11\ minute\ mode' kernel the drift factor
+would be clobbered to near zero.
+.IP \(bu 2
+It would not allow the use of 'cold' drift correction. With most
+configurations using 'cold' drift will yield favorable results. Cold,
+means when the machine is turned off which can have a significant impact
+on the drift factor.
+.IP \(bu 2
+(Re)calculating drift factor on every shutdown delivers suboptimal
+results. For example, if ephemeral conditions cause the machine to be
+abnormally hot the drift factor calculation would be out of range.
+.PP
+.RB "Having " \%hwclock
+calculate the drift factor is a good starting point, but for optimal
+results it will likely need to be adjusted by directly editing the
+.I @ADJTIME_PATH@
+file. For most configurations once a machine's optimal drift factor is
+crafted it should not need to be changed. Therefore, the old behavior to
+automatically (re)calculate drift was changed and now requires this
+option to be used. See the discussion below, under
+.BR "The Adjust Function" .
+.RE
+.
+.SH OPTIONS FOR ALPHA MACHINES ONLY
+.
+.TP
+.B \-\-arc
+This option is equivalent to
+.BI \%\-\-epoch= 1980
+and is used to specify the most common epoch on Alphas
+with ARC console (but Ruffians have an epoch of 1900).
+.
+.TP
+.BI \-\-epoch= year
+Specifies the year which is the beginning of the Hardware Clock's epoch,
+that is the number of years into AD to which a zero value in the
+Hardware Clock's year counter refers. It is used together with the
+.B \%\-\-setepoch
+option to set the kernel's idea of the epoch of the Hardware Clock, or
+otherwise to specify the epoch for use with direct ISA access.
+.sp
+For example, on a Digital Unix machine:
+.RS
+.IP "" 4
+.BI hwclock\ \-\-setepoch\ \-\-epoch= 1952
+.RE
+.
.TP
-.BR \-u , \ \-\-utc
-Indicate that the Hardware Clock is kept in Coordinated Universal Time.
-See the discussion under \fB\-\-localtime\fR.
-
-
+.B \-\-funky\-toy
+.TQ
+.B \-\-jensen
+These two options specify what kind of Alpha machine you have. They
+are invalid if you do not have an Alpha and are usually unnecessary
+if you do;
+.B \%hwclock
+should be able to determine what it is running on when
+.I \%/proc
+is mounted.
+.sp
+.RB "The " \%\-\-jensen
+option is used for Jensen models;
+.B \%\-\-funky\-toy
+means that the machine requires the UF bit instead of the UIP bit in
+the Hardware Clock to detect a time transition. "Toy" in the option
+name refers to the Time Of Year facility of the machine.
+.
+.TP
+.B \-\-srm
+This option is equivalent to
+.BI \%\-\-epoch= 1900
+and is used to specify the most common epoch on Alphas
+with SRM console.
+.
.SH NOTES
-
+.
.SS Clocks in a Linux System
.PP
-There are two main clocks in a Linux system:
+There are two types of date-time clocks:
.PP
.B The Hardware Clock:
-This is a clock that runs independently of any control program running
-in the CPU and even when the machine is powered off.
+This clock is an independent hardware device, with its own power domain
+(battery, capacitor, etc), that operates when the machine is powered off,
+or even unplugged.
.PP
-On an ISA system, this clock is specified as part of the ISA standard.
-The control program can read or set this clock to a whole second, but
-the control program can also detect the edges of the 1 second clock
-ticks, so the clock actually has virtually infinite precision.
+On an ISA compatible system, this clock is specified as part of the ISA
+standard. A control program can read or set this clock only to a whole
+second, but it can also detect the edges of the 1 second clock ticks, so
+the clock actually has virtually infinite precision.
.PP
This clock is commonly called the hardware clock, the real time clock,
the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its
capitalized form, was coined for use by
-.B hwclock
-because all of the other names are inappropriate to the point of being
-misleading.
+.BR \%hwclock .
+The Linux kernel also refers to it as the persistent clock.
.PP
-So for example, some non-ISA systems have a few real time clocks with
+Some non-ISA systems have a few real time clocks with
only one of them having its own power domain.
A very low power external I2C or SPI clock chip might be used with a
backup battery as the hardware clock to initialize a more functional
integrated real-time clock which is used for most other purposes.
.PP
-.B The System Time:
-This is the time kept by a clock inside the Linux kernel and driven by
+.B The System Clock:
+This clock is part of the Linux kernel and is driven by
a timer interrupt. (On an ISA machine, the timer interrupt is part of
the ISA standard.) It has meaning only while Linux is running on the
machine. The System Time is the number of seconds since 00:00:00
January 1, 1970 UTC (or more succinctly, the number of seconds since
-1969). The System Time is not an integer, though. It has virtually
+1969 UTC). The System Time is not an integer, though. It has virtually
infinite precision.
.PP
The System Time is the time that matters. The Hardware Clock's basic
-purpose in a Linux system is to keep time when Linux is not running. You
-initialize the System Time to the time from the Hardware Clock when Linux
-starts up, and then never use the Hardware Clock again. Note that in DOS,
-for which ISA was designed, the Hardware Clock is the only real time clock.
+purpose is to keep time when Linux is not running so that the System
+Clock can be initialized from it at boot. Note that in DOS, for which
+ISA was designed, the Hardware Clock is the only real time clock.
.PP
It is important that the System Time not have any discontinuities such as
would happen if you used the
-.BR date (1L)
+.BR \%date (1)
program to set it while the system is running. You can, however, do whatever
you want to the Hardware Clock while the system is running, and the next
time Linux starts up, it will do so with the adjusted time from the Hardware
-Clock.
+Clock. Note: currently this is not possible on most systems because
+.B \%hwclock\ \-\-systohc
+is called at shutdown.
.PP
-A Linux kernel maintains a concept of a local timezone for the system.
+The Linux kernel's timezone is set by
+.BR hwclock .
But don't be misled -- almost nobody cares what timezone the kernel
thinks it is in. Instead, programs that care about the timezone
(perhaps because they want to display a local time for you) almost
always use a more traditional method of determining the timezone: They
-use the TZ environment variable and/or the
-.I /usr/share/zoneinfo
-directory, as explained in the man page for
-.BR tzset (3).
+use the TZ environment variable or the
+.I \%/etc/localtime
+file, as explained in the man page for
+.BR \%tzset (3).
However, some programs and fringe parts of the Linux kernel such as filesystems
-use the kernel timezone value. An example is the vfat filesystem. If the
+use the kernel's timezone value. An example is the vfat filesystem. If the
kernel timezone value is wrong, the vfat filesystem will report and set the
-wrong timestamps on files. Another example is the kernel's NTP 11 minute mode.
+wrong timestamps on files. Another example is the kernel's NTP \%'11\ minute\ mode.'
If the kernel's timezone value and/or the
-.I persistent_clock_is_local
-variable are wrong, then the Hardware Clock will be set incorrectly by 11 minute
-mode. See the discussion below, under
+.I \%persistent_clock_is_local
+variable are wrong, then the Hardware Clock will be set incorrectly
+by \%'11\ minute\ mode.' See the discussion below, under
.BR "Automatic Hardware Clock Synchronization by the Kernel" .
.PP
-.B hwclock
-sets the kernel timezone to the value indicated by TZ and/or
-.I /usr/share/zoneinfo
-when you set the System Time using the
-.B \-\-hctosys
-option.
+.B \%hwclock
+sets the kernel's timezone to the value indicated by TZ or
+.IR \%/etc/localtime " with the"
+.BR \%\-\-hctosys " or " \%\-\-systz " functions."
.PP
-The timezone value actually consists of two parts: 1) a field
+The kernel's timezone value actually consists of two parts: 1) a field
tz_minuteswest indicating how many minutes local time (not adjusted
for DST) lags behind UTC, and 2) a field tz_dsttime indicating
the type of Daylight Savings Time (DST) convention that is in effect
in the locality at the present time.
This second field is not used under Linux and is always zero.
-(See also
-.BR settimeofday (2).)
-
+See also
+.BR \%settimeofday (2).
+.
.SS User access and setuid
.PP
Sometimes, you need to install
-.B hwclock
+.B \%hwclock
setuid root. If you want users other than the superuser to be able to
display the clock value using the direct ISA I/O method, install it setuid
-root. If you have the /dev/rtc interface on your system or are on a non-ISA
-system, there's probably no need for users to use the direct ISA I/O method,
-so don't bother.
+root. If you have the rtc device interface on your system, or are on a non-ISA
+compatible system, there is probably no need for users to have the direct
+ISA I/O method, so do not bother. See the
+.BR \-\-rtc " option."
.PP
In any case, hwclock will not allow you to set anything unless you have the
superuser real uid. (This restriction is not necessary if you haven't
installed setuid root, but it's there for now.)
-
-.SS How hwclock accesses the Hardware Clock
+.
+.SS Hardware Clock Access Methods
.PP
-.B hwclock
+.B \%hwclock
uses many different ways to get and set Hardware Clock values.
-The most normal way is to do I/O to the device special file /dev/rtc,
+The most normal way is to do I/O to the rtc device special file,
which is presumed to be driven by the rtc device driver. However,
-this method is not always available. For one thing, the rtc driver is
-a relatively recent addition to Linux. Older systems don't have it.
+this method is not always available as older systems do not have it.
Also, though there are versions of the rtc driver that work on DEC
Alphas, there appear to be plenty of Alphas on which the rtc driver
does not work (a common symptom is hwclock hanging).
-Moreover, recent Linux systems have more generic support for RTCs,
-even systems that have more than one, so you might need to override
-the default by specifying
-.I /dev/rtc0
-or
-.I /dev/rtc1
-instead.
+Moreover, Linux systems using the rtc framework with udev, are capable
+of supporting multiple Hardware Clocks. This may bring about the need
+to override the default rtc device by specifying one with the
+.BR \-\-rtc " option."
+.
.PP
On older systems, the method of accessing the Hardware Clock depends on
the system hardware.
.PP
-On an ISA system,
-.B hwclock
+On an ISA compatible system,
+.B \%hwclock
can directly access the "CMOS memory" registers that
constitute the clock, by doing I/O to Ports 0x70 and 0x71. It does
this with actual I/O instructions and consequently can only do it if
running with superuser effective userid. (In the case of a Jensen
Alpha, there is no way for
-.B hwclock
+.B \%hwclock
to execute those I/O instructions, and so it uses instead the
-/dev/port device special file, which provides almost as low-level an
+\%/dev/port device special file, which provides almost as low-level an
interface to the I/O subsystem.)
.PP
This is a really poor method of accessing the clock, for all the
reasons that userspace programs are generally not supposed to do
-direct I/O and disable interrupts. \fBhwclock\fR provides it because it is
-the only method available on ISA and Alpha systems which don't have
-working rtc device drivers available.
+direct I/O and disable interrupts.
+.B \%hwclock
+provides it because it is the only method available on ISA compatible
+and Alpha systems which do not have working rtc device drivers available.
.PP
On an m68k system,
-.B hwclock
-can access the clock via the console driver, via the device special
-file /dev/tty1.
+.B \%hwclock
+can access the clock with the console driver, via the device special file
+.IR \%/dev/tty1 .
.PP
-.B hwclock
-tries to use /dev/rtc. If it is compiled for a kernel that doesn't have
-that function or it is unable to open /dev/rtc
-(or the alternative special file you've defined on the command line)
-.B hwclock
-will fall back to another method, if available. On an ISA or Alpha
-machine, you can force
-.B hwclock
-to use the direct manipulation of the CMOS registers without even trying
-.I /dev/rtc
-by specifying the
-.B \-\-directisa
-option.
-
+.B \%hwclock
+tries to use the rtc device interface first. If it is compiled for a
+kernel that does not have that function or it is unable to open it (or
+the alternative special file defined on the command line with
+.BR \-\-rtc ") " \%hwclock
+will fall back to another method, if available. On an ISA compatible or
+Alpha machine,
+.B \%hwclock
+can be forced to use the direct manipulation of the CMOS registers
+without even trying the rtc device interface by specifying the
+.BR \%\-\-directisa " option."
+.
.SS The Adjust Function
.PP
The Hardware Clock is usually not very accurate. However, much of its
inaccuracy is completely predictable - it gains or loses the same amount
of time every day. This is called systematic drift.
-.BR hwclock 's
-.I \-\-adjust
+.BR \%hwclock "'s " \%\-\-adjust
function lets you apply systematic drift corrections to the
Hardware Clock.
.PP
It works like this:
-.B hwclock
-keeps a file,
+.BR \%hwclock " keeps a file,"
.IR @ADJTIME_PATH@ ,
that keeps some historical information. This is called the adjtime file.
.PP
Suppose you start with no adjtime file. You issue a
-.B hwclock \-\-set
+.B \%hwclock\ \-\-set
command to set the Hardware Clock to the true current time.
-.B hwclock
+.B \%hwclock
creates the adjtime file and records in it the current time as the
last time the clock was calibrated.
Five days later, the clock has gained 10 seconds, so you issue a
-.B hwclock \-\-set \-\-update-drift
+.B \%hwclock\ \-\-set\ \-\-update\-drift
command to set it back 10 seconds.
-.B hwclock
+.B \%hwclock
updates the adjtime file to show the current time as the last time the
clock was calibrated, and records 2 seconds per day as the systematic
drift rate. 24 hours go by, and then you issue a
-.B hwclock \-\-adjust
+.B \%hwclock\ \-\-adjust
command.
-.B hwclock
+.B \%hwclock
consults the adjtime file and sees that the clock gains 2 seconds per
day when left alone and that it has been left alone for exactly one
day. So it subtracts 2 seconds from the Hardware Clock. It then
records the current time as the last time the clock was adjusted.
Another 24 hours go by and you issue another
-.BR "hwclock \-\-adjust" .
-.B hwclock
+.BR \%hwclock\ \-\-adjust .
+.B \%hwclock
does the same thing: subtracts 2 seconds and updates the adjtime file
with the current time as the last time the clock was adjusted.
.PP
When you use the
-.B \-\-update-drift
-option with
-.BR \-\-set\ or \ \-\-systohc ,
-the systematic drift rate is (re)calculated based on how long it has been
-since the last calibration, how long it has been since the last
-adjustment, what drift rate was assumed in any intervening
-adjustments, and the amount by which the clock is presently off. This updated
-drift factor is then saved in
+.BR \%\-\-update\-drift " option with " \-\-set " or " \%\-\-systohc ,
+the systematic drift rate is (re)calculated by comparing the fully drift
+corrected current Hardware Clock time with the new set time, from that
+it derives the 24 hour drift rate based on the last calibrated timestamp
+from the adjtime file. This updated drift factor is then saved in
.IR @ADJTIME_PATH@ .
.PP
A small amount of error creeps in when
the Hardware Clock is set, so
-.B \-\-adjust
+.B \%\-\-adjust
refrains from making any adjustment that is less
than 1 second. Later on, when you request an adjustment again, the accumulated
drift will be more than 1 second and
-.B \-\-adjust
+.B \%\-\-adjust
will make the adjustment including any fractional amount.
.PP
-.B hwclock \-\-hctosys
+.B \%hwclock\ \-\-hctosys
also uses the adjtime file data to compensate the value read from the Hardware
-Clock before using it to set the System Time. It does not share the 1 second
-limitation of \fB--adjust\fR, and will correct sub-second drift values immediately.
-It does not change the Hardware Clock time or the adjtime file. This may
-eliminate the need to use \fB--adjust\fR, unless something else on the system needs
-the Hardware Clock to be compensated. The drift compensation can be inhibited
-by using the
-.B --noadjfile
-option.
-.PP
-The adjtime file, while named for its historical purpose of controlling
-adjustments only, actually contains other information for use by hwclock
-in remembering information from one invocation to the next.
+Clock before using it to set the System Clock. It does not share the 1 second
+limitation of
+.BR \%\-\-adjust ,
+and will correct sub-second drift values immediately. It does not
+change the Hardware Clock time nor the adjtime file. This may eliminate
+the need to use
+.BR \%\-\-adjust ,
+unless something else on the system needs the Hardware Clock to be
+compensated.
+.
+.SS The Adjtime File
+While named for its historical purpose of controlling adjustments only,
+it actually contains other information used by
+.B hwclock
+from one invocation to the next.
.PP
The format of the adjtime file is, in ASCII:
.PP
@@ -617,7 +759,7 @@ Line 1: Three numbers, separated by blanks: 1) the systematic drift rate
in seconds per day, floating point decimal; 2) the resulting number of
seconds since 1969 UTC of most recent adjustment or calibration,
decimal integer; 3) zero (for compatibility with
-.BR clock (8))
+.BR \%clock (8))
as a decimal integer.
.PP
Line 2: One number: the resulting number of seconds since 1969 UTC of most
@@ -629,98 +771,326 @@ contain a valid time). This is a decimal integer.
Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to
Coordinated Universal Time or local time. You can always override this
value with options on the
-.B hwclock
+.B \%hwclock
command line.
.PP
You can use an adjtime file that was previously used with the
-.BR clock (8)
-program with
-.BR hwclock .
-
+.BR \%clock "(8) program with " \%hwclock .
+.
.SS Automatic Hardware Clock Synchronization by the Kernel
.PP
You should be aware of another way that the Hardware Clock is kept
synchronized in some systems. The Linux kernel has a mode wherein it
copies the System Time to the Hardware Clock every 11 minutes.
This is a good mode to use when you are using something sophisticated
-like ntp to keep your System Time synchronized. (ntp is a way to keep
+like NTP to keep your System Clock synchronized. (NTP is a way to keep
your System Time synchronized either to a time server somewhere on the
network or to a radio clock hooked up to your system. See RFC 1305.)
.PP
-This mode (we'll call it "11 minute mode") is off until something
-turns it on. The ntp daemon ntpd is one thing that turns it on. You
+This mode (we'll call it \%'11\ minute\ mode') is off until something
+turns it on. The NTP daemon ntpd is one thing that turns it on. You
can turn it off by running anything, including
-.BR "hwclock \-\-hctosys" ,
-that sets the System Time the old fashioned way. However, if the ntp daemon is
+.BR \%hwclock\ \-\-hctosys ,
+that sets the System Clock the old fashioned way. However, if the NTP daemon is
still running, it will turn 11 minute mode back on again the next time it
synchronizes the System Clock.
.PP
-If your system runs with 11 minute mode on, it may need
-.B hwclock \-\-hctosys
+If your system runs with \%'11\ minute\ mode' on, it may need to use either
+.BR \%\-\-hctosys " or " \%\-\-systz
in a startup script, especially if the Hardware Clock is configured to to use
-the local timescale.
-
-The first user space command to set the System Clock informs the
+the local timescale. Unless the kernel is informed of what timescale the
+Hardware Clock is using, it may clobber it with the wrong one. The kernel
+uses UTC by default.
+.PP
+The first userspace command to set the System Clock informs the
kernel what timescale the Hardware Clock is using. This happens via the
-.I persistent_clock_is_local
+.I \%persistent_clock_is_local
kernel variable. If
-.B hwclock \-\-hctosys
+.BR \%\-\-hctosys " or " \%\-\-systz
is the first, it will set this variable according to the adjtime file or the
appropriate command-line argument. Note that when using this capability and the
Hardware Clock timescale configuration is changed, then a reboot is required to
notify the kernel.
-
-Don't use
-.B hwclock \-\-adjust
-with 11 minute mode. You'll just make a mess.
-
+.PP
+.B \%hwclock\ \-\-adjust
+should not be used with NTP \%'11\ minute\ mode.'
+.
.SS ISA Hardware Clock Century value
.PP
There is some sort of standard that defines CMOS memory Byte 50 on an ISA
machine as an indicator of what century it is.
-.B hwclock
+.B \%hwclock
does not use or set that byte because there are some machines that
don't define the byte that way, and it really isn't necessary anyway,
since the year-of-century does a good job of implying which century it
is.
.PP
If you have a bona fide use for a CMOS century byte, contact the
-.B hwclock
+.B \%hwclock
maintainer; an option may be appropriate.
.PP
Note that this section is only relevant when you are using the "direct
ISA" method of accessing the Hardware Clock.
ACPI provides a standard way to access century values, when they
are supported by the hardware.
-
+.
+.SH DATE-TIME CONFIGURATION
+.in +4
+.SS Keeping Time without External Synchronization
+.in
+.PP
+This discussion is based on the following conditions:
+.IP \(bu 2
+Nothing is running that alters the date-time clocks, e.g.,
+.BR \%ntpd "(1), cron jobs, et al."
+.IP \(bu 2
+The system timezone is configured for the correct local time. See below
+.BR "POSIX vs 'RIGHT'" .
+.IP \(bu 2
+Early in startup the following are called in this order:
+.br
+.BI \%adjtimex\ \-\-tick \ <value>\ \-\-frequency \ <value>
+.br
+.B \%hwclock\ \-\-hctosys
+.IP \(bu 2
+During shutdown the following is called:
+.br
+.B \%hwclock\ \-\-systohc
+.PP
+Whether maintaining precision time with
+.BR \%ntpd (1)
+or not, it makes sense to configure the system to keep reasonably good
+date-time on its own.
+.PP
+The first step in making that happen is having a clear understanding of
+the big picture. There are two completely separate hardware devices
+running at their own speed and drifting away from the 'correct' time at
+their own rates. The methods and software for drift correction are
+different for each of them. However, most systems are configured to
+exchange values between these two clocks at startup and shutdown. Now
+the individual device's time keeping errors are transfered back and
+forth between each other. Attempt to configure drift correction for only
+one of them, and the other's drift will be overlaid upon it. If the big
+picture is not kept in mind, confusion will soon ensue.
+.PP
+This problem can be avoided when configuring drift correction for the
+System Clock by simply not shutting down the machine. This, plus the
+fact that all of
+.BR \%hwclock 's
+precision (including calculating drift factors) depends upon the System
+Clock's rate being correct, means that configuration of the System Clock
+should be done first.
+.PP
+The System Clock drift is corrected with the
+.BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency
+options. These two work together, tick is the course adjustment and
+frequency is the fine adjustment.
+.PP
+Some Linux distributions attempt to automatically calculate the System
+Clock drift with
+.BR \%adjtimex 's
+compare operation. Trying to correct one
+drifting clock by using another drifting clock as a reference is akin to
+a dog trying to catch its own tail. Success may happen eventually, but
+great effort and frustration will likely precede it. This automation may
+yield an improvement over no configuration, but expecting optimum
+results would be in error. A better choice for manual configuration
+would be
+.BR \%adjtimex 's " \-\-log " options.
+.PP
+It may be more effective to simply track the System Clock drift with
+.BR \%ntpdate\ \-q " , or " \%date\ \-Ins
+and a precision timepiece, and then calculate the correction manually.
+.PP
+After setting the tick and frequency values, continue to test and refine the
+adjustments until the System Clock keeps good time. See
+.BR \%adjtimex (8)
+for more information and the example demonstrating manual drift
+calculations.
+.PP
+Once the System Clock is ticking smoothly, move on to the Hardware Clock.
+.PP
+As a rule, cold drift will work best for most use cases. This should be
+true even for 24/7 machines whose normal downtime consists of a reboot.
+In that case the drift factor value makes little difference, but on the
+rare occasion that the machine is shutdown for an extended period then
+cold drift should yield better results.
+.PP
+.B Steps to calculate cold drift:
+.IP 1 2
+.RB "Confirm that " ntpd "(1) will not be launched at startup."
+.IP 2 2
+.RI The " System Clock " "time must be correct at shutdown!"
+.IP 3 2
+Shutdown the system.
+.IP 4 2
+Let an extended period pass without changing the Hardware Clock.
+.IP 5 2
+Start the system.
+.IP 6 2
+.RB "Immediately use " hwclock " to set the correct time with the"
+.BR \%\-\-update\-drift " option."
+.PP
+Note: if step six uses
+.RB \%\-\-systohc ,
+then the System Clock must be set correctly (step 6a) just before doing so.
+.PP
+.RB "Having " hwclock
+calculate the drift factor is a good starting point, but for optimal
+results it will likely need to be adjusted by directly editing the
+.I @ADJTIME_PATH@
+file. Continue to test and refine the drift factor until the Hardware
+Clock is corrected properly at startup. To check this, first make sure
+that the System Time is correct before shutdown and then use
+.BR \%ntpdate\ \-q ", or " \%date\ \-Ins
+and a precision timepiece, immediately after startup.
+.PP
+Both clocks typically use a quartz crystal oscillator. Crystals are
+used for reference oscillators in electronics because by most measures
+they produce a very clean and stable sine wave. Their greatest
+shortcoming is that they have a Positive Temperature Coefficient;
+meaning that their frequency increases as the temperature increases and
+vise versa. Therefore, both the Hardware and System Clock's drift rate
+changes with intrinsic and extrinsic machine temperatures. These
+characteristics will vary by machine depending upon its design.
+.PP
+Drift correction strategies are many, but as a general guide the goal
+would be to find a longterm average. A year long average to take into
+account seasonal ambient temperature shifts may be a good target period.
+So perhaps the date-time advances a bit in the summer and declines a bit
+in the winter, but at the end of a year it balances to zero.
+.PP
+If this is beginning to sound futile, it is not. Left on its own a
+machine can lose 3 seconds per day or more. Accumulated drift over a
+year may easily exceed half an hour. Using carefully crafted drift
+corrections can make a significant improvement in a machine's ability to
+keep reasonably good date-time.
+.
+.SS LOCAL vs UTC
+Keeping the Hardware Clock in a local timescale causes inconsistent
+daylight saving time results:
+.IP \(bu 2
+If Linux is running during a daylight saving time change, the time
+written to the Hardware Clock will be adjusted for the change.
+.IP \(bu 2
+If Linux is NOT running during a daylight saving time change, the time
+read from the Hardware Clock will NOT be adjusted for the change.
+.PP
+The Hardware Clock on an ISA compatible system keeps only a date and time,
+it has no concept of timezone nor daylight saving. Therefore, when
+.B hwclock
+is told that it is in local time, it assumes it is in the 'correct'
+local time and makes no adjustments to the time read from it.
+.PP
+Linux handles daylight saving time changes transparently only when the
+Hardware Clock is kept in the UTC timescale. Doing so is made easy for
+system administrators as
+.B \%hwclock
+uses local time for its output and as the argument to the
+.BR \%\-\-date " option."
+.PP
+POSIX systems, like Linux, are designed to have the System Clock operate
+in the UTC timescale. The Hardware Clock's purpose is to initialize the
+System Clock, so also keeping it in UTC makes sense.
+.PP
+Linux does, however, attempt to accommodate the Hardware Clock being in
+the local timescale. This is primarily for dual-booting with older
+versions of MS Windows. From Windows 7 on, the RealTimeIsUniversal
+registry key is supposed to be working properly so that its Hardware
+Clock can be kept in UTC.
+.
+.SS POSIX vs 'RIGHT'
+A discussion on date-time configuration would be incomplete without
+addressing timezones, this is mostly well covered by
+.BR tzset (3).
+One area that seems to have no documentation is the 'right'
+directory of the IANA Time Zone Database, aka tz, aka zoneinfo.
+.PP
+There are two separate databases in the zoneinfo system, posix
+and 'right'. 'Right' (now named leaps) includes leap seconds and posix
+does not. To use the 'right' database the System Clock must be kept in
+\%UTC\ +\ leap_seconds, i.e., \%TAI\ \-\ 10. This allows calculating the
+exact number of seconds between two dates that cross a leap second
+epoch. The System Clock is then converted to the correct civil time,
+including UTC, by using the 'right' timezone files which subtract the
+leap seconds. Note: this configuration is considered experimental and is
+known to have issues.
+.PP
+To configure a system to use a particular database all of the files
+located in its directory must be copied to the root of
+.IR \%/usr/share/zoneinfo .
+Files are never used directly from the posix or 'right' subdirectories, e.g.,
+.RI \%TZ=' right/Europe/Dublin '.
+This habit was becoming so common that the upstream zoneinfo project
+restructured the system's file tree by moving the posix and 'right'
+subdirectories out of the zoneinfo directory and into sibling directories:
+.br
+.in +2
+.I /usr/share/zoneinfo
+.br
+.I /usr/share/posix
+.br
+.I /usr/share/leaps
+.PP
+Unfortunately, some Linux distributions are changing it back to the old
+tree structure in their packages. So the problem of system
+administrators reaching into the 'right' subdirectory persists. This
+causes the system timezone to be configured to include leap seconds
+while the zoneinfo database is still configured to exclude them. Then
+when an application such as a World Clock needs the South_Pole timezone
+file; or an email MTA, or
+.B hwclock
+needs the UTC timezone file; they fetch it from the root of
+.I \%/usr/share/zoneinfo
+, because that is what they are supposed to do. Those files exclude leap
+seconds, but the System Clock now includes them, causing an incorrect
+time conversion.
+.PP
+Attempting to mix and match files from these separate databases will not
+work, because they each require the System Clock to use a different
+timescale. The zoneinfo database must be configured to use either posix
+or 'right', as described above.
+.
.SH "ENVIRONMENT VARIABLES"
.I TZ
-
+.
.SH FILES
+.br
.I @ADJTIME_PATH@
-.I /usr/share/zoneinfo/
-.RI ( /usr/lib/zoneinfo
-on old systems)
+.br
+.I /etc/localtime
+.br
.I /dev/rtc
+.br
.I /dev/rtc0
+.br
+.I /dev/misc/rtc
+.br
+.I /dev/efirtc
+.br
+.I /dev/misc/efirtc
+.br
.I /dev/port
+.br
.I /dev/tty1
+.br
.I /proc/cpuinfo
-
+.
.SH "SEE ALSO"
.BR date (1),
+.BR adjtimex (8),
.BR gettimeofday (2),
.BR settimeofday (2),
.BR crontab (1),
.BR tzset (3)
-
+.
.SH AUTHORS
Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
based on work done on the
-.I clock
+.BR \%clock (8)
program by Charles Hedrick, Rob Hooft, and Harald Koenig.
See the source code for complete history and credits.
-
+.
.SH AVAILABILITY
The hwclock command is part of the util-linux package and is available from
ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
^ permalink raw reply related [flat|nested] 11+ messages in thread