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