994 lines
37 KiB
Groff
994 lines
37 KiB
Groff
.\" 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 can be used to overwrite the internally used delay
|
|
when setting the 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
|
|
.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
|
|
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
|
|
.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
|
|
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 floating point decimal.
|
|
.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
|
|
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
|
|
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 (2)
|
|
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 (1p),
|
|
.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/.
|