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