The following functions are mutually exclusive, only one can be
given at a time. If none is given, the default is --show.
-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 The Adjust
Function.
--getepoch; --setepoch
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.
--predict
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.
-r, --show; --get
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.
-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 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
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.
--systz
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.
The first two are only available on the first call of
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.
-w, --systohc
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.
-V, --version
Display version information and exit.
-h, --help
Display help text and exit.
