1HWCLOCK(8)                   System Administration                  HWCLOCK(8)
2
3
4

NAME

6       hwclock - time clocks utility
7

SYNOPSIS

9       hwclock [function] [option...]
10

DESCRIPTION

12       hwclock is an administration tool for the time clocks. It can: display
13       the Hardware Clock time; set the Hardware Clock to a specified time;
14       set the Hardware Clock from the System Clock; set the System Clock from
15       the Hardware Clock; compensate for Hardware Clock drift; correct the
16       System Clock timescale; set the kernel’s timezone, NTP timescale, and
17       epoch (Alpha only); and predict future Hardware Clock values based on
18       its drift rate.
19
20       Since v2.26 important changes were made to the --hctosys function and
21       the --directisa option, and a new option --update-drift was added. See
22       their respective descriptions below.
23

FUNCTIONS

25       The following functions are mutually exclusive, only one can be given
26       at a time. If none is given, the default is --show.
27
28       -a, --adjust
29           Add or subtract time from the Hardware Clock to account for
30           systematic drift since the last time the clock was set or adjusted.
31           See the discussion below, under The Adjust Function.
32
33       --getepoch; --setepoch
34           These functions are for Alpha machines only, and are only available
35           through the Linux kernel RTC driver.
36
37           They are used to read and set the kernel’s Hardware Clock epoch
38           value. Epoch is the number of years into AD to which a zero year
39           value in the Hardware Clock refers. For example, if the machine’s
40           BIOS sets the year counter in the Hardware Clock to contain the
41           number of full years since 1952, then the kernel’s Hardware Clock
42           epoch value must be 1952.
43
44           The --setepoch function requires using the --epoch option to
45           specify the year. For example:
46
47           hwclock --setepoch --epoch=1952
48
49           The RTC driver attempts to guess the correct epoch value, so
50           setting it may not be required.
51
52           This epoch value is used whenever hwclock reads or sets the
53           Hardware Clock on an Alpha machine. For ISA machines the kernel
54           uses the fixed Hardware Clock epoch of 1900.
55
56       --param-get=parameter; --param-set=parameter=value
57           Read and set the RTC’s parameter. This is useful, for example, to
58           retrieve the RTC’s feature or set the RTC’s Backup Switchover Mode.
59
60           parameter is either a numeric RTC parameter value (see the Kernel’s
61           include/uapi/linux/rtc.h) or an alias. See --help for a list of
62           valid aliases. parameter and value, if prefixed with 0x, are
63           interpreted as hexadecimal, otherwise decimal values.
64
65       --predict
66           Predict what the Hardware Clock will read in the future based upon
67           the time given by the --date option and the information in
68           /etc/adjtime. This is useful, for example, to account for drift
69           when setting a Hardware Clock wakeup (aka alarm). See rtcwake(8).
70
71           Do not use this function if the Hardware Clock is being modified by
72           anything other than the current operating system’s hwclock command,
73           such as '11 minute mode' or from dual-booting another OS.
74
75       -r, --show; --get
76           Read the Hardware Clock and print its time to standard output in
77           the ISO 8601 format. The time shown is always in local time, even
78           if you keep your Hardware Clock in UTC. See the --localtime option.
79
80           Showing the Hardware Clock time is the default when no function is
81           specified.
82
83           The --get function also applies drift correction to the time read,
84           based upon the information in /etc/adjtime. Do not use this
85           function if the Hardware Clock is being modified by anything other
86           than the current operating system’s hwclock command, such as '11
87           minute mode' or from dual-booting another OS.
88
89       -s, --hctosys
90           Set the System Clock from the Hardware Clock. The time read from
91           the Hardware Clock is compensated to account for systematic drift
92           before using it to set the System Clock. See the discussion below,
93           under The Adjust Function.
94
95           The System Clock must be kept in the UTC timescale for date-time
96           applications to work correctly in conjunction with the timezone
97           configured for the system. If the Hardware Clock is kept in local
98           time then the time read from it must be shifted to the UTC
99           timescale before using it to set the System Clock. The --hctosys
100           function does this based upon the information in the /etc/adjtime
101           file or the command line arguments --localtime and --utc. Note: no
102           daylight saving adjustment is made. See the discussion below, under
103           LOCAL vs UTC.
104
105           The kernel also keeps a timezone value, the --hctosys function sets
106           it to the timezone configured for the system. The system timezone
107           is configured by the TZ environment variable or the /etc/localtime
108           file, as tzset(3) would interpret them. The obsolete tz_dsttime
109           field of the kernel’s timezone value is set to zero. (For details
110           on what this field used to mean, see settimeofday(2).)
111
112           When used in a startup script, making the --hctosys function the
113           first caller of settimeofday(2) from boot, it will set the NTP '11
114           minute mode' timescale via the persistent_clock_is_local kernel
115           variable. If the Hardware Clock’s timescale configuration is
116           changed then a reboot is required to inform the kernel. See the
117           discussion below, under Automatic Hardware Clock Synchronization by
118           the Kernel.
119
120           This is a good function to use in one of the system startup scripts
121           before the file systems are mounted read/write.
122
123           This function should never be used on a running system. Jumping
124           system time will cause problems, such as corrupted filesystem
125           timestamps. Also, if something has changed the Hardware Clock, like
126           NTP’s '11 minute mode', then --hctosys will set the time
127           incorrectly by including drift compensation.
128
129           Drift compensation can be inhibited by setting the drift factor in
130           /etc/adjtime to zero. This setting will be persistent as long as
131           the --update-drift option is not used with --systohc at shutdown
132           (or anywhere else). Another way to inhibit this is by using the
133           --noadjfile option when calling the --hctosys function. A third
134           method is to delete the /etc/adjtime file. Hwclock will then
135           default to using the UTC timescale for the Hardware Clock. If the
136           Hardware Clock is ticking local time it will need to be defined in
137           the file. This can be done by calling hwclock --localtime --adjust;
138           when the file is not present this command will not actually adjust
139           the Clock, but it will create the file with local time configured,
140           and a drift factor of zero.
141
142           A condition under which inhibiting hwclock's drift correction may
143           be desired is when dual-booting multiple operating systems. If
144           while this instance of Linux is stopped, another OS changes the
145           Hardware Clock’s value, then when this instance is started again
146           the drift correction applied will be incorrect.
147
148           For hwclock's drift correction to work properly it is imperative
149           that nothing changes the Hardware Clock while its Linux instance is
150           not running.
151
152       --set
153           Set the Hardware Clock to the time given by the --date option, and
154           update the timestamps in /etc/adjtime. With the --update-drift
155           option also (re)calculate the drift factor. Try it without the
156           option if --set fails. See --update-drift below.
157
158       --systz
159           This is an alternate to the --hctosys function that does not read
160           the Hardware Clock nor set the System Clock; consequently there is
161           not any drift correction. It is intended to be used in a startup
162           script on systems with kernels above version 2.6 where you know the
163           System Clock has been set from the Hardware Clock by the kernel
164           during boot.
165
166           It does the following things that are detailed above in the
167           --hctosys function:
168
169           •   Corrects the System Clock timescale to UTC as needed. Only
170               instead of accomplishing this by setting the System Clock,
171               hwclock simply informs the kernel and it handles the change.
172
173           •   Sets the kernel’s NTP '11 minute mode' timescale.
174
175           •   Sets the kernel’s timezone.
176
177       The first two are only available on the first call of settimeofday(2)
178       after boot. Consequently this option only makes sense when used in a
179       startup script. If the Hardware Clocks timescale configuration is
180       changed then a reboot would be required to inform the kernel.
181
182       -w, --systohc
183           Set the Hardware Clock from the System Clock, and update the
184           timestamps in /etc/adjtime. With the --update-drift option also
185           (re)calculate the drift factor. Try it without the option if
186           --systohc fails. See --update-drift below.
187
188       -h, --help
189           Display help text and exit.
190
191       -V, --version
192           Print version and exit.
193

OPTIONS

195       --adjfile=filename
196           Override the default /etc/adjtime file path.
197
198       --date=date_string
199           This option must be used with the --set or --predict functions,
200           otherwise it is ignored.
201
202           hwclock --set --date='16:45'
203
204           hwclock --predict --date='2525-08-14 07:11:05'
205
206           The argument must be in local time, even if you keep your Hardware
207           Clock in UTC. See the --localtime option. Therefore, the argument
208           should not include any timezone information. It also should not be
209           a relative time like "+5 minutes", because hwclock's precision
210           depends upon correlation between the argument’s value and when the
211           enter key is pressed. Fractional seconds are silently dropped. This
212           option is capable of understanding many time and date formats, but
213           the previous parameters should be observed.
214
215       --delay=seconds
216           This option can be used to overwrite the internally used delay when
217           setting the clock time. The default is 0.5 (500ms) for rtc_cmos,
218           for another RTC types the delay is 0. If RTC type is impossible to
219           determine (from sysfs) then it defaults also to 0.5 to be
220           backwardly compatible.
221
222           The 500ms default is based on commonly used MC146818A-compatible
223           (x86) hardware clock. This Hardware Clock can only be set to any
224           integer time plus one half second. The integer time is required
225           because there is no interface to set or get a fractional second.
226           The additional half second delay is because the Hardware Clock
227           updates to the following second precisely 500 ms after setting the
228           new time. Unfortunately, this behavior is hardware specific and in
229           some cases another delay is required.
230
231       -D, --debug
232           Use --verbose. The --debug option has been deprecated and may be
233           repurposed or removed in a future release.
234
235       --directisa
236           This option is meaningful for ISA compatible machines in the x86
237           and x86_64 family. For other machines, it has no effect. This
238           option tells hwclock to use explicit I/O instructions to access the
239           Hardware Clock. Without this option, hwclock will use the rtc
240           device file, which it assumes to be driven by the Linux RTC device
241           driver. As of v2.26 it will no longer automatically use directisa
242           when the rtc driver is unavailable; this was causing an unsafe
243           condition that could allow two processes to access the Hardware
244           Clock at the same time. Direct hardware access from userspace
245           should only be used for testing, troubleshooting, and as a last
246           resort when all other methods fail. See the --rtc option.
247
248       --epoch=year
249           This option is required when using the --setepoch function. The
250           minimum year value is 1900. The maximum is system dependent
251           (ULONG_MAX - 1).
252
253       -f, --rtc=filename
254           Override hwclock's default rtc device file name. Otherwise it will
255           use the first one found in this order: /dev/rtc0, /dev/rtc,
256           /dev/misc/rtc. For IA-64: /dev/efirtc /dev/misc/efirtc
257
258       -l, --localtime; -u, --utc
259           Indicate which timescale the Hardware Clock is set to.
260
261           The Hardware Clock may be configured to use either the UTC or the
262           local timescale, but nothing in the clock itself says which
263           alternative is being used. The --localtime or --utc options give
264           this information to the hwclock command. If you specify the wrong
265           one (or specify neither and take a wrong default), both setting and
266           reading the Hardware Clock will be incorrect.
267
268           If you specify neither --utc nor --localtime then the one last
269           given with a set function (--set, --systohc, or --adjust), as
270           recorded in /etc/adjtime, will be used. If the adjtime file doesn’t
271           exist, the default is UTC.
272
273           Note: daylight saving time changes may be inconsistent when the
274           Hardware Clock is kept in local time. See the discussion below,
275           under LOCAL vs UTC.
276
277       --noadjfile
278           Disable the facilities provided by /etc/adjtime. hwclock will not
279           read nor write to that file with this option. Either --utc or
280           --localtime must be specified when using this option.
281
282       --test
283           Do not actually change anything on the system, that is, the Clocks
284           or /etc/adjtime (--verbose is implicit with this option).
285
286       --update-drift
287           Update the Hardware Clock’s drift factor in /etc/adjtime. It can
288           only be used with --set or --systohc.
289
290           A minimum four hour period between settings is required. This is to
291           avoid invalid calculations. The longer the period, the more precise
292           the resulting drift factor will be.
293
294           This option was added in v2.26, because it is typical for systems
295           to call hwclock --systohc at shutdown; with the old behavior this
296           would automatically (re)calculate the drift factor which caused
297           several problems:
298
299           •   When using NTP with an '11 minute mode' kernel the drift factor
300               would be clobbered to near zero.
301
302           •   It would not allow the use of 'cold' drift correction. With
303               most configurations using 'cold' drift will yield favorable
304               results. Cold, means when the machine is turned off which can
305               have a significant impact on the drift factor.
306
307           •   (Re)calculating drift factor on every shutdown delivers
308               suboptimal results. For example, if ephemeral conditions cause
309               the machine to be abnormally hot the drift factor calculation
310               would be out of range.
311
312           •   Significantly increased system shutdown times (as of v2.31 when
313               not using --update-drift the RTC is not read).
314
315       Having hwclock calculate the drift factor is a good starting point, but
316       for optimal results it will likely need to be adjusted by directly
317       editing the /etc/adjtime file. For most configurations once a machine’s
318       optimal drift factor is crafted it should not need to be changed.
319       Therefore, the old behavior to automatically (re)calculate drift was
320       changed and now requires this option to be used. See the discussion
321       below, under The Adjust Function.
322
323       This option requires reading the Hardware Clock before setting it. If
324       it cannot be read, then this option will cause the set functions to
325       fail. This can happen, for example, if the Hardware Clock is corrupted
326       by a power failure. In that case, the clock must first be set without
327       this option. Despite it not working, the resulting drift correction
328       factor would be invalid anyway.
329
330       -v, --verbose
331           Display more details about what hwclock is doing internally.
332

NOTES

334   Clocks in a Linux System
335       There are two types of date-time clocks:
336
337       The Hardware Clock: This clock is an independent hardware device, with
338       its own power domain (battery, capacitor, etc), that operates when the
339       machine is powered off, or even unplugged.
340
341       On an ISA compatible system, this clock is specified as part of the ISA
342       standard. A control program can read or set this clock only to a whole
343       second, but it can also detect the edges of the 1 second clock ticks,
344       so the clock actually has virtually infinite precision.
345
346       This clock is commonly called the hardware clock, the real time clock,
347       the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its
348       capitalized form, was coined for use by hwclock. The Linux kernel also
349       refers to it as the persistent clock.
350
351       Some non-ISA systems have a few real time clocks with only one of them
352       having its own power domain. A very low power external I2C or SPI clock
353       chip might be used with a backup battery as the hardware clock to
354       initialize a more functional integrated real-time clock which is used
355       for most other purposes.
356
357       The System Clock: This clock is part of the Linux kernel and is driven
358       by a timer interrupt. (On an ISA machine, the timer interrupt is part
359       of the ISA standard.) It has meaning only while Linux is running on the
360       machine. The System Time is the number of seconds since 00:00:00
361       January 1, 1970 UTC (or more succinctly, the number of seconds since
362       1969 UTC). The System Time is not an integer, though. It has virtually
363       infinite precision.
364
365       The System Time is the time that matters. The Hardware Clock’s basic
366       purpose is to keep time when Linux is not running so that the System
367       Clock can be initialized from it at boot. Note that in DOS, for which
368       ISA was designed, the Hardware Clock is the only real time clock.
369
370       It is important that the System Time not have any discontinuities such
371       as would happen if you used the date(1) program to set it while the
372       system is running. You can, however, do whatever you want to the
373       Hardware Clock while the system is running, and the next time Linux
374       starts up, it will do so with the adjusted time from the Hardware
375       Clock. Note: currently this is not possible on most systems because
376       hwclock --systohc is called at shutdown.
377
378       The Linux kernel’s timezone is set by hwclock. But don’t be misled —
379       almost nobody cares what timezone the kernel thinks it is in. Instead,
380       programs that care about the timezone (perhaps because they want to
381       display a local time for you) almost always use a more traditional
382       method of determining the timezone: They use the TZ environment
383       variable or the /etc/localtime file, as explained in the man page for
384       tzset(3). However, some programs and fringe parts of the Linux kernel
385       such as filesystems use the kernel’s timezone value. An example is the
386       vfat filesystem. If the kernel timezone value is wrong, the vfat
387       filesystem will report and set the wrong timestamps on files. Another
388       example is the kernel’s NTP '11 minute mode'. If the kernel’s timezone
389       value and/or the persistent_clock_is_local variable are wrong, then the
390       Hardware Clock will be set incorrectly by '11 minute mode'. See the
391       discussion below, under Automatic Hardware Clock Synchronization by the
392       Kernel.
393
394       hwclock sets the kernel’s timezone to the value indicated by TZ or
395       /etc/localtime with the --hctosys or --systz functions.
396
397       The kernel’s timezone value actually consists of two parts: 1) a field
398       tz_minuteswest indicating how many minutes local time (not adjusted for
399       DST) lags behind UTC, and 2) a field tz_dsttime indicating the type of
400       Daylight Savings Time (DST) convention that is in effect in the
401       locality at the present time. This second field is not used under Linux
402       and is always zero. See also settimeofday(2).
403
404   Hardware Clock Access Methods
405       hwclock uses many different ways to get and set Hardware Clock values.
406       The most normal way is to do I/O to the rtc device special file, which
407       is presumed to be driven by the rtc device driver. Also, Linux systems
408       using the rtc framework with udev, are capable of supporting multiple
409       Hardware Clocks. This may bring about the need to override the default
410       rtc device by specifying one with the --rtc option.
411
412       However, this method is not always available as older systems do not
413       have an rtc driver. On these systems, the method of accessing the
414       Hardware Clock depends on the system hardware.
415
416       On an ISA compatible system, hwclock can directly access the "CMOS
417       memory" registers that constitute the clock, by doing I/O to Ports 0x70
418       and 0x71. It does this with actual I/O instructions and consequently
419       can only do it if running with superuser effective userid. This method
420       may be used by specifying the --directisa option.
421
422       This is a really poor method of accessing the clock, for all the
423       reasons that userspace programs are generally not supposed to do direct
424       I/O and disable interrupts. hwclock provides it for testing,
425       troubleshooting, and because it may be the only method available on ISA
426       systems which do not have a working rtc device driver.
427
428   The Adjust Function
429       The Hardware Clock is usually not very accurate. However, much of its
430       inaccuracy is completely predictable - it gains or loses the same
431       amount of time every day. This is called systematic drift. hwclock's
432       --adjust function lets you apply systematic drift corrections to the
433       Hardware Clock.
434
435       It works like this: hwclock keeps a file, /etc/adjtime, that keeps some
436       historical information. This is called the adjtime file.
437
438       Suppose you start with no adjtime file. You issue a hwclock --set
439       command to set the Hardware Clock to the true current time. hwclock
440       creates the adjtime file and records in it the current time as the last
441       time the clock was calibrated. Five days later, the clock has gained 10
442       seconds, so you issue a hwclock --set --update-drift command to set it
443       back 10 seconds. hwclock updates the adjtime file to show the current
444       time as the last time the clock was calibrated, and records 2 seconds
445       per day as the systematic drift rate. 24 hours go by, and then you
446       issue a hwclock --adjust command. hwclock consults the adjtime file and
447       sees that the clock gains 2 seconds per day when left alone and that it
448       has been left alone for exactly one day. So it subtracts 2 seconds from
449       the Hardware Clock. It then records the current time as the last time
450       the clock was adjusted. Another 24 hours go by and you issue another
451       hwclock --adjust. hwclock does the same thing: subtracts 2 seconds and
452       updates the adjtime file with the current time as the last time the
453       clock was adjusted.
454
455       When you use the --update-drift option with --set or --systohc, the
456       systematic drift rate is (re)calculated by comparing the fully drift
457       corrected current Hardware Clock time with the new set time, from that
458       it derives the 24 hour drift rate based on the last calibrated
459       timestamp from the adjtime file. This updated drift factor is then
460       saved in /etc/adjtime.
461
462       A small amount of error creeps in when the Hardware Clock is set, so
463       --adjust refrains from making any adjustment that is less than 1
464       second. Later on, when you request an adjustment again, the accumulated
465       drift will be more than 1 second and --adjust will make the adjustment
466       including any fractional amount.
467
468       hwclock --hctosys also uses the adjtime file data to compensate the
469       value read from the Hardware Clock before using it to set the System
470       Clock. It does not share the 1 second limitation of --adjust, and will
471       correct sub-second drift values immediately. It does not change the
472       Hardware Clock time nor the adjtime file. This may eliminate the need
473       to use --adjust, unless something else on the system needs the Hardware
474       Clock to be compensated.
475
476   The Adjtime File
477       While named for its historical purpose of controlling adjustments only,
478       it actually contains other information used by hwclock from one
479       invocation to the next.
480
481       The format of the adjtime file is, in ASCII:
482
483       Line 1: Three numbers, separated by blanks: 1) the systematic drift
484       rate in seconds per day, floating point decimal; 2) the resulting
485       number of seconds since 1969 UTC of most recent adjustment or
486       calibration, decimal integer; 3) zero (for compatibility with clock(8))
487       as a floating point decimal.
488
489       Line 2: One number: the resulting number of seconds since 1969 UTC of
490       most recent calibration. Zero if there has been no calibration yet or
491       it is known that any previous calibration is moot (for example, because
492       the Hardware Clock has been found, since that calibration, not to
493       contain a valid time). This is a decimal integer.
494
495       Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to
496       Coordinated Universal Time or local time. You can always override this
497       value with options on the hwclock command line.
498
499       You can use an adjtime file that was previously used with the clock(8)
500       program with hwclock.
501
502   Automatic Hardware Clock Synchronization by the Kernel
503       You should be aware of another way that the Hardware Clock is kept
504       synchronized in some systems. The Linux kernel has a mode wherein it
505       copies the System Time to the Hardware Clock every 11 minutes. This
506       mode is a compile time option, so not all kernels will have this
507       capability. This is a good mode to use when you are using something
508       sophisticated like NTP to keep your System Clock synchronized. (NTP is
509       a way to keep your System Time synchronized either to a time server
510       somewhere on the network or to a radio clock hooked up to your system.
511       See RFC 1305.)
512
513       If the kernel is compiled with the '11 minute mode' option it will be
514       active when the kernel’s clock discipline is in a synchronized state.
515       When in this state, bit 6 (the bit that is set in the mask 0x0040) of
516       the kernel’s time_status variable is unset. This value is output as the
517       'status' line of the adjtimex --print or ntptime commands.
518
519       It takes an outside influence, like the NTP daemon to put the kernel’s
520       clock discipline into a synchronized state, and therefore turn on '11
521       minute mode'. It can be turned off by running anything that sets the
522       System Clock the old fashioned way, including hwclock --hctosys.
523       However, if the NTP daemon is still running, it will turn '11 minute
524       mode' back on again the next time it synchronizes the System Clock.
525
526       If your system runs with '11 minute mode' on, it may need to use either
527       --hctosys or --systz in a startup script, especially if the Hardware
528       Clock is configured to use the local timescale. Unless the kernel is
529       informed of what timescale the Hardware Clock is using, it may clobber
530       it with the wrong one. The kernel uses UTC by default.
531
532       The first userspace command to set the System Clock informs the kernel
533       what timescale the Hardware Clock is using. This happens via the
534       persistent_clock_is_local kernel variable. If --hctosys or --systz is
535       the first, it will set this variable according to the adjtime file or
536       the appropriate command-line argument. Note that when using this
537       capability and the Hardware Clock timescale configuration is changed,
538       then a reboot is required to notify the kernel.
539
540       hwclock --adjust should not be used with NTP '11 minute mode'.
541
542   ISA Hardware Clock Century value
543       There is some sort of standard that defines CMOS memory Byte 50 on an
544       ISA machine as an indicator of what century it is. hwclock does not use
545       or set that byte because there are some machines that don’t define the
546       byte that way, and it really isn’t necessary anyway, since the
547       year-of-century does a good job of implying which century it is.
548
549       If you have a bona fide use for a CMOS century byte, contact the
550       hwclock maintainer; an option may be appropriate.
551
552       Note that this section is only relevant when you are using the "direct
553       ISA" method of accessing the Hardware Clock. ACPI provides a standard
554       way to access century values, when they are supported by the hardware.
555

DATE-TIME CONFIGURATION

557   Keeping Time without External Synchronization
558       This discussion is based on the following conditions:
559
560       •   Nothing is running that alters the date-time clocks, such as NTP
561           daemon or a cron job."
562
563       •   The system timezone is configured for the correct local time. See
564           below, under POSIX vs 'RIGHT'.
565
566       •   Early during startup the following are called, in this order:
567           adjtimex --tick value --frequency value hwclock --hctosys
568
569       •   During shutdown the following is called: hwclock --systohc
570
571           •   Systems without adjtimex may use ntptime.
572
573       Whether maintaining precision time with NTP daemon or not, it makes
574       sense to configure the system to keep reasonably good date-time on its
575       own.
576
577       The first step in making that happen is having a clear understanding of
578       the big picture. There are two completely separate hardware devices
579       running at their own speed and drifting away from the 'correct' time at
580       their own rates. The methods and software for drift correction are
581       different for each of them. However, most systems are configured to
582       exchange values between these two clocks at startup and shutdown. Now
583       the individual device’s time keeping errors are transferred back and
584       forth between each other. Attempt to configure drift correction for
585       only one of them, and the other’s drift will be overlaid upon it.
586
587       This problem can be avoided when configuring drift correction for the
588       System Clock by simply not shutting down the machine. This, plus the
589       fact that all of hwclock's precision (including calculating drift
590       factors) depends upon the System Clock’s rate being correct, means that
591       configuration of the System Clock should be done first.
592
593       The System Clock drift is corrected with the adjtimex(8) command’s
594       --tick and --frequency options. These two work together: tick is the
595       coarse adjustment and frequency is the fine adjustment. (For systems
596       that do not have an adjtimex package, ntptime -f ppm may be used
597       instead.)
598
599       Some Linux distributions attempt to automatically calculate the System
600       Clock drift with adjtimex's compare operation. Trying to correct one
601       drifting clock by using another drifting clock as a reference is akin
602       to a dog trying to catch its own tail. Success may happen eventually,
603       but great effort and frustration will likely precede it. This
604       automation may yield an improvement over no configuration, but
605       expecting optimum results would be in error. A better choice for manual
606       configuration would be adjtimex's --log options.
607
608       It may be more effective to simply track the System Clock drift with
609       sntp, or date -Ins and a precision timepiece, and then calculate the
610       correction manually.
611
612       After setting the tick and frequency values, continue to test and
613       refine the adjustments until the System Clock keeps good time. See
614       adjtimex(2) for more information and the example demonstrating manual
615       drift calculations.
616
617       Once the System Clock is ticking smoothly, move on to the Hardware
618       Clock.
619
620       As a rule, cold drift will work best for most use cases. This should be
621       true even for 24/7 machines whose normal downtime consists of a reboot.
622       In that case the drift factor value makes little difference. But on the
623       rare occasion that the machine is shut down for an extended period,
624       then cold drift should yield better results.
625
626       Steps to calculate cold drift:
627
628       1
629           Ensure that NTP daemon will not be launched at startup.
630
631       2
632           The System Clock time must be correct at shutdown!
633
634       3
635           Shut down the system.
636
637       4
638           Let an extended period pass without changing the Hardware Clock.
639
640       5
641           Start the system.
642
643       6
644           Immediately use hwclock to set the correct time, adding the
645           --update-drift option.
646
647       Note: if step 6 uses --systohc, then the System Clock must be set
648       correctly (step 6a) just before doing so.
649
650       Having hwclock calculate the drift factor is a good starting point, but
651       for optimal results it will likely need to be adjusted by directly
652       editing the /etc/adjtime file. Continue to test and refine the drift
653       factor until the Hardware Clock is corrected properly at startup. To
654       check this, first make sure that the System Time is correct before
655       shutdown and then use sntp, or date -Ins and a precision timepiece,
656       immediately after startup.
657
658   LOCAL vs UTC
659       Keeping the Hardware Clock in a local timescale causes inconsistent
660       daylight saving time results:
661
662       •   If Linux is running during a daylight saving time change, the time
663           written to the Hardware Clock will be adjusted for the change.
664
665       •   If Linux is NOT running during a daylight saving time change, the
666           time read from the Hardware Clock will NOT be adjusted for the
667           change.
668
669       The Hardware Clock on an ISA compatible system keeps only a date and
670       time, it has no concept of timezone nor daylight saving. Therefore,
671       when hwclock is told that it is in local time, it assumes it is in the
672       'correct' local time and makes no adjustments to the time read from it.
673
674       Linux handles daylight saving time changes transparently only when the
675       Hardware Clock is kept in the UTC timescale. Doing so is made easy for
676       system administrators as hwclock uses local time for its output and as
677       the argument to the --date option.
678
679       POSIX systems, like Linux, are designed to have the System Clock
680       operate in the UTC timescale. The Hardware Clock’s purpose is to
681       initialize the System Clock, so also keeping it in UTC makes sense.
682
683       Linux does, however, attempt to accommodate the Hardware Clock being in
684       the local timescale. This is primarily for dual-booting with older
685       versions of MS Windows. From Windows 7 on, the RealTimeIsUniversal
686       registry key is supposed to be working properly so that its Hardware
687       Clock can be kept in UTC.
688
689   POSIX vs 'RIGHT'
690       A discussion on date-time configuration would be incomplete without
691       addressing timezones, this is mostly well covered by tzset(3). One area
692       that seems to have no documentation is the 'right' directory of the
693       Time Zone Database, sometimes called tz or zoneinfo.
694
695       There are two separate databases in the zoneinfo system, posix and
696       'right'. 'Right' (now named zoneinfo-leaps) includes leap seconds and
697       posix does not. To use the 'right' database the System Clock must be
698       set to (UTC + leap seconds), which is equivalent to (TAI - 10). This
699       allows calculating the exact number of seconds between two dates that
700       cross a leap second epoch. The System Clock is then converted to the
701       correct civil time, including UTC, by using the 'right' timezone files
702       which subtract the leap seconds. Note: this configuration is considered
703       experimental and is known to have issues.
704
705       To configure a system to use a particular database all of the files
706       located in its directory must be copied to the root of
707       /usr/share/zoneinfo. Files are never used directly from the posix or
708       'right' subdirectories, e.g., TZ='right/Europe/Dublin'. This habit was
709       becoming so common that the upstream zoneinfo project restructured the
710       system’s file tree by moving the posix and 'right' subdirectories out
711       of the zoneinfo directory and into sibling directories:
712
713       /usr/share/zoneinfo, /usr/share/zoneinfo-posix,
714       /usr/share/zoneinfo-leaps
715
716       Unfortunately, some Linux distributions are changing it back to the old
717       tree structure in their packages. So the problem of system
718       administrators reaching into the 'right' subdirectory persists. This
719       causes the system timezone to be configured to include leap seconds
720       while the zoneinfo database is still configured to exclude them. Then
721       when an application such as a World Clock needs the South_Pole timezone
722       file; or an email MTA, or hwclock needs the UTC timezone file; they
723       fetch it from the root of /usr/share/zoneinfo , because that is what
724       they are supposed to do. Those files exclude leap seconds, but the
725       System Clock now includes them, causing an incorrect time conversion.
726
727       Attempting to mix and match files from these separate databases will
728       not work, because they each require the System Clock to use a different
729       timescale. The zoneinfo database must be configured to use either posix
730       or 'right', as described above, or by assigning a database path to the
731       TZDIR environment variable.
732

EXIT STATUS

734       One of the following exit values will be returned:
735
736       EXIT_SUCCESS ('0' on POSIX systems)
737           Successful program execution.
738
739       EXIT_FAILURE ('1' on POSIX systems)
740           The operation failed or the command syntax was not valid.
741

ENVIRONMENT

743       TZ
744           If this variable is set its value takes precedence over the system
745           configured timezone.
746
747       TZDIR
748           If this variable is set its value takes precedence over the system
749           configured timezone database directory path.
750

FILES

752       /etc/adjtime
753           The configuration and state file for hwclock. See also
754           adjtime_config(5).
755
756       /etc/localtime
757           The system timezone file.
758
759       /usr/share/zoneinfo/
760           The system timezone database directory.
761
762       Device files hwclock may try for Hardware Clock access: /dev/rtc0
763       /dev/rtc /dev/misc/rtc /dev/efirtc /dev/misc/efirtc
764

SEE ALSO

766       date(1), adjtime_config(5), adjtimex(8), gettimeofday(2),
767       settimeofday(2), crontab(1p), tzset(3)
768

AUTHORS

770       Written by Bryan Henderson <bryanh@giraffe-data.com>, September 1996,
771       based on work done on the clock(8) program by Charles Hedrick, Rob
772       Hooft, and Harald Koenig. See the source code for complete history and
773       credits.
774

REPORTING BUGS

776       For bug reports, use the issue tracker at
777       https://github.com/util-linux/util-linux/issues.
778

AVAILABILITY

780       The hwclock command is part of the util-linux package which can be
781       downloaded from Linux Kernel Archive
782       <https://www.kernel.org/pub/linux/utils/util-linux/>.
783
784
785
786util-linux 2.39.2                 2023-08-17                        HWCLOCK(8)
Impressum