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