]>
Commit | Line | Data |
---|---|---|
df48a721 | 1 | .TH HWCLOCK 8 "October 2014" "util-linux" "System Administration" |
fd6b7a7f | 2 | .SH NAME |
5474e57f | 3 | hwclock \- query or set the hardware clock (RTC) |
fd6b7a7f | 4 | .SH SYNOPSIS |
93f9a8e4 | 5 | .B hwclock |
5474e57f BS |
6 | .RI [ function ] |
7 | .RI [ option ...] | |
fd6b7a7f KZ |
8 | |
9 | .SH DESCRIPTION | |
66ee8158 | 10 | .B hwclock |
fd6b7a7f KZ |
11 | is a tool for accessing the Hardware Clock. You can display the |
12 | current time, set the Hardware Clock to a specified time, set the | |
5474e57f | 13 | Hardware Clock from the System Time, or set the System Time from the |
fd6b7a7f KZ |
14 | Hardware Clock. |
15 | .PP | |
9abb2685 KZ |
16 | You can also run |
17 | .B hwclock | |
5474e57f BS |
18 | periodically to add or subtract time from the Hardware Clock to |
19 | compensate for systematic drift (where the clock consistently loses or | |
20 | gains time at a certain rate when left to run). | |
fd6b7a7f | 21 | |
732ac3a5 KZ |
22 | Since v2.26 |
23 | .B hwclock | |
5cb71d2b WP |
24 | does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default. |
25 | It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or | |
26 | \fB\-\-systohc\fR, to force drift factor updates. | |
732ac3a5 KZ |
27 | |
28 | Since v2.26 | |
5cb71d2b | 29 | .B hwclock \-\-hctosys |
df48a721 BS |
30 | does a better job at setting the System Clock: it no longer simply copies |
31 | the time from the Hardware Clock to the System Clock, but sets the System | |
32 | Clock to a drift-compensated time. (That is: it reads the Hardware Clock, | |
33 | applies a compensation for the systematic drift to this read time, and | |
34 | then sets the System Clock to the resulting value.) | |
35 | Therefore it is no longer necessary to run \fBhwclock --adjust\fR before | |
36 | doing \fBhwclock --hctosys\fR, and thus \fBhwclock\fR can be used very | |
37 | early on in the boot process when the root filesystem is still read-only. | |
732ac3a5 | 38 | |
28e984a4 | 39 | .SH FUNCTIONS |
9abb2685 KZ |
40 | You need exactly one of the following options to tell |
41 | .B hwclock | |
fd6b7a7f | 42 | what function to perform: |
ae4cc2ad BS |
43 | .TP |
44 | .B \-\-adjust | |
45 | Add or subtract time from the Hardware Clock to account for systematic | |
46 | drift since the last time the clock was set or adjusted. See the | |
47 | discussion below, under \fBThe Adjust Function\fR. | |
48 | .TP | |
49 | .BR \-c , \ \-\-compare | |
50 | Periodically compare the Hardware Clock to the System Time and output | |
51 | the difference every 10 seconds. This will also print the frequency | |
52 | offset and tick. | |
53 | .TP | |
54 | .B \-\-getepoch | |
55 | Print the kernel's Hardware Clock epoch value to standard output. | |
56 | This is the number of years into AD to which a zero year value in the | |
57 | Hardware Clock refers. For example, if you are using the convention | |
58 | that the year counter in your Hardware Clock contains the number of | |
59 | full years since 1952, then the kernel's Hardware Clock epoch value | |
60 | must be 1952. | |
fc56c363 | 61 | .sp |
ae4cc2ad BS |
62 | This epoch value is used whenever |
63 | .B hwclock | |
64 | reads or sets the Hardware Clock. | |
65 | .TP | |
66 | .BI \-\-predict | |
67 | Predict what the RTC will read at the time given by the | |
68 | .B \-\-date | |
69 | option, based on the adjtime file. This is useful for example if you | |
70 | need to set an RTC wakeup time to a distant future and want to account | |
71 | for the RTC drift. | |
fd6b7a7f | 72 | .TP |
93f9a8e4 | 73 | .BR \-r , \ \-\-show |
5474e57f | 74 | Read the Hardware Clock and print the time on standard output. |
c07ebfa1 | 75 | The time shown is always in local time, even if you keep your Hardware Clock |
7eda085c KZ |
76 | in Coordinated Universal Time. See the |
77 | .B \-\-utc | |
78 | option. | |
5474e57f | 79 | Showing the Hardware Clock time is the default when no function is specified. |
fd6b7a7f | 80 | .TP |
cb7efbc1 WP |
81 | .B \-\-get |
82 | Like | |
83 | .B --show | |
84 | only with drift correction applied to the time read. This is useful when the | |
85 | Hardware Clock is not being periodically updated by something such as NTP's | |
86 | 11 minute mode or when not using | |
87 | .BR --adjust . | |
88 | .TP | |
93f9a8e4 | 89 | .BR \-s , \ \-\-hctosys |
cb7efbc1 WP |
90 | Set the System Time from the Hardware Clock. The time read from the Hardware |
91 | Clock is compensated to account for systematic drift before using it to set the | |
92 | System Clock. See the discussion below, under \fBThe Adjust Function\fR. | |
fc56c363 | 93 | .sp |
22853e4a KZ |
94 | Also set the kernel's timezone value to the local timezone |
95 | as indicated by the TZ environment variable and/or | |
a2c5f3ca | 96 | .IR /usr/share/zoneinfo , |
9abb2685 | 97 | as |
7eda085c | 98 | .BR tzset (3) |
22853e4a KZ |
99 | would interpret them. |
100 | The obsolete tz_dsttime field of the kernel's timezone value is set | |
5474e57f | 101 | to DST_NONE. (For details on what this field used to mean, see |
22853e4a | 102 | .BR settimeofday (2).) |
fc56c363 | 103 | .sp |
8db424dc WP |
104 | When used in a startup script, making it the first caller of |
105 | .BR settimeofday (2) | |
106 | from boot, it will set the NTP 11 minute mode time scale via the | |
107 | .I persistent_clock_is_local | |
df48a721 BS |
108 | kernel variable. See the discussion below, under |
109 | .BR "Automatic Hardware Clock Synchronization by the Kernel" . | |
fc56c363 | 110 | .sp |
5c36a0eb | 111 | This is a good option to use in one of the system startup scripts. |
fc56c363 | 112 | .sp |
8db424dc WP |
113 | This option should never be used on a running system. Jumping system time |
114 | will cause problems, such as, corrupted file system timestamps. | |
115 | Also, if NTP 11 minute mode is active then | |
116 | .B --hctosys | |
117 | will set the time incorrectly by | |
118 | including drift compensation. Drift compensation can be inhibited by using the | |
119 | .B --noadjfile | |
120 | option. | |
fd6b7a7f | 121 | .TP |
ae4cc2ad BS |
122 | .B \-\-set |
123 | Set the Hardware Clock to the time given by the | |
124 | .B \-\-date | |
125 | option. | |
126 | .TP | |
127 | .B \-\-setepoch | |
128 | Set the kernel's Hardware Clock epoch value to the value specified by the | |
129 | .B \-\-epoch | |
130 | option. See the | |
131 | .B \-\-getepoch | |
132 | option for details. | |
fd6b7a7f | 133 | .TP |
88a3372e | 134 | .B \-\-systz |
910a0900 | 135 | Set the kernel's timezone and reset the System Time based on the current timezone. |
fc56c363 | 136 | .sp |
910a0900 | 137 | The system time is only reset on the first call after boot. |
fc56c363 | 138 | .sp |
910a0900 TG |
139 | The local timezone is taken to be what is |
140 | indicated by the TZ environment variable and/or | |
88a3372e SJR |
141 | .IR /usr/share/zoneinfo , |
142 | as | |
143 | .BR tzset (3) | |
144 | would interpret them. | |
145 | The obsolete tz_dsttime field of the kernel's timezone value is set | |
5474e57f | 146 | to DST_NONE. (For details on what this field used to mean, see |
88a3372e | 147 | .BR settimeofday (2).) |
fc56c363 | 148 | .sp |
88a3372e SJR |
149 | This is an alternate option to |
150 | .B \-\-hctosys | |
151 | that does not read the hardware clock, and may be used in system startup | |
152 | scripts for recent 2.6 kernels where you know the System Time contains | |
ae4cc2ad | 153 | the Hardware Clock time. If the Hardware Clock is already in UTC, it is |
910a0900 | 154 | not reset. |
88a3372e | 155 | .TP |
ae4cc2ad BS |
156 | .BR \-w , \ \-\-systohc |
157 | Set the Hardware Clock to the current System Time. | |
2b6fc908 | 158 | .TP |
ae4cc2ad BS |
159 | .BR \-V , \ \-\-version |
160 | Display version information and exit. | |
d0b76eac | 161 | .TP |
5474e57f | 162 | .BR \-h , \ \-\-help |
b4362b6f | 163 | Display help text and exit. |
5474e57f BS |
164 | |
165 | .SH OPTIONS | |
364cda48 | 166 | |
da82f6fe | 167 | .TP |
93f9a8e4 | 168 | .BI \-\-adjfile= filename |
ae4cc2ad | 169 | Override the default @ADJTIME_PATH@. |
88681c5f | 170 | |
fd6b7a7f | 171 | .TP |
ae4cc2ad BS |
172 | .B \-\-arc |
173 | This option is equivalent to | |
174 | .B \-\-epoch=1980 | |
175 | and is used to specify the most common epoch on Alphas | |
176 | with ARC console (but Ruffians have epoch 1900). | |
5c36a0eb | 177 | |
7eda085c KZ |
178 | .TP |
179 | .B \-\-badyear | |
ae4cc2ad | 180 | Indicate that the Hardware Clock is incapable of storing years outside |
9abb2685 | 181 | the range 1994-1999. There is a problem in some BIOSes (almost all |
7eda085c KZ |
182 | Award BIOSes made between 4/26/94 and 5/31/95) wherein they are unable |
183 | to deal with years after 1999. If one attempts to set the year-of-century | |
184 | value to something less than 94 (or 95 in some cases), the value that | |
185 | actually gets set is 94 (or 95). Thus, if you have one of these machines, | |
66ee8158 | 186 | .B hwclock |
7eda085c KZ |
187 | cannot set the year after 1999 and cannot use the value of the clock as |
188 | the true time in the normal way. | |
fc56c363 | 189 | .sp |
7eda085c | 190 | To compensate for this (without your getting a BIOS update, which would |
9abb2685 | 191 | definitely be preferable), always use |
7eda085c | 192 | .B \-\-badyear |
9abb2685 | 193 | if you have one of these machines. When |
66ee8158 | 194 | .B hwclock |
7eda085c | 195 | knows it's working with a brain-damaged clock, it ignores the year part of |
9abb2685 | 196 | the Hardware Clock value and instead tries to guess the year based on the |
8d8ea18e | 197 | last calibrated date in the adjtime file, by assuming that date is |
9abb2685 | 198 | within the past year. For this to work, you had better do a |
5474e57f | 199 | .B hwclock \-\-set |
7eda085c | 200 | or |
5474e57f | 201 | .B hwclock \-\-systohc |
7eda085c | 202 | at least once a year! |
fc56c363 | 203 | .sp |
9abb2685 | 204 | Though |
66ee8158 | 205 | .B hwclock |
7eda085c KZ |
206 | ignores the year value when it reads the Hardware Clock, it sets the |
207 | year value when it sets the clock. It sets it to 1995, 1996, 1997, or | |
208 | 1998, whichever one has the same position in the leap year cycle as | |
209 | the true year. That way, the Hardware Clock inserts leap days where | |
210 | they belong. Again, if you let the Hardware Clock run for more than a | |
211 | year without setting it, this scheme could be defeated and you could | |
212 | end up losing a day. | |
fc56c363 | 213 | .sp |
66ee8158 | 214 | .B hwclock |
9abb2685 | 215 | warns you that you probably need |
7eda085c | 216 | .B \-\-badyear |
9abb2685 | 217 | whenever it finds your Hardware Clock set to 1994 or 1995. |
7eda085c KZ |
218 | |
219 | .TP | |
ae4cc2ad BS |
220 | .BI \-\-date= date_string |
221 | You need this option if you specify the | |
222 | .B \-\-set | |
223 | or | |
224 | .B \-\-predict | |
225 | functions, otherwise it is ignored. | |
226 | It specifies the time to which to set the Hardware Clock, or the | |
227 | time for which to predict the Hardware Clock reading. | |
228 | The value of this option is an argument to the | |
229 | .BR date (1) | |
230 | program. | |
231 | For example: | |
fc56c363 | 232 | .sp |
ae4cc2ad | 233 | .B " hwclock" --set --date="2011-08-14 16:45:05" |
fc56c363 | 234 | .sp |
ae4cc2ad BS |
235 | The argument must be in local time, even if you keep your Hardware Clock in |
236 | Coordinated Universal time. See the | |
237 | .B \-\-utc | |
238 | option. | |
239 | ||
7eda085c | 240 | .TP |
ae4cc2ad BS |
241 | .B \-\-debug |
242 | Display a lot of information about what | |
243 | .B hwclock | |
244 | is doing internally. Some of its function is complex and this output | |
245 | can help you understand how the program works. | |
246 | ||
7eda085c | 247 | .TP |
ae4cc2ad BS |
248 | .B \-\-directisa |
249 | This option is meaningful only on an ISA machine or an Alpha (which implements | |
250 | enough of ISA to be, roughly speaking, an ISA machine for | |
251 | .BR hwclock 's | |
252 | purposes). For other machines, it has no effect. This option tells | |
253 | .B hwclock | |
254 | to use explicit I/O instructions to access the Hardware Clock. | |
255 | Without this option, | |
256 | .B hwclock | |
257 | will try to use the /dev/rtc device (which it assumes to be driven by the | |
258 | RTC device driver). If it is unable to open the device (for reading), it will | |
259 | use the explicit I/O instructions anyway. | |
260 | ||
261 | .TP | |
262 | .BI \-\-epoch= year | |
263 | Specifies the year which is the beginning of the Hardware Clock's | |
264 | epoch, that is the number of years into AD to which a zero value in the | |
265 | Hardware Clock's year counter refers. It is used together with | |
266 | the \fB\-\-setepoch\fR option to set the kernel's idea of the epoch of the | |
267 | Hardware Clock, or otherwise to specify the epoch for use with | |
268 | direct ISA access. | |
fc56c363 | 269 | .sp |
ae4cc2ad | 270 | For example, on a Digital Unix machine: |
fc56c363 | 271 | .sp |
ae4cc2ad BS |
272 | .B " hwclock" --setepoch --epoch=1952 |
273 | ||
274 | .TP | |
275 | .BR \-f , \ \-\-rtc=\fIfilename\fB | |
276 | Overrides the default /dev file name, which is | |
277 | .IR /dev/rtc | |
278 | on many platforms but may be | |
279 | .IR /dev/rtc0 , | |
280 | .IR /dev/rtc1 , | |
281 | and so on. | |
282 | ||
7eda085c KZ |
283 | .TP |
284 | .B \-\-funky\-toy | |
ae4cc2ad BS |
285 | .TP |
286 | .B \-\-jensen | |
c07ebfa1 KZ |
287 | These two options specify what kind of Alpha machine you have. They |
288 | are invalid if you don't have an Alpha and are usually unnecessary | |
9abb2685 KZ |
289 | if you do, because |
290 | .B hwclock | |
291 | should be able to determine by itself what it's | |
eb63b9b8 KZ |
292 | running on, at least when |
293 | .I /proc | |
c07ebfa1 KZ |
294 | is mounted. |
295 | (If you find you need one of these options to make | |
9abb2685 | 296 | .B hwclock |
c07ebfa1 | 297 | work, contact the maintainer to see if the program can be improved |
5474e57f | 298 | to detect your system automatically. Output of `hwclock --debug' |
c07ebfa1 | 299 | and `cat /proc/cpuinfo' may be of interest.) |
fc56c363 | 300 | .sp |
5474e57f | 301 | Option |
9abb2685 | 302 | .B \-\-jensen |
5474e57f | 303 | means you are running on a Jensen model. And |
9abb2685 | 304 | .B \-\-funky\-toy |
5474e57f | 305 | means that on your machine one has to use the UF bit instead |
7eda085c | 306 | of the UIP bit in the Hardware Clock to detect a time transition. "Toy" |
9abb2685 | 307 | in the option name refers to the Time Of Year facility of the machine. |
7eda085c | 308 | |
ae4cc2ad BS |
309 | .TP |
310 | .B \-\-localtime | |
311 | Indicate that the Hardware Clock is kept in local time. | |
fc56c363 | 312 | .sp |
ae4cc2ad BS |
313 | It is your choice whether to keep |
314 | your clock in UTC or in local time, but nothing in the clock itself | |
315 | says which alternative | |
316 | you've chosen. So with \fB\-\-localtime\fR or \fB\-\-utc\fR | |
317 | you give this information to | |
318 | .BR hwclock . | |
319 | If you specify the wrong one (or specify neither and take a wrong default), | |
320 | both setting and querying the Hardware Clock will be messed up. | |
fc56c363 | 321 | .sp |
ae4cc2ad BS |
322 | If you specify neither |
323 | .B \-\-utc | |
324 | nor | |
325 | .BR \-\-localtime , | |
326 | the default is whichever was specified the last time | |
327 | .B hwclock | |
328 | was used to set the clock (i.e. | |
329 | .B hwclock | |
330 | was successfully run with the | |
331 | .BR \-\-set , | |
332 | .BR \-\-systohc , | |
333 | or | |
334 | .B \-\-adjust | |
335 | options), as recorded in the adjtime file. If the adjtime file doesn't | |
336 | exist, the default is UTC time. | |
337 | ||
338 | .TP | |
339 | .B \-\-noadjfile | |
340 | Disable the facilities provided by | |
341 | .IR @ADJTIME_PATH@ . | |
342 | .B hwclock | |
343 | will not read nor write to that file with this option. Either | |
344 | .B \-\-utc | |
345 | or | |
346 | .B \-\-localtime | |
347 | must be specified when using this option. | |
348 | ||
349 | .TP | |
350 | .B \-\-srm | |
351 | This option is equivalent to | |
352 | .B \-\-epoch=1900 | |
353 | and is used to specify the most common epoch on Alphas | |
354 | with SRM console. | |
7eda085c | 355 | |
2b6fc908 | 356 | .TP |
fd6b7a7f | 357 | .B \-\-test |
2b6fc908 KZ |
358 | Do everything except actually updating the Hardware Clock or anything |
359 | else. This is useful, especially in conjunction with | |
93f9a8e4 | 360 | .BR \-\-debug , |
cd950279 WP |
361 | in learning about the internal operations of hwclock. |
362 | ||
363 | .TP | |
df48a721 | 364 | .B \-\-update-drift |
cd950279 WP |
365 | Update the Hardware Clock's drift factor in |
366 | .IR @ADJTIME_PATH@ . | |
367 | It is used with | |
368 | .BR --set\ or \ --systohc , | |
369 | otherwise it is ignored. | |
df48a721 | 370 | See the discussion below, under \fBThe Adjust Function\fR. |
ae4cc2ad | 371 | |
fd6b7a7f | 372 | .TP |
ae4cc2ad BS |
373 | .BR \-u , \ \-\-utc |
374 | Indicate that the Hardware Clock is kept in Coordinated Universal Time. | |
375 | See the discussion under \fB\-\-localtime\fR. | |
fd6b7a7f KZ |
376 | |
377 | ||
378 | .SH NOTES | |
379 | ||
ae4cc2ad | 380 | .SS Clocks in a Linux System |
fd6b7a7f KZ |
381 | .PP |
382 | There are two main clocks in a Linux system: | |
383 | .PP | |
9abb2685 | 384 | .B The Hardware Clock: |
fd6b7a7f | 385 | This is a clock that runs independently of any control program running |
2b6fc908 | 386 | in the CPU and even when the machine is powered off. |
ae4cc2ad | 387 | .PP |
2b6fc908 KZ |
388 | On an ISA system, this clock is specified as part of the ISA standard. |
389 | The control program can read or set this clock to a whole second, but | |
390 | the control program can also detect the edges of the 1 second clock | |
391 | ticks, so the clock actually has virtually infinite precision. | |
fd6b7a7f KZ |
392 | .PP |
393 | This clock is commonly called the hardware clock, the real time clock, | |
394 | the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its | |
9abb2685 KZ |
395 | capitalized form, was coined for use by |
396 | .B hwclock | |
fd6b7a7f KZ |
397 | because all of the other names are inappropriate to the point of being |
398 | misleading. | |
399 | .PP | |
88681c5f KZ |
400 | So for example, some non-ISA systems have a few real time clocks with |
401 | only one of them having its own power domain. | |
402 | A very low power external I2C or SPI clock chip might be used with a | |
403 | backup battery as the hardware clock to initialize a more functional | |
404 | integrated real-time clock which is used for most other purposes. | |
405 | .PP | |
9abb2685 | 406 | .B The System Time: |
fd6b7a7f | 407 | This is the time kept by a clock inside the Linux kernel and driven by |
2b6fc908 | 408 | a timer interrupt. (On an ISA machine, the timer interrupt is part of |
ae4cc2ad | 409 | the ISA standard.) It has meaning only while Linux is running on the |
2b6fc908 KZ |
410 | machine. The System Time is the number of seconds since 00:00:00 |
411 | January 1, 1970 UTC (or more succinctly, the number of seconds since | |
412 | 1969). The System Time is not an integer, though. It has virtually | |
413 | infinite precision. | |
fd6b7a7f KZ |
414 | .PP |
415 | The System Time is the time that matters. The Hardware Clock's basic | |
416 | purpose in a Linux system is to keep time when Linux is not running. You | |
417 | initialize the System Time to the time from the Hardware Clock when Linux | |
418 | starts up, and then never use the Hardware Clock again. Note that in DOS, | |
419 | for which ISA was designed, the Hardware Clock is the only real time clock. | |
420 | .PP | |
421 | It is important that the System Time not have any discontinuities such as | |
9abb2685 | 422 | would happen if you used the |
7eda085c | 423 | .BR date (1L) |
fd6b7a7f KZ |
424 | program to set it while the system is running. You can, however, do whatever |
425 | you want to the Hardware Clock while the system is running, and the next | |
426 | time Linux starts up, it will do so with the adjusted time from the Hardware | |
8cf4152c | 427 | Clock. |
5c36a0eb KZ |
428 | .PP |
429 | A Linux kernel maintains a concept of a local timezone for the system. | |
430 | But don't be misled -- almost nobody cares what timezone the kernel | |
431 | thinks it is in. Instead, programs that care about the timezone | |
432 | (perhaps because they want to display a local time for you) almost | |
433 | always use a more traditional method of determining the timezone: They | |
5213517f KZ |
434 | use the TZ environment variable and/or the |
435 | .I /usr/share/zoneinfo | |
436 | directory, as explained in the man page for | |
437 | .BR tzset (3). | |
8db424dc WP |
438 | However, some programs and fringe parts of the Linux kernel such as filesystems |
439 | use the kernel timezone value. An example is the vfat filesystem. If the | |
440 | kernel timezone value is wrong, the vfat filesystem will report and set the | |
441 | wrong timestamps on files. Another example is the kernel's NTP 11 minute mode. | |
442 | If the kernel's timezone value and/or the | |
443 | .I persistent_clock_is_local | |
444 | variable are wrong, then the Hardware Clock will be set incorrectly by 11 minute | |
445 | mode. See the discussion below, under | |
df48a721 | 446 | .BR "Automatic Hardware Clock Synchronization by the Kernel" . |
5c36a0eb | 447 | .PP |
66ee8158 | 448 | .B hwclock |
5c36a0eb | 449 | sets the kernel timezone to the value indicated by TZ and/or |
5213517f | 450 | .I /usr/share/zoneinfo |
9abb2685 | 451 | when you set the System Time using the |
5c36a0eb KZ |
452 | .B \-\-hctosys |
453 | option. | |
454 | .PP | |
22853e4a KZ |
455 | The timezone value actually consists of two parts: 1) a field |
456 | tz_minuteswest indicating how many minutes local time (not adjusted | |
457 | for DST) lags behind UTC, and 2) a field tz_dsttime indicating | |
458 | the type of Daylight Savings Time (DST) convention that is in effect | |
459 | in the locality at the present time. | |
460 | This second field is not used under Linux and is always zero. | |
461 | (See also | |
462 | .BR settimeofday (2).) | |
fd6b7a7f | 463 | |
ae4cc2ad | 464 | .SS User access and setuid |
a6ccf39b SK |
465 | .PP |
466 | Sometimes, you need to install | |
467 | .B hwclock | |
ae4cc2ad | 468 | setuid root. If you want users other than the superuser to be able to |
a6ccf39b | 469 | display the clock value using the direct ISA I/O method, install it setuid |
ae4cc2ad | 470 | root. If you have the /dev/rtc interface on your system or are on a non-ISA |
a6ccf39b SK |
471 | system, there's probably no need for users to use the direct ISA I/O method, |
472 | so don't bother. | |
ae4cc2ad | 473 | .PP |
a6ccf39b | 474 | In any case, hwclock will not allow you to set anything unless you have the |
ae4cc2ad BS |
475 | superuser real uid. (This restriction is not necessary if you haven't |
476 | installed setuid root, but it's there for now.) | |
a6ccf39b | 477 | |
ae4cc2ad | 478 | .SS How hwclock accesses the Hardware Clock |
2b6fc908 | 479 | .PP |
9abb2685 | 480 | .B hwclock |
93f9a8e4 | 481 | uses many different ways to get and set Hardware Clock values. |
2b6fc908 KZ |
482 | The most normal way is to do I/O to the device special file /dev/rtc, |
483 | which is presumed to be driven by the rtc device driver. However, | |
484 | this method is not always available. For one thing, the rtc driver is | |
485 | a relatively recent addition to Linux. Older systems don't have it. | |
7eda085c KZ |
486 | Also, though there are versions of the rtc driver that work on DEC |
487 | Alphas, there appear to be plenty of Alphas on which the rtc driver | |
488 | does not work (a common symptom is hwclock hanging). | |
88681c5f KZ |
489 | Moreover, recent Linux systems have more generic support for RTCs, |
490 | even systems that have more than one, so you might need to override | |
491 | the default by specifying | |
492 | .I /dev/rtc0 | |
493 | or | |
494 | .I /dev/rtc1 | |
495 | instead. | |
2b6fc908 KZ |
496 | .PP |
497 | On older systems, the method of accessing the Hardware Clock depends on | |
9abb2685 | 498 | the system hardware. |
2b6fc908 | 499 | .PP |
9abb2685 KZ |
500 | On an ISA system, |
501 | .B hwclock | |
7eda085c KZ |
502 | can directly access the "CMOS memory" registers that |
503 | constitute the clock, by doing I/O to Ports 0x70 and 0x71. It does | |
504 | this with actual I/O instructions and consequently can only do it if | |
505 | running with superuser effective userid. (In the case of a Jensen | |
506 | Alpha, there is no way for | |
9abb2685 | 507 | .B hwclock |
7eda085c KZ |
508 | to execute those I/O instructions, and so it uses instead the |
509 | /dev/port device special file, which provides almost as low-level an | |
ae4cc2ad BS |
510 | interface to the I/O subsystem.) |
511 | .PP | |
2b6fc908 | 512 | This is a really poor method of accessing the clock, for all the |
ae4cc2ad BS |
513 | reasons that userspace programs are generally not supposed to do |
514 | direct I/O and disable interrupts. \fBhwclock\fR provides it because it is | |
7eda085c KZ |
515 | the only method available on ISA and Alpha systems which don't have |
516 | working rtc device drivers available. | |
2b6fc908 KZ |
517 | .PP |
518 | On an m68k system, | |
66ee8158 | 519 | .B hwclock |
2b6fc908 KZ |
520 | can access the clock via the console driver, via the device special |
521 | file /dev/tty1. | |
522 | .PP | |
9abb2685 | 523 | .B hwclock |
2b6fc908 | 524 | tries to use /dev/rtc. If it is compiled for a kernel that doesn't have |
88681c5f KZ |
525 | that function or it is unable to open /dev/rtc |
526 | (or the alternative special file you've defined on the command line) | |
9abb2685 | 527 | .B hwclock |
7eda085c | 528 | will fall back to another method, if available. On an ISA or Alpha |
2b6fc908 | 529 | machine, you can force |
66ee8158 | 530 | .B hwclock |
2b6fc908 | 531 | to use the direct manipulation of the CMOS registers without even trying |
7eda085c | 532 | .I /dev/rtc |
93f9a8e4 PB |
533 | by specifying the |
534 | .B \-\-directisa | |
535 | option. | |
2b6fc908 | 536 | |
ae4cc2ad | 537 | .SS The Adjust Function |
fd6b7a7f KZ |
538 | .PP |
539 | The Hardware Clock is usually not very accurate. However, much of its | |
7eda085c | 540 | inaccuracy is completely predictable - it gains or loses the same amount |
fd6b7a7f | 541 | of time every day. This is called systematic drift. |
9abb2685 | 542 | .BR hwclock 's |
cb7efbc1 WP |
543 | .I \-\-adjust |
544 | function lets you apply systematic drift corrections to the | |
545 | Hardware Clock. | |
fd6b7a7f | 546 | .PP |
9abb2685 KZ |
547 | It works like this: |
548 | .B hwclock | |
fd6b7a7f | 549 | keeps a file, |
2ad21963 | 550 | .IR @ADJTIME_PATH@ , |
fd6b7a7f KZ |
551 | that keeps some historical information. This is called the adjtime file. |
552 | .PP | |
9abb2685 | 553 | Suppose you start with no adjtime file. You issue a |
df48a721 | 554 | .B hwclock \-\-set |
9abb2685 | 555 | command to set the Hardware Clock to the true current time. |
ae4cc2ad | 556 | .B hwclock |
9abb2685 | 557 | creates the adjtime file and records in it the current time as the |
fd6b7a7f | 558 | last time the clock was calibrated. |
df48a721 BS |
559 | Five days later, the clock has gained 10 seconds, so you issue a |
560 | .B hwclock \-\-set \-\-update-drift | |
9abb2685 | 561 | command to set it back 10 seconds. |
ae4cc2ad | 562 | .B hwclock |
fd6b7a7f KZ |
563 | updates the adjtime file to show the current time as the last time the |
564 | clock was calibrated, and records 2 seconds per day as the systematic | |
565 | drift rate. 24 hours go by, and then you issue a | |
df48a721 | 566 | .B hwclock \-\-adjust |
9abb2685 | 567 | command. |
ae4cc2ad | 568 | .B hwclock |
fd6b7a7f KZ |
569 | consults the adjtime file and sees that the clock gains 2 seconds per |
570 | day when left alone and that it has been left alone for exactly one | |
571 | day. So it subtracts 2 seconds from the Hardware Clock. It then | |
572 | records the current time as the last time the clock was adjusted. | |
df48a721 BS |
573 | Another 24 hours go by and you issue another |
574 | .BR "hwclock \-\-adjust" . | |
ae4cc2ad | 575 | .B hwclock |
fd6b7a7f KZ |
576 | does the same thing: subtracts 2 seconds and updates the adjtime file |
577 | with the current time as the last time the clock was adjusted. | |
578 | .PP | |
cd950279 | 579 | When you use the |
df48a721 | 580 | .B \-\-update-drift |
cd950279 | 581 | option with |
df48a721 | 582 | .BR \-\-set\ or \ \-\-systohc , |
cd950279 | 583 | the systematic drift rate is (re)calculated based on how long it has been |
fd6b7a7f KZ |
584 | since the last calibration, how long it has been since the last |
585 | adjustment, what drift rate was assumed in any intervening | |
cd950279 WP |
586 | adjustments, and the amount by which the clock is presently off. This updated |
587 | drift factor is then saved in | |
588 | .IR @ADJTIME_PATH@ . | |
fd6b7a7f | 589 | .PP |
cb7efbc1 WP |
590 | A small amount of error creeps in when |
591 | the Hardware Clock is set, so | |
df48a721 | 592 | .B \-\-adjust |
cb7efbc1 WP |
593 | refrains from making any adjustment that is less |
594 | than 1 second. Later on, when you request an adjustment again, the accumulated | |
595 | drift will be more than 1 second and | |
df48a721 | 596 | .B \-\-adjust |
cb7efbc1 WP |
597 | will make the adjustment including any fractional amount. |
598 | .PP | |
df48a721 | 599 | .B hwclock \-\-hctosys |
cb7efbc1 WP |
600 | also uses the adjtime file data to compensate the value read from the Hardware |
601 | Clock before using it to set the System Time. It does not share the 1 second | |
df48a721 | 602 | limitation of \fB--adjust\fR, and will correct sub-second drift values immediately. |
cb7efbc1 | 603 | It does not change the Hardware Clock time or the adjtime file. This may |
df48a721 | 604 | eliminate the need to use \fB--adjust\fR, unless something else on the system needs |
cb7efbc1 WP |
605 | the Hardware Clock to be compensated. The drift compensation can be inhibited |
606 | by using the | |
607 | .B --noadjfile | |
608 | option. | |
fd6b7a7f | 609 | .PP |
7eda085c KZ |
610 | The adjtime file, while named for its historical purpose of controlling |
611 | adjustments only, actually contains other information for use by hwclock | |
612 | in remembering information from one invocation to the next. | |
613 | .PP | |
5c36a0eb | 614 | The format of the adjtime file is, in ASCII: |
fd6b7a7f | 615 | .PP |
df48a721 BS |
616 | Line 1: Three numbers, separated by blanks: 1) the systematic drift rate |
617 | in seconds per day, floating point decimal; 2) the resulting number of | |
5c36a0eb KZ |
618 | seconds since 1969 UTC of most recent adjustment or calibration, |
619 | decimal integer; 3) zero (for compatibility with | |
66ee8158 | 620 | .BR clock (8)) |
7eda085c | 621 | as a decimal integer. |
fd6b7a7f | 622 | .PP |
df48a721 | 623 | Line 2: One number: the resulting number of seconds since 1969 UTC of most |
7eda085c KZ |
624 | recent calibration. Zero if there has been no calibration yet or it |
625 | is known that any previous calibration is moot (for example, because | |
9abb2685 | 626 | the Hardware Clock has been found, since that calibration, not to |
7eda085c KZ |
627 | contain a valid time). This is a decimal integer. |
628 | .PP | |
9abb2685 | 629 | Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to |
7eda085c | 630 | Coordinated Universal Time or local time. You can always override this |
9abb2685 | 631 | value with options on the |
66ee8158 | 632 | .B hwclock |
7eda085c | 633 | command line. |
fd6b7a7f | 634 | .PP |
9abb2685 | 635 | You can use an adjtime file that was previously used with the |
66ee8158 | 636 | .BR clock (8) |
9abb2685 | 637 | program with |
93f9a8e4 | 638 | .BR hwclock . |
fd6b7a7f | 639 | |
ae4cc2ad BS |
640 | .SS Automatic Hardware Clock Synchronization by the Kernel |
641 | .PP | |
9abb2685 | 642 | You should be aware of another way that the Hardware Clock is kept |
5c36a0eb | 643 | synchronized in some systems. The Linux kernel has a mode wherein it |
9abb2685 | 644 | copies the System Time to the Hardware Clock every 11 minutes. |
5c36a0eb KZ |
645 | This is a good mode to use when you are using something sophisticated |
646 | like ntp to keep your System Time synchronized. (ntp is a way to keep | |
647 | your System Time synchronized either to a time server somewhere on the | |
ae4cc2ad BS |
648 | network or to a radio clock hooked up to your system. See RFC 1305.) |
649 | .PP | |
5c36a0eb | 650 | This mode (we'll call it "11 minute mode") is off until something |
8db424dc | 651 | turns it on. The ntp daemon ntpd is one thing that turns it on. You |
5c36a0eb | 652 | can turn it off by running anything, including |
df48a721 | 653 | .BR "hwclock \-\-hctosys" , |
8db424dc WP |
654 | that sets the System Time the old fashioned way. However, if the ntp daemon is |
655 | still running, it will turn 11 minute mode back on again the next time it | |
656 | synchronizes the System Clock. | |
ae4cc2ad | 657 | .PP |
8db424dc | 658 | If your system runs with 11 minute mode on, it may need |
df48a721 | 659 | .B hwclock \-\-hctosys |
98ac7745 | 660 | in a startup script, especially if the Hardware Clock is configured to use |
8db424dc WP |
661 | the local timescale. |
662 | ||
663 | The first user space command to set the System Clock informs the | |
df48a721 | 664 | kernel what timescale the Hardware Clock is using. This happens via the |
8db424dc | 665 | .I persistent_clock_is_local |
df48a721 BS |
666 | kernel variable. If |
667 | .B hwclock \-\-hctosys | |
8db424dc | 668 | is the first, it will set this variable according to the adjtime file or the |
df48a721 | 669 | appropriate command-line argument. Note that when using this capability and the |
8db424dc WP |
670 | Hardware Clock timescale configuration is changed, then a reboot is required to |
671 | notify the kernel. | |
672 | ||
673 | Don't use | |
df48a721 | 674 | .B hwclock \-\-adjust |
8db424dc | 675 | with 11 minute mode. You'll just make a mess. |
5c36a0eb | 676 | |
ae4cc2ad BS |
677 | .SS ISA Hardware Clock Century value |
678 | .PP | |
7eda085c | 679 | There is some sort of standard that defines CMOS memory Byte 50 on an ISA |
9abb2685 | 680 | machine as an indicator of what century it is. |
66ee8158 | 681 | .B hwclock |
7eda085c KZ |
682 | does not use or set that byte because there are some machines that |
683 | don't define the byte that way, and it really isn't necessary anyway, | |
684 | since the year-of-century does a good job of implying which century it | |
685 | is. | |
ae4cc2ad | 686 | .PP |
9abb2685 | 687 | If you have a bona fide use for a CMOS century byte, contact the |
66ee8158 | 688 | .B hwclock |
7eda085c | 689 | maintainer; an option may be appropriate. |
ae4cc2ad | 690 | .PP |
7eda085c KZ |
691 | Note that this section is only relevant when you are using the "direct |
692 | ISA" method of accessing the Hardware Clock. | |
88681c5f KZ |
693 | ACPI provides a standard way to access century values, when they |
694 | are supported by the hardware. | |
7eda085c KZ |
695 | |
696 | .SH "ENVIRONMENT VARIABLES" | |
5c36a0eb KZ |
697 | .I TZ |
698 | ||
fd6b7a7f | 699 | .SH FILES |
2ad21963 | 700 | .I @ADJTIME_PATH@ |
a2c5f3ca KZ |
701 | .I /usr/share/zoneinfo/ |
702 | .RI ( /usr/lib/zoneinfo | |
703 | on old systems) | |
7eda085c | 704 | .I /dev/rtc |
88681c5f | 705 | .I /dev/rtc0 |
7eda085c KZ |
706 | .I /dev/port |
707 | .I /dev/tty1 | |
708 | .I /proc/cpuinfo | |
709 | ||
710 | .SH "SEE ALSO" | |
7eda085c KZ |
711 | .BR date (1), |
712 | .BR gettimeofday (2), | |
713 | .BR settimeofday (2), | |
714 | .BR crontab (1), | |
715 | .BR tzset (3) | |
fd6b7a7f KZ |
716 | |
717 | .SH AUTHORS | |
63cccae4 | 718 | Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com), |
2b6fc908 | 719 | based on work done on the |
fd6b7a7f | 720 | .I clock |
9abb2685 | 721 | program by Charles Hedrick, Rob Hooft, and Harald Koenig. |
7eda085c KZ |
722 | See the source code for complete history and credits. |
723 | ||
86d62711 | 724 | .SH AVAILABILITY |
601d12fb KZ |
725 | The hwclock command is part of the util-linux package and is available from |
726 | ftp://ftp.kernel.org/pub/linux/utils/util-linux/. |