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