Adding upstream version 2.33.1.upstream/2.33.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 998 insertions, 0 deletions

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
new file mode 100644
index 0000000..dacdd27
--- /dev/null
+++ b/sys-utils/hwclock.8.in
@@ -0,0 +1,998 @@
+.\" 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'.
+.\"
+.TH HWCLOCK 8 "July 2017" "util-linux" "System Administration"
+.SH NAME
+hwclock \- time clocks utility
+.SH SYNOPSIS
+.B hwclock
+.RI [ function ]
+.RI [ option ...]
+.
+.SH DESCRIPTION
+.B hwclock
+is an administration tool for the time clocks.  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); and predict future
+Hardware Clock values based on its drift rate.
+.PP
+Since v2.26 important changes were made to the
+.B \-\-hctosys
+function and the
+.B \-\-directisa
+option, and a new option
+.B \-\-update\-drift
+was added.  See their respective descriptions below.
+.
+.SH FUNCTIONS
+The following functions are mutually exclusive, only one can be given at
+a time.  If none is given, the default is \fB\-\-show\fR.
+.TP
+.B \-a, \-\-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
+.BR "The Adjust Function" .
+.
+.TP
+.B \-\-getepoch
+.TQ
+.B \-\-setepoch
+These functions are for Alpha machines only, and are only available
+through the Linux kernel RTC driver.
+.sp
+They are used to 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 the machine's BIOS sets the year
+counter in the Hardware Clock to contain the number of full years since
+1952, then the kernel's Hardware Clock epoch value must be 1952.
+.sp
+The \fB\%\-\-setepoch\fR function requires using the
+.B \%\-\-epoch
+option to specify the year.  For example:
+.RS
+.IP "" 4
+.B hwclock\ \-\-setepoch\ \-\-epoch=1952
+.PP
+The RTC driver attempts to guess the correct epoch value, so setting it
+may not be required.
+.PP
+This epoch value is used whenever
+.B \%hwclock
+reads or sets the Hardware Clock on an Alpha machine.  For ISA machines
+the kernel uses the fixed Hardware Clock epoch of 1900.
+.RE
+.
+.TP
+.B \-\-predict
+Predict what the Hardware Clock will read in the future based upon the
+time given by the
+.B \-\-date
+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 its time to standard output in the
+.B ISO 8601
+format.
+The time shown is always in local time, even if you keep your Hardware Clock
+in UTC.  See the
+.B \%\-\-localtime
+option.
+.sp
+Showing the Hardware Clock time is the default when no function is specified.
+.sp
+The
+.B \-\-get
+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 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
+.BR "The Adjust Function" .
+.sp
+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 zero.  (For details on what this field used to mean, see
+.BR \%settimeofday (2).)
+.sp
+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 function to use in one of the system startup scripts before the
+file systems are mounted read/write.
+.sp
+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, and update the timestamps in
+.IR @ADJTIME_PATH@ .
+With the
+.B \%\-\-update-drift
+option also (re)calculate the drift factor.  Try it without the option if
+.BR \%\-\-set " fails.  See " \%\-\-update-drift " below."
+.
+.TP
+.B \-\-systz
+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
+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 from the System Clock, and update the timestamps in
+.IR @ADJTIME_PATH@ .
+With the
+.B \%\-\-update-drift
+option also (re)calculate the drift factor.  Try it without the option if
+.BR \%\-\-systohc " fails.  See " \%\-\-update-drift " below."
+.
+.TP
+.BR \-V , \ \-\-version
+Display version information and exit.
+.
+.TP
+.BR \-h , \ \-\-help
+Display help text and exit.
+.
+.SH OPTIONS
+.
+.TP
+.BI \-\-adjfile= filename
+.RI "Override the default " @ADJTIME_PATH@ " file path."
+.
+.TP
+.BI \%\-\-date= date_string
+This option must be used with the
+.B \-\-set
+or
+.B \%\-\-predict
+functions, otherwise it is ignored.
+.RS
+.IP "" 4
+.B "hwclock\ \-\-set\ \-\-date='16:45'"
+.IP "" 4
+.B "hwclock\ \-\-predict\ \-\-date='2525-08-14\ 07:11:05'"
+.PP
+The argument must be in local time, even if you keep your Hardware Clock in
+UTC.  See the
+.B \%\-\-localtime
+option.  Therefore, the argument should not include any timezone information.
+It also should 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.  Fractional seconds are silently dropped.  This option is
+capable of understanding many time and date formats, but the previous
+parameters should be observed.
+.RE
+.
+.TP
+.BI \%\-\-delay= seconds
+This option allows to overwrite internally used delay when set clock time. The
+default is 0.5 (500ms) for rtc_cmos, for another RTC types the delay is 0. If
+RTC type is impossible to determine (from sysfs) then it defaults also to 0.5
+to be backwardly compatible.
+.RS
+.PP
+The 500ms default is based on commonly used MC146818A-compatible (x86) hardware clock. This
+Hardware Clock can only be set to any integer time plus one half second.  The
+integer time is required because there is no interface to set or get a
+fractional second.  The additional half second delay is because the Hardware
+Clock updates to the following second precisely 500 ms after setting the new
+time. Unfortunately, this behavior is hardware specific and in same cases
+another delay is required.
+.RE
+.
+.TP
+.TP
+.BR \-D ", " \-\-debug
+.RB Use\  \-\-verbose .
+.RB The\  \%\-\-debug\  option
+has been deprecated and may be repurposed or removed in a future release.
+.
+.TP
+.B \-\-directisa
+This option is meaningful for ISA compatible machines in the x86 and
+x86_64 family.  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 use the rtc device file, which it assumes to be driven by the Linux
+RTC device driver.  As of v2.26 it will no longer automatically use
+directisa when the rtc driver is unavailable; this was causing an unsafe
+condition that could allow two processes to access the Hardware Clock at
+the same time.  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
+.BI \-\-epoch= year
+This option is required when using the
+.BR \%\-\-setepoch \ function.
+.RI "The minimum " year
+value is 1900. The maximum is system dependent
+.RB ( ULONG_MAX\ -\ 1 ).
+.
+.TP
+.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/rtc0
+.br
+.I /dev/rtc
+.br
+.I /dev/misc/rtc
+.br
+.in
+.RB "For " IA-64:
+.in +4
+.br
+.I /dev/efirtc
+.br
+.I /dev/misc/efirtc
+.in
+.
+.TP
+.BR \-l , \ \-\-localtime
+.TQ
+.BR \-u ", " \-\-utc
+Indicate which timescale the Hardware Clock is set to.
+.sp
+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
+.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
+will not read nor write to that file with this option.  Either
+.BR \-\-utc " or " \%\-\-localtime
+must be specified when using this option.
+.
+.TP
+.B \-\-test
+Do not actually change anything on the system, that is, the Clocks or
+.I @ADJTIME_PATH@
+.RB ( \%\-\-verbose
+is implicit with this option).
+.
+.TP
+.B \-\-update\-drift
+Update the Hardware Clock's drift factor in
+.IR @ADJTIME_PATH@ .
+It can only be used with
+.BR \-\-set " or " \%\-\-systohc ,
+.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 NTP 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.
+.IP \(bu 2
+Significantly increased system shutdown times (as of v2.31 when not
+using
+.B \%\-\-update\-drift
+the RTC is not read).
+.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" .
+.PP
+This option requires reading the Hardware Clock before setting it.  If
+it cannot be read, then this option will cause the set functions to fail.
+This can happen, for example, if the Hardware Clock is corrupted by a
+power failure.  In that case, the clock must first be set without this
+option.  Despite it not working, the resulting drift correction factor
+would be invalid anyway.
+.RE
+.
+.TP
+.BR \-v ", " \-\-verbose
+Display more details about what
+.B \%hwclock
+is doing internally.
+.
+.SH NOTES
+.
+.SS Clocks in a Linux System
+.PP
+There are two types of date-time clocks:
+.PP
+.B The Hardware Clock:
+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 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
+.BR \%hwclock .
+The Linux kernel also refers to it as the persistent clock.
+.PP
+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 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 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 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 (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.  Note: currently this is not possible on most systems because
+.B \%hwclock\ \-\-systohc
+is called at shutdown.
+.PP
+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 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'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'.
+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
+.BR "Automatic Hardware Clock Synchronization by the Kernel" .
+.PP
+.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 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).
+.
+.SS Hardware Clock Access Methods
+.PP
+.B \%hwclock
+uses many different ways to get and set Hardware Clock values.  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.  Also, 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
+However, this method is not always available as older systems do not
+have an rtc driver.  On these systems, the method of accessing the
+Hardware Clock depends on the system hardware.
+.PP
+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.  This method may be used by
+specifying the
+.BR \%\-\-directisa " option."
+.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.
+.B \%hwclock
+provides it for testing, troubleshooting, and  because it may be the
+only method available on ISA systems which do not have a working rtc
+device driver.
+.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 " \%\-\-adjust
+function lets you apply systematic drift corrections to the
+Hardware Clock.
+.PP
+It works like this:
+.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
+command to set the Hardware Clock to the true current time.
+.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
+command to set it back 10 seconds.
+.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
+command.
+.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
+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
+.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
+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
+will make the adjustment including any fractional amount.
+.PP
+.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 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
+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))
+as a decimal integer.
+.PP
+Line 2: One number: the resulting number of seconds since 1969 UTC of most
+recent calibration.  Zero if there has been no calibration yet or it
+is known that any previous calibration is moot (for example, because
+the Hardware Clock has been found, since that calibration, not to
+contain a valid time).  This is a decimal integer.
+.PP
+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
+command line.
+.PP
+You can use an adjtime file that was previously used with the
+.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 mode
+is a compile time option, so not all kernels will have this capability.
+This is a good mode to use when you are using something sophisticated
+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
+If the kernel is compiled with the \%'11\ minute\ mode' option it will
+be active when the kernel's clock discipline is in a synchronized state.
+When in this state, bit 6 (the bit that is set in the mask 0x0040)
+of the kernel's
+.I \%time_status
+variable is unset. This value is output as the 'status' line of the
+.BR \%adjtimex\ --print " or " \%ntptime " commands."
+.PP
+It takes an outside influence, like the NTP daemon
+to put the kernel's clock discipline into a synchronized state, and
+therefore turn on \%'11\ minute\ mode'.
+It can be turned off by running anything that sets the System Clock the old
+fashioned way, including
+.BR "\%hwclock\ \-\-hctosys" .
+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 to use either
+.BR \%\-\-hctosys " or " \%\-\-systz
+in a startup script, especially if the Hardware Clock is configured to use
+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
+kernel variable.  If
+.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.
+.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
+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
+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, such as NTP daemon or a cron job."
+.IP \(bu 2
+The system timezone is configured for the correct local time.  See below, under
+.BR "POSIX vs 'RIGHT'" .
+.IP \(bu 2
+Early during 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
+.in +4
+.BR * " Systems without " adjtimex " may use " ntptime .
+.in
+.PP
+Whether maintaining precision time with NTP daemon
+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 transferred 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.
+.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 coarse adjustment and
+frequency is the fine adjustment.  (For systems that do not have an
+.BR \%adjtimex " package,"
+.BI \%ntptime\ \-f\  ppm
+may be used instead.)
+.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 \%sntp ", 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 shut down for an extended period, then
+cold drift should yield better results.
+.PP
+.B Steps to calculate cold drift:
+.IP 1 2
+.B "Ensure that NTP daemon will not be launched at startup."
+.IP 2 2
+.RI The " System Clock " "time must be correct at shutdown!"
+.IP 3 2
+Shut down 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, adding the"
+.BR \%\-\-update\-drift " option."
+.PP
+Note: if step 6 uses
+.BR \%\-\-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 \%sntp ", or " \%date\ \-Ins
+and a precision timepiece, immediately after startup.
+.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 Time Zone Database, sometimes called tz or zoneinfo.
+.PP
+There are two separate databases in the zoneinfo system, posix
+and 'right'. 'Right' (now named zoneinfo\-leaps) includes leap seconds and posix
+does not. To use the 'right' database the System Clock must be set to
+\%(UTC\ +\ leap seconds), which is equivalent to \%(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:
+.PP
+.in +2
+.I /usr/share/zoneinfo
+.br
+.I /usr/share/zoneinfo\-posix
+.br
+.I /usr/share/zoneinfo\-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, or by assigning a database path to the
+.SB TZDIR
+environment variable.
+.SH EXIT STATUS
+One of the following exit values will be returned:
+.TP
+.BR EXIT_SUCCESS " ('0' on POSIX systems)"
+Successful program execution.
+.TP
+.BR EXIT_FAILURE " ('1' on POSIX systems)"
+The operation failed or the command syntax was not valid.
+.SH ENVIRONMENT
+.TP
+.B TZ
+If this variable is set its value takes precedence over the system
+configured timezone.
+.TP
+.B TZDIR
+If this variable is set its value takes precedence over the system
+configured timezone database directory path.
+.SH FILES
+.TP
+.I @ADJTIME_PATH@
+The configuration and state file for hwclock.
+.TP
+.I /etc/localtime
+The system timezone file.
+.TP
+.I /usr/share/zoneinfo/
+The system timezone database directory.
+.PP
+Device files
+.B hwclock
+may try for Hardware Clock access:
+.br
+.I /dev/rtc0
+.br
+.I /dev/rtc
+.br
+.I /dev/misc/rtc
+.br
+.I /dev/efirtc
+.br
+.I /dev/misc/efirtc
+.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
+.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
+https://www.kernel.org/pub/linux/utils/util-linux/.