1HWCLOCK(8) System Administration HWCLOCK(8)
2
6 hwclock - time clocks utility
7
9 hwclock [function] [option...]
10
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 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
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 -a, --adjust
29 Add or subtract time from the Hardware Clock to account for sys‐
30 tematic drift since the last time the clock was set or adjusted.
31 See the discussion below, under The Adjust Function.
32 --getepoch
34 --setepoch
35 These functions are for Alpha machines only, and are only avail‐
36 able through the Linux kernel RTC driver.
37 They are used to read and set the kernel's Hardware Clock epoch
39 value. Epoch is the number of years into AD to which a zero
40 year value in the Hardware Clock refers. For example, if the
41 machine's BIOS sets the year counter in the Hardware Clock to
42 contain the number of full years since 1952, then the kernel's
43 Hardware Clock epoch value must be 1952.
44 The --setepoch function requires using the --epoch option to
46 specify the year. For example:
47 hwclock --setepoch --epoch=1952
49 The RTC driver attempts to guess the correct epoch value, so
51 setting it may not be required.
52 This epoch value is used whenever hwclock reads or sets the
54 Hardware Clock on an Alpha machine. For ISA machines the kernel
55 uses the fixed Hardware Clock epoch of 1900.
56 --predict
58 Predict what the Hardware Clock will read in the future based
59 upon the time given by the --date option and the information in
60 /etc/adjtime. This is useful, for example, to account for drift
61 when setting a Hardware Clock wakeup (aka alarm). See
62 rtcwake(8).
63 Do not use this function if the Hardware Clock is being modified
65 by anything other than the current operating system's hwclock
66 command, such as '11 minute mode' or from dual-booting another
67 OS.
68 -r, --show
70 --get
71 Read the Hardware Clock and print its time to standard output in
72 the ISO 8601 format. The time shown is always in local time,
73 even if you keep your Hardware Clock in UTC. See the
74 --localtime option.
75 Showing the Hardware Clock time is the default when no function
77 is specified.
78 The --get function also applies drift correction to the time
80 read, based upon the information in /etc/adjtime. Do not use
81 this function if the Hardware Clock is being modified by any‐
82 thing other than the current operating system's hwclock command,
83 such as '11 minute mode' or from dual-booting another OS.
84 -s, --hctosys
86 Set the System Clock from the Hardware Clock. The time read
87 from the Hardware Clock is compensated to account for systematic
88 drift before using it to set the System Clock. See the discus‐
89 sion below, under The Adjust Function.
90 The System Clock must be kept in the UTC timescale for date-time
92 applications to work correctly in conjunction with the timezone
93 configured for the system. If the Hardware Clock is kept in
94 local time then the time read from it must be shifted to the UTC
95 timescale before using it to set the System Clock. The
96 --hctosys function does this based upon the information in the
97 /etc/adjtime file or the command line arguments --localtime and
98 --utc. Note: no daylight saving adjustment is made. See the
99 discussion below, under LOCAL vs UTC.
100 The kernel also keeps a timezone value, the --hctosys function
102 sets it to the timezone configured for the system. The system
103 timezone is configured by the TZ environment variable or the
104 /etc/localtime file, as tzset(3) would interpret them. The
105 obsolete tz_dsttime field of the kernel's timezone value is set
106 to zero. (For details on what this field used to mean, see
107 settimeofday(2).)
108 When used in a startup script, making the --hctosys function the
110 first caller of settimeofday(2) from boot, it will set the NTP
111 '11 minute mode' timescale via the persistent_clock_is_local
112 kernel variable. If the Hardware Clock's timescale configura‐
113 tion is changed then a reboot is required to inform the kernel.
114 See the discussion below, under Automatic Hardware Clock Syn‐
115 chronization by the Kernel.
116 This is a good function to use in one of the system startup
118 scripts before the file systems are mounted read/write.
119 This function should never be used on a running system. Jumping
121 system time will cause problems, such as corrupted filesystem
122 timestamps. Also, if something has changed the Hardware Clock,
123 like NTP's '11 minute mode', then --hctosys will set the time
124 incorrectly by including drift compensation.
125 Drift compensation can be inhibited by setting the drift factor
127 in /etc/adjtime to zero. This setting will be persistent as
128 long as the --update-drift option is not used with --systohc at
129 shutdown (or anywhere else). Another way to inhibit this is by
130 using the --noadjfile option when calling the --hctosys func‐
131 tion. A third method is to delete the /etc/adjtime file.
132 Hwclock will then default to using the UTC timescale for the
133 Hardware Clock. If the Hardware Clock is ticking local time it
134 will need to be defined in the file. This can be done by call‐
135 ing hwclock --localtime --adjust; when the file is not present
136 this command will not actually adjust the Clock, but it will
137 create the file with local time configured, and a drift factor
138 of zero.
139 A condition under which inhibiting hwclock's drift correction
141 may be desired is when dual-booting multiple operating systems.
142 If while this instance of Linux is stopped, another OS changes
143 the Hardware Clock's value, then when this instance is started
144 again the drift correction applied will be incorrect.
145 For hwclock's drift correction to work properly it is imperative
147 that nothing changes the Hardware Clock while its Linux instance
148 is not running.
149 --set Set the Hardware Clock to the time given by the --date option,
151 and update the timestamps in /etc/adjtime. With the
152 --update-drift option also (re)calculate the drift factor. Try
153 it without the option if --set fails. See --update-drift below.
154 --systz
156 This is an alternate to the --hctosys function that does not
157 read the Hardware Clock nor set the System Clock; consequently
158 there is not any drift correction. It is intended to be used in
159 a startup script on systems with kernels above version 2.6 where
160 you know the System Clock has been set from the Hardware Clock
161 by the kernel during boot.
162 It does the following things that are detailed above in the
164 --hctosys function:
165 · Corrects the System Clock timescale to UTC as needed. Only
167 instead of accomplishing this by setting the System Clock,
168 hwclock simply informs the kernel and it handles the change.
169 · Sets the kernel's NTP '11 minute mode' timescale.
171 · Sets the kernel's timezone.
173 The first two are only available on the first call of
175 settimeofday(2) after boot. Consequently this option only makes
176 sense when used in a startup script. If the Hardware Clocks
177 timescale configuration is changed then a reboot would be
178 required to inform the kernel.
179 -w, --systohc
181 Set the Hardware Clock from the System Clock, and update the
182 timestamps in /etc/adjtime. With the --update-drift option also
183 (re)calculate the drift factor. Try it without the option if
184 --systohc fails. See --update-drift below.
185 -V, --version
187 Display version information and exit.
188 -h, --help
190 Display help text and exit.
191
193 --adjfile=filename
194 Override the default /etc/adjtime file path.
195 --date=date_string
197 This option must be used with the --set or --predict functions,
198 otherwise it is ignored.
199 hwclock --set --date='16:45'
201 hwclock --predict --date='2525-08-14 07:11:05'
203 The argument must be in local time, even if you keep your Hard‐
205 ware Clock in UTC. See the --localtime option. Therefore, the
206 argument should not include any timezone information. It also
207 should not be a relative time like "+5 minutes", because
208 hwclock's precision depends upon correlation between the argu‐
209 ment's value and when the enter key is pressed. Fractional sec‐
210 onds are silently dropped. This option is capable of under‐
211 standing many time and date formats, but the previous parameters
212 should be observed.
213 --delay=seconds
215 This option can be used to overwrite the internally used delay
216 when setting the clock time. The default is 0.5 (500ms) for
217 rtc_cmos, for another RTC types the delay is 0. If RTC type is
218 impossible to determine (from sysfs) then it defaults also to
219 0.5 to be backwardly compatible.
220 The 500ms default is based on commonly used MC146818A-compatible
222 (x86) hardware clock. This Hardware Clock can only be set to any
223 integer time plus one half second. The integer time is required
224 because there is no interface to set or get a fractional second.
225 The additional half second delay is because the Hardware Clock
226 updates to the following second precisely 500 ms after setting
227 the new time. Unfortunately, this behavior is hardware specific
228 and in same cases another delay is required.
229 -D, --debug
231 Use --verbose. The --debug option has been deprecated and may
232 be repurposed or removed in a future release.
233 --directisa
235 This option is meaningful for ISA compatible machines in the x86
236 and x86_64 family. For other machines, it has no effect. This
237 option tells hwclock to use explicit I/O instructions to access
238 the Hardware Clock. Without this option, hwclock will use the
239 rtc device file, which it assumes to be driven by the Linux RTC
240 device driver. As of v2.26 it will no longer automatically use
241 directisa when the rtc driver is unavailable; this was causing
242 an unsafe condition that could allow two processes to access the
243 Hardware Clock at the same time. Direct hardware access from
244 userspace should only be used for testing, troubleshooting, and
245 as a last resort when all other methods fail. See the --rtc
246 option.
247 --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 -f, --rtc=filename
254 Override hwclock's default rtc device file name. Otherwise it
255 will use the first one found in this order:
256 /dev/rtc0
257 /dev/rtc
258 /dev/misc/rtc
259 For IA-64:
260 /dev/efirtc
261 /dev/misc/efirtc
262 -l, --localtime
264 -u, --utc
265 Indicate which timescale the Hardware Clock is set to.
266 The Hardware Clock may be configured to use either the UTC or
268 the local timescale, but nothing in the clock itself says which
269 alternative is being used. The --localtime or --utc options
270 give this information to the hwclock command. If you specify
271 the wrong one (or specify neither and take a wrong default),
272 both setting and reading the Hardware Clock will be incorrect.
273 If you specify neither --utc nor --localtime then the one last
275 given with a set function (--set, --systohc, or --adjust), as
276 recorded in /etc/adjtime, will be used. If the adjtime file
277 doesn't exist, the default is UTC.
278 Note: daylight saving time changes may be inconsistent when the
280 Hardware Clock is kept in local time. See the discussion below,
281 under LOCAL vs UTC.
282 --noadjfile
284 Disable the facilities provided by /etc/adjtime. hwclock will
285 not read nor write to that file with this option. Either --utc
286 or --localtime must be specified when using this option.
287 --test Do not actually change anything on the system, that is, the
289 Clocks or /etc/adjtime (--verbose is implicit with this option).
290 --update-drift
292 Update the Hardware Clock's drift factor in /etc/adjtime. It
293 can only be used with --set or --systohc,
294 A minimum four hour period between settings is required. This
296 is to avoid invalid calculations. The longer the period, the
297 more precise the resulting drift factor will be.
298 This option was added in v2.26, because it is typical for sys‐
300 tems to call hwclock --systohc at shutdown; with the old behav‐
301 iour this would automatically (re)calculate the drift factor
302 which caused several problems:
303 · When using NTP with an '11 minute mode' kernel the drift fac‐
305 tor would be clobbered to near zero.
306 · It would not allow the use of 'cold' drift correction. With
308 most configurations using 'cold' drift will yield favorable
309 results. Cold, means when the machine is turned off which can
310 have a significant impact on the drift factor.
311 · (Re)calculating drift factor on every shutdown delivers subop‐
313 timal results. For example, if ephemeral conditions cause the
314 machine to be abnormally hot the drift factor calculation
315 would be out of range.
316 · Significantly increased system shutdown times (as of v2.31
318 when not using --update-drift the RTC is not read).
319 Having hwclock calculate the drift factor is a good starting
321 point, but for optimal results it will likely need to be
322 adjusted by directly editing the /etc/adjtime file. For most
323 configurations once a machine's optimal drift factor is crafted
324 it should not need to be changed. Therefore, the old behavior
325 to automatically (re)calculate drift was changed and now
326 requires this option to be used. See the discussion below,
327 under The Adjust Function.
328 This option requires reading the Hardware Clock before setting
330 it. If it cannot be read, then this option will cause the set
331 functions to fail. This can happen, for example, if the Hard‐
332 ware Clock is corrupted by a power failure. In that case, the
333 clock must first be set without this option. Despite it not
334 working, the resulting drift correction factor would be invalid
335 anyway.
336 -v, --verbose
338 Display more details about what hwclock is doing internally.
339
341 Clocks in a Linux System
342 There are two types of date-time clocks:
343 The Hardware Clock: This clock is an independent hardware device, with
345 its own power domain (battery, capacitor, etc), that operates when the
346 machine is powered off, or even unplugged.
347 On an ISA compatible system, this clock is specified as part of the ISA
349 standard. A control program can read or set this clock only to a whole
350 second, but it can also detect the edges of the 1 second clock ticks,
351 so the clock actually has virtually infinite precision.
352 This clock is commonly called the hardware clock, the real time clock,
354 the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its
355 capitalized form, was coined for use by hwclock. The Linux kernel also
356 refers to it as the persistent clock.
357 Some non-ISA systems have a few real time clocks with only one of them
359 having its own power domain. A very low power external I2C or SPI
360 clock chip might be used with a backup battery as the hardware clock to
361 initialize a more functional integrated real-time clock which is used
362 for most other purposes.
363 The System Clock: This clock is part of the Linux kernel and is driven
365 by a timer interrupt. (On an ISA machine, the timer interrupt is part
366 of the ISA standard.) It has meaning only while Linux is running on
367 the machine. The System Time is the number of seconds since 00:00:00
368 January 1, 1970 UTC (or more succinctly, the number of seconds since
369 1969 UTC). The System Time is not an integer, though. It has virtu‐
370 ally infinite precision.
371 The System Time is the time that matters. The Hardware Clock's basic
373 purpose is to keep time when Linux is not running so that the System
374 Clock can be initialized from it at boot. Note that in DOS, for which
375 ISA was designed, the Hardware Clock is the only real time clock.
376 It is important that the System Time not have any discontinuities such
378 as would happen if you used the date(1) program to set it while the
379 system is running. You can, however, do whatever you want to the Hard‐
380 ware Clock while the system is running, and the next time Linux starts
381 up, it will do so with the adjusted time from the Hardware Clock.
382 Note: currently this is not possible on most systems because
383 hwclock --systohc is called at shutdown.
384 The Linux kernel's timezone is set by hwclock. But don't be misled --
386 almost nobody cares what timezone the kernel thinks it is in. Instead,
387 programs that care about the timezone (perhaps because they want to
388 display a local time for you) almost always use a more traditional
389 method of determining the timezone: They use the TZ environment vari‐
390 able or the /etc/localtime file, as explained in the man page for
391 tzset(3). However, some programs and fringe parts of the Linux kernel
392 such as filesystems use the kernel's timezone value. An example is the
393 vfat filesystem. If the kernel timezone value is wrong, the vfat
394 filesystem will report and set the wrong timestamps on files. Another
395 example is the kernel's NTP '11 minute mode'. If the kernel's timezone
396 value and/or the persistent_clock_is_local variable are wrong, then the
397 Hardware Clock will be set incorrectly by '11 minute mode'. See the
398 discussion below, under Automatic Hardware Clock Synchronization by the
399 Kernel.
400 hwclock sets the kernel's timezone to the value indicated by TZ or
402 /etc/localtime with the --hctosys or --systz functions.
403 The kernel's timezone value actually consists of two parts: 1) a field
405 tz_minuteswest indicating how many minutes local time (not adjusted for
406 DST) lags behind UTC, and 2) a field tz_dsttime indicating the type of
407 Daylight Savings Time (DST) convention that is in effect in the local‐
408 ity at the present time. This second field is not used under Linux and
409 is always zero. See also settimeofday(2).
410 Hardware Clock Access Methods
412 hwclock uses many different ways to get and set Hardware Clock values.
413 The most normal way is to do I/O to the rtc device special file, which
414 is presumed to be driven by the rtc device driver. Also, Linux systems
415 using the rtc framework with udev, are capable of supporting multiple
416 Hardware Clocks. This may bring about the need to override the default
417 rtc device by specifying one with the --rtc option.
418 However, this method is not always available as older systems do not
420 have an rtc driver. On these systems, the method of accessing the
421 Hardware Clock depends on the system hardware.
422 On an ISA compatible system, hwclock can directly access the "CMOS mem‐
424 ory" registers that constitute the clock, by doing I/O to Ports 0x70
425 and 0x71. It does this with actual I/O instructions and consequently
426 can only do it if running with superuser effective userid. This method
427 may be used by specifying the --directisa option.
428 This is a really poor method of accessing the clock, for all the rea‐
430 sons that userspace programs are generally not supposed to do direct
431 I/O and disable interrupts. hwclock provides it for testing, trou‐
432 bleshooting, and because it may be the only method available on ISA
433 systems which do not have a working rtc device driver.
434 The Adjust Function
436 The Hardware Clock is usually not very accurate. However, much of its
437 inaccuracy is completely predictable - it gains or loses the same
438 amount of time every day. This is called systematic drift. hwclock's
439 --adjust function lets you apply systematic drift corrections to the
440 Hardware Clock.
441 It works like this: hwclock keeps a file, /etc/adjtime, that keeps some
443 historical information. This is called the adjtime file.
444 Suppose you start with no adjtime file. You issue a hwclock --set com‐
446 mand to set the Hardware Clock to the true current time. hwclock cre‐
447 ates the adjtime file and records in it the current time as the last
448 time the clock was calibrated. Five days later, the clock has gained
449 10 seconds, so you issue a hwclock --set --update-drift command to set
450 it back 10 seconds. hwclock updates the adjtime file to show the cur‐
451 rent time as the last time the clock was calibrated, and records 2 sec‐
452 onds per day as the systematic drift rate. 24 hours go by, and then
453 you issue a hwclock --adjust command. hwclock consults the adjtime
454 file and sees that the clock gains 2 seconds per day when left alone
455 and that it has been left alone for exactly one day. So it subtracts 2
456 seconds from the Hardware Clock. It then records the current time as
457 the last time the clock was adjusted. Another 24 hours go by and you
458 issue another hwclock --adjust. hwclock does the same thing: subtracts
459 2 seconds and updates the adjtime file with the current time as the
460 last time the clock was adjusted.
461 When you use the --update-drift option with --set or --systohc, the
463 systematic drift rate is (re)calculated by comparing the fully drift
464 corrected current Hardware Clock time with the new set time, from that
465 it derives the 24 hour drift rate based on the last calibrated time‐
466 stamp from the adjtime file. This updated drift factor is then saved
467 in /etc/adjtime.
468 A small amount of error creeps in when the Hardware Clock is set, so
470 --adjust refrains from making any adjustment that is less than 1 sec‐
471 ond. Later on, when you request an adjustment again, the accumulated
472 drift will be more than 1 second and --adjust will make the adjustment
473 including any fractional amount.
474 hwclock --hctosys also uses the adjtime file data to compensate the
476 value read from the Hardware Clock before using it to set the System
477 Clock. It does not share the 1 second limitation of --adjust, and will
478 correct sub-second drift values immediately. It does not change the
479 Hardware Clock time nor the adjtime file. This may eliminate the need
480 to use --adjust, unless something else on the system needs the Hardware
481 Clock to be compensated.
482 The Adjtime File
484 While named for its historical purpose of controlling adjustments only,
485 it actually contains other information used by hwclock from one invoca‐
486 tion to the next.
487 The format of the adjtime file is, in ASCII:
489 Line 1: Three numbers, separated by blanks: 1) the systematic drift
491 rate in seconds per day, floating point decimal; 2) the resulting num‐
492 ber of seconds since 1969 UTC of most recent adjustment or calibration,
493 decimal integer; 3) zero (for compatibility with clock(8)) as a float‐
494 ing point decimal.
495 Line 2: One number: the resulting number of seconds since 1969 UTC of
497 most recent calibration. Zero if there has been no calibration yet or
498 it is known that any previous calibration is moot (for example, because
499 the Hardware Clock has been found, since that calibration, not to con‐
500 tain a valid time). This is a decimal integer.
501 Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to
503 Coordinated Universal Time or local time. You can always override this
504 value with options on the hwclock command line.
505 You can use an adjtime file that was previously used with the clock(8)
507 program with hwclock.
508 Automatic Hardware Clock Synchronization by the Kernel
510 You should be aware of another way that the Hardware Clock is kept syn‐
511 chronized in some systems. The Linux kernel has a mode wherein it
512 copies the System Time to the Hardware Clock every 11 minutes. This
513 mode is a compile time option, so not all kernels will have this capa‐
514 bility. This is a good mode to use when you are using something
515 sophisticated like NTP to keep your System Clock synchronized. (NTP is
516 a way to keep your System Time synchronized either to a time server
517 somewhere on the network or to a radio clock hooked up to your system.
518 See RFC 1305.)
519 If the kernel is compiled with the '11 minute mode' option it will be
521 active when the kernel's clock discipline is in a synchronized state.
522 When in this state, bit 6 (the bit that is set in the mask 0x0040) of
523 the kernel's time_status variable is unset. This value is output as the
524 'status' line of the adjtimex --print or ntptime commands.
525 It takes an outside influence, like the NTP daemon to put the kernel's
527 clock discipline into a synchronized state, and therefore turn on
528 '11 minute mode'. It can be turned off by running anything that sets
529 the System Clock the old fashioned way, including hwclock --hctosys.
530 However, if the NTP daemon is still running, it will turn
531 '11 minute mode' back on again the next time it synchronizes the System
532 Clock.
533 If your system runs with '11 minute mode' on, it may need to use either
535 --hctosys or --systz in a startup script, especially if the Hardware
536 Clock is configured to use the local timescale. Unless the kernel is
537 informed of what timescale the Hardware Clock is using, it may clobber
538 it with the wrong one. The kernel uses UTC by default.
539 The first userspace command to set the System Clock informs the kernel
541 what timescale the Hardware Clock is using. This happens via the
542 persistent_clock_is_local kernel variable. If --hctosys or --systz is
543 the first, it will set this variable according to the adjtime file or
544 the appropriate command-line argument. Note that when using this capa‐
545 bility and the Hardware Clock timescale configuration is changed, then
546 a reboot is required to notify the kernel.
547 hwclock --adjust should not be used with NTP '11 minute mode'.
549 ISA Hardware Clock Century value
551 There is some sort of standard that defines CMOS memory Byte 50 on an
552 ISA machine as an indicator of what century it is. hwclock does not
553 use or set that byte because there are some machines that don't define
554 the byte that way, and it really isn't necessary anyway, since the
555 year-of-century does a good job of implying which century it is.
556 If you have a bona fide use for a CMOS century byte, contact the
558 hwclock maintainer; an option may be appropriate.
559 Note that this section is only relevant when you are using the "direct
561 ISA" method of accessing the Hardware Clock. ACPI provides a standard
562 way to access century values, when they are supported by the hardware.
563
565 Keeping Time without External Synchronization
566 This discussion is based on the following conditions:
567 · Nothing is running that alters the date-time clocks, such as NTP dae‐
569 mon or a cron job."
570 · The system timezone is configured for the correct local time. See
572 below, under POSIX vs 'RIGHT'.
573 · Early during startup the following are called, in this order:
575 adjtimex --tick value --frequency value
576 hwclock --hctosys
577 · During shutdown the following is called:
579 hwclock --systohc
580 * Systems without adjtimex may use ntptime.
582 Whether maintaining precision time with NTP daemon or not, it makes
584 sense to configure the system to keep reasonably good date-time on its
585 own.
586 The first step in making that happen is having a clear understanding of
588 the big picture. There are two completely separate hardware devices
589 running at their own speed and drifting away from the 'correct' time at
590 their own rates. The methods and software for drift correction are
591 different for each of them. However, most systems are configured to
592 exchange values between these two clocks at startup and shutdown. Now
593 the individual device's time keeping errors are transferred back and
594 forth between each other. Attempt to configure drift correction for
595 only one of them, and the other's drift will be overlaid upon it.
596 This problem can be avoided when configuring drift correction for the
598 System Clock by simply not shutting down the machine. This, plus the
599 fact that all of hwclock's precision (including calculating drift fac‐
600 tors) depends upon the System Clock's rate being correct, means that
601 configuration of the System Clock should be done first.
602 The System Clock drift is corrected with the adjtimex(8) command's
604 --tick and --frequency options. These two work together: tick is the
605 coarse adjustment and frequency is the fine adjustment. (For systems
606 that do not have an adjtimex package, ntptime -f ppm may be used
607 instead.)
608 Some Linux distributions attempt to automatically calculate the System
610 Clock drift with adjtimex's compare operation. Trying to correct one
611 drifting clock by using another drifting clock as a reference is akin
612 to a dog trying to catch its own tail. Success may happen eventually,
613 but great effort and frustration will likely precede it. This automa‐
614 tion may yield an improvement over no configuration, but expecting
615 optimum results would be in error. A better choice for manual configu‐
616 ration would be adjtimex's --log options.
617 It may be more effective to simply track the System Clock drift with
619 sntp, or date -Ins and a precision timepiece, and then calculate the
620 correction manually.
621 After setting the tick and frequency values, continue to test and
623 refine the adjustments until the System Clock keeps good time. See
624 adjtimex(2) for more information and the example demonstrating manual
625 drift calculations.
626 Once the System Clock is ticking smoothly, move on to the Hardware
628 Clock.
629 As a rule, cold drift will work best for most use cases. This should
631 be true even for 24/7 machines whose normal downtime consists of a
632 reboot. In that case the drift factor value makes little difference.
633 But on the rare occasion that the machine is shut down for an extended
634 period, then cold drift should yield better results.
635 Steps to calculate cold drift:
637 1 Ensure that NTP daemon will not be launched at startup.
639 2 The System Clock time must be correct at shutdown!
641 3 Shut down the system.
643 4 Let an extended period pass without changing the Hardware Clock.
645 5 Start the system.
647 6 Immediately use hwclock to set the correct time, adding the
649 --update-drift option.
650 Note: if step 6 uses --systohc, then the System Clock must be set cor‐
652 rectly (step 6a) just before doing so.
653 Having hwclock calculate the drift factor is a good starting point, but
655 for optimal results it will likely need to be adjusted by directly
656 editing the /etc/adjtime file. Continue to test and refine the drift
657 factor until the Hardware Clock is corrected properly at startup. To
658 check this, first make sure that the System Time is correct before
659 shutdown and then use sntp, or date -Ins and a precision timepiece,
660 immediately after startup.
661 LOCAL vs UTC
663 Keeping the Hardware Clock in a local timescale causes inconsistent
664 daylight saving time results:
665 · If Linux is running during a daylight saving time change, the time
667 written to the Hardware Clock will be adjusted for the change.
668 · If Linux is NOT running during a daylight saving time change, the
670 time read from the Hardware Clock will NOT be adjusted for the
671 change.
672 The Hardware Clock on an ISA compatible system keeps only a date and
674 time, it has no concept of timezone nor daylight saving. Therefore,
675 when hwclock is told that it is in local time, it assumes it is in the
676 'correct' local time and makes no adjustments to the time read from it.
677 Linux handles daylight saving time changes transparently only when the
679 Hardware Clock is kept in the UTC timescale. Doing so is made easy for
680 system administrators as hwclock uses local time for its output and as
681 the argument to the --date option.
682 POSIX systems, like Linux, are designed to have the System Clock oper‐
684 ate in the UTC timescale. The Hardware Clock's purpose is to initialize
685 the System Clock, so also keeping it in UTC makes sense.
686 Linux does, however, attempt to accommodate the Hardware Clock being in
688 the local timescale. This is primarily for dual-booting with older ver‐
689 sions of MS Windows. From Windows 7 on, the RealTimeIsUniversal reg‐
690 istry key is supposed to be working properly so that its Hardware Clock
691 can be kept in UTC.
692 POSIX vs 'RIGHT'
694 A discussion on date-time configuration would be incomplete without
695 addressing timezones, this is mostly well covered by tzset(3). One
696 area that seems to have no documentation is the 'right' directory of
697 the Time Zone Database, sometimes called tz or zoneinfo.
698 There are two separate databases in the zoneinfo system, posix and
700 'right'. 'Right' (now named zoneinfo-leaps) includes leap seconds and
701 posix does not. To use the 'right' database the System Clock must be
702 set to (UTC + leap seconds), which is equivalent to (TAI - 10). This
703 allows calculating the exact number of seconds between two dates that
704 cross a leap second epoch. The System Clock is then converted to the
705 correct civil time, including UTC, by using the 'right' timezone files
706 which subtract the leap seconds. Note: this configuration is considered
707 experimental and is known to have issues.
708 To configure a system to use a particular database all of the files
710 located in its directory must be copied to the root of
711 /usr/share/zoneinfo. Files are never used directly from the posix or
712 'right' subdirectories, e.g., TZ='right/Europe/Dublin'. This habit was
713 becoming so common that the upstream zoneinfo project restructured the
714 system's file tree by moving the posix and 'right' subdirectories out
715 of the zoneinfo directory and into sibling directories:
716 /usr/share/zoneinfo
718 /usr/share/zoneinfo-posix
719 /usr/share/zoneinfo-leaps
720 Unfortunately, some Linux distributions are changing it back to the old
722 tree structure in their packages. So the problem of system administra‐
723 tors reaching into the 'right' subdirectory persists. This causes the
724 system timezone to be configured to include leap seconds while the
725 zoneinfo database is still configured to exclude them. Then when an
726 application such as a World Clock needs the South_Pole timezone file;
727 or an email MTA, or hwclock needs the UTC timezone file; they fetch it
728 from the root of /usr/share/zoneinfo , because that is what they are
729 supposed to do. Those files exclude leap seconds, but the System Clock
730 now includes them, causing an incorrect time conversion.
731 Attempting to mix and match files from these separate databases will
733 not work, because they each require the System Clock to use a different
734 timescale. The zoneinfo database must be configured to use either posix
735 or 'right', as described above, or by assigning a database path to the
736 TZDIR environment variable.
737
739 One of the following exit values will be returned:
740 EXIT_SUCCESS ('0' on POSIX systems)
742 Successful program execution.
743 EXIT_FAILURE ('1' on POSIX systems)
745 The operation failed or the command syntax was not valid.
746
748 TZ If this variable is set its value takes precedence over the sys‐
749 tem configured timezone.
750 TZDIR If this variable is set its value takes precedence over the sys‐
752 tem configured timezone database directory path.
753
755 /etc/adjtime
756 The configuration and state file for hwclock.
757 /etc/localtime
759 The system timezone file.
760 /usr/share/zoneinfo/
762 The system timezone database directory.
763 Device files hwclock may try for Hardware Clock access:
765 /dev/rtc0
766 /dev/rtc
767 /dev/misc/rtc
768 /dev/efirtc
769 /dev/misc/efirtc
770
772 date(1), adjtimex(8), gettimeofday(2), settimeofday(2), crontab(1p),
773 tzset(3)
774
776 Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
777 based on work done on the clock(8) program by Charles Hedrick, Rob
778 Hooft, and Harald Koenig. See the source code for complete history and
779 credits.
780
782 The hwclock command is part of the util-linux package and is available
783 from https://www.kernel.org/pub/linux/utils/util-linux/.
784util-linux July 2017 HWCLOCK(8)