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
30 systematic drift since the last time the clock was set or adjusted.
31 See the discussion below, under The Adjust Function.
32 --getepoch; --setepoch
34 These functions are for Alpha machines only, and are only available
35 through the Linux kernel RTC driver.
36 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 The --setepoch function requires using the --epoch option to
45 specify the year. For example:
46 hwclock --setepoch --epoch=1952
48 The RTC driver attempts to guess the correct epoch value, so
50 setting it may not be required.
51 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 --predict
57 Predict what the Hardware Clock will read in the future based upon
58 the time given by the --date option and the information in
59 /etc/adjtime. This is useful, for example, to account for drift
60 when setting a Hardware Clock wakeup (aka alarm). See rtcwake(8).
61 Do not use this function if the Hardware Clock is being modified by
63 anything other than the current operating system’s hwclock command,
64 such as '11 minute mode' or from dual-booting another OS.
65 -r, --show; --get
67 Read the Hardware Clock and print its time to standard output in
68 the ISO 8601 format. The time shown is always in local time, even
69 if you keep your Hardware Clock in UTC. See the --localtime option.
70 Showing the Hardware Clock time is the default when no function is
72 specified.
73 The --get function also applies drift correction to the time read,
75 based upon the information in /etc/adjtime. Do not use this
76 function if the Hardware Clock is being modified by anything other
77 than the current operating system’s hwclock command, such as '11
78 minute mode' or from dual-booting another OS.
79 -s, --hctosys
81 Set the System Clock from the Hardware Clock. The time read from
82 the Hardware Clock is compensated to account for systematic drift
83 before using it to set the System Clock. See the discussion below,
84 under The Adjust Function.
85 The System Clock must be kept in the UTC timescale for date-time
87 applications to work correctly in conjunction with the timezone
88 configured for the system. If the Hardware Clock is kept in local
89 time then the time read from it must be shifted to the UTC
90 timescale before using it to set the System Clock. The --hctosys
91 function does this based upon the information in the /etc/adjtime
92 file or the command line arguments --localtime and --utc. Note: no
93 daylight saving adjustment is made. See the discussion below, under
94 LOCAL vs UTC.
95 The kernel also keeps a timezone value, the --hctosys function sets
97 it to the timezone configured for the system. The system timezone
98 is configured by the TZ environment variable or the /etc/localtime
99 file, as tzset(3) would interpret them. The obsolete tz_dsttime
100 field of the kernel’s timezone value is set to zero. (For details
101 on what this field used to mean, see settimeofday(2).)
102 When used in a startup script, making the --hctosys function the
104 first caller of settimeofday(2) from boot, it will set the NTP '11
105 minute mode' timescale via the persistent_clock_is_local kernel
106 variable. If the Hardware Clock’s timescale configuration is
107 changed then a reboot is required to inform the kernel. See the
108 discussion below, under Automatic Hardware Clock Synchronization by
109 the Kernel.
110 This is a good function to use in one of the system startup scripts
112 before the file systems are mounted read/write.
113 This function should never be used on a running system. Jumping
115 system time will cause problems, such as corrupted filesystem
116 timestamps. Also, if something has changed the Hardware Clock, like
117 NTP’s '11 minute mode', then --hctosys will set the time
118 incorrectly by including drift compensation.
119 Drift compensation can be inhibited by setting the drift factor in
121 /etc/adjtime to zero. This setting will be persistent as long as
122 the --update-drift option is not used with --systohc at shutdown
123 (or anywhere else). Another way to inhibit this is by using the
124 --noadjfile option when calling the --hctosys function. A third
125 method is to delete the /etc/adjtime file. Hwclock will then
126 default to using the UTC timescale for the Hardware Clock. If the
127 Hardware Clock is ticking local time it will need to be defined in
128 the file. This can be done by calling hwclock --localtime --adjust;
129 when the file is not present this command will not actually adjust
130 the Clock, but it will create the file with local time configured,
131 and a drift factor of zero.
132 A condition under which inhibiting hwclock's drift correction may
134 be desired is when dual-booting multiple operating systems. If
135 while this instance of Linux is stopped, another OS changes the
136 Hardware Clock’s value, then when this instance is started again
137 the drift correction applied will be incorrect.
138 For hwclock's drift correction to work properly it is imperative
140 that nothing changes the Hardware Clock while its Linux instance is
141 not running.
142 --set
144 Set the Hardware Clock to the time given by the --date option, and
145 update the timestamps in /etc/adjtime. With the --update-drift
146 option also (re)calculate the drift factor. Try it without the
147 option if --set fails. See --update-drift below.
148 --systz
150 This is an alternate to the --hctosys function that does not read
151 the Hardware Clock nor set the System Clock; consequently there is
152 not any drift correction. It is intended to be used in a startup
153 script on systems with kernels above version 2.6 where you know the
154 System Clock has been set from the Hardware Clock by the kernel
155 during boot.
156 It does the following things that are detailed above in the
158 --hctosys function:
159 • Corrects the System Clock timescale to UTC as needed. Only
161 instead of accomplishing this by setting the System Clock,
162 hwclock simply informs the kernel and it handles the change.
163 • Sets the kernel’s NTP '11 minute mode' timescale.
165 • Sets the kernel’s timezone.
167 The first two are only available on the first call of settimeofday(2)
169 after boot. Consequently this option only makes sense when used in a
170 startup script. If the Hardware Clocks timescale configuration is
171 changed then a reboot would be required to inform the kernel.
172 -w, --systohc
174 Set the Hardware Clock from the System Clock, and update the
175 timestamps in /etc/adjtime. With the --update-drift option also
176 (re)calculate the drift factor. Try it without the option if
177 --systohc fails. See --update-drift below.
178 -V, --version
180 Display version information and exit.
181 -h, --help
183 Display help text and exit.
184
186 --adjfile=filename
187 Override the default /etc/adjtime file path.
188 --date=date_string
190 This option must be used with the --set or --predict functions,
191 otherwise it is ignored.
192 hwclock --set --date='16:45'
194 hwclock --predict --date='2525-08-14 07:11:05'
196 The argument must be in local time, even if you keep your Hardware
198 Clock in UTC. See the --localtime option. Therefore, the argument
199 should not include any timezone information. It also should not be
200 a relative time like "+5 minutes", because hwclock's precision
201 depends upon correlation between the argument’s value and when the
202 enter key is pressed. Fractional seconds are silently dropped. This
203 option is capable of understanding many time and date formats, but
204 the previous parameters should be observed.
205 --delay=seconds
207 This option can be used to overwrite the internally used delay when
208 setting the clock time. The default is 0.5 (500ms) for rtc_cmos,
209 for another RTC types the delay is 0. If RTC type is impossible to
210 determine (from sysfs) then it defaults also to 0.5 to be
211 backwardly compatible.
212 The 500ms default is based on commonly used MC146818A-compatible
214 (x86) hardware clock. This Hardware Clock can only be set to any
215 integer time plus one half second. The integer time is required
216 because there is no interface to set or get a fractional second.
217 The additional half second delay is because the Hardware Clock
218 updates to the following second precisely 500 ms after setting the
219 new time. Unfortunately, this behavior is hardware specific and in
220 same cases another delay is required.
221 -D, --debug
223 Use --verbose. The --debug option has been deprecated and may be
224 repurposed or removed in a future release.
225 --directisa
227 This option is meaningful for ISA compatible machines in the x86
228 and x86_64 family. For other machines, it has no effect. This
229 option tells hwclock to use explicit I/O instructions to access the
230 Hardware Clock. Without this option, hwclock will use the rtc
231 device file, which it assumes to be driven by the Linux RTC device
232 driver. As of v2.26 it will no longer automatically use directisa
233 when the rtc driver is unavailable; this was causing an unsafe
234 condition that could allow two processes to access the Hardware
235 Clock at the same time. Direct hardware access from userspace
236 should only be used for testing, troubleshooting, and as a last
237 resort when all other methods fail. See the --rtc option.
238 --epoch=year
240 This option is required when using the --setepoch function. The
241 minimum year value is 1900. The maximum is system dependent
242 (ULONG_MAX - 1).
243 -f, --rtc=filename
245 Override hwclock's default rtc device file name. Otherwise it will
246 use the first one found in this order: /dev/rtc0, /dev/rtc,
247 /dev/misc/rtc. For IA-64: /dev/efirtc /dev/misc/efirtc
248 -l, --localtime; -u, --utc
250 Indicate which timescale the Hardware Clock is set to.
251 The Hardware Clock may be configured to use either the UTC or the
253 local timescale, but nothing in the clock itself says which
254 alternative is being used. The --localtime or --utc options give
255 this information to the hwclock command. If you specify the wrong
256 one (or specify neither and take a wrong default), both setting and
257 reading the Hardware Clock will be incorrect.
258 If you specify neither --utc nor --localtime then the one last
260 given with a set function (--set, --systohc, or --adjust), as
261 recorded in /etc/adjtime, will be used. If the adjtime file doesn’t
262 exist, the default is UTC.
263 Note: daylight saving time changes may be inconsistent when the
265 Hardware Clock is kept in local time. See the discussion below,
266 under LOCAL vs UTC.
267 --noadjfile
269 Disable the facilities provided by /etc/adjtime. hwclock will not
270 read nor write to that file with this option. Either --utc or
271 --localtime must be specified when using this option.
272 --test
274 Do not actually change anything on the system, that is, the Clocks
275 or /etc/adjtime (--verbose is implicit with this option).
276 --update-drift
278 Update the Hardware Clock’s drift factor in /etc/adjtime. It can
279 only be used with --set or --systohc.
280 A minimum four hour period between settings is required. This is to
282 avoid invalid calculations. The longer the period, the more precise
283 the resulting drift factor will be.
284 This option was added in v2.26, because it is typical for systems
286 to call hwclock --systohc at shutdown; with the old behavior this
287 would automatically (re)calculate the drift factor which caused
288 several problems:
289 • When using NTP with an '11 minute mode' kernel the drift factor
291 would be clobbered to near zero.
292 • It would not allow the use of 'cold' drift correction. With
294 most configurations using 'cold' drift will yield favorable
295 results. Cold, means when the machine is turned off which can
296 have a significant impact on the drift factor.
297 • (Re)calculating drift factor on every shutdown delivers
299 suboptimal results. For example, if ephemeral conditions cause
300 the machine to be abnormally hot the drift factor calculation
301 would be out of range.
302 • Significantly increased system shutdown times (as of v2.31 when
304 not using --update-drift the RTC is not read).
305 Having hwclock calculate the drift factor is a good starting point, but
307 for optimal results it will likely need to be adjusted by directly
308 editing the /etc/adjtime file. For most configurations once a machine’s
309 optimal drift factor is crafted it should not need to be changed.
310 Therefore, the old behavior to automatically (re)calculate drift was
311 changed and now requires this option to be used. See the discussion
312 below, under The Adjust Function.
313 This option requires reading the Hardware Clock before setting it. If
315 it cannot be read, then this option will cause the set functions to
316 fail. This can happen, for example, if the Hardware Clock is corrupted
317 by a power failure. In that case, the clock must first be set without
318 this option. Despite it not working, the resulting drift correction
319 factor would be invalid 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 clock
344 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 the
351 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 virtually
354 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
364 Hardware Clock while the system is running, and the next time Linux
365 starts up, it will do so with the adjusted time from the Hardware
366 Clock. 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
374 variable 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
392 locality at the present time. This second field is not used under Linux
393 and 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
408 memory" 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
414 reasons that userspace programs are generally not supposed to do direct
415 I/O and disable interrupts. hwclock provides it for testing,
416 troubleshooting, 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
430 command to set the Hardware Clock to the true current time. hwclock
431 creates 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 10
433 seconds, so you issue a hwclock --set --update-drift command to set it
434 back 10 seconds. hwclock updates the adjtime file to show the current
435 time as the last time the clock was calibrated, and records 2 seconds
436 per day as the systematic drift rate. 24 hours go by, and then you
437 issue a hwclock --adjust command. hwclock consults the adjtime file and
438 sees that the clock gains 2 seconds per day when left alone and that it
439 has been left alone for exactly one day. So it subtracts 2 seconds from
440 the Hardware Clock. It then records the current time as the last time
441 the clock was adjusted. Another 24 hours go by and you issue another
442 hwclock --adjust. hwclock does the same thing: subtracts 2 seconds and
443 updates the adjtime file with the current time as the last time the
444 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
450 timestamp from the adjtime file. This updated drift factor is then
451 saved 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
455 second. 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
470 invocation 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
476 number of seconds since 1969 UTC of most recent adjustment or
477 calibration, decimal integer; 3) zero (for compatibility with clock(8))
478 as a floating point decimal.
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
484 contain 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
495 synchronized 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
498 capability. 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 to put the kernel’s
511 clock discipline into a synchronized state, and therefore turn on '11
512 minute mode'. It can be turned off by running anything that sets the
513 System Clock the old fashioned way, including hwclock --hctosys.
514 However, if the NTP daemon is still running, it will turn '11 minute
515 mode' back on again the next time it synchronizes the System Clock.
516 If your system runs with '11 minute mode' on, it may need to use either
518 --hctosys or --systz in a startup script, especially if the Hardware
519 Clock is configured to use the local timescale. Unless the kernel is
520 informed of what timescale the Hardware Clock is using, it may clobber
521 it with the wrong one. The kernel uses UTC by default.
522 The first userspace command to set the System Clock informs the kernel
524 what timescale the Hardware Clock is using. This happens via the
525 persistent_clock_is_local kernel variable. If --hctosys or --systz is
526 the first, it will set this variable according to the adjtime file or
527 the appropriate command-line argument. Note that when using this
528 capability and the Hardware Clock timescale configuration is changed,
529 then a reboot is required to notify the kernel.
530 hwclock --adjust should not be used with NTP '11 minute mode'.
532 ISA Hardware Clock Century value
534 There is some sort of standard that defines CMOS memory Byte 50 on an
535 ISA machine as an indicator of what century it is. hwclock does not use
536 or set that byte because there are some machines that don’t define the
537 byte that way, and it really isn’t necessary anyway, since the
538 year-of-century does a good job of implying which century it is.
539 If you have a bona fide use for a CMOS century byte, contact the
541 hwclock maintainer; an option may be appropriate.
542 Note that this section is only relevant when you are using the "direct
544 ISA" method of accessing the Hardware Clock. ACPI provides a standard
545 way to access century values, when they are supported by the hardware.
546
548 Keeping Time without External Synchronization
549 This discussion is based on the following conditions:
550 • Nothing is running that alters the date-time clocks, such as NTP
552 daemon or a cron job."
553 • The system timezone is configured for the correct local time. See
555 below, under POSIX vs 'RIGHT'.
556 • Early during startup the following are called, in this order:
558 adjtimex --tick value --frequency value hwclock --hctosys
559 • During shutdown the following is called: hwclock --systohc
561 • Systems without adjtimex may use ntptime.
563 Whether maintaining precision time with NTP daemon or not, it makes
565 sense to configure the system to keep reasonably good date-time on its
566 own.
567 The first step in making that happen is having a clear understanding of
569 the big picture. There are two completely separate hardware devices
570 running at their own speed and drifting away from the 'correct' time at
571 their own rates. The methods and software for drift correction are
572 different for each of them. However, most systems are configured to
573 exchange values between these two clocks at startup and shutdown. Now
574 the individual device’s time keeping errors are transferred back and
575 forth between each other. Attempt to configure drift correction for
576 only one of them, and the other’s drift will be overlaid upon it.
577 This problem can be avoided when configuring drift correction for the
579 System Clock by simply not shutting down the machine. This, plus the
580 fact that all of hwclock's precision (including calculating drift
581 factors) depends upon the System Clock’s rate being correct, means that
582 configuration of the System Clock should be done first.
583 The System Clock drift is corrected with the adjtimex(8) command’s
585 --tick and --frequency options. These two work together: tick is the
586 coarse adjustment and frequency is the fine adjustment. (For systems
587 that do not have an adjtimex package, ntptime -f ppm may be used
588 instead.)
589 Some Linux distributions attempt to automatically calculate the System
591 Clock drift with adjtimex's compare operation. Trying to correct one
592 drifting clock by using another drifting clock as a reference is akin
593 to a dog trying to catch its own tail. Success may happen eventually,
594 but great effort and frustration will likely precede it. This
595 automation may yield an improvement over no configuration, but
596 expecting optimum results would be in error. A better choice for manual
597 configuration would be adjtimex's --log options.
598 It may be more effective to simply track the System Clock drift with
600 sntp, or date -Ins and a precision timepiece, and then calculate the
601 correction manually.
602 After setting the tick and frequency values, continue to test and
604 refine the adjustments until the System Clock keeps good time. See
605 adjtimex(2) for more information and the example demonstrating manual
606 drift calculations.
607 Once the System Clock is ticking smoothly, move on to the Hardware
609 Clock.
610 As a rule, cold drift will work best for most use cases. This should be
612 true even for 24/7 machines whose normal downtime consists of a reboot.
613 In that case the drift factor value makes little difference. But on the
614 rare occasion that the machine is shut down for an extended period,
615 then cold drift should yield better results.
616 Steps to calculate cold drift:
618 1
620 Ensure that NTP daemon will not be launched at startup.
621 2
623 The System Clock time must be correct at shutdown!
624 3
626 Shut down the system.
627 4
629 Let an extended period pass without changing the Hardware Clock.
630 5
632 Start the system.
633 6
635 Immediately use hwclock to set the correct time, adding the
636 --update-drift option.
637 Note: if step 6 uses --systohc, then the System Clock must be set
639 correctly (step 6a) just before doing so.
640 Having hwclock calculate the drift factor is a good starting point, but
642 for optimal results it will likely need to be adjusted by directly
643 editing the /etc/adjtime file. Continue to test and refine the drift
644 factor until the Hardware Clock is corrected properly at startup. To
645 check this, first make sure that the System Time is correct before
646 shutdown and then use sntp, or date -Ins and a precision timepiece,
647 immediately after startup.
648 LOCAL vs UTC
650 Keeping the Hardware Clock in a local timescale causes inconsistent
651 daylight saving time results:
652 • If Linux is running during a daylight saving time change, the time
654 written to the Hardware Clock will be adjusted for the change.
655 • If Linux is NOT running during a daylight saving time change, the
657 time read from the Hardware Clock will NOT be adjusted for the
658 change.
659 The Hardware Clock on an ISA compatible system keeps only a date and
661 time, it has no concept of timezone nor daylight saving. Therefore,
662 when hwclock is told that it is in local time, it assumes it is in the
663 'correct' local time and makes no adjustments to the time read from it.
664 Linux handles daylight saving time changes transparently only when the
666 Hardware Clock is kept in the UTC timescale. Doing so is made easy for
667 system administrators as hwclock uses local time for its output and as
668 the argument to the --date option.
669 POSIX systems, like Linux, are designed to have the System Clock
671 operate in the UTC timescale. The Hardware Clock’s purpose is to
672 initialize the System Clock, so also keeping it in UTC makes sense.
673 Linux does, however, attempt to accommodate the Hardware Clock being in
675 the local timescale. This is primarily for dual-booting with older
676 versions of MS Windows. From Windows 7 on, the RealTimeIsUniversal
677 registry key is supposed to be working properly so that its Hardware
678 Clock can be kept in UTC.
679 POSIX vs 'RIGHT'
681 A discussion on date-time configuration would be incomplete without
682 addressing timezones, this is mostly well covered by tzset(3). One area
683 that seems to have no documentation is the 'right' directory of the
684 Time Zone Database, sometimes called tz or zoneinfo.
685 There are two separate databases in the zoneinfo system, posix and
687 'right'. 'Right' (now named zoneinfo-leaps) includes leap seconds and
688 posix does not. To use the 'right' database the System Clock must be
689 set to (UTC + leap seconds), which is equivalent to (TAI - 10). This
690 allows calculating the exact number of seconds between two dates that
691 cross a leap second epoch. The System Clock is then converted to the
692 correct civil time, including UTC, by using the 'right' timezone files
693 which subtract the leap seconds. Note: this configuration is considered
694 experimental and is known to have issues.
695 To configure a system to use a particular database all of the files
697 located in its directory must be copied to the root of
698 /usr/share/zoneinfo. Files are never used directly from the posix or
699 'right' subdirectories, e.g., TZ='right/Europe/Dublin'. This habit was
700 becoming so common that the upstream zoneinfo project restructured the
701 system’s file tree by moving the posix and 'right' subdirectories out
702 of the zoneinfo directory and into sibling directories:
703 /usr/share/zoneinfo, /usr/share/zoneinfo-posix,
705 /usr/share/zoneinfo-leaps
706 Unfortunately, some Linux distributions are changing it back to the old
708 tree structure in their packages. So the problem of system
709 administrators reaching into the 'right' subdirectory persists. This
710 causes the system timezone to be configured to include leap seconds
711 while the zoneinfo database is still configured to exclude them. Then
712 when an application such as a World Clock needs the South_Pole timezone
713 file; or an email MTA, or hwclock needs the UTC timezone file; they
714 fetch it from the root of /usr/share/zoneinfo , because that is what
715 they are supposed to do. Those files exclude leap seconds, but the
716 System Clock now includes them, causing an incorrect time conversion.
717 Attempting to mix and match files from these separate databases will
719 not work, because they each require the System Clock to use a different
720 timescale. The zoneinfo database must be configured to use either posix
721 or 'right', as described above, or by assigning a database path to the
722 TZDIR environment variable.
723
725 One of the following exit values will be returned:
726 EXIT_SUCCESS ('0' on POSIX systems)
728 Successful program execution.
729 EXIT_FAILURE ('1' on POSIX systems)
731 The operation failed or the command syntax was not valid.
732
734 TZ
735 If this variable is set its value takes precedence over the system
736 configured timezone.
737 TZDIR
739 If this variable is set its value takes precedence over the system
740 configured timezone database directory path.
741
743 /etc/adjtime
744 The configuration and state file for hwclock.
745 /etc/localtime
747 The system timezone file.
748 /usr/share/zoneinfo/
750 The system timezone database directory.
751 Device files hwclock may try for Hardware Clock access: /dev/rtc0
753 /dev/rtc /dev/misc/rtc /dev/efirtc /dev/misc/efirtc
754
756 date(1), adjtimex(8), gettimeofday(2), settimeofday(2), crontab(1p),
757 tzset(3)
758
760 Written by Bryan Henderson <bryanh@giraffe-data.com>, September 1996,
761 based on work done on the clock(8) program by Charles Hedrick, Rob
762 Hooft, and Harald Koenig. See the source code for complete history and
763 credits.
764
766 For bug reports, use the issue tracker at
767 https://github.com/karelzak/util-linux/issues.
768
770 The hwclock command is part of the util-linux package which can be
771 downloaded from Linux Kernel Archive
772 <https://www.kernel.org/pub/linux/utils/util-linux/>.
773util-linux 2.37.2 2021-06-02 HWCLOCK(8)