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