]>
Commit | Line | Data |
---|---|---|
1 | .\" hwclock.8.in -- man page for util-linux' hwclock | |
2 | .\" | |
3 | .\" 2015-01-07 J William Piggott | |
4 | .\" Authored new section: DATE-TIME CONFIGURATION. | |
5 | .\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'. | |
6 | .\" | |
7 | .TH HWCLOCK 8 "July 2017" "util-linux" "System Administration" | |
8 | .SH NAME | |
9 | hwclock \- time clocks utility | |
10 | .SH SYNOPSIS | |
11 | .B hwclock | |
12 | .RI [ function ] | |
13 | .RI [ option ...] | |
14 | . | |
15 | .SH DESCRIPTION | |
16 | .B hwclock | |
17 | is an administration tool for the time clocks. It can: display the | |
18 | Hardware Clock time; set the Hardware Clock to a specified time; set the | |
19 | Hardware Clock from the System Clock; set the System Clock from the | |
20 | Hardware Clock; compensate for Hardware Clock drift; correct the System | |
21 | Clock timescale; set the kernel's timezone, NTP timescale, and epoch | |
22 | (Alpha only); and predict future | |
23 | Hardware Clock values based on its drift rate. | |
24 | .PP | |
25 | Since v2.26 important changes were made to the | |
26 | .B \-\-hctosys | |
27 | function and the | |
28 | .B \-\-directisa | |
29 | option, and a new option | |
30 | .B \-\-update\-drift | |
31 | was added. See their respective descriptions below. | |
32 | . | |
33 | .SH FUNCTIONS | |
34 | The following functions are mutually exclusive, only one can be given at | |
35 | a time. If none is given, the default is \fB\-\-show\fR. | |
36 | .TP | |
37 | .B \-a, \-\-adjust | |
38 | Add or subtract time from the Hardware Clock to account for systematic | |
39 | drift since the last time the clock was set or adjusted. See the | |
40 | discussion below, under | |
41 | .BR "The Adjust Function" . | |
42 | . | |
43 | .TP | |
44 | .B \-\-getepoch | |
45 | .TQ | |
46 | .B \-\-setepoch | |
47 | These functions are for Alpha machines only, and are only available | |
48 | through the Linux kernel RTC driver. | |
49 | .sp | |
50 | They are used to read and set the kernel's Hardware Clock epoch value. | |
51 | Epoch is the number of years into AD to which a zero year value in the | |
52 | Hardware Clock refers. For example, if the machine's BIOS sets the year | |
53 | counter in the Hardware Clock to contain the number of full years since | |
54 | 1952, then the kernel's Hardware Clock epoch value must be 1952. | |
55 | .sp | |
56 | The \fB\%\-\-setepoch\fR function requires using the | |
57 | .B \%\-\-epoch | |
58 | option to specify the year. For example: | |
59 | .RS | |
60 | .IP "" 4 | |
61 | .B hwclock\ \-\-setepoch\ \-\-epoch=1952 | |
62 | .PP | |
63 | The RTC driver attempts to guess the correct epoch value, so setting it | |
64 | may not be required. | |
65 | .PP | |
66 | This epoch value is used whenever | |
67 | .B \%hwclock | |
68 | reads or sets the Hardware Clock on an Alpha machine. For ISA machines | |
69 | the kernel uses the fixed Hardware Clock epoch of 1900. | |
70 | .RE | |
71 | . | |
72 | .TP | |
73 | .B \-\-predict | |
74 | Predict what the Hardware Clock will read in the future based upon the | |
75 | time given by the | |
76 | .B \-\-date | |
77 | option and the information in | |
78 | .IR @ADJTIME_PATH@ . | |
79 | This is useful, for example, to account for drift when setting a | |
80 | Hardware Clock wakeup (aka alarm). See | |
81 | .BR \%rtcwake (8). | |
82 | .sp | |
83 | Do not use this function if the Hardware Clock is being modified by | |
84 | anything other than the current operating system's | |
85 | .B \%hwclock | |
86 | command, such as \%'11\ minute\ mode' or from dual-booting another OS. | |
87 | . | |
88 | .TP | |
89 | .BR \-r , \ \-\-show | |
90 | .TQ | |
91 | .B \-\-get | |
92 | .br | |
93 | Read the Hardware Clock and print its time to standard output in the | |
94 | .B ISO 8601 | |
95 | format. | |
96 | The time shown is always in local time, even if you keep your Hardware Clock | |
97 | in UTC. See the | |
98 | .B \%\-\-localtime | |
99 | option. | |
100 | .sp | |
101 | Showing the Hardware Clock time is the default when no function is specified. | |
102 | .sp | |
103 | The | |
104 | .B \-\-get | |
105 | function also applies drift correction to the time read, based upon the | |
106 | information in | |
107 | .IR @ADJTIME_PATH@ . | |
108 | Do not use this function if the Hardware Clock is being modified by | |
109 | anything other than the current operating system's | |
110 | .B \%hwclock | |
111 | command, such as \%'11\ minute\ mode' or from dual-booting another OS. | |
112 | . | |
113 | .TP | |
114 | .BR \-s , \ \-\-hctosys | |
115 | Set the System Clock from the Hardware Clock. The time read from the Hardware | |
116 | Clock is compensated to account for systematic drift before using it to set the | |
117 | System Clock. See the discussion below, under | |
118 | .BR "The Adjust Function" . | |
119 | .sp | |
120 | The System Clock must be kept in the UTC timescale for date-time | |
121 | applications to work correctly in conjunction with the timezone configured | |
122 | for the system. If the Hardware Clock is kept in local time then the time read | |
123 | from it must be shifted to the UTC timescale before using it to set the System | |
124 | Clock. The | |
125 | .B \%\-\-hctosys | |
126 | function does this based upon the information in the | |
127 | .I @ADJTIME_PATH@ | |
128 | file or the command line arguments | |
129 | .BR \%\-\-localtime " and " \-\-utc . | |
130 | Note: no daylight saving adjustment is made. See the discussion below, under | |
131 | .BR "LOCAL vs UTC" . | |
132 | .sp | |
133 | The kernel also keeps a timezone value, the | |
134 | .B \%\-\-hctosys | |
135 | function sets it to the timezone configured for the system. The system | |
136 | timezone is configured by the TZ environment variable or the | |
137 | .I \%/etc/localtime | |
138 | file, as | |
139 | .BR \%tzset (3) | |
140 | would interpret them. | |
141 | The obsolete tz_dsttime field of the kernel's timezone value is set | |
142 | to zero. (For details on what this field used to mean, see | |
143 | .BR \%settimeofday (2).) | |
144 | .sp | |
145 | When used in a startup script, making the | |
146 | .B \%\-\-hctosys | |
147 | function the first caller of | |
148 | .BR \%settimeofday (2) | |
149 | from boot, it will set the NTP \%'11\ minute\ mode' timescale via the | |
150 | .I \%persistent_clock_is_local | |
151 | kernel variable. If the Hardware Clock's timescale configuration is | |
152 | changed then a reboot is required to inform the kernel. See the | |
153 | discussion below, under | |
154 | .BR "Automatic Hardware Clock Synchronization by the Kernel" . | |
155 | .sp | |
156 | This is a good function to use in one of the system startup scripts before the | |
157 | file systems are mounted read/write. | |
158 | .sp | |
159 | This function should never be used on a running system. Jumping system time | |
160 | will cause problems, such as corrupted filesystem timestamps. Also, if | |
161 | something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then | |
162 | .B \%\-\-hctosys | |
163 | will set the time incorrectly by including drift compensation. | |
164 | .sp | |
165 | Drift compensation can be inhibited by setting the drift factor in | |
166 | .I @ADJTIME_PATH@ | |
167 | to zero. This setting will be persistent as long as the | |
168 | .BR \%\-\-update\-drift " option is not used with " \%\-\-systohc | |
169 | at shutdown (or anywhere else). Another way to inhibit this is by using the | |
170 | .BR \%\-\-noadjfile " option when calling the " \%\-\-hctosys | |
171 | function. A third method is to delete the | |
172 | .IR @ADJTIME_PATH@ " file." | |
173 | .B Hwclock | |
174 | will then default to using the UTC timescale for the Hardware Clock. If | |
175 | the Hardware Clock is ticking local time it will need to be defined in | |
176 | the file. This can be done by calling | |
177 | .BR hwclock\ \-\-localtime\ \-\-adjust ; | |
178 | when the file is not present this command will not actually | |
179 | adjust the Clock, but it will create the file with local time | |
180 | configured, and a drift factor of zero. | |
181 | .sp | |
182 | A condition under which inhibiting | |
183 | .BR hwclock 's | |
184 | drift correction may be desired is when dual-booting multiple operating | |
185 | systems. If while this instance of Linux is stopped, another OS changes | |
186 | the Hardware Clock's value, then when this instance is started again the | |
187 | drift correction applied will be incorrect. | |
188 | .sp | |
189 | .RB "For " hwclock 's | |
190 | drift correction to work properly it is imperative that nothing changes | |
191 | the Hardware Clock while its Linux instance is not running. | |
192 | . | |
193 | .TP | |
194 | .B \-\-set | |
195 | Set the Hardware Clock to the time given by the | |
196 | .B \-\-date | |
197 | option, and update the timestamps in | |
198 | .IR @ADJTIME_PATH@ . | |
199 | With the | |
200 | .B \%\-\-update-drift | |
201 | option also (re)calculate the drift factor. Try it without the option if | |
202 | .BR \%\-\-set " fails. See " \%\-\-update-drift " below." | |
203 | . | |
204 | .TP | |
205 | .B \-\-systz | |
206 | This is an alternate to the | |
207 | .B \%\-\-hctosys | |
208 | function that does not read the Hardware Clock nor set the System Clock; | |
209 | consequently there is not any drift correction. It is intended to be | |
210 | used in a startup script on systems with kernels above version 2.6 where | |
211 | you know the System Clock has been set from the Hardware Clock by the | |
212 | kernel during boot. | |
213 | .sp | |
214 | It does the following things that are detailed above in the | |
215 | .BR \%\-\-hctosys " function:" | |
216 | .RS | |
217 | .IP \(bu 2 | |
218 | Corrects the System Clock timescale to UTC as needed. Only instead of | |
219 | accomplishing this by setting the System Clock, | |
220 | .B hwclock | |
221 | simply informs the kernel and it handles the change. | |
222 | .IP \(bu 2 | |
223 | Sets the kernel's NTP \%'11\ minute\ mode' timescale. | |
224 | .IP \(bu 2 | |
225 | Sets the kernel's timezone. | |
226 | .PP | |
227 | The first two are only available on the first call of | |
228 | .BR \%settimeofday (2) | |
229 | after boot. Consequently this option only makes sense when used in a | |
230 | startup script. If the Hardware Clocks timescale configuration is | |
231 | changed then a reboot would be required to inform the kernel. | |
232 | .RE | |
233 | . | |
234 | .TP | |
235 | .BR \-w , \ \-\-systohc | |
236 | Set the Hardware Clock from the System Clock, and update the timestamps in | |
237 | .IR @ADJTIME_PATH@ . | |
238 | With the | |
239 | .B \%\-\-update-drift | |
240 | option also (re)calculate the drift factor. Try it without the option if | |
241 | .BR \%\-\-systohc " fails. See " \%\-\-update-drift " below." | |
242 | . | |
243 | .TP | |
244 | .BR \-V , \ \-\-version | |
245 | Display version information and exit. | |
246 | . | |
247 | .TP | |
248 | .BR \-h , \ \-\-help | |
249 | Display help text and exit. | |
250 | . | |
251 | .SH OPTIONS | |
252 | . | |
253 | .TP | |
254 | .BI \-\-adjfile= filename | |
255 | .RI "Override the default " @ADJTIME_PATH@ " file path." | |
256 | . | |
257 | .TP | |
258 | .BI \%\-\-date= date_string | |
259 | This option must be used with the | |
260 | .B \-\-set | |
261 | or | |
262 | .B \%\-\-predict | |
263 | functions, otherwise it is ignored. | |
264 | .RS | |
265 | .IP "" 4 | |
266 | .B "hwclock\ \-\-set\ \-\-date='16:45'" | |
267 | .IP "" 4 | |
268 | .B "hwclock\ \-\-predict\ \-\-date='2525-08-14\ 07:11:05'" | |
269 | .PP | |
270 | The argument must be in local time, even if you keep your Hardware Clock in | |
271 | UTC. See the | |
272 | .B \%\-\-localtime | |
273 | option. Therefore, the argument should not include any timezone information. | |
274 | It also should not be a relative time like "+5 minutes", because | |
275 | .BR \%hwclock 's | |
276 | precision depends upon correlation between the argument's value and when the | |
277 | enter key is pressed. Fractional seconds are silently dropped. This option is | |
278 | capable of understanding many time and date formats, but the previous | |
279 | parameters should be observed. | |
280 | .RE | |
281 | . | |
282 | .TP | |
283 | .BI \%\-\-delay= seconds | |
284 | This option allows to overwrite internally used delay when set clock time. The | |
285 | default is 0.5 (500ms) for rtc_cmos, for another RTC types the delay is 0. If | |
286 | RTC type is impossible to determine (from sysfs) then it defaults also to 0.5 | |
287 | to be backwardly compatible. | |
288 | .RS | |
289 | .PP | |
290 | The 500ms default is based on commonly used MC146818A-compatible (x86) hardware clock. This | |
291 | Hardware Clock can only be set to any integer time plus one half second. The | |
292 | integer time is required because there is no interface to set or get a | |
293 | fractional second. The additional half second delay is because the Hardware | |
294 | Clock updates to the following second precisely 500 ms after setting the new | |
295 | time. Unfortunately, this behavior is hardware specific and in same cases | |
296 | another delay is required. | |
297 | .RE | |
298 | . | |
299 | .TP | |
300 | .TP | |
301 | .BR \-D ", " \-\-debug | |
302 | .RB Use\ \-\-verbose . | |
303 | .RB The\ \%\-\-debug\ option | |
304 | has been deprecated and may be repurposed or removed in a future release. | |
305 | . | |
306 | .TP | |
307 | .B \-\-directisa | |
308 | This option is meaningful for ISA compatible machines in the x86 and | |
309 | x86_64 family. For other machines, it has no effect. This option tells | |
310 | .B \%hwclock | |
311 | to use explicit I/O instructions to access the Hardware Clock. | |
312 | Without this option, | |
313 | .B \%hwclock | |
314 | will use the rtc device file, which it assumes to be driven by the Linux | |
315 | RTC device driver. As of v2.26 it will no longer automatically use | |
316 | directisa when the rtc driver is unavailable; this was causing an unsafe | |
317 | condition that could allow two processes to access the Hardware Clock at | |
318 | the same time. Direct hardware access from userspace should only be | |
319 | used for testing, troubleshooting, and as a last resort when all other | |
320 | methods fail. See the | |
321 | .BR \-\-rtc " option." | |
322 | . | |
323 | .TP | |
324 | .BI \-\-epoch= year | |
325 | This option is required when using the | |
326 | .BR \%\-\-setepoch \ function. | |
327 | .RI "The minimum " year | |
328 | value is 1900. The maximum is system dependent | |
329 | .RB ( ULONG_MAX\ -\ 1 ). | |
330 | . | |
331 | .TP | |
332 | .BR \-f , \ \-\-rtc=\fIfilename\fR | |
333 | .RB "Override " \%hwclock 's | |
334 | default rtc device file name. Otherwise it will | |
335 | use the first one found in this order: | |
336 | .in +4 | |
337 | .br | |
338 | .I /dev/rtc0 | |
339 | .br | |
340 | .I /dev/rtc | |
341 | .br | |
342 | .I /dev/misc/rtc | |
343 | .br | |
344 | .in | |
345 | .RB "For " IA-64: | |
346 | .in +4 | |
347 | .br | |
348 | .I /dev/efirtc | |
349 | .br | |
350 | .I /dev/misc/efirtc | |
351 | .in | |
352 | . | |
353 | .TP | |
354 | .BR \-l , \ \-\-localtime | |
355 | .TQ | |
356 | .BR \-u ", " \-\-utc | |
357 | Indicate which timescale the Hardware Clock is set to. | |
358 | .sp | |
359 | The Hardware Clock may be configured to use either the UTC or the local | |
360 | timescale, but nothing in the clock itself says which alternative is | |
361 | being used. The | |
362 | .BR \%\-\-localtime " or " \-\-utc | |
363 | options give this information to the | |
364 | .B \%hwclock | |
365 | command. If you specify the wrong one (or specify neither and take a | |
366 | wrong default), both setting and reading the Hardware Clock will be | |
367 | incorrect. | |
368 | .sp | |
369 | If you specify neither | |
370 | .BR \-\-utc " nor " \%\-\-localtime | |
371 | then the one last given with a set function | |
372 | .RB ( \-\-set ", " \%\-\-systohc ", or " \%\-\-adjust ), | |
373 | as recorded in | |
374 | .IR @ADJTIME_PATH@ , | |
375 | will be used. If the adjtime file doesn't exist, the default is UTC. | |
376 | .sp | |
377 | Note: daylight saving time changes may be inconsistent when the | |
378 | Hardware Clock is kept in local time. See the discussion below, under | |
379 | .BR "LOCAL vs UTC" . | |
380 | . | |
381 | .TP | |
382 | .B \-\-noadjfile | |
383 | Disable the facilities provided by | |
384 | .IR @ADJTIME_PATH@ . | |
385 | .B \%hwclock | |
386 | will not read nor write to that file with this option. Either | |
387 | .BR \-\-utc " or " \%\-\-localtime | |
388 | must be specified when using this option. | |
389 | . | |
390 | .TP | |
391 | .B \-\-test | |
392 | Do not actually change anything on the system, that is, the Clocks or | |
393 | .I @ADJTIME_PATH@ | |
394 | .RB ( \%\-\-verbose | |
395 | is implicit with this option). | |
396 | . | |
397 | .TP | |
398 | .B \-\-update\-drift | |
399 | Update the Hardware Clock's drift factor in | |
400 | .IR @ADJTIME_PATH@ . | |
401 | It can only be used with | |
402 | .BR \-\-set " or " \%\-\-systohc , | |
403 | .sp | |
404 | A minimum four hour period between settings is required. This is to | |
405 | avoid invalid calculations. The longer the period, the more precise the | |
406 | resulting drift factor will be. | |
407 | .sp | |
408 | This option was added in v2.26, because | |
409 | it is typical for systems to call | |
410 | .B \%hwclock\ \-\-systohc | |
411 | at shutdown; with the old behaviour this would automatically | |
412 | (re)calculate the drift factor which caused several problems: | |
413 | .RS | |
414 | .IP \(bu 2 | |
415 | When using NTP with an \%'11\ minute\ mode' kernel the drift factor | |
416 | would be clobbered to near zero. | |
417 | .IP \(bu 2 | |
418 | It would not allow the use of 'cold' drift correction. With most | |
419 | configurations using 'cold' drift will yield favorable results. Cold, | |
420 | means when the machine is turned off which can have a significant impact | |
421 | on the drift factor. | |
422 | .IP \(bu 2 | |
423 | (Re)calculating drift factor on every shutdown delivers suboptimal | |
424 | results. For example, if ephemeral conditions cause the machine to be | |
425 | abnormally hot the drift factor calculation would be out of range. | |
426 | .IP \(bu 2 | |
427 | Significantly increased system shutdown times (as of v2.31 when not | |
428 | using | |
429 | .B \%\-\-update\-drift | |
430 | the RTC is not read). | |
431 | .PP | |
432 | .RB "Having " \%hwclock | |
433 | calculate the drift factor is a good starting point, but for optimal | |
434 | results it will likely need to be adjusted by directly editing the | |
435 | .I @ADJTIME_PATH@ | |
436 | file. For most configurations once a machine's optimal drift factor is | |
437 | crafted it should not need to be changed. Therefore, the old behavior to | |
438 | automatically (re)calculate drift was changed and now requires this | |
439 | option to be used. See the discussion below, under | |
440 | .BR "The Adjust Function" . | |
441 | .PP | |
442 | This option requires reading the Hardware Clock before setting it. If | |
443 | it cannot be read, then this option will cause the set functions to fail. | |
444 | This can happen, for example, if the Hardware Clock is corrupted by a | |
445 | power failure. In that case, the clock must first be set without this | |
446 | option. Despite it not working, the resulting drift correction factor | |
447 | would be invalid anyway. | |
448 | .RE | |
449 | . | |
450 | .TP | |
451 | .BR \-v ", " \-\-verbose | |
452 | Display more details about what | |
453 | .B \%hwclock | |
454 | is doing internally. | |
455 | . | |
456 | .SH NOTES | |
457 | . | |
458 | .SS Clocks in a Linux System | |
459 | .PP | |
460 | There are two types of date-time clocks: | |
461 | .PP | |
462 | .B The Hardware Clock: | |
463 | This clock is an independent hardware device, with its own power domain | |
464 | (battery, capacitor, etc), that operates when the machine is powered off, | |
465 | or even unplugged. | |
466 | .PP | |
467 | On an ISA compatible system, this clock is specified as part of the ISA | |
468 | standard. A control program can read or set this clock only to a whole | |
469 | second, but it can also detect the edges of the 1 second clock ticks, so | |
470 | the clock actually has virtually infinite precision. | |
471 | .PP | |
472 | This clock is commonly called the hardware clock, the real time clock, | |
473 | the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its | |
474 | capitalized form, was coined for use by | |
475 | .BR \%hwclock . | |
476 | The Linux kernel also refers to it as the persistent clock. | |
477 | .PP | |
478 | Some non-ISA systems have a few real time clocks with | |
479 | only one of them having its own power domain. | |
480 | A very low power external I2C or SPI clock chip might be used with a | |
481 | backup battery as the hardware clock to initialize a more functional | |
482 | integrated real-time clock which is used for most other purposes. | |
483 | .PP | |
484 | .B The System Clock: | |
485 | This clock is part of the Linux kernel and is driven by | |
486 | a timer interrupt. (On an ISA machine, the timer interrupt is part of | |
487 | the ISA standard.) It has meaning only while Linux is running on the | |
488 | machine. The System Time is the number of seconds since 00:00:00 | |
489 | January 1, 1970 UTC (or more succinctly, the number of seconds since | |
490 | 1969 UTC). The System Time is not an integer, though. It has virtually | |
491 | infinite precision. | |
492 | .PP | |
493 | The System Time is the time that matters. The Hardware Clock's basic | |
494 | purpose is to keep time when Linux is not running so that the System | |
495 | Clock can be initialized from it at boot. Note that in DOS, for which | |
496 | ISA was designed, the Hardware Clock is the only real time clock. | |
497 | .PP | |
498 | It is important that the System Time not have any discontinuities such as | |
499 | would happen if you used the | |
500 | .BR \%date (1) | |
501 | program to set it while the system is running. You can, however, do whatever | |
502 | you want to the Hardware Clock while the system is running, and the next | |
503 | time Linux starts up, it will do so with the adjusted time from the Hardware | |
504 | Clock. Note: currently this is not possible on most systems because | |
505 | .B \%hwclock\ \-\-systohc | |
506 | is called at shutdown. | |
507 | .PP | |
508 | The Linux kernel's timezone is set by | |
509 | .BR hwclock . | |
510 | But don't be misled -- almost nobody cares what timezone the kernel | |
511 | thinks it is in. Instead, programs that care about the timezone | |
512 | (perhaps because they want to display a local time for you) almost | |
513 | always use a more traditional method of determining the timezone: They | |
514 | use the TZ environment variable or the | |
515 | .I \%/etc/localtime | |
516 | file, as explained in the man page for | |
517 | .BR \%tzset (3). | |
518 | However, some programs and fringe parts of the Linux kernel such as filesystems | |
519 | use the kernel's timezone value. An example is the vfat filesystem. If the | |
520 | kernel timezone value is wrong, the vfat filesystem will report and set the | |
521 | wrong timestamps on files. Another example is the kernel's NTP \%'11\ minute\ mode'. | |
522 | If the kernel's timezone value and/or the | |
523 | .I \%persistent_clock_is_local | |
524 | variable are wrong, then the Hardware Clock will be set incorrectly | |
525 | by \%'11\ minute\ mode'. See the discussion below, under | |
526 | .BR "Automatic Hardware Clock Synchronization by the Kernel" . | |
527 | .PP | |
528 | .B \%hwclock | |
529 | sets the kernel's timezone to the value indicated by TZ or | |
530 | .IR \%/etc/localtime " with the" | |
531 | .BR \%\-\-hctosys " or " \%\-\-systz " functions." | |
532 | .PP | |
533 | The kernel's timezone value actually consists of two parts: 1) a field | |
534 | tz_minuteswest indicating how many minutes local time (not adjusted | |
535 | for DST) lags behind UTC, and 2) a field tz_dsttime indicating | |
536 | the type of Daylight Savings Time (DST) convention that is in effect | |
537 | in the locality at the present time. | |
538 | This second field is not used under Linux and is always zero. | |
539 | See also | |
540 | .BR \%settimeofday (2). | |
541 | . | |
542 | .SS Hardware Clock Access Methods | |
543 | .PP | |
544 | .B \%hwclock | |
545 | uses many different ways to get and set Hardware Clock values. The most | |
546 | normal way is to do I/O to the rtc device special file, which is | |
547 | presumed to be driven by the rtc device driver. Also, Linux systems | |
548 | using the rtc framework with udev, are capable of supporting multiple | |
549 | Hardware Clocks. This may bring about the need to override the default | |
550 | rtc device by specifying one with the | |
551 | .BR \-\-rtc " option." | |
552 | .PP | |
553 | However, this method is not always available as older systems do not | |
554 | have an rtc driver. On these systems, the method of accessing the | |
555 | Hardware Clock depends on the system hardware. | |
556 | .PP | |
557 | On an ISA compatible system, | |
558 | .B \%hwclock | |
559 | can directly access the "CMOS memory" registers that | |
560 | constitute the clock, by doing I/O to Ports 0x70 and 0x71. It does | |
561 | this with actual I/O instructions and consequently can only do it if | |
562 | running with superuser effective userid. This method may be used by | |
563 | specifying the | |
564 | .BR \%\-\-directisa " option." | |
565 | .PP | |
566 | This is a really poor method of accessing the clock, for all the | |
567 | reasons that userspace programs are generally not supposed to do | |
568 | direct I/O and disable interrupts. | |
569 | .B \%hwclock | |
570 | provides it for testing, troubleshooting, and because it may be the | |
571 | only method available on ISA systems which do not have a working rtc | |
572 | device driver. | |
573 | .SS The Adjust Function | |
574 | .PP | |
575 | The Hardware Clock is usually not very accurate. However, much of its | |
576 | inaccuracy is completely predictable - it gains or loses the same amount | |
577 | of time every day. This is called systematic drift. | |
578 | .BR \%hwclock "'s " \%\-\-adjust | |
579 | function lets you apply systematic drift corrections to the | |
580 | Hardware Clock. | |
581 | .PP | |
582 | It works like this: | |
583 | .BR \%hwclock " keeps a file," | |
584 | .IR @ADJTIME_PATH@ , | |
585 | that keeps some historical information. This is called the adjtime file. | |
586 | .PP | |
587 | Suppose you start with no adjtime file. You issue a | |
588 | .B \%hwclock\ \-\-set | |
589 | command to set the Hardware Clock to the true current time. | |
590 | .B \%hwclock | |
591 | creates the adjtime file and records in it the current time as the | |
592 | last time the clock was calibrated. | |
593 | Five days later, the clock has gained 10 seconds, so you issue a | |
594 | .B \%hwclock\ \-\-set\ \-\-update\-drift | |
595 | command to set it back 10 seconds. | |
596 | .B \%hwclock | |
597 | updates the adjtime file to show the current time as the last time the | |
598 | clock was calibrated, and records 2 seconds per day as the systematic | |
599 | drift rate. 24 hours go by, and then you issue a | |
600 | .B \%hwclock\ \-\-adjust | |
601 | command. | |
602 | .B \%hwclock | |
603 | consults the adjtime file and sees that the clock gains 2 seconds per | |
604 | day when left alone and that it has been left alone for exactly one | |
605 | day. So it subtracts 2 seconds from the Hardware Clock. It then | |
606 | records the current time as the last time the clock was adjusted. | |
607 | Another 24 hours go by and you issue another | |
608 | .BR \%hwclock\ \-\-adjust . | |
609 | .B \%hwclock | |
610 | does the same thing: subtracts 2 seconds and updates the adjtime file | |
611 | with the current time as the last time the clock was adjusted. | |
612 | .PP | |
613 | When you use the | |
614 | .BR \%\-\-update\-drift " option with " \-\-set " or " \%\-\-systohc , | |
615 | the systematic drift rate is (re)calculated by comparing the fully drift | |
616 | corrected current Hardware Clock time with the new set time, from that | |
617 | it derives the 24 hour drift rate based on the last calibrated timestamp | |
618 | from the adjtime file. This updated drift factor is then saved in | |
619 | .IR @ADJTIME_PATH@ . | |
620 | .PP | |
621 | A small amount of error creeps in when | |
622 | the Hardware Clock is set, so | |
623 | .B \%\-\-adjust | |
624 | refrains from making any adjustment that is less | |
625 | than 1 second. Later on, when you request an adjustment again, the accumulated | |
626 | drift will be more than 1 second and | |
627 | .B \%\-\-adjust | |
628 | will make the adjustment including any fractional amount. | |
629 | .PP | |
630 | .B \%hwclock\ \-\-hctosys | |
631 | also uses the adjtime file data to compensate the value read from the Hardware | |
632 | Clock before using it to set the System Clock. It does not share the 1 second | |
633 | limitation of | |
634 | .BR \%\-\-adjust , | |
635 | and will correct sub-second drift values immediately. It does not | |
636 | change the Hardware Clock time nor the adjtime file. This may eliminate | |
637 | the need to use | |
638 | .BR \%\-\-adjust , | |
639 | unless something else on the system needs the Hardware Clock to be | |
640 | compensated. | |
641 | . | |
642 | .SS The Adjtime File | |
643 | While named for its historical purpose of controlling adjustments only, | |
644 | it actually contains other information used by | |
645 | .B hwclock | |
646 | from one invocation to the next. | |
647 | .PP | |
648 | The format of the adjtime file is, in ASCII: | |
649 | .PP | |
650 | Line 1: Three numbers, separated by blanks: 1) the systematic drift rate | |
651 | in seconds per day, floating point decimal; 2) the resulting number of | |
652 | seconds since 1969 UTC of most recent adjustment or calibration, | |
653 | decimal integer; 3) zero (for compatibility with | |
654 | .BR \%clock (8)) | |
655 | as a decimal integer. | |
656 | .PP | |
657 | Line 2: One number: the resulting number of seconds since 1969 UTC of most | |
658 | recent calibration. Zero if there has been no calibration yet or it | |
659 | is known that any previous calibration is moot (for example, because | |
660 | the Hardware Clock has been found, since that calibration, not to | |
661 | contain a valid time). This is a decimal integer. | |
662 | .PP | |
663 | Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to | |
664 | Coordinated Universal Time or local time. You can always override this | |
665 | value with options on the | |
666 | .B \%hwclock | |
667 | command line. | |
668 | .PP | |
669 | You can use an adjtime file that was previously used with the | |
670 | .BR \%clock "(8) program with " \%hwclock . | |
671 | . | |
672 | .SS Automatic Hardware Clock Synchronization by the Kernel | |
673 | .PP | |
674 | You should be aware of another way that the Hardware Clock is kept | |
675 | synchronized in some systems. The Linux kernel has a mode wherein it | |
676 | copies the System Time to the Hardware Clock every 11 minutes. This mode | |
677 | is a compile time option, so not all kernels will have this capability. | |
678 | This is a good mode to use when you are using something sophisticated | |
679 | like NTP to keep your System Clock synchronized. (NTP is a way to keep | |
680 | your System Time synchronized either to a time server somewhere on the | |
681 | network or to a radio clock hooked up to your system. See RFC 1305.) | |
682 | .PP | |
683 | If the kernel is compiled with the \%'11\ minute\ mode' option it will | |
684 | be active when the kernel's clock discipline is in a synchronized state. | |
685 | When in this state, bit 6 (the bit that is set in the mask 0x0040) | |
686 | of the kernel's | |
687 | .I \%time_status | |
688 | variable is unset. This value is output as the 'status' line of the | |
689 | .BR \%adjtimex\ --print " or " \%ntptime " commands." | |
690 | .PP | |
691 | It takes an outside influence, like the NTP daemon | |
692 | to put the kernel's clock discipline into a synchronized state, and | |
693 | therefore turn on \%'11\ minute\ mode'. | |
694 | It can be turned off by running anything that sets the System Clock the old | |
695 | fashioned way, including | |
696 | .BR "\%hwclock\ \-\-hctosys" . | |
697 | However, if the NTP daemon is still running, it will turn \%'11\ minute\ mode' | |
698 | back on again the next time it synchronizes the System Clock. | |
699 | .PP | |
700 | If your system runs with \%'11\ minute\ mode' on, it may need to use either | |
701 | .BR \%\-\-hctosys " or " \%\-\-systz | |
702 | in a startup script, especially if the Hardware Clock is configured to use | |
703 | the local timescale. Unless the kernel is informed of what timescale the | |
704 | Hardware Clock is using, it may clobber it with the wrong one. The kernel | |
705 | uses UTC by default. | |
706 | .PP | |
707 | The first userspace command to set the System Clock informs the | |
708 | kernel what timescale the Hardware Clock is using. This happens via the | |
709 | .I \%persistent_clock_is_local | |
710 | kernel variable. If | |
711 | .BR \%\-\-hctosys " or " \%\-\-systz | |
712 | is the first, it will set this variable according to the adjtime file or the | |
713 | appropriate command-line argument. Note that when using this capability and the | |
714 | Hardware Clock timescale configuration is changed, then a reboot is required to | |
715 | notify the kernel. | |
716 | .PP | |
717 | .B \%hwclock\ \-\-adjust | |
718 | should not be used with NTP \%'11\ minute\ mode'. | |
719 | . | |
720 | .SS ISA Hardware Clock Century value | |
721 | .PP | |
722 | There is some sort of standard that defines CMOS memory Byte 50 on an ISA | |
723 | machine as an indicator of what century it is. | |
724 | .B \%hwclock | |
725 | does not use or set that byte because there are some machines that | |
726 | don't define the byte that way, and it really isn't necessary anyway, | |
727 | since the year-of-century does a good job of implying which century it | |
728 | is. | |
729 | .PP | |
730 | If you have a bona fide use for a CMOS century byte, contact the | |
731 | .B \%hwclock | |
732 | maintainer; an option may be appropriate. | |
733 | .PP | |
734 | Note that this section is only relevant when you are using the "direct | |
735 | ISA" method of accessing the Hardware Clock. | |
736 | ACPI provides a standard way to access century values, when they | |
737 | are supported by the hardware. | |
738 | . | |
739 | .SH DATE-TIME CONFIGURATION | |
740 | .in +4 | |
741 | .SS Keeping Time without External Synchronization | |
742 | .in | |
743 | .PP | |
744 | This discussion is based on the following conditions: | |
745 | .IP \(bu 2 | |
746 | Nothing is running that alters the date-time clocks, such as NTP daemon or a cron job." | |
747 | .IP \(bu 2 | |
748 | The system timezone is configured for the correct local time. See below, under | |
749 | .BR "POSIX vs 'RIGHT'" . | |
750 | .IP \(bu 2 | |
751 | Early during startup the following are called, in this order: | |
752 | .br | |
753 | .BI \%adjtimex\ \-\-tick \ value\ \-\-frequency \ value | |
754 | .br | |
755 | .B \%hwclock\ \-\-hctosys | |
756 | .IP \(bu 2 | |
757 | During shutdown the following is called: | |
758 | .br | |
759 | .B \%hwclock\ \-\-systohc | |
760 | .PP | |
761 | .in +4 | |
762 | .BR * " Systems without " adjtimex " may use " ntptime . | |
763 | .in | |
764 | .PP | |
765 | Whether maintaining precision time with NTP daemon | |
766 | or not, it makes sense to configure the system to keep reasonably good | |
767 | date-time on its own. | |
768 | .PP | |
769 | The first step in making that happen is having a clear understanding of | |
770 | the big picture. There are two completely separate hardware devices | |
771 | running at their own speed and drifting away from the 'correct' time at | |
772 | their own rates. The methods and software for drift correction are | |
773 | different for each of them. However, most systems are configured to | |
774 | exchange values between these two clocks at startup and shutdown. Now | |
775 | the individual device's time keeping errors are transferred back and | |
776 | forth between each other. Attempt to configure drift correction for only | |
777 | one of them, and the other's drift will be overlaid upon it. | |
778 | .PP | |
779 | This problem can be avoided when configuring drift correction for the | |
780 | System Clock by simply not shutting down the machine. This, plus the | |
781 | fact that all of | |
782 | .BR \%hwclock 's | |
783 | precision (including calculating drift factors) depends upon the System | |
784 | Clock's rate being correct, means that configuration of the System Clock | |
785 | should be done first. | |
786 | .PP | |
787 | The System Clock drift is corrected with the | |
788 | .BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency | |
789 | options. These two work together: tick is the coarse adjustment and | |
790 | frequency is the fine adjustment. (For systems that do not have an | |
791 | .BR \%adjtimex " package," | |
792 | .BI \%ntptime\ \-f\ ppm | |
793 | may be used instead.) | |
794 | .PP | |
795 | Some Linux distributions attempt to automatically calculate the System | |
796 | Clock drift with | |
797 | .BR \%adjtimex 's | |
798 | compare operation. Trying to correct one | |
799 | drifting clock by using another drifting clock as a reference is akin to | |
800 | a dog trying to catch its own tail. Success may happen eventually, but | |
801 | great effort and frustration will likely precede it. This automation may | |
802 | yield an improvement over no configuration, but expecting optimum | |
803 | results would be in error. A better choice for manual configuration | |
804 | would be | |
805 | .BR \%adjtimex 's " \-\-log " options. | |
806 | .PP | |
807 | It may be more effective to simply track the System Clock drift with | |
808 | .BR \%sntp ", or " \%date\ \-Ins | |
809 | and a precision timepiece, and then calculate the correction manually. | |
810 | .PP | |
811 | After setting the tick and frequency values, continue to test and refine the | |
812 | adjustments until the System Clock keeps good time. See | |
813 | .BR \%adjtimex (8) | |
814 | for more information and the example demonstrating manual drift | |
815 | calculations. | |
816 | .PP | |
817 | Once the System Clock is ticking smoothly, move on to the Hardware Clock. | |
818 | .PP | |
819 | As a rule, cold drift will work best for most use cases. This should be | |
820 | true even for 24/7 machines whose normal downtime consists of a reboot. | |
821 | In that case the drift factor value makes little difference. But on the | |
822 | rare occasion that the machine is shut down for an extended period, then | |
823 | cold drift should yield better results. | |
824 | .PP | |
825 | .B Steps to calculate cold drift: | |
826 | .IP 1 2 | |
827 | .B "Ensure that NTP daemon will not be launched at startup." | |
828 | .IP 2 2 | |
829 | .RI The " System Clock " "time must be correct at shutdown!" | |
830 | .IP 3 2 | |
831 | Shut down the system. | |
832 | .IP 4 2 | |
833 | Let an extended period pass without changing the Hardware Clock. | |
834 | .IP 5 2 | |
835 | Start the system. | |
836 | .IP 6 2 | |
837 | .RB "Immediately use " hwclock " to set the correct time, adding the" | |
838 | .BR \%\-\-update\-drift " option." | |
839 | .PP | |
840 | Note: if step 6 uses | |
841 | .BR \%\-\-systohc , | |
842 | then the System Clock must be set correctly (step 6a) just before doing so. | |
843 | .PP | |
844 | .RB "Having " hwclock | |
845 | calculate the drift factor is a good starting point, but for optimal | |
846 | results it will likely need to be adjusted by directly editing the | |
847 | .I @ADJTIME_PATH@ | |
848 | file. Continue to test and refine the drift factor until the Hardware | |
849 | Clock is corrected properly at startup. To check this, first make sure | |
850 | that the System Time is correct before shutdown and then use | |
851 | .BR \%sntp ", or " \%date\ \-Ins | |
852 | and a precision timepiece, immediately after startup. | |
853 | .SS LOCAL vs UTC | |
854 | Keeping the Hardware Clock in a local timescale causes inconsistent | |
855 | daylight saving time results: | |
856 | .IP \(bu 2 | |
857 | If Linux is running during a daylight saving time change, the time | |
858 | written to the Hardware Clock will be adjusted for the change. | |
859 | .IP \(bu 2 | |
860 | If Linux is NOT running during a daylight saving time change, the time | |
861 | read from the Hardware Clock will NOT be adjusted for the change. | |
862 | .PP | |
863 | The Hardware Clock on an ISA compatible system keeps only a date and time, | |
864 | it has no concept of timezone nor daylight saving. Therefore, when | |
865 | .B hwclock | |
866 | is told that it is in local time, it assumes it is in the 'correct' | |
867 | local time and makes no adjustments to the time read from it. | |
868 | .PP | |
869 | Linux handles daylight saving time changes transparently only when the | |
870 | Hardware Clock is kept in the UTC timescale. Doing so is made easy for | |
871 | system administrators as | |
872 | .B \%hwclock | |
873 | uses local time for its output and as the argument to the | |
874 | .BR \%\-\-date " option." | |
875 | .PP | |
876 | POSIX systems, like Linux, are designed to have the System Clock operate | |
877 | in the UTC timescale. The Hardware Clock's purpose is to initialize the | |
878 | System Clock, so also keeping it in UTC makes sense. | |
879 | .PP | |
880 | Linux does, however, attempt to accommodate the Hardware Clock being in | |
881 | the local timescale. This is primarily for dual-booting with older | |
882 | versions of MS Windows. From Windows 7 on, the RealTimeIsUniversal | |
883 | registry key is supposed to be working properly so that its Hardware | |
884 | Clock can be kept in UTC. | |
885 | . | |
886 | .SS POSIX vs 'RIGHT' | |
887 | A discussion on date-time configuration would be incomplete without | |
888 | addressing timezones, this is mostly well covered by | |
889 | .BR tzset (3). | |
890 | One area that seems to have no documentation is the 'right' | |
891 | directory of the Time Zone Database, sometimes called tz or zoneinfo. | |
892 | .PP | |
893 | There are two separate databases in the zoneinfo system, posix | |
894 | and 'right'. 'Right' (now named zoneinfo\-leaps) includes leap seconds and posix | |
895 | does not. To use the 'right' database the System Clock must be set to | |
896 | \%(UTC\ +\ leap seconds), which is equivalent to \%(TAI\ \-\ 10). This | |
897 | allows calculating the | |
898 | exact number of seconds between two dates that cross a leap second | |
899 | epoch. The System Clock is then converted to the correct civil time, | |
900 | including UTC, by using the 'right' timezone files which subtract the | |
901 | leap seconds. Note: this configuration is considered experimental and is | |
902 | known to have issues. | |
903 | .PP | |
904 | To configure a system to use a particular database all of the files | |
905 | located in its directory must be copied to the root of | |
906 | .IR \%/usr/share/zoneinfo . | |
907 | Files are never used directly from the posix or 'right' subdirectories, e.g., | |
908 | .RI \%TZ=' right/Europe/Dublin '. | |
909 | This habit was becoming so common that the upstream zoneinfo project | |
910 | restructured the system's file tree by moving the posix and 'right' | |
911 | subdirectories out of the zoneinfo directory and into sibling directories: | |
912 | .PP | |
913 | .in +2 | |
914 | .I /usr/share/zoneinfo | |
915 | .br | |
916 | .I /usr/share/zoneinfo\-posix | |
917 | .br | |
918 | .I /usr/share/zoneinfo\-leaps | |
919 | .PP | |
920 | Unfortunately, some Linux distributions are changing it back to the old | |
921 | tree structure in their packages. So the problem of system | |
922 | administrators reaching into the 'right' subdirectory persists. This | |
923 | causes the system timezone to be configured to include leap seconds | |
924 | while the zoneinfo database is still configured to exclude them. Then | |
925 | when an application such as a World Clock needs the South_Pole timezone | |
926 | file; or an email MTA, or | |
927 | .B hwclock | |
928 | needs the UTC timezone file; they fetch it from the root of | |
929 | .I \%/usr/share/zoneinfo | |
930 | , because that is what they are supposed to do. Those files exclude leap | |
931 | seconds, but the System Clock now includes them, causing an incorrect | |
932 | time conversion. | |
933 | .PP | |
934 | Attempting to mix and match files from these separate databases will not | |
935 | work, because they each require the System Clock to use a different | |
936 | timescale. The zoneinfo database must be configured to use either posix | |
937 | or 'right', as described above, or by assigning a database path to the | |
938 | .SB TZDIR | |
939 | environment variable. | |
940 | .SH EXIT STATUS | |
941 | One of the following exit values will be returned: | |
942 | .TP | |
943 | .BR EXIT_SUCCESS " ('0' on POSIX systems)" | |
944 | Successful program execution. | |
945 | .TP | |
946 | .BR EXIT_FAILURE " ('1' on POSIX systems)" | |
947 | The operation failed or the command syntax was not valid. | |
948 | .SH ENVIRONMENT | |
949 | .TP | |
950 | .B TZ | |
951 | If this variable is set its value takes precedence over the system | |
952 | configured timezone. | |
953 | .TP | |
954 | .B TZDIR | |
955 | If this variable is set its value takes precedence over the system | |
956 | configured timezone database directory path. | |
957 | .SH FILES | |
958 | .TP | |
959 | .I @ADJTIME_PATH@ | |
960 | The configuration and state file for hwclock. | |
961 | .TP | |
962 | .I /etc/localtime | |
963 | The system timezone file. | |
964 | .TP | |
965 | .I /usr/share/zoneinfo/ | |
966 | The system timezone database directory. | |
967 | .PP | |
968 | Device files | |
969 | .B hwclock | |
970 | may try for Hardware Clock access: | |
971 | .br | |
972 | .I /dev/rtc0 | |
973 | .br | |
974 | .I /dev/rtc | |
975 | .br | |
976 | .I /dev/misc/rtc | |
977 | .br | |
978 | .I /dev/efirtc | |
979 | .br | |
980 | .I /dev/misc/efirtc | |
981 | .SH "SEE ALSO" | |
982 | .BR date (1), | |
983 | .BR adjtimex (8), | |
984 | .BR gettimeofday (2), | |
985 | .BR settimeofday (2), | |
986 | .BR crontab (1), | |
987 | .BR tzset (3) | |
988 | . | |
989 | .SH AUTHORS | |
990 | Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com), | |
991 | based on work done on the | |
992 | .BR \%clock (8) | |
993 | program by Charles Hedrick, Rob Hooft, and Harald Koenig. | |
994 | See the source code for complete history and credits. | |
995 | . | |
996 | .SH AVAILABILITY | |
997 | The hwclock command is part of the util-linux package and is available from | |
998 | https://www.kernel.org/pub/linux/utils/util-linux/. |