1HWCLOCK(8) System Manager's Manual HWCLOCK(8)
2
6 hwclock - query and set the hardware clock (RTC)
7
9 hwclock [functions] [options]
10
13 hwclock is a tool for accessing the Hardware Clock. You can display
14 the current time, set the Hardware Clock to a specified time, set the
15 Hardware Clock to the System Time, and set the System Time from the
16 Hardware Clock.
17 You can also run hwclock periodically to insert or remove time from the
19 Hardware Clock to compensate for systematic drift (where the clock con‐
20 sistently gains or loses time at a certain rate if left to run).
21
24 You need exactly one of the following options to tell hwclock what
25 function to perform:
26 -r, --show
28 Read the Hardware Clock and print the time on Standard Output.
29 The time shown is always in local time, even if you keep your
30 Hardware Clock in Coordinated Universal Time. See the --utc
31 option.
32 -c, --compare
35 Periodically compare the Hardware Clock to the System Time and
36 output the difference every 10 seconds. This will also print
37 the frequency offset and tick.
38 --set Set the Hardware Clock to the time given by the --date option.
41 -s, --hctosys
43 Set the System Time from the Hardware Clock.
44 Also set the kernel's timezone value to the local timezone as
46 indicated by the TZ environment variable and/or /usr/share/zone‐
47 info, as tzset(3) would interpret them. The obsolete tz_dsttime
48 field of the kernel's timezone value is set to DST_NONE. (For
49 details on what this field used to mean, see settimeofday(2).)
50 This is a good option to use in one of the system startup
52 scripts.
53 -w, --systohc
55 Set the Hardware Clock to the current System Time.
56 --systz
58 Set the kernel's timezone and reset the System Time based on the
59 current timezone.
60 The system time is only reset on the first call after boot.
62 The local timezone is taken to be what is indicated by the TZ
64 environment variable and/or /usr/share/zoneinfo, as tzset(3)
65 would interpret them. The obsolete tz_dsttime field of the ker‐
66 nel's timezone value is set to DST_NONE. (For details on what
67 this field used to mean, see settimeofday(2).)
68 This is an alternate option to --hctosys that does not read the
70 hardware clock, and may be used in system startup scripts for
71 recent 2.6 kernels where you know the System Time contains the
72 Hardware Clock time. If the Hardware Clock is already in UTC, it
73 is not reset.
74 --adjust
76 Add or subtract time from the Hardware Clock to account for sys‐
77 tematic drift since the last time the clock was set or adjusted.
78 See discussion below.
79 --getepoch
81 Print the kernel's Hardware Clock epoch value to standard out‐
82 put. This is the number of years into AD to which a zero year
83 value in the Hardware Clock refers. For example, if you are
84 using the convention that the year counter in your Hardware
85 Clock contains the number of full years since 1952, then the
86 kernel's Hardware Counter epoch value must be 1952.
87 This epoch value is used whenever hwclock reads or sets the
89 Hardware Clock.
90 --setepoch
92 Set the kernel's Hardware Clock epoch value to the value speci‐
93 fied by the --epoch option. See the --getepoch option for
94 details.
95 -v, --version
97 Print the version of hwclock on Standard Output.
98 --date=date_string
100 You need this option if you specify the --set option. Other‐
101 wise, it is ignored. This specifies the time to which to set
102 the Hardware Clock. The value of this option is an argument to
103 the date(1) program. For example,
104 hwclock --set --date="9/22/96 16:45:05"
106 The argument is in local time, even if you keep your Hardware
108 Clock in Coordinated Universal time. See the --utc option.
109 --epoch=year
112 Specifies the year which is the beginning of the Hardware
113 Clock's epoch. I.e. the number of years into AD to which a zero
114 value in the Hardware Clock's year counter refers. It is used
115 together with the --setepoch option to set the kernel's idea of
116 the epoch of the Hardware Clock, or otherwise to specify the
117 epoch for use with direct ISA access.
118 For example, on a Digital Unix machine:
120 hwclock --setepoch --epoch=1952
122
126 The following options apply to most functions.
127 -u, --utc
129 --localtime
131 Indicates that the Hardware Clock is kept in Coordinated Univer‐
132 sal Time or local time, respectively. It is your choice whether
133 to keep your clock in UTC or local time, but nothing in the
134 clock tells which you've chosen. So this option is how you give
135 that information to hwclock.
136 If you specify the wrong one of these options (or specify nei‐
138 ther and take a wrong default), both setting and querying of the
139 Hardware Clock will be messed up.
140 If you specify neither --utc nor --localtime , the default is
142 whichever was specified the last time hwclock was used to set
143 the clock (i.e. hwclock was successfully run with the --set,
144 --systohc, or --adjust options), as recorded in the adjtime
145 file. If the adjtime file doesn't exist, the default is local
146 time.
147 --noadjfile
150 disables the facilities provided by /etc/adjtime. hwclock will
151 not read nor write to that file with this option. Either --utc
152 or --localtime must be specified when using this option.
153 --adjfile=filename
156 overrides the default /etc/adjtime.
157 -f, --rtc=filename
160 overrides the default /dev file name, which is /dev/rtc on many
161 platforms but may be /dev/rtc0, /dev/rtc1, and so on.
162 --directisa
165 is meaningful only on an ISA machine or an Alpha (which imple‐
166 ments enough of ISA to be, roughly speaking, an ISA machine for
167 hwclock's purposes). For other machines, it has no effect.
168 This option tells hwclock to use explicit I/O instructions to
169 access the Hardware Clock. Without this option, hwclock will
170 try to use the /dev/rtc device (which it assumes to be driven by
171 the rtc device driver). If it is unable to open the device (for
172 read), it will use the explicit I/O instructions anyway.
173 The rtc device driver was new in Linux Release 2.
175 --badyear
177 Indicates that the Hardware Clock is incapable of storing years
178 outside the range 1994-1999. There is a problem in some BIOSes
179 (almost all Award BIOSes made between 4/26/94 and 5/31/95)
180 wherein they are unable to deal with years after 1999. If one
181 attempts to set the year-of-century value to something less than
182 94 (or 95 in some cases), the value that actually gets set is 94
183 (or 95). Thus, if you have one of these machines, hwclock can‐
184 not set the year after 1999 and cannot use the value of the
185 clock as the true time in the normal way.
186 To compensate for this (without your getting a BIOS update,
188 which would definitely be preferable), always use --badyear if
189 you have one of these machines. When hwclock knows it's working
190 with a brain-damaged clock, it ignores the year part of the
191 Hardware Clock value and instead tries to guess the year based
192 on the last calibrated date in the adjtime file, by assuming
193 that that date is within the past year. For this to work, you
194 had better do a hwclock --set or hwclock --systohc at least once
195 a year!
196 Though hwclock ignores the year value when it reads the Hardware
198 Clock, it sets the year value when it sets the clock. It sets
199 it to 1995, 1996, 1997, or 1998, whichever one has the same
200 position in the leap year cycle as the true year. That way, the
201 Hardware Clock inserts leap days where they belong. Again, if
202 you let the Hardware Clock run for more than a year without set‐
203 ting it, this scheme could be defeated and you could end up los‐
204 ing a day.
205 hwclock warns you that you probably need --badyear whenever it
207 finds your Hardware Clock set to 1994 or 1995.
208 --srm This option is equivalent to --epoch=1900 and is used to specify
211 the most common epoch on Alphas with SRM console.
212 --arc This option is equivalent to --epoch=1980 and is used to specify
214 the most common epoch on Alphas with ARC console (but Ruffians
215 have epoch 1900).
216 --jensen
218 --funky-toy
220 These two options specify what kind of Alpha machine you have.
221 They are invalid if you don't have an Alpha and are usually
222 unnecessary if you do, because hwclock should be able to deter‐
223 mine by itself what it's running on, at least when /proc is
224 mounted. (If you find you need one of these options to make
225 hwclock work, contact the maintainer to see if the program can
226 be improved to detect your system automatically. Output of
227 `hwclock --debug' and `cat /proc/cpuinfo' may be of interest.)
228 --jensen means you are running on a Jensen model.
230 --funky-toy means that on your machine, one has to use the UF
232 bit instead of the UIP bit in the Hardware Clock to detect a
233 time transition. "Toy" in the option name refers to the Time Of
234 Year facility of the machine.
235 --test Do everything except actually updating the Hardware Clock or
239 anything else. This is useful, especially in conjunction with
240 --debug, in learning about hwclock.
241 --debug
243 Display a lot of information about what hwclock is doing inter‐
244 nally. Some of its function is complex and this output can help
245 you understand how the program works.
246
251 There are two main clocks in a Linux system:
252 The Hardware Clock: This is a clock that runs independently of any con‐
254 trol program running in the CPU and even when the machine is powered
255 off.
256 On an ISA system, this clock is specified as part of the ISA standard.
258 The control program can read or set this clock to a whole second, but
259 the control program can also detect the edges of the 1 second clock
260 ticks, so the clock actually has virtually infinite precision.
261 This clock is commonly called the hardware clock, the real time clock,
263 the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its
264 capitalized form, was coined for use by hwclock because all of the
265 other names are inappropriate to the point of being misleading.
266 So for example, some non-ISA systems have a few real time clocks with
268 only one of them having its own power domain. A very low power exter‐
269 nal I2C or SPI clock chip might be used with a backup battery as the
270 hardware clock to initialize a more functional integrated real-time
271 clock which is used for most other purposes.
272 The System Time: This is the time kept by a clock inside the Linux ker‐
274 nel and driven by a timer interrupt. (On an ISA machine, the timer
275 interrupt is part of the ISA standard). It has meaning only while
276 Linux is running on the machine. The System Time is the number of sec‐
277 onds since 00:00:00 January 1, 1970 UTC (or more succinctly, the number
278 of seconds since 1969). The System Time is not an integer, though. It
279 has virtually infinite precision.
280 The System Time is the time that matters. The Hardware Clock's basic
282 purpose in a Linux system is to keep time when Linux is not running.
283 You initialize the System Time to the time from the Hardware Clock when
284 Linux starts up, and then never use the Hardware Clock again. Note
285 that in DOS, for which ISA was designed, the Hardware Clock is the only
286 real time clock.
287 It is important that the System Time not have any discontinuities such
289 as would happen if you used the date(1L) program to set it while the
290 system is running. You can, however, do whatever you want to the Hard‐
291 ware Clock while the system is running, and the next time Linux starts
292 up, it will do so with the adjusted time from the Hardware Clock.
293 A Linux kernel maintains a concept of a local timezone for the system.
295 But don't be misled -- almost nobody cares what timezone the kernel
296 thinks it is in. Instead, programs that care about the timezone (per‐
297 haps because they want to display a local time for you) almost always
298 use a more traditional method of determining the timezone: They use the
299 TZ environment variable and/or the /usr/share/zoneinfo directory, as
300 explained in the man page for tzset(3). However, some programs and
301 fringe parts of the Linux kernel such as filesystems use the kernel
302 timezone value. An example is the vfat filesystem. If the kernel
303 timezone value is wrong, the vfat filesystem will report and set the
304 wrong timestamps on files.
305 hwclock sets the kernel timezone to the value indicated by TZ and/or
307 /usr/share/zoneinfo when you set the System Time using the --hctosys
308 option.
309 The timezone value actually consists of two parts: 1) a field tz_min‐
311 uteswest indicating how many minutes local time (not adjusted for DST)
312 lags behind UTC, and 2) a field tz_dsttime indicating the type of Day‐
313 light Savings Time (DST) convention that is in effect in the locality
314 at the present time. This second field is not used under Linux and is
315 always zero. (See also settimeofday(2).)
316
319 hwclock uses many different ways to get and set Hardware Clock values.
320 The most normal way is to do I/O to the device special file /dev/rtc,
321 which is presumed to be driven by the rtc device driver. However, this
322 method is not always available. For one thing, the rtc driver is a
323 relatively recent addition to Linux. Older systems don't have it.
324 Also, though there are versions of the rtc driver that work on DEC
325 Alphas, there appear to be plenty of Alphas on which the rtc driver
326 does not work (a common symptom is hwclock hanging). Moreover, recent
327 Linux systems have more generic support for RTCs, even systems that
328 have more than one, so you might need to override the default by speci‐
329 fying /dev/rtc0 or /dev/rtc1 instead.
330 On older systems, the method of accessing the Hardware Clock depends on
332 the system hardware.
333 On an ISA system, hwclock can directly access the "CMOS memory" regis‐
335 ters that constitute the clock, by doing I/O to Ports 0x70 and 0x71.
336 It does this with actual I/O instructions and consequently can only do
337 it if running with superuser effective userid. (In the case of a
338 Jensen Alpha, there is no way for hwclock to execute those I/O instruc‐
339 tions, and so it uses instead the /dev/port device special file, which
340 provides almost as low-level an interface to the I/O subsystem).
341 This is a really poor method of accessing the clock, for all the rea‐
343 sons that user space programs are generally not supposed to do direct
344 I/O and disable interrupts. Hwclock provides it because it is the only
345 method available on ISA and Alpha systems which don't have working rtc
346 device drivers available.
347 On an m68k system, hwclock can access the clock via the console driver,
350 via the device special file /dev/tty1.
351 hwclock tries to use /dev/rtc. If it is compiled for a kernel that
353 doesn't have that function or it is unable to open /dev/rtc (or the
354 alternative special file you've defined on the command line) hwclock
355 will fall back to another method, if available. On an ISA or Alpha
356 machine, you can force hwclock to use the direct manipulation of the
357 CMOS registers without even trying /dev/rtc by specifying the --direc‐
358 tisa option.
359
363 The Hardware Clock is usually not very accurate. However, much of its
364 inaccuracy is completely predictable - it gains or loses the same
365 amount of time every day. This is called systematic drift. hwclock's
366 "adjust" function lets you make systematic corrections to correct the
367 systematic drift.
368 It works like this: hwclock keeps a file, /etc/adjtime, that keeps some
370 historical information. This is called the adjtime file.
371 Suppose you start with no adjtime file. You issue a hwclock --set com‐
373 mand to set the Hardware Clock to the true current time. Hwclock cre‐
374 ates the adjtime file and records in it the current time as the last
375 time the clock was calibrated. 5 days later, the clock has gained 10
376 seconds, so you issue another hwclock --set command to set it back 10
377 seconds. Hwclock updates the adjtime file to show the current time as
378 the last time the clock was calibrated, and records 2 seconds per day
379 as the systematic drift rate. 24 hours go by, and then you issue a
380 hwclock --adjust command. Hwclock consults the adjtime file and sees
381 that the clock gains 2 seconds per day when left alone and that it has
382 been left alone for exactly one day. So it subtracts 2 seconds from
383 the Hardware Clock. It then records the current time as the last time
384 the clock was adjusted. Another 24 hours goes by and you issue another
385 hwclock --adjust. Hwclock does the same thing: subtracts 2 seconds and
386 updates the adjtime file with the current time as the last time the
387 clock was adjusted.
388 Every time you calibrate (set) the clock (using --set or --systohc),
390 hwclock recalculates the systematic drift rate based on how long it has
391 been since the last calibration, how long it has been since the last
392 adjustment, what drift rate was assumed in any intervening adjustments,
393 and the amount by which the clock is presently off.
394 A small amount of error creeps in any time hwclock sets the clock, so
396 it refrains from making an adjustment that would be less than 1 second.
397 Later on, when you request an adjustment again, the accumulated drift
398 will be more than a second and hwclock will do the adjustment then.
399 It is good to do a hwclock --adjust just before the hwclock --hctosys
401 at system startup time, and maybe periodically while the system is run‐
402 ning via cron.
403 The adjtime file, while named for its historical purpose of controlling
405 adjustments only, actually contains other information for use by
406 hwclock in remembering information from one invocation to the next.
407 The format of the adjtime file is, in ASCII:
409 Line 1: 3 numbers, separated by blanks: 1) systematic drift rate in
411 seconds per day, floating point decimal; 2) Resulting number of seconds
412 since 1969 UTC of most recent adjustment or calibration, decimal inte‐
413 ger; 3) zero (for compatibility with clock(8)) as a decimal integer.
414 Line 2: 1 number: Resulting number of seconds since 1969 UTC of most
416 recent calibration. Zero if there has been no calibration yet or it is
417 known that any previous calibration is moot (for example, because the
418 Hardware Clock has been found, since that calibration, not to contain a
419 valid time). This is a decimal integer.
420 Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to
422 Coordinated Universal Time or local time. You can always override this
423 value with options on the hwclock command line.
424 You can use an adjtime file that was previously used with the clock(8)
426 program with hwclock.
427
431 You should be aware of another way that the Hardware Clock is kept syn‐
432 chronized in some systems. The Linux kernel has a mode wherein it
433 copies the System Time to the Hardware Clock every 11 minutes. This is
434 a good mode to use when you are using something sophisticated like ntp
435 to keep your System Time synchronized. (ntp is a way to keep your Sys‐
436 tem Time synchronized either to a time server somewhere on the network
437 or to a radio clock hooked up to your system. See RFC 1305).
438 This mode (we'll call it "11 minute mode") is off until something turns
440 it on. The ntp daemon xntpd is one thing that turns it on. You can
441 turn it off by running anything, including hwclock --hctosys, that sets
442 the System Time the old fashioned way.
443 If your system runs with 11 minute mode on, don't use hwclock --adjust
445 or hwclock --hctosys. You'll just make a mess. It is acceptable to
446 use a hwclock --hctosys at startup time to get a reasonable System Time
447 until your system is able to set the System Time from the external
448 source and start 11 minute mode.
449
453 There is some sort of standard that defines CMOS memory Byte 50 on an
454 ISA machine as an indicator of what century it is. hwclock does not
455 use or set that byte because there are some machines that don't define
456 the byte that way, and it really isn't necessary anyway, since the
457 year-of-century does a good job of implying which century it is.
458 If you have a bona fide use for a CMOS century byte, contact the
460 hwclock maintainer; an option may be appropriate.
461 Note that this section is only relevant when you are using the "direct
463 ISA" method of accessing the Hardware Clock. ACPI provides a standard
464 way to access century values, when they are supported by the hardware.
465
468 TZ
469
472 /etc/adjtime /usr/share/zoneinfo/ (/usr/lib/zoneinfo on old systems)
473 /dev/rtc /dev/rtc0 /dev/port /dev/tty1 /proc/cpuinfo
474
477 date(1), gettimeofday(2), settimeofday(2), crontab(1), tzset(3)
478
481 Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
482 based on work done on the clock program by Charles Hedrick, Rob Hooft,
483 and Harald Koenig. See the source code for complete history and cred‐
484 its.
485
488 The hwclock command is part of the util-linux-ng package and is avail‐
489 able from ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.
490 06 August 2008 HWCLOCK(8)