NAME
hwclock - time clocks utilitySYNOPSIS
hwclock [function] [option...]DESCRIPTION
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.FUNCTIONS
The following functions are mutually exclusive, only one can be given at a time. If none is given, the default is --show.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 The Adjust Function.
These functions are for Alpha machines only,
and are only available through the Linux kernel RTC driver.
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.
The --setepoch function requires using the --epoch option to
specify the year. For example:
hwclock --setepoch --epoch=1952
The RTC driver attempts to guess the correct epoch value, so setting it may not
be required.
This epoch value is used whenever hwclock reads or sets the Hardware
Clock on an Alpha machine. For ISA machines the kernel uses the fixed Hardware
Clock epoch of 1900.
Read and set the RTC’s parameter. This
is useful, for example, to retrieve the RTC’s feature or set the
RTC’s Backup Switchover Mode.
parameter is either a numeric RTC parameter value (see the
Kernel’s include/uapi/linux/rtc.h) or an alias. See
--help for a list of valid aliases. parameter and value,
if prefixed with 0x, are interpreted as hexadecimal, otherwise decimal
values.
Predict what the Hardware Clock will read in
the future based upon the time given by the --date option and the
information in /etc/adjtime. This is useful, for example, to account
for drift when setting a Hardware Clock wakeup (aka alarm). See
rtcwake(8).
Do not use this function if the Hardware Clock is being modified by anything
other than the current operating system’s hwclock command, such
as '11 minute mode' or from dual-booting another OS.
Read the Hardware Clock and print its time to
standard output in the ISO 8601 format. The time shown is always in
local time, even if you keep your Hardware Clock in UTC. See the
--localtime option.
Showing the Hardware Clock time is the default when no function is specified.
The --get function also applies drift correction to the time read, based
upon the information in /etc/adjtime. Do not use this function if the
Hardware Clock is being modified by anything other than the current operating
system’s hwclock command, such as '11 minute mode' or from
dual-booting another OS.
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
The Adjust Function.
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
--hctosys function does this based upon the information in the
/etc/adjtime file or the command line arguments --localtime and
--utc. Note: no daylight saving adjustment is made. See the discussion
below, under LOCAL vs UTC.
The kernel also keeps a timezone value, the --hctosys function sets it to
the timezone configured for the system. The system timezone is configured by
the TZ environment variable or the /etc/localtime file, as
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 settimeofday(2).)
When used in a startup script, making the --hctosys function the first
caller of settimeofday(2) from boot, it will set the NTP '11 minute
mode' timescale via the 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 Automatic
Hardware Clock Synchronization by the Kernel.
This is a good function to use in one of the system startup scripts before the
file systems are mounted read/write.
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
--hctosys will set the time incorrectly by including drift
compensation.
Drift compensation can be inhibited by setting the drift factor in
/etc/adjtime to zero. This setting will be persistent as long as the
--update-drift option is not used with --systohc at shutdown (or
anywhere else). Another way to inhibit this is by using the --noadjfile
option when calling the --hctosys function. A third method is to delete
the /etc/adjtime file. 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
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.
A condition under which inhibiting 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.
For hwclock's drift correction to work properly it is imperative that
nothing changes the Hardware Clock while its Linux instance is not
running.
Set the Hardware Clock to the time given by
the --date option, and update the timestamps in /etc/adjtime.
With the --update-drift option also (re)calculate the drift factor. Try
it without the option if --set fails. See --update-drift
below.
This is an alternate to the --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.
It does the following things that are detailed above in the --hctosys
function:
•Corrects the System Clock timescale to
UTC as needed. Only instead of accomplishing this by setting the System Clock,
hwclock simply informs the kernel and it handles the change.
•Sets the kernel’s NTP '11
minute mode' timescale.
•Sets the kernel’s
timezone.
Set the Hardware Clock from the System Clock,
and update the timestamps in /etc/adjtime. With the
--update-drift option also (re)calculate the drift factor. Try it
without the option if --systohc fails. See --update-drift
below.
Display help text and exit.
Print version and exit.
OPTIONS
--adjfile=filenameOverride the default /etc/adjtime file
path.
This option must be used with the --set
or --predict functions, otherwise it is ignored.
hwclock --set --date='16:45'
hwclock --predict --date='2525-08-14 07:11:05'
The argument must be in local time, even if you keep your Hardware Clock in UTC.
See the --localtime option. Therefore, the argument should not include
any timezone information. It also should not be a relative time like "+5
minutes", because 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.
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.
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.
Use --verbose. The --debug
option has been deprecated and may be repurposed or removed in a future
release.
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 hwclock to use explicit I/O instructions to access
the Hardware Clock. Without this option, 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 --rtc option.
This option is required when using the
--setepoch function. The minimum year value is 1900. The maximum
is system dependent ( ULONG_MAX - 1).
Override hwclock's default rtc device
file name. Otherwise it will use the first one found in this order:
/dev/rtc0, /dev/rtc, /dev/misc/rtc. For IA-64:
/dev/efirtc /dev/misc/efirtc
Indicate which timescale the Hardware Clock is
set to.
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 --localtime or --utc options give this information to
the 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.
If you specify neither --utc nor --localtime then the one last
given with a set function ( --set, --systohc, or
--adjust), as recorded in /etc/adjtime, will be used. If the
adjtime file doesn’t exist, the default is UTC.
Note: daylight saving time changes may be inconsistent when the Hardware Clock
is kept in local time. See the discussion below, under LOCAL vs
UTC.
Disable the facilities provided by
/etc/adjtime. hwclock will not read nor write to that file with
this option. Either --utc or --localtime must be specified when
using this option.
Do not actually change anything on the system,
that is, the Clocks or /etc/adjtime (--verbose is implicit with
this option).
Update the Hardware Clock’s drift
factor in /etc/adjtime. It can only be used with --set or
--systohc.
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.
This option was added in v2.26, because it is typical for systems to call
hwclock --systohc at shutdown; with the old behavior this would
automatically (re)calculate the drift factor which caused several problems:
•When using NTP with an '11 minute
mode' kernel the drift factor would be clobbered to near zero.
•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.
•(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.
•Significantly increased system
shutdown times (as of v2.31 when not using --update-drift the RTC is
not read).
Display more details about what hwclock
is doing internally.
NOTES
Clocks in a Linux System
There are two types of date-time clocks:Hardware Clock Access Methods
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 --rtc option.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. hwclock's --adjust function lets you apply systematic drift corrections to the Hardware Clock.The Adjtime File
While named for its historical purpose of controlling adjustments only, it actually contains other information used by hwclock from one invocation to the next.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.)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. 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.DATE-TIME CONFIGURATION
Keeping Time without External Synchronization
This discussion is based on the following conditions:•Nothing is running that alters the
date-time clocks, such as NTP daemon or a cron job."
•The system timezone is configured for
the correct local time. See below, under POSIX vs 'RIGHT'.
•Early during startup the following are
called, in this order: adjtimex --tick value --frequency
value hwclock --hctosys
•During shutdown the following is
called: hwclock --systohc
•Systems without adjtimex may
use ntptime.
Ensure that NTP daemon will not be launched
at startup.
The System Clock time must be correct
at shutdown!
Shut down the system.
Let an extended period pass without changing
the Hardware Clock.
Start the system.
Immediately use hwclock to set the
correct time, adding the --update-drift option.
LOCAL vs UTC
Keeping the Hardware Clock in a local timescale causes inconsistent daylight saving time results:•If Linux is running during a daylight
saving time change, the time written to the Hardware Clock will be adjusted
for the change.
•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.
POSIX vs 'RIGHT'
A discussion on date-time configuration would be incomplete without addressing timezones, this is mostly well covered by tzset(3). One area that seems to have no documentation is the 'right' directory of the Time Zone Database, sometimes called tz or zoneinfo.EXIT STATUS
One of the following exit values will be returned:Successful program execution.
The operation failed or the command syntax was
not valid.
ENVIRONMENT
TZIf this variable is set its value takes
precedence over the system configured timezone.
If this variable is set its value takes
precedence over the system configured timezone database directory path.
FILES
/etc/adjtimeThe configuration and state file for
hwclock. See also adjtime_config(5).
The system timezone file.
The system timezone database directory.
SEE ALSO
date(1), adjtime_config(5), adjtimex(8), gettimeofday(2), settimeofday(2), crontab(1p), tzset(3)AUTHORS
Written by Bryan <[email protected]>Henderson September 1996, based on work done on the clock(8) program by Charles Hedrick, Rob Hooft, and Harald Koenig. See the source code for complete history and credits.REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.AVAILABILITY
The hwclock command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.2022-05-11 | util-linux 2.38.1 |