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