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