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 -D, --debug
215 Use --verbose. The --debug option has been deprecated and may
216 be repurposed or removed in a future release.
217 --directisa
219 This option is meaningful for ISA compatible machines in the x86
220 and x86_64 family. For other machines, it has no effect. This
221 option tells hwclock to use explicit I/O instructions to access
222 the Hardware Clock. Without this option, hwclock will use the
223 rtc device file, which it assumes to be driven by the Linux RTC
224 device driver. As of v2.26 it will no longer automatically use
225 directisa when the rtc driver is unavailable; this was causing
226 an unsafe condition that could allow two processes to access the
227 Hardware Clock at the same time. Direct hardware access from
228 userspace should only be used for testing, troubleshooting, and
229 as a last resort when all other methods fail. See the --rtc
230 option.
231 --epoch=year
233 This option is required when using the --setepoch function. The
234 minimum year value is 1900. The maximum is system dependent
235 (ULONG_MAX - 1).
236 -f, --rtc=filename
238 Override hwclock's default rtc device file name. Otherwise it
239 will use the first one found in this order:
240 /dev/rtc0
241 /dev/rtc
242 /dev/misc/rtc
243 For IA-64:
244 /dev/efirtc
245 /dev/misc/efirtc
246 -l, --localtime
248 -u, --utc
249 Indicate which timescale the Hardware Clock is set to.
250 The Hardware Clock may be configured to use either the UTC or
252 the local timescale, but nothing in the clock itself says which
253 alternative is being used. The --localtime or --utc options
254 give this information to the hwclock command. If you specify
255 the wrong one (or specify neither and take a wrong default),
256 both setting and reading the Hardware Clock will be incorrect.
257 If you specify neither --utc nor --localtime then the one last
259 given with a set function (--set, --systohc, or --adjust), as
260 recorded in /etc/adjtime, will be used. If the adjtime file
261 doesn't exist, the default is UTC.
262 Note: daylight saving time changes may be inconsistent when the
264 Hardware Clock is kept in local time. See the discussion below,
265 under LOCAL vs UTC.
266 --noadjfile
268 Disable the facilities provided by /etc/adjtime. hwclock will
269 not read nor write to that file with this option. Either --utc
270 or --localtime must be specified when using this option.
271 --test Do not actually change anything on the system, that is, the
273 Clocks or /etc/adjtime (--verbose is implicit with this option).
274 --update-drift
276 Update the Hardware Clock's drift factor in /etc/adjtime. It
277 can only be used with --set or --systohc,
278 A minimum four hour period between settings is required. This
280 is to avoid invalid calculations. The longer the period, the
281 more precise the resulting drift factor will be.
282 This option was added in v2.26, because it is typical for sys‐
284 tems to call hwclock --systohc at shutdown; with the old behav‐
285 iour this would automatically (re)calculate the drift factor
286 which caused several problems:
287 · When using ntpd with an '11 minute mode' kernel the drift fac‐
289 tor would be clobbered to near zero.
290 · It would not allow the use of 'cold' drift correction. With
292 most configurations using 'cold' drift will yield favorable
293 results. Cold, means when the machine is turned off which can
294 have a significant impact on the drift factor.
295 · (Re)calculating drift factor on every shutdown delivers subop‐
297 timal results. For example, if ephemeral conditions cause the
298 machine to be abnormally hot the drift factor calculation
299 would be out of range.
300 · Significantly increased system shutdown times (as of v2.31
302 when not using --update-drift the RTC is not read).
303 Having hwclock calculate the drift factor is a good starting
305 point, but for optimal results it will likely need to be
306 adjusted by directly editing the /etc/adjtime file. For most
307 configurations once a machine's optimal drift factor is crafted
308 it should not need to be changed. Therefore, the old behavior
309 to automatically (re)calculate drift was changed and now
310 requires this option to be used. See the discussion below,
311 under The Adjust Function.
312 This option requires reading the Hardware Clock before setting
314 it. If it cannot be read, then this option will cause the set
315 functions to fail. This can happen, for example, if the Hard‐
316 ware Clock is corrupted by a power failure. In that case, the
317 clock must first be set without this option. Despite it not
318 working, the resulting drift correction factor would be invalid
319 anyway.
320 -v, --verbose
322 Display more details about what hwclock is doing internally.
323
325 Clocks in a Linux System
326 There are two types of date-time clocks:
327 The Hardware Clock: This clock is an independent hardware device, with
329 its own power domain (battery, capacitor, etc), that operates when the
330 machine is powered off, or even unplugged.
331 On an ISA compatible system, this clock is specified as part of the ISA
333 standard. A control program can read or set this clock only to a whole
334 second, but it can also detect the edges of the 1 second clock ticks,
335 so the clock actually has virtually infinite precision.
336 This clock is commonly called the hardware clock, the real time clock,
338 the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its
339 capitalized form, was coined for use by hwclock. The Linux kernel also
340 refers to it as the persistent clock.
341 Some non-ISA systems have a few real time clocks with only one of them
343 having its own power domain. A very low power external I2C or SPI
344 clock chip might be used with a backup battery as the hardware clock to
345 initialize a more functional integrated real-time clock which is used
346 for most other purposes.
347 The System Clock: This clock is part of the Linux kernel and is driven
349 by a timer interrupt. (On an ISA machine, the timer interrupt is part
350 of the ISA standard.) It has meaning only while Linux is running on
351 the machine. The System Time is the number of seconds since 00:00:00
352 January 1, 1970 UTC (or more succinctly, the number of seconds since
353 1969 UTC). The System Time is not an integer, though. It has virtu‐
354 ally infinite precision.
355 The System Time is the time that matters. The Hardware Clock's basic
357 purpose is to keep time when Linux is not running so that the System
358 Clock can be initialized from it at boot. Note that in DOS, for which
359 ISA was designed, the Hardware Clock is the only real time clock.
360 It is important that the System Time not have any discontinuities such
362 as would happen if you used the date(1) program to set it while the
363 system is running. You can, however, do whatever you want to the Hard‐
364 ware Clock while the system is running, and the next time Linux starts
365 up, it will do so with the adjusted time from the Hardware Clock.
366 Note: currently this is not possible on most systems because
367 hwclock --systohc is called at shutdown.
368 The Linux kernel's timezone is set by hwclock. But don't be misled --
370 almost nobody cares what timezone the kernel thinks it is in. Instead,
371 programs that care about the timezone (perhaps because they want to
372 display a local time for you) almost always use a more traditional
373 method of determining the timezone: They use the TZ environment vari‐
374 able or the /etc/localtime file, as explained in the man page for
375 tzset(3). However, some programs and fringe parts of the Linux kernel
376 such as filesystems use the kernel's timezone value. An example is the
377 vfat filesystem. If the kernel timezone value is wrong, the vfat
378 filesystem will report and set the wrong timestamps on files. Another
379 example is the kernel's NTP '11 minute mode'. If the kernel's timezone
380 value and/or the persistent_clock_is_local variable are wrong, then the
381 Hardware Clock will be set incorrectly by '11 minute mode'. See the
382 discussion below, under Automatic Hardware Clock Synchronization by the
383 Kernel.
384 hwclock sets the kernel's timezone to the value indicated by TZ or
386 /etc/localtime with the --hctosys or --systz functions.
387 The kernel's timezone value actually consists of two parts: 1) a field
389 tz_minuteswest indicating how many minutes local time (not adjusted for
390 DST) lags behind UTC, and 2) a field tz_dsttime indicating the type of
391 Daylight Savings Time (DST) convention that is in effect in the local‐
392 ity at the present time. This second field is not used under Linux and
393 is always zero. See also settimeofday(2).
394 Hardware Clock Access Methods
396 hwclock uses many different ways to get and set Hardware Clock values.
397 The most normal way is to do I/O to the rtc device special file, which
398 is presumed to be driven by the rtc device driver. Also, Linux systems
399 using the rtc framework with udev, are capable of supporting multiple
400 Hardware Clocks. This may bring about the need to override the default
401 rtc device by specifying one with the --rtc option.
402 However, this method is not always available as older systems do not
404 have an rtc driver. On these systems, the method of accessing the
405 Hardware Clock depends on the system hardware.
406 On an ISA compatible system, hwclock can directly access the "CMOS mem‐
408 ory" registers that constitute the clock, by doing I/O to Ports 0x70
409 and 0x71. It does this with actual I/O instructions and consequently
410 can only do it if running with superuser effective userid. This method
411 may be used by specifying the --directisa option.
412 This is a really poor method of accessing the clock, for all the rea‐
414 sons that userspace programs are generally not supposed to do direct
415 I/O and disable interrupts. hwclock provides it for testing, trou‐
416 bleshooting, and because it may be the only method available on ISA
417 systems which do not have a working rtc device driver.
418 The Adjust Function
420 The Hardware Clock is usually not very accurate. However, much of its
421 inaccuracy is completely predictable - it gains or loses the same
422 amount of time every day. This is called systematic drift. hwclock's
423 --adjust function lets you apply systematic drift corrections to the
424 Hardware Clock.
425 It works like this: hwclock keeps a file, /etc/adjtime, that keeps some
427 historical information. This is called the adjtime file.
428 Suppose you start with no adjtime file. You issue a hwclock --set com‐
430 mand to set the Hardware Clock to the true current time. hwclock cre‐
431 ates the adjtime file and records in it the current time as the last
432 time the clock was calibrated. Five days later, the clock has gained
433 10 seconds, so you issue a hwclock --set --update-drift command to set
434 it back 10 seconds. hwclock updates the adjtime file to show the cur‐
435 rent time as the last time the clock was calibrated, and records 2 sec‐
436 onds per day as the systematic drift rate. 24 hours go by, and then
437 you issue a hwclock --adjust command. hwclock consults the adjtime
438 file and sees that the clock gains 2 seconds per day when left alone
439 and that it has been left alone for exactly one day. So it subtracts 2
440 seconds from the Hardware Clock. It then records the current time as
441 the last time the clock was adjusted. Another 24 hours go by and you
442 issue another hwclock --adjust. hwclock does the same thing: subtracts
443 2 seconds and updates the adjtime file with the current time as the
444 last time the clock was adjusted.
445 When you use the --update-drift option with --set or --systohc, the
447 systematic drift rate is (re)calculated by comparing the fully drift
448 corrected current Hardware Clock time with the new set time, from that
449 it derives the 24 hour drift rate based on the last calibrated time‐
450 stamp from the adjtime file. This updated drift factor is then saved
451 in /etc/adjtime.
452 A small amount of error creeps in when the Hardware Clock is set, so
454 --adjust refrains from making any adjustment that is less than 1 sec‐
455 ond. Later on, when you request an adjustment again, the accumulated
456 drift will be more than 1 second and --adjust will make the adjustment
457 including any fractional amount.
458 hwclock --hctosys also uses the adjtime file data to compensate the
460 value read from the Hardware Clock before using it to set the System
461 Clock. It does not share the 1 second limitation of --adjust, and will
462 correct sub-second drift values immediately. It does not change the
463 Hardware Clock time nor the adjtime file. This may eliminate the need
464 to use --adjust, unless something else on the system needs the Hardware
465 Clock to be compensated.
466 The Adjtime File
468 While named for its historical purpose of controlling adjustments only,
469 it actually contains other information used by hwclock from one invoca‐
470 tion to the next.
471 The format of the adjtime file is, in ASCII:
473 Line 1: Three numbers, separated by blanks: 1) the systematic drift
475 rate in seconds per day, floating point decimal; 2) the resulting num‐
476 ber of seconds since 1969 UTC of most recent adjustment or calibration,
477 decimal integer; 3) zero (for compatibility with clock(8)) as a decimal
478 integer.
479 Line 2: One number: the resulting number of seconds since 1969 UTC of
481 most recent calibration. Zero if there has been no calibration yet or
482 it is known that any previous calibration is moot (for example, because
483 the Hardware Clock has been found, since that calibration, not to con‐
484 tain a valid time). This is a decimal integer.
485 Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to
487 Coordinated Universal Time or local time. You can always override this
488 value with options on the hwclock command line.
489 You can use an adjtime file that was previously used with the clock(8)
491 program with hwclock.
492 Automatic Hardware Clock Synchronization by the Kernel
494 You should be aware of another way that the Hardware Clock is kept syn‐
495 chronized in some systems. The Linux kernel has a mode wherein it
496 copies the System Time to the Hardware Clock every 11 minutes. This
497 mode is a compile time option, so not all kernels will have this capa‐
498 bility. This is a good mode to use when you are using something
499 sophisticated like NTP to keep your System Clock synchronized. (NTP is
500 a way to keep your System Time synchronized either to a time server
501 somewhere on the network or to a radio clock hooked up to your system.
502 See RFC 1305.)
503 If the kernel is compiled with the '11 minute mode' option it will be
505 active when the kernel's clock discipline is in a synchronized state.
506 When in this state, bit 6 (the bit that is set in the mask 0x0040) of
507 the kernel's time_status variable is unset. This value is output as the
508 'status' line of the adjtimex --print or ntptime commands.
509 It takes an outside influence, like the NTP daemon ntpd(1), to put the
511 kernel's clock discipline into a synchronized state, and therefore turn
512 on '11 minute mode'. It can be turned off by running anything that
513 sets the System Clock the old fashioned way, including
514 hwclock --hctosys. However, if the NTP daemon is still running, it
515 will turn '11 minute mode' back on again the next time it synchronizes
516 the System Clock.
517 If your system runs with '11 minute mode' on, it may need to use either
519 --hctosys or --systz in a startup script, especially if the Hardware
520 Clock is configured to use the local timescale. Unless the kernel is
521 informed of what timescale the Hardware Clock is using, it may clobber
522 it with the wrong one. The kernel uses UTC by default.
523 The first userspace command to set the System Clock informs the kernel
525 what timescale the Hardware Clock is using. This happens via the
526 persistent_clock_is_local kernel variable. If --hctosys or --systz is
527 the first, it will set this variable according to the adjtime file or
528 the appropriate command-line argument. Note that when using this capa‐
529 bility and the Hardware Clock timescale configuration is changed, then
530 a reboot is required to notify the kernel.
531 hwclock --adjust should not be used with NTP '11 minute mode'.
533 ISA Hardware Clock Century value
535 There is some sort of standard that defines CMOS memory Byte 50 on an
536 ISA machine as an indicator of what century it is. hwclock does not
537 use or set that byte because there are some machines that don't define
538 the byte that way, and it really isn't necessary anyway, since the
539 year-of-century does a good job of implying which century it is.
540 If you have a bona fide use for a CMOS century byte, contact the
542 hwclock maintainer; an option may be appropriate.
543 Note that this section is only relevant when you are using the "direct
545 ISA" method of accessing the Hardware Clock. ACPI provides a standard
546 way to access century values, when they are supported by the hardware.
547
549 Keeping Time without External Synchronization
550 This discussion is based on the following conditions:
551 · Nothing is running that alters the date-time clocks, such as ntpd(1)
553 or a cron job.
554 · The system timezone is configured for the correct local time. See
556 below, under POSIX vs 'RIGHT'.
557 · Early during startup the following are called, in this order:
559 adjtimex --tick value --frequency value
560 hwclock --hctosys
561 · During shutdown the following is called:
563 hwclock --systohc
564 * Systems without adjtimex may use ntptime.
566 Whether maintaining precision time with ntpd(1) or not, it makes sense
568 to configure the system to keep reasonably good date-time on its own.
569 The first step in making that happen is having a clear understanding of
571 the big picture. There are two completely separate hardware devices
572 running at their own speed and drifting away from the 'correct' time at
573 their own rates. The methods and software for drift correction are
574 different for each of them. However, most systems are configured to
575 exchange values between these two clocks at startup and shutdown. Now
576 the individual device's time keeping errors are transferred back and
577 forth between each other. Attempt to configure drift correction for
578 only one of them, and the other's drift will be overlaid upon it.
579 This problem can be avoided when configuring drift correction for the
581 System Clock by simply not shutting down the machine. This, plus the
582 fact that all of hwclock's precision (including calculating drift fac‐
583 tors) depends upon the System Clock's rate being correct, means that
584 configuration of the System Clock should be done first.
585 The System Clock drift is corrected with the adjtimex(8) command's
587 --tick and --frequency options. These two work together: tick is the
588 coarse adjustment and frequency is the fine adjustment. (For systems
589 that do not have an adjtimex package, ntptime -f ppm may be used
590 instead.)
591 Some Linux distributions attempt to automatically calculate the System
593 Clock drift with adjtimex's compare operation. Trying to correct one
594 drifting clock by using another drifting clock as a reference is akin
595 to a dog trying to catch its own tail. Success may happen eventually,
596 but great effort and frustration will likely precede it. This automa‐
597 tion may yield an improvement over no configuration, but expecting
598 optimum results would be in error. A better choice for manual configu‐
599 ration would be adjtimex's --log options.
600 It may be more effective to simply track the System Clock drift with
602 sntp, or date -Ins and a precision timepiece, and then calculate the
603 correction manually.
604 After setting the tick and frequency values, continue to test and
606 refine the adjustments until the System Clock keeps good time. See
607 adjtimex(8) for more information and the example demonstrating manual
608 drift calculations.
609 Once the System Clock is ticking smoothly, move on to the Hardware
611 Clock.
612 As a rule, cold drift will work best for most use cases. This should
614 be true even for 24/7 machines whose normal downtime consists of a
615 reboot. In that case the drift factor value makes little difference.
616 But on the rare occasion that the machine is shut down for an extended
617 period, then cold drift should yield better results.
618 Steps to calculate cold drift:
620 1 Ensure that ntpd(1) will not be launched at startup.
622 2 The System Clock time must be correct at shutdown!
624 3 Shut down the system.
626 4 Let an extended period pass without changing the Hardware Clock.
628 5 Start the system.
630 6 Immediately use hwclock to set the correct time, adding the
632 --update-drift option.
633 Note: if step 6 uses --systohc, then the System Clock must be set cor‐
635 rectly (step 6a) just before doing so.
636 Having hwclock calculate the drift factor is a good starting point, but
638 for optimal results it will likely need to be adjusted by directly
639 editing the /etc/adjtime file. Continue to test and refine the drift
640 factor until the Hardware Clock is corrected properly at startup. To
641 check this, first make sure that the System Time is correct before
642 shutdown and then use sntp, or date -Ins and a precision timepiece,
643 immediately after startup.
644 LOCAL vs UTC
646 Keeping the Hardware Clock in a local timescale causes inconsistent
647 daylight saving time results:
648 · If Linux is running during a daylight saving time change, the time
650 written to the Hardware Clock will be adjusted for the change.
651 · If Linux is NOT running during a daylight saving time change, the
653 time read from the Hardware Clock will NOT be adjusted for the
654 change.
655 The Hardware Clock on an ISA compatible system keeps only a date and
657 time, it has no concept of timezone nor daylight saving. Therefore,
658 when hwclock is told that it is in local time, it assumes it is in the
659 'correct' local time and makes no adjustments to the time read from it.
660 Linux handles daylight saving time changes transparently only when the
662 Hardware Clock is kept in the UTC timescale. Doing so is made easy for
663 system administrators as hwclock uses local time for its output and as
664 the argument to the --date option.
665 POSIX systems, like Linux, are designed to have the System Clock oper‐
667 ate in the UTC timescale. The Hardware Clock's purpose is to initialize
668 the System Clock, so also keeping it in UTC makes sense.
669 Linux does, however, attempt to accommodate the Hardware Clock being in
671 the local timescale. This is primarily for dual-booting with older ver‐
672 sions of MS Windows. From Windows 7 on, the RealTimeIsUniversal reg‐
673 istry key is supposed to be working properly so that its Hardware Clock
674 can be kept in UTC.
675 POSIX vs 'RIGHT'
677 A discussion on date-time configuration would be incomplete without
678 addressing timezones, this is mostly well covered by tzset(3). One
679 area that seems to have no documentation is the 'right' directory of
680 the Time Zone Database, sometimes called tz or zoneinfo.
681 There are two separate databases in the zoneinfo system, posix and
683 'right'. 'Right' (now named zoneinfo-leaps) includes leap seconds and
684 posix does not. To use the 'right' database the System Clock must be
685 set to (UTC + leap seconds), which is equivalent to (TAI - 10). This
686 allows calculating the exact number of seconds between two dates that
687 cross a leap second epoch. The System Clock is then converted to the
688 correct civil time, including UTC, by using the 'right' timezone files
689 which subtract the leap seconds. Note: this configuration is considered
690 experimental and is known to have issues.
691 To configure a system to use a particular database all of the files
693 located in its directory must be copied to the root of
694 /usr/share/zoneinfo. Files are never used directly from the posix or
695 'right' subdirectories, e.g., TZ='right/Europe/Dublin'. This habit was
696 becoming so common that the upstream zoneinfo project restructured the
697 system's file tree by moving the posix and 'right' subdirectories out
698 of the zoneinfo directory and into sibling directories:
699 /usr/share/zoneinfo
701 /usr/share/zoneinfo-posix
702 /usr/share/zoneinfo-leaps
703 Unfortunately, some Linux distributions are changing it back to the old
705 tree structure in their packages. So the problem of system administra‐
706 tors reaching into the 'right' subdirectory persists. This causes the
707 system timezone to be configured to include leap seconds while the
708 zoneinfo database is still configured to exclude them. Then when an
709 application such as a World Clock needs the South_Pole timezone file;
710 or an email MTA, or hwclock needs the UTC timezone file; they fetch it
711 from the root of /usr/share/zoneinfo , because that is what they are
712 supposed to do. Those files exclude leap seconds, but the System Clock
713 now includes them, causing an incorrect time conversion.
714 Attempting to mix and match files from these separate databases will
716 not work, because they each require the System Clock to use a different
717 timescale. The zoneinfo database must be configured to use either posix
718 or 'right', as described above, or by assigning a database path to the
719 TZDIR environment variable.
720
722 One of the following exit values will be returned:
723 EXIT_SUCCESS ('0' on POSIX systems)
725 Successful program execution.
726 EXIT_FAILURE ('1' on POSIX systems)
728 The operation failed or the command syntax was not valid.
729
731 TZ If this variable is set its value takes precedence over the sys‐
732 tem configured timezone.
733 TZDIR If this variable is set its value takes precedence over the sys‐
735 tem configured timezone database directory path.
736
738 /etc/adjtime
739 The configuration and state file for hwclock.
740 /etc/localtime
742 The system timezone file.
743 /usr/share/zoneinfo/
745 The system timezone database directory.
746 Device files hwclock may try for Hardware Clock access:
748 /dev/rtc0
749 /dev/rtc
750 /dev/misc/rtc
751 /dev/efirtc
752 /dev/misc/efirtc
753
755 date(1), adjtimex(8), gettimeofday(2), settimeofday(2), crontab(1),
756 tzset(3)
757
759 Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
760 based on work done on the clock(8) program by Charles Hedrick, Rob
761 Hooft, and Harald Koenig. See the source code for complete history and
762 credits.
763
765 The hwclock command is part of the util-linux package and is available
766 from https://www.kernel.org/pub/linux/utils/util-linux/.
767util-linux July 2017 HWCLOCK(8)