| .TH HWCLOCK 8 "06 August 2008" |
| .SH NAME |
| hwclock \- query and set the hardware clock (RTC) |
| .SH SYNOPSIS |
| .B hwclock |
| .RI [ functions ] |
| .RI [ options ] |
| |
| .SH DESCRIPTION |
| .B hwclock |
| is a tool for accessing the Hardware Clock. You can display the |
| current time, set the Hardware Clock to a specified time, set the |
| Hardware Clock to the System Time, and set the System Time from the |
| Hardware Clock. |
| .PP |
| You can also run |
| .B hwclock |
| periodically to insert or remove time from the Hardware Clock to |
| compensate for systematic drift (where the clock consistently gains or |
| loses time at a certain rate if left to run). |
| |
| .SH FUNCTIONS |
| You need exactly one of the following options to tell |
| .B hwclock |
| what function to perform: |
| .PP |
| .TP |
| .BR \-r , \ \-\-show |
| Read the Hardware Clock and print the time on Standard Output. |
| The time shown is always in local time, even if you keep your Hardware Clock |
| in Coordinated Universal Time. See the |
| .B \-\-utc |
| option. |
| |
| .TP |
| .B \-\-set |
| Set the Hardware Clock to the time given by the |
| .B \-\-date |
| option. |
| .TP |
| .BR \-s , \ \-\-hctosys |
| Set the System Time from the Hardware Clock. |
| |
| Also set the kernel's timezone value to the local timezone |
| as indicated by the TZ environment variable and/or |
| .IR /usr/share/zoneinfo , |
| as |
| .BR tzset (3) |
| would interpret them. |
| The obsolete tz_dsttime field of the kernel's timezone value is set |
| to DST_NONE. (For details on what this field used to mean, see |
| .BR settimeofday (2).) |
| |
| This is a good option to use in one of the system startup scripts. |
| .TP |
| .BR \-w , \ \-\-systohc |
| Set the Hardware Clock to the current System Time. |
| .TP |
| .B \-\-systz |
| Reset the System Time based on the current timezone. |
| |
| Also set the kernel's timezone value to the local timezone |
| as indicated by the TZ environment variable and/or |
| .IR /usr/share/zoneinfo , |
| as |
| .BR tzset (3) |
| would interpret them. |
| The obsolete tz_dsttime field of the kernel's timezone value is set |
| to DST_NONE. (For details on what this field used to mean, see |
| .BR settimeofday (2).) |
| |
| This is an alternate option to |
| .B \-\-hctosys |
| that does not read the hardware clock, and may be used in system startup |
| scripts for recent 2.6 kernels where you know the System Time contains |
| the Hardware Clock time. |
| .TP |
| .B \-\-adjust |
| Add or subtract time from the Hardware Clock to account for systematic |
| drift since the last time the clock was set or adjusted. See discussion |
| below. |
| .TP |
| .B \-\-getepoch |
| Print the kernel's Hardware Clock epoch value to standard output. |
| This is the number of years into AD to which a zero year value in the |
| Hardware Clock refers. For example, if you are using the convention |
| that the year counter in your Hardware Clock contains the number of |
| full years since 1952, then the kernel's Hardware Counter epoch value |
| must be 1952. |
| |
| This epoch value is used whenever hwclock reads or sets the Hardware Clock. |
| .TP |
| .B \-\-setepoch |
| Set the kernel's Hardware Clock epoch value to the value specified by the |
| .B \-\-epoch |
| option. See the |
| .B \-\-getepoch |
| option for details. |
| .TP |
| .BR \-v , \ \-\-version |
| Print the version of |
| .B hwclock |
| on Standard Output. |
| .TP |
| .BI \-\-date= date_string |
| You need this option if you specify the |
| .B \-\-set |
| option. Otherwise, it is ignored. |
| This specifies the time to which to set the Hardware Clock. |
| The value of this option is an argument to the |
| .BR date (1) |
| program. |
| For example, |
| .sp |
| .I hwclock --set --date="9/22/96 16:45:05" |
| .sp |
| The argument is in local time, even if you keep your Hardware Clock in |
| Coordinated Universal time. See the |
| .B \-\-utc |
| option. |
| |
| .TP |
| .BI \-\-epoch= year |
| Specifies the year which is the beginning of the Hardware Clock's |
| epoch. I.e. the number of years into AD to which a zero value in the |
| Hardware Clock's year counter refers. It is used together with |
| the \-\-setepoch option to set the kernel's idea of the epoch of the |
| Hardware Clock, or otherwise to specify the epoch for use with |
| direct ISA access. |
| |
| For example, on a Digital Unix machine: |
| .sp |
| .I hwclock --setepoch --epoch=1952 |
| |
| |
| .SH OPTIONS |
| .PP |
| The following options apply to most functions. |
| .TP |
| .BR \-u , \ \-\-utc |
| .TP |
| .B \-\-localtime |
| Indicates that the Hardware Clock is kept in Coordinated Universal |
| Time or local time, respectively. It is your choice whether to keep |
| your clock in UTC or local time, but nothing in the clock tells which |
| you've chosen. So this option is how you give that information to |
| .BR hwclock . |
| |
| If you specify the wrong one of these options (or specify neither and |
| take a wrong default), both setting and querying of the Hardware Clock |
| will be messed up. |
| |
| If you specify neither |
| .B \-\-utc |
| nor |
| .B \-\-localtime |
| , the default is whichever was specified the last time |
| .B hwclock |
| was used to set the clock (i.e. hwclock was successfully run with the |
| .BR \-\-set , |
| .BR \-\-systohc , |
| or |
| .B \-\-adjust |
| options), as recorded in the adjtime file. If the adjtime file doesn't |
| exist, the default is local time. |
| |
| .TP |
| .B \-\-noadjfile |
| disables the facilities provided by |
| .IR /etc/adjtime . |
| .B hwclock |
| will not read nor write to that file with this option. Either |
| .B \-\-utc |
| or |
| .B \-\-localtime |
| must be specified when using this option. |
| |
| .TP |
| .BI \-\-adjfile= filename |
| overrides the default /etc/adjtime. |
| |
| .TP |
| .BR \-f , \ \-\-rtc=\fIfilename\fB |
| overrides the default /dev file name, which is |
| .IR /dev/rtc |
| on many platforms but may be |
| .IR /dev/rtc0 , |
| .IR /dev/rtc1 , |
| and so on. |
| |
| .TP |
| .B \-\-directisa |
| is meaningful only on an ISA machine or an Alpha (which implements enough |
| of ISA to be, roughly speaking, an ISA machine for |
| .BR hwclock 's |
| purposes). For other machines, it has no effect. This option tells |
| .B hwclock |
| to use explicit I/O instructions to access the Hardware Clock. |
| Without this option, |
| .B hwclock |
| will try to use the /dev/rtc device (which it assumes to be driven by the |
| rtc device driver). If it is unable to open the device (for read), it will |
| use the explicit I/O instructions anyway. |
| |
| The rtc device driver was new in Linux Release 2. |
| .TP |
| .B \-\-badyear |
| Indicates that the Hardware Clock is incapable of storing years outside |
| the range 1994-1999. There is a problem in some BIOSes (almost all |
| Award BIOSes made between 4/26/94 and 5/31/95) wherein they are unable |
| to deal with years after 1999. If one attempts to set the year-of-century |
| value to something less than 94 (or 95 in some cases), the value that |
| actually gets set is 94 (or 95). Thus, if you have one of these machines, |
| .B hwclock |
| cannot set the year after 1999 and cannot use the value of the clock as |
| the true time in the normal way. |
| |
| To compensate for this (without your getting a BIOS update, which would |
| definitely be preferable), always use |
| .B \-\-badyear |
| if you have one of these machines. When |
| .B hwclock |
| knows it's working with a brain-damaged clock, it ignores the year part of |
| the Hardware Clock value and instead tries to guess the year based on the |
| last calibrated date in the adjtime file, by assuming that that date is |
| within the past year. For this to work, you had better do a |
| .I hwclock \-\-set |
| or |
| .I hwclock \-\-systohc |
| at least once a year! |
| |
| Though |
| .B hwclock |
| ignores the year value when it reads the Hardware Clock, it sets the |
| year value when it sets the clock. It sets it to 1995, 1996, 1997, or |
| 1998, whichever one has the same position in the leap year cycle as |
| the true year. That way, the Hardware Clock inserts leap days where |
| they belong. Again, if you let the Hardware Clock run for more than a |
| year without setting it, this scheme could be defeated and you could |
| end up losing a day. |
| |
| .B hwclock |
| warns you that you probably need |
| .B \-\-badyear |
| whenever it finds your Hardware Clock set to 1994 or 1995. |
| |
| .TP |
| .B \-\-srm |
| This option is equivalent to |
| .B \-\-epoch=1900 |
| and is used to specify the most common epoch on Alphas |
| with SRM console. |
| .TP |
| .B \-\-arc |
| This option is equivalent to |
| .B \-\-epoch=1980 |
| and is used to specify the most common epoch on Alphas |
| with ARC console (but Ruffians have epoch 1900). |
| .TP |
| .B \-\-jensen |
| .TP |
| .B \-\-funky\-toy |
| These two options specify what kind of Alpha machine you have. They |
| are invalid if you don't have an Alpha and are usually unnecessary |
| if you do, because |
| .B hwclock |
| should be able to determine by itself what it's |
| running on, at least when |
| .I /proc |
| is mounted. |
| (If you find you need one of these options to make |
| .B hwclock |
| work, contact the maintainer to see if the program can be improved |
| to detect your system automatically. Output of `hwclock --debug' |
| and `cat /proc/cpuinfo' may be of interest.) |
| |
| .B \-\-jensen |
| means you are running on a Jensen model. |
| |
| .B \-\-funky\-toy |
| means that on your machine, one has to use the UF bit instead |
| of the UIP bit in the Hardware Clock to detect a time transition. "Toy" |
| in the option name refers to the Time Of Year facility of the machine. |
| |
| |
| .TP |
| .B \-\-test |
| Do everything except actually updating the Hardware Clock or anything |
| else. This is useful, especially in conjunction with |
| .BR \-\-debug , |
| in learning about |
| .BR hwclock . |
| .TP |
| .B \-\-debug |
| Display a lot of information about what |
| .B hwclock |
| is doing internally. Some of its function is complex and this output |
| can help you understand how the program works. |
| |
| |
| .SH NOTES |
| |
| |
| .SH Clocks in a Linux System |
| .PP |
| There are two main clocks in a Linux system: |
| .PP |
| .B The Hardware Clock: |
| This is a clock that runs independently of any control program running |
| in the CPU and even when the machine is powered off. |
| |
| On an ISA system, this clock is specified as part of the ISA standard. |
| The control program can read or set this clock to a whole second, but |
| the control program can also detect the edges of the 1 second clock |
| ticks, so the clock actually has virtually infinite precision. |
| .PP |
| This clock is commonly called the hardware clock, the real time clock, |
| the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its |
| capitalized form, was coined for use by |
| .B hwclock |
| because all of the other names are inappropriate to the point of being |
| misleading. |
| .PP |
| So for example, some non-ISA systems have a few real time clocks with |
| only one of them having its own power domain. |
| A very low power external I2C or SPI clock chip might be used with a |
| backup battery as the hardware clock to initialize a more functional |
| integrated real-time clock which is used for most other purposes. |
| .PP |
| .B The System Time: |
| This is the time kept by a clock inside the Linux kernel and driven by |
| a timer interrupt. (On an ISA machine, the timer interrupt is part of |
| the ISA standard). It has meaning only while Linux is running on the |
| machine. The System Time is the number of seconds since 00:00:00 |
| January 1, 1970 UTC (or more succinctly, the number of seconds since |
| 1969). The System Time is not an integer, though. It has virtually |
| infinite precision. |
| .PP |
| The System Time is the time that matters. The Hardware Clock's basic |
| purpose in a Linux system is to keep time when Linux is not running. You |
| initialize the System Time to the time from the Hardware Clock when Linux |
| starts up, and then never use the Hardware Clock again. Note that in DOS, |
| for which ISA was designed, the Hardware Clock is the only real time clock. |
| .PP |
| It is important that the System Time not have any discontinuities such as |
| would happen if you used the |
| .BR date (1L) |
| program to set it while the system is running. You can, however, do whatever |
| you want to the Hardware Clock while the system is running, and the next |
| time Linux starts up, it will do so with the adjusted time from the Hardware |
| Clock. You can also use the program |
| .BR adjtimex (8) |
| to smoothly adjust the System Time while the system runs. |
| .PP |
| A Linux kernel maintains a concept of a local timezone for the system. |
| But don't be misled -- almost nobody cares what timezone the kernel |
| thinks it is in. Instead, programs that care about the timezone |
| (perhaps because they want to display a local time for you) almost |
| always use a more traditional method of determining the timezone: They |
| use the TZ environment variable and/or the |
| .I /usr/share/zoneinfo |
| directory, as explained in the man page for |
| .BR tzset (3). |
| However, some |
| programs and fringe parts of the Linux kernel such as filesystems use |
| the kernel timezone value. An example is the vfat filesystem. If the |
| kernel timezone value is wrong, the vfat filesystem will report and |
| set the wrong timestamps on files. |
| .PP |
| .B hwclock |
| sets the kernel timezone to the value indicated by TZ and/or |
| .I /usr/share/zoneinfo |
| when you set the System Time using the |
| .B \-\-hctosys |
| option. |
| .PP |
| The timezone value actually consists of two parts: 1) a field |
| tz_minuteswest indicating how many minutes local time (not adjusted |
| for DST) lags behind UTC, and 2) a field tz_dsttime indicating |
| the type of Daylight Savings Time (DST) convention that is in effect |
| in the locality at the present time. |
| This second field is not used under Linux and is always zero. |
| (See also |
| .BR settimeofday (2).) |
| |
| .SH How hwclock Accesses the Hardware Clock |
| .PP |
| .B hwclock |
| uses many different ways to get and set Hardware Clock values. |
| The most normal way is to do I/O to the device special file /dev/rtc, |
| which is presumed to be driven by the rtc device driver. However, |
| this method is not always available. For one thing, the rtc driver is |
| a relatively recent addition to Linux. Older systems don't have it. |
| Also, though there are versions of the rtc driver that work on DEC |
| Alphas, there appear to be plenty of Alphas on which the rtc driver |
| does not work (a common symptom is hwclock hanging). |
| Moreover, recent Linux systems have more generic support for RTCs, |
| even systems that have more than one, so you might need to override |
| the default by specifying |
| .I /dev/rtc0 |
| or |
| .I /dev/rtc1 |
| instead. |
| .PP |
| On older systems, the method of accessing the Hardware Clock depends on |
| the system hardware. |
| .PP |
| On an ISA system, |
| .B hwclock |
| can directly access the "CMOS memory" registers that |
| constitute the clock, by doing I/O to Ports 0x70 and 0x71. It does |
| this with actual I/O instructions and consequently can only do it if |
| running with superuser effective userid. (In the case of a Jensen |
| Alpha, there is no way for |
| .B hwclock |
| to execute those I/O instructions, and so it uses instead the |
| /dev/port device special file, which provides almost as low-level an |
| interface to the I/O subsystem). |
| |
| This is a really poor method of accessing the clock, for all the |
| reasons that user space programs are generally not supposed to do |
| direct I/O and disable interrupts. Hwclock provides it because it is |
| the only method available on ISA and Alpha systems which don't have |
| working rtc device drivers available. |
| |
| .PP |
| On an m68k system, |
| .B hwclock |
| can access the clock via the console driver, via the device special |
| file /dev/tty1. |
| .PP |
| .B hwclock |
| tries to use /dev/rtc. If it is compiled for a kernel that doesn't have |
| that function or it is unable to open /dev/rtc |
| (or the alternative special file you've defined on the command line) |
| .B hwclock |
| will fall back to another method, if available. On an ISA or Alpha |
| machine, you can force |
| .B hwclock |
| to use the direct manipulation of the CMOS registers without even trying |
| .I /dev/rtc |
| by specifying the |
| .B \-\-directisa |
| option. |
| |
| |
| .SH The Adjust Function |
| .PP |
| The Hardware Clock is usually not very accurate. However, much of its |
| inaccuracy is completely predictable - it gains or loses the same amount |
| of time every day. This is called systematic drift. |
| .BR hwclock 's |
| "adjust" function lets you make systematic corrections to correct the |
| systematic drift. |
| .PP |
| It works like this: |
| .B hwclock |
| keeps a file, |
| .IR /etc/adjtime , |
| that keeps some historical information. This is called the adjtime file. |
| .PP |
| Suppose you start with no adjtime file. You issue a |
| .I hwclock \-\-set |
| command to set the Hardware Clock to the true current time. |
| .B Hwclock |
| creates the adjtime file and records in it the current time as the |
| last time the clock was calibrated. |
| 5 days later, the clock has gained 10 seconds, so you issue another |
| .I hwclock \-\-set |
| command to set it back 10 seconds. |
| .B Hwclock |
| updates the adjtime file to show the current time as the last time the |
| clock was calibrated, and records 2 seconds per day as the systematic |
| drift rate. 24 hours go by, and then you issue a |
| .I hwclock \-\-adjust |
| command. |
| .B Hwclock |
| consults the adjtime file and sees that the clock gains 2 seconds per |
| day when left alone and that it has been left alone for exactly one |
| day. So it subtracts 2 seconds from the Hardware Clock. It then |
| records the current time as the last time the clock was adjusted. |
| Another 24 hours goes by and you issue another |
| .IR "hwclock \-\-adjust" . |
| .B Hwclock |
| does the same thing: subtracts 2 seconds and updates the adjtime file |
| with the current time as the last time the clock was adjusted. |
| .PP |
| Every time you calibrate (set) the clock (using |
| .I \-\-set |
| or |
| .IR \-\-systohc ), |
| .B hwclock |
| recalculates the systematic drift rate based on how long it has been |
| since the last calibration, how long it has been since the last |
| adjustment, what drift rate was assumed in any intervening |
| adjustments, and the amount by which the clock is presently off. |
| .PP |
| A small amount of error creeps in any time |
| .B hwclock |
| sets the clock, so it refrains from making an adjustment that would be |
| less than 1 second. Later on, when you request an adjustment again, |
| the accumulated drift will be more than a second and |
| .B hwclock |
| will do the adjustment then. |
| .PP |
| It is good to do a |
| .I hwclock \-\-adjust |
| just before the |
| .I hwclock \-\-hctosys |
| at system startup time, and maybe periodically while the system is |
| running via cron. |
| .PP |
| The adjtime file, while named for its historical purpose of controlling |
| adjustments only, actually contains other information for use by hwclock |
| in remembering information from one invocation to the next. |
| .PP |
| The format of the adjtime file is, in ASCII: |
| .PP |
| Line 1: 3 numbers, separated by blanks: 1) systematic drift rate in |
| seconds per day, floating point decimal; 2) Resulting number of |
| seconds since 1969 UTC of most recent adjustment or calibration, |
| decimal integer; 3) zero (for compatibility with |
| .BR clock (8)) |
| as a decimal integer. |
| .PP |
| Line 2: 1 number: Resulting number of seconds since 1969 UTC of most |
| recent calibration. Zero if there has been no calibration yet or it |
| is known that any previous calibration is moot (for example, because |
| the Hardware Clock has been found, since that calibration, not to |
| contain a valid time). This is a decimal integer. |
| .PP |
| Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to |
| Coordinated Universal Time or local time. You can always override this |
| value with options on the |
| .B hwclock |
| command line. |
| .PP |
| You can use an adjtime file that was previously used with the |
| .BR clock (8) |
| program with |
| .BR hwclock . |
| |
| |
| .SH "Automatic Hardware Clock Synchronization By the Kernel" |
| |
| You should be aware of another way that the Hardware Clock is kept |
| synchronized in some systems. The Linux kernel has a mode wherein it |
| copies the System Time to the Hardware Clock every 11 minutes. |
| This is a good mode to use when you are using something sophisticated |
| like ntp to keep your System Time synchronized. (ntp is a way to keep |
| your System Time synchronized either to a time server somewhere on the |
| network or to a radio clock hooked up to your system. See RFC 1305). |
| |
| This mode (we'll call it "11 minute mode") is off until something |
| turns it on. The ntp daemon xntpd is one thing that turns it on. You |
| can turn it off by running anything, including |
| .IR "hwclock \-\-hctosys" , |
| that sets the System Time the old fashioned way. |
| |
| To see if it is on or |
| off, use the command |
| .I adjtimex \-\-print |
| and look at the value of "status". If the "64" bit of this number |
| (expressed in binary) equal to 0, 11 minute mode is on. Otherwise, it |
| is off. |
| |
| If your system runs with 11 minute mode on, don't use |
| .I hwclock \-\-adjust |
| or |
| .IR "hwclock \-\-hctosys" . |
| You'll just make a mess. It is acceptable to use a |
| .I hwclock \-\-hctosys |
| at startup time to get a reasonable System Time until your system is |
| able to set the System Time from the external source and start 11 |
| minute mode. |
| |
| |
| .SH ISA Hardware Clock Century value |
| |
| There is some sort of standard that defines CMOS memory Byte 50 on an ISA |
| machine as an indicator of what century it is. |
| .B hwclock |
| does not use or set that byte because there are some machines that |
| don't define the byte that way, and it really isn't necessary anyway, |
| since the year-of-century does a good job of implying which century it |
| is. |
| |
| If you have a bona fide use for a CMOS century byte, contact the |
| .B hwclock |
| maintainer; an option may be appropriate. |
| |
| Note that this section is only relevant when you are using the "direct |
| ISA" method of accessing the Hardware Clock. |
| ACPI provides a standard way to access century values, when they |
| are supported by the hardware. |
| |
| .SH "ENVIRONMENT VARIABLES" |
| .I TZ |
| |
| .SH FILES |
| .I /etc/adjtime |
| .I /usr/share/zoneinfo/ |
| .RI ( /usr/lib/zoneinfo |
| on old systems) |
| .I /dev/rtc |
| .I /dev/rtc0 |
| .I /dev/port |
| .I /dev/tty1 |
| .I /proc/cpuinfo |
| |
| .SH "SEE ALSO" |
| .BR adjtimex (8), |
| .BR date (1), |
| .BR gettimeofday (2), |
| .BR settimeofday (2), |
| .BR crontab (1), |
| .BR tzset (3) |
| |
| .SH AUTHORS |
| Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com), |
| based on work done on the |
| .I clock |
| program by Charles Hedrick, Rob Hooft, and Harald Koenig. |
| See the source code for complete history and credits. |
| |
| .SH AVAILABILITY |
| The hwclock command is part of the util-linux-ng package and is available from |
| ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/. |