| .\" hwclock.8.in -- man page for util-linux' hwclock |
| .\" |
| .\" 2015-01-07 J William Piggott |
| .\" Authored new section: DATE-TIME CONFIGURATION. |
| .\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'. |
| .\" Errata and drop outdated language. |
| .\" Updates for v2.26 |
| .\" |
| .\" |
| .\" ------------------------------- |
| .\" Included for troff portability. |
| .\" Continuation line for .TP header. |
| .de TQ |
| . br |
| . ns |
| . TP \\$1\" no doublequotes around argument! |
| .. |
| . |
| .\" ------------------------------- |
| . |
| .TH HWCLOCK 8 "January 2015" "util-linux" "System Administration" |
| .SH NAME |
| hwclock \- read or set the hardware clock (RTC) |
| .SH SYNOPSIS |
| .B hwclock |
| .RI [ function ] |
| .RI [ option ...] |
| . |
| .SH DESCRIPTION |
| .B hwclock |
| is a tool for accessing the Hardware Clock. It can: display the |
| Hardware Clock time; set the Hardware Clock to a specified time; set the |
| Hardware Clock from the System Clock; set the System Clock from the |
| Hardware Clock; compensate for Hardware Clock drift; correct the System |
| Clock timescale; set the kernel's timezone, NTP timescale, and epoch |
| (Alpha only); compare the System and Hardware Clocks; and predict future |
| Hardware Clock values based on its drift rate. |
| .PP |
| Since v2.26 important changes were made to the |
| .B \-\-hctosys |
| function, the |
| .B \-\-directisa |
| option, and a new option |
| .B \-\-update\-drift |
| was added. See their respective sections below. |
| . |
| .SH FUNCTIONS |
| The following functions are mutually exclusive, only one can be given at |
| a time. If none are given the default is |
| .BR \-\-show . |
| .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 the |
| discussion below, under |
| .BR "The Adjust Function" . |
| . |
| .TP |
| .BR \-c , \ \-\-compare |
| Periodically compare the Hardware Clock to the System Time and output |
| the difference every 10 seconds. This will also print the frequency |
| offset and tick. |
| . |
| .TP |
| .B \-\-getepoch |
| .TQ |
| .B \-\-setepoch |
| These functions are for Alpha machines only. |
| .sp |
| Read and set the kernel's Hardware Clock epoch value. |
| Epoch 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 Clock epoch value |
| must be 1952. |
| .sp |
| The set function requires using the |
| .B \%\-\-epoch |
| option. |
| .sp |
| This epoch value is used whenever |
| .B \%hwclock |
| reads or sets the Hardware Clock. |
| . |
| .TP |
| .B \-\-predict |
| Predict what the Hardware Clock will read in the future based upon the |
| time given by the |
| .B \-\-date |
| option and the information in |
| .IR @ADJTIME_PATH@ . |
| This is useful, for example, to account for drift when setting a |
| Hardware Clock wakeup (aka alarm). See |
| .BR \%rtcwake (8). |
| .sp |
| Do not use this function if the Hardware Clock is being modified by |
| anything other than the current operating system's |
| .B \%hwclock |
| command, such as \%'11\ minute\ mode' or from dual-booting another OS. |
| . |
| .TP |
| .BR \-r , \ \-\-show |
| .TQ |
| .B \-\-get |
| .br |
| 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 UTC. See the |
| .B \%\-\-localtime |
| option. |
| .sp |
| Showing the Hardware Clock time is the default when no function is specified. |
| .sp |
| The |
| .B \-\-get |
| function also applies drift correction to the time read, based upon the |
| information in |
| .IR @ADJTIME_PATH@ . |
| Do not use this function if the Hardware Clock is being modified by |
| anything other than the current operating system's |
| .B \%hwclock |
| command, such as \%'11\ minute\ mode' or from dual-booting another OS. |
| . |
| .TP |
| .BR \-s , \ \-\-hctosys |
| Set the System Clock from the Hardware Clock. The time read from the Hardware |
| Clock is compensated to account for systematic drift before using it to set the |
| System Clock. See the discussion below, under |
| .BR "The Adjust Function" . |
| .sp |
| The System Clock must be kept in the UTC timescale for date-time |
| applications to work correctly in conjunction with the timezone configured |
| for the system. If the Hardware Clock is kept in local time then the time read |
| from it must be shifted to the UTC timescale before using it to set the System |
| Clock. The |
| .B \%\-\-hctosys |
| function does this based upon the information in the |
| .I @ADJTIME_PATH@ |
| file or the command line arguments |
| .BR \%\-\-localtime " and " \-\-utc . |
| Note: no daylight saving adjustment is made. See the discussion below under |
| .BR "LOCAL vs UTC" . |
| .sp |
| The kernel also keeps a timezone value, the |
| .B \%\-\-hctosys |
| function sets it to the timezone configured for the system. The system |
| timezone is configured by the TZ environment variable or the |
| .I \%/etc/localtime |
| file, as |
| .BR \%tzset (3) |
| would interpret them. |
| The obsolete tz_dsttime field of the kernel's timezone value is set |
| to zero. (For details on what this field used to mean, see |
| .BR \%settimeofday (2).) |
| .sp |
| When used in a startup script, making the |
| .B \%\-\-hctosys |
| function the first caller of |
| .BR \%settimeofday (2) |
| from boot, it will set the NTP \%'11\ minute\ mode' timescale via the |
| .I \%persistent_clock_is_local |
| kernel variable. If the Hardware Clock's timescale configuration is |
| changed then a reboot is required to inform the kernel. See the |
| discussion below, under |
| .BR "Automatic Hardware Clock Synchronization by the Kernel" . |
| .sp |
| This is a good function to use in one of the system startup scripts before the |
| file systems are mounted read/write. |
| .sp |
| This function should never be used on a running system. Jumping system time |
| will cause problems, such as, corrupted filesystem timestamps. Also, if |
| something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then |
| .B \%\-\-hctosys |
| will set the time incorrectly by including drift compensation. |
| .sp |
| Drift compensation can be inhibited by setting the drift factor in |
| .I @ADJTIME_PATH@ |
| to zero. This setting will be persistent as long as the |
| .BR \%\-\-update\-drift " option is not used with " \%\-\-systohc |
| at shutdown (or anywhere else). Another way to inhibit this is by using the |
| .BR \%\-\-noadjfile " option when calling the " \%\-\-hctosys |
| function. A third method is to delete the |
| .IR @ADJTIME_PATH@ " file." |
| .B Hwclock |
| will then default to using the UTC timescale for the Hardware Clock. If |
| the Hardware Clock is ticking local time it will need to be defined in |
| the file. This can be done by calling |
| .BR hwclock\ \-\-localtime\ \-\-adjust ; |
| when the file is not present this command will not actually |
| adjust the Clock, but it will create the file with local time |
| configured, and a drift factor of zero. |
| .sp |
| A condition under which inhibiting |
| .BR hwclock 's |
| drift correction may be desired is when dual-booting multiple operating |
| systems. If while this instance of Linux is stopped, another OS changes |
| the Hardware Clock's value, then when this instance is started again the |
| drift correction applied will be incorrect. |
| .sp |
| .RB "For " hwclock 's |
| drift correction to work properly it is imperative that nothing changes |
| the Hardware Clock while its Linux instance is not running. |
| . |
| .TP |
| .B \-\-set |
| Set the Hardware Clock to the time given by the |
| .BR \-\-date |
| option, and update the timestamps in |
| .IR @ADJTIME_PATH@ . |
| With the |
| .B --update-drift |
| option (re)calculate the drift factor. |
| . |
| .TP |
| .B \-\-systz |
| This is an alternate to the |
| .B \%\-\-hctosys |
| function that does not read the Hardware Clock nor set the System Clock; |
| consequently there is not any drift correction. It is intended to be |
| used in a startup script on systems with kernels above version 2.6 where |
| you know the System Clock has been set from the Hardware Clock by the |
| kernel during boot. |
| .sp |
| It does the following things that are detailed above in the |
| .BR \%\-\-hctosys " function:" |
| .RS |
| .IP \(bu 2 |
| Corrects the System Clock timescale to UTC as needed. Only instead of |
| accomplishing this by setting the System Clock, |
| .B hwclock |
| simply informs the kernel and it handles the change. |
| .IP \(bu 2 |
| Sets the kernel's NTP \%'11\ minute\ mode' timescale. |
| .IP \(bu 2 |
| Sets the kernel's timezone. |
| .PP |
| The first two are only available on the first call of |
| .BR \%settimeofday (2) |
| after boot. Consequently this option only makes sense when used in a |
| startup script. If the Hardware Clocks timescale configuration is |
| changed then a reboot would be required to inform the kernel. |
| .RE |
| . |
| .TP |
| .BR \-w , \ \-\-systohc |
| Set the Hardware Clock from the System Clock, and update the timestamps in |
| .IR @ADJTIME_PATH@ . |
| With the |
| .B --update-drift |
| option (re)calculate the drift factor. |
| . |
| .TP |
| .BR \-V , \ \-\-version |
| Display version information and exit. |
| . |
| .TP |
| .BR \-h , \ \-\-help |
| Display help text and exit. |
| . |
| .SH OPTIONS |
| . |
| .TP |
| .BI \-\-adjfile= filename |
| .RI "Override the default " @ADJTIME_PATH@ " file path." |
| . |
| .TP |
| .B \-\-badyear |
| Indicate 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. |
| .sp |
| 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 date is |
| within the past year. For this to work, you had better do a |
| .B \%hwclock\ \-\-set |
| or |
| .B \%hwclock\ \-\-systohc |
| at least once a year! |
| .sp |
| 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. |
| .sp |
| .B \%hwclock |
| warns you that you probably need |
| .B \%\-\-badyear |
| whenever it finds your Hardware Clock set to 1994 or 1995. |
| . |
| .TP |
| .BI \%\-\-date= date_string |
| You need this option if you specify the |
| .B \-\-set |
| or |
| .B \%\-\-predict |
| functions, otherwise it is ignored. |
| It specifies the time to which to set the Hardware Clock, or the |
| time for which to predict the Hardware Clock reading. |
| The value of this option is used as an argument to the |
| .BR date "(1) program's " \-\-date |
| option. For example: |
| .RS |
| .IP "" 4 |
| .BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 ' |
| .PP |
| The argument must be in local time, even if you keep your Hardware Clock in |
| UTC. See the |
| .B \%\-\-localtime |
| option. The argument must not be a relative time like "+5 minutes", because |
| .BR \%hwclock 's |
| precision depends upon correlation between the argument's value and when |
| the enter key is pressed. |
| .RE |
| . |
| .TP |
| .B \-\-debug |
| Display a lot of information about what |
| .B \%hwclock |
| is doing internally. Some of its functions are complex and this output |
| can help you understand how the program works. |
| . |
| .TP |
| .B \-\-directisa |
| This option is meaningful for: ISA compatible machines including x86, and |
| x86_64; and Alpha (which has a similar Hardware Clock interface). 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 use the rtc device, which it assumes to be driven by the RTC device |
| driver. As of v2.26 it will no longer automatically use directisa when |
| the rtc driver is unavailable; this was causing an unsafe condition that |
| could allow two processes to access the Hardware Clock at the same time. |
| Direct hardware access from userspace should only be used for testing, |
| troubleshooting, and as a last resort when all other methods fail. See |
| the |
| .BR \-\-rtc " option." |
| . |
| .TP |
| .BR \-f , \ \-\-rtc=\fIfilename\fR |
| .RB "Override " \%hwclock 's |
| default rtc device file name. Otherwise it will |
| use the first one found in this order: |
| .in +4 |
| .br |
| .I /dev/rtc |
| .br |
| .I /dev/rtc0 |
| .br |
| .I /dev/misc/rtc |
| .br |
| .in |
| .RB "For " IA-64: |
| .in +4 |
| .br |
| .I /dev/efirtc |
| .br |
| .I /dev/misc/efirtc |
| .in |
| . |
| .TP |
| .B \-\-localtime |
| .TQ |
| .BR \-u ", " \-\-utc |
| Indicate which timescale the Hardware Clock is set to. |
| .sp |
| The Hardware Clock may be configured to use either the UTC or the local |
| timescale, but nothing in the clock itself says which alternative is |
| being used. The |
| .BR \%\-\-localtime " or " \-\-utc |
| options give this information to the |
| .B \%hwclock |
| command. If you specify the wrong one (or specify neither and take a |
| wrong default), both setting and reading the Hardware Clock will be |
| incorrect. |
| .sp |
| If you specify neither |
| .BR \-\-utc " nor " \%\-\-localtime |
| then the one last given with a set function |
| .RB ( \-\-set ", " \%\-\-systohc ", or " \%\-\-adjust ), |
| as recorded in |
| .IR @ADJTIME_PATH@ , |
| will be used. If the adjtime file doesn't exist, the default is UTC. |
| .sp |
| Note: daylight saving time changes may be inconsistent when the |
| Hardware Clock is kept in local time. See the discussion below under |
| .BR "LOCAL vs UTC" . |
| . |
| .TP |
| .B \-\-noadjfile |
| Disable the facilities provided by |
| .IR @ADJTIME_PATH@ . |
| .B \%hwclock |
| will not read nor write to that file with this option. Either |
| .BR \-\-utc " or " \%\-\-localtime |
| must be specified when using this option. |
| . |
| .TP |
| .B \-\-test |
| Do not actually change anything on the system, i.e., the Clocks or |
| adjtime file. This is useful, especially in conjunction with |
| .BR \%\-\-debug , |
| in learning about the internal operations of hwclock. |
| . |
| .TP |
| .B \-\-update\-drift |
| Update the Hardware Clock's drift factor in |
| .IR @ADJTIME_PATH@ . |
| It is used with |
| .BR \-\-set " or " \%\-\-systohc , |
| otherwise it is ignored. |
| .sp |
| A minimum four hour period between settings is required. This is to |
| avoid invalid calculations. The longer the period, the more precise the |
| resulting drift factor will be. |
| .sp |
| This option was added in v2.26, because |
| it is typical for systems to call |
| .B \%hwclock\ \-\-systohc |
| at shutdown; with the old behaviour this would automatically |
| (re)calculate the drift factor which caused several problems: |
| .RS |
| .IP \(bu 2 |
| When using ntpd with an \%'11\ minute\ mode' kernel the drift factor |
| would be clobbered to near zero. |
| .IP \(bu 2 |
| It would not allow the use of 'cold' drift correction. With most |
| configurations using 'cold' drift will yield favorable results. Cold, |
| means when the machine is turned off which can have a significant impact |
| on the drift factor. |
| .IP \(bu 2 |
| (Re)calculating drift factor on every shutdown delivers suboptimal |
| results. For example, if ephemeral conditions cause the machine to be |
| abnormally hot the drift factor calculation would be out of range. |
| .PP |
| .RB "Having " \%hwclock |
| calculate the drift factor is a good starting point, but for optimal |
| results it will likely need to be adjusted by directly editing the |
| .I @ADJTIME_PATH@ |
| file. For most configurations once a machine's optimal drift factor is |
| crafted it should not need to be changed. Therefore, the old behavior to |
| automatically (re)calculate drift was changed and now requires this |
| option to be used. See the discussion below, under |
| .BR "The Adjust Function" . |
| .RE |
| . |
| .SH OPTIONS FOR ALPHA MACHINES ONLY |
| . |
| .TP |
| .B \-\-arc |
| This option is equivalent to |
| .BI \%\-\-epoch= 1980 |
| and is used to specify the most common epoch on Alphas |
| with ARC console (but Ruffians have an epoch of 1900). |
| . |
| .TP |
| .BI \-\-epoch= year |
| Specifies the year which is the beginning of the Hardware Clock's epoch, |
| that is 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 |
| .B \%\-\-setepoch |
| option to set the kernel's idea of the epoch of the Hardware Clock. |
| .sp |
| For example, on a Digital Unix machine: |
| .RS |
| .IP "" 4 |
| .BI hwclock\ \-\-setepoch\ \-\-epoch= 1952 |
| .RE |
| . |
| .TP |
| .B \-\-funky\-toy |
| .TQ |
| .B \-\-jensen |
| These two options specify what kind of Alpha machine you have. They |
| are invalid if you do not have an Alpha and are usually unnecessary |
| if you do; |
| .B \%hwclock |
| should be able to determine what it is running on when |
| .I \%/proc |
| is mounted. |
| .sp |
| .RB "The " \%\-\-jensen |
| option is used for Jensen models; |
| .B \%\-\-funky\-toy |
| means that the machine requires 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 \-\-srm |
| This option is equivalent to |
| .BI \%\-\-epoch= 1900 |
| and is used to specify the most common epoch on Alphas |
| with SRM console. |
| . |
| .SH NOTES |
| . |
| .SS Clocks in a Linux System |
| .PP |
| There are two types of date-time clocks: |
| .PP |
| .B The Hardware Clock: |
| This clock is an independent hardware device, with its own power domain |
| (battery, capacitor, etc), that operates when the machine is powered off, |
| or even unplugged. |
| .PP |
| On an ISA compatible system, this clock is specified as part of the ISA |
| standard. A control program can read or set this clock only to a whole |
| second, but it 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 |
| .BR \%hwclock . |
| The Linux kernel also refers to it as the persistent clock. |
| .PP |
| 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 Clock: |
| This clock is part of the Linux kernel and is 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 UTC). 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 is to keep time when Linux is not running so that the System |
| Clock can be initialized from it at boot. 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 (1) |
| 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. Note: currently this is not possible on most systems because |
| .B \%hwclock\ \-\-systohc |
| is called at shutdown. |
| .PP |
| The Linux kernel's timezone is set by |
| .BR hwclock . |
| 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 or the |
| .I \%/etc/localtime |
| file, 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's 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. Another example is the kernel's NTP \%'11\ minute\ mode.' |
| If the kernel's timezone value and/or the |
| .I \%persistent_clock_is_local |
| variable are wrong, then the Hardware Clock will be set incorrectly |
| by \%'11\ minute\ mode.' See the discussion below, under |
| .BR "Automatic Hardware Clock Synchronization by the Kernel" . |
| .PP |
| .B \%hwclock |
| sets the kernel's timezone to the value indicated by TZ or |
| .IR \%/etc/localtime " with the" |
| .BR \%\-\-hctosys " or " \%\-\-systz " functions." |
| .PP |
| The kernel's 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). |
| . |
| .SS User access and setuid |
| .PP |
| Sometimes, you need to install |
| .B \%hwclock |
| setuid root. If you want users other than the superuser to be able to |
| display the clock value using the direct ISA I/O method, install it setuid |
| root. If you have the rtc device interface on your system, or are on a non-ISA |
| compatible system, there is probably no need for users to have the direct |
| ISA I/O method, so do not bother. See the |
| .BR \-\-rtc " option." |
| .PP |
| In any case, hwclock will not allow you to set anything unless you have the |
| superuser real uid. (This restriction is not necessary if you haven't |
| installed setuid root, but it's there for now.) |
| . |
| .SS Hardware Clock Access Methods |
| .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 rtc device special file, which is |
| presumed to be driven by the rtc device driver. Also, Linux systems |
| using the rtc framework with udev, are capable of supporting multiple |
| Hardware Clocks. This may bring about the need to override the default |
| rtc device by specifying one with the |
| .BR \-\-rtc " option." |
| .PP |
| However, this method is not always available as older systems do not |
| have an rtc driver. On these systems, the method of accessing the |
| Hardware Clock depends on the system hardware. |
| .PP |
| On an ISA compatible 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. This method may be used by |
| specifying the |
| .BR \%\-\-directisa " option." |
| .PP |
| This is a really poor method of accessing the clock, for all the |
| reasons that userspace programs are generally not supposed to do |
| direct I/O and disable interrupts. |
| .B \%hwclock |
| provides it for testing, troubleshooting, and because it may be the |
| only method available on ISA compatible and Alpha systems which do not |
| have a working rtc device driver. |
| .PP |
| 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 |
| .I \%/dev/port |
| device special file, which provides almost as low-level an interface to |
| the I/O subsystem. |
| .PP |
| On an m68k system, |
| .B \%hwclock |
| can access the clock with the console driver, via the device special file |
| .IR \%/dev/tty1 . |
| .SS 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 apply systematic drift corrections to the |
| Hardware Clock. |
| .PP |
| It works like this: |
| .BR \%hwclock " keeps a file," |
| .IR @ADJTIME_PATH@ , |
| that keeps some historical information. This is called the adjtime file. |
| .PP |
| Suppose you start with no adjtime file. You issue a |
| .B \%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. |
| Five days later, the clock has gained 10 seconds, so you issue a |
| .B \%hwclock\ \-\-set\ \-\-update\-drift |
| 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 |
| .B \%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 go by and you issue another |
| .BR \%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 |
| When you use the |
| .BR \%\-\-update\-drift " option with " \-\-set " or " \%\-\-systohc , |
| the systematic drift rate is (re)calculated by comparing the fully drift |
| corrected current Hardware Clock time with the new set time, from that |
| it derives the 24 hour drift rate based on the last calibrated timestamp |
| from the adjtime file. This updated drift factor is then saved in |
| .IR @ADJTIME_PATH@ . |
| .PP |
| A small amount of error creeps in when |
| the Hardware Clock is set, so |
| .B \%\-\-adjust |
| refrains from making any adjustment that is less |
| than 1 second. Later on, when you request an adjustment again, the accumulated |
| drift will be more than 1 second and |
| .B \%\-\-adjust |
| will make the adjustment including any fractional amount. |
| .PP |
| .B \%hwclock\ \-\-hctosys |
| also uses the adjtime file data to compensate the value read from the Hardware |
| Clock before using it to set the System Clock. It does not share the 1 second |
| limitation of |
| .BR \%\-\-adjust , |
| and will correct sub-second drift values immediately. It does not |
| change the Hardware Clock time nor the adjtime file. This may eliminate |
| the need to use |
| .BR \%\-\-adjust , |
| unless something else on the system needs the Hardware Clock to be |
| compensated. |
| . |
| .SS The Adjtime File |
| While named for its historical purpose of controlling adjustments only, |
| it actually contains other information used by |
| .B hwclock |
| from one invocation to the next. |
| .PP |
| The format of the adjtime file is, in ASCII: |
| .PP |
| Line 1: Three numbers, separated by blanks: 1) the systematic drift rate |
| in seconds per day, floating point decimal; 2) the 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: One number: the 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 " \%hwclock . |
| . |
| .SS Automatic Hardware Clock Synchronization by the Kernel |
| .PP |
| 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 Clock 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.) |
| .PP |
| This mode (we'll call it \%'11\ minute\ mode') is off until something |
| turns it on. The NTP daemon ntpd is one thing that turns it on. You |
| can turn it off by running anything, including |
| .BR \%hwclock\ \-\-hctosys , |
| that sets the System Clock the old fashioned way. However, if the NTP daemon is |
| still running, it will turn 11 minute mode back on again the next time it |
| synchronizes the System Clock. |
| .PP |
| When \%'11\ minute\ mode' is active the 64 bit of the kernel's |
| .I time_status |
| variable is unset. The status variable can be checked with the |
| .BR \%adjtimex\ --print " or " \%ntptime " commands." |
| .PP |
| If your system runs with \%'11\ minute\ mode' on, it may need to use either |
| .BR \%\-\-hctosys " or " \%\-\-systz |
| in a startup script, especially if the Hardware Clock is configured to use |
| the local timescale. Unless the kernel is informed of what timescale the |
| Hardware Clock is using, it may clobber it with the wrong one. The kernel |
| uses UTC by default. |
| .PP |
| The first userspace command to set the System Clock informs the |
| kernel what timescale the Hardware Clock is using. This happens via the |
| .I \%persistent_clock_is_local |
| kernel variable. If |
| .BR \%\-\-hctosys " or " \%\-\-systz |
| is the first, it will set this variable according to the adjtime file or the |
| appropriate command-line argument. Note that when using this capability and the |
| Hardware Clock timescale configuration is changed, then a reboot is required to |
| notify the kernel. |
| .PP |
| .B \%hwclock\ \-\-adjust |
| should not be used with NTP \%'11\ minute\ mode.' |
| . |
| .SS ISA Hardware Clock Century value |
| .PP |
| 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. |
| .PP |
| If you have a bona fide use for a CMOS century byte, contact the |
| .B \%hwclock |
| maintainer; an option may be appropriate. |
| .PP |
| 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 DATE-TIME CONFIGURATION |
| .in +4 |
| .SS Keeping Time without External Synchronization |
| .in |
| .PP |
| This discussion is based on the following conditions: |
| .IP \(bu 2 |
| Nothing is running that alters the date-time clocks, e.g., |
| .BR \%ntpd "(1), cron jobs, et al." |
| .IP \(bu 2 |
| The system timezone is configured for the correct local time. See below |
| .BR "POSIX vs 'RIGHT'" . |
| .IP \(bu 2 |
| Early in startup the following are called in this order: |
| .br |
| .BI \%adjtimex\ \-\-tick \ <value>\ \-\-frequency \ <value> |
| .br |
| .B \%hwclock\ \-\-hctosys |
| .IP \(bu 2 |
| During shutdown the following is called: |
| .br |
| .B \%hwclock\ \-\-systohc |
| .PP |
| .in +4 |
| .BR * " Systems without " adjtimex " may use " ntptime . |
| .in |
| .PP |
| Whether maintaining precision time with |
| .BR \%ntpd (1) |
| or not, it makes sense to configure the system to keep reasonably good |
| date-time on its own. |
| .PP |
| The first step in making that happen is having a clear understanding of |
| the big picture. There are two completely separate hardware devices |
| running at their own speed and drifting away from the 'correct' time at |
| their own rates. The methods and software for drift correction are |
| different for each of them. However, most systems are configured to |
| exchange values between these two clocks at startup and shutdown. Now |
| the individual device's time keeping errors are transferred back and |
| forth between each other. Attempt to configure drift correction for only |
| one of them, and the other's drift will be overlaid upon it. If the big |
| picture is not kept in mind, confusion will soon ensue. |
| .PP |
| This problem can be avoided when configuring drift correction for the |
| System Clock by simply not shutting down the machine. This, plus the |
| fact that all of |
| .BR \%hwclock 's |
| precision (including calculating drift factors) depends upon the System |
| Clock's rate being correct, means that configuration of the System Clock |
| should be done first. |
| .PP |
| The System Clock drift is corrected with the |
| .BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency |
| options. These two work together, tick is the course adjustment and |
| frequency is the fine adjustment. (For system that do not have an |
| .BR \%adjtimex " package," |
| .BI \%ntptime\ \-f\ <ppm> |
| may be use instead.) |
| .PP |
| Some Linux distributions attempt to automatically calculate the System |
| Clock drift with |
| .BR \%adjtimex 's |
| compare operation. Trying to correct one |
| drifting clock by using another drifting clock as a reference is akin to |
| a dog trying to catch its own tail. Success may happen eventually, but |
| great effort and frustration will likely precede it. This automation may |
| yield an improvement over no configuration, but expecting optimum |
| results would be in error. A better choice for manual configuration |
| would be |
| .BR \%adjtimex 's " \-\-log " options. |
| .PP |
| It may be more effective to simply track the System Clock drift with |
| .BR \%ntpdate\ \-q " , or " \%date\ \-Ins |
| and a precision timepiece, and then calculate the correction manually. |
| .PP |
| After setting the tick and frequency values, continue to test and refine the |
| adjustments until the System Clock keeps good time. See |
| .BR \%adjtimex (8) |
| for more information and the example demonstrating manual drift |
| calculations. |
| .PP |
| Once the System Clock is ticking smoothly, move on to the Hardware Clock. |
| .PP |
| As a rule, cold drift will work best for most use cases. This should be |
| true even for 24/7 machines whose normal downtime consists of a reboot. |
| In that case the drift factor value makes little difference, but on the |
| rare occasion that the machine is shutdown for an extended period then |
| cold drift should yield better results. |
| .PP |
| .B Steps to calculate cold drift: |
| .IP 1 2 |
| .RB "Confirm that " ntpd "(1) will not be launched at startup." |
| .IP 2 2 |
| .RI The " System Clock " "time must be correct at shutdown!" |
| .IP 3 2 |
| Shutdown the system. |
| .IP 4 2 |
| Let an extended period pass without changing the Hardware Clock. |
| .IP 5 2 |
| Start the system. |
| .IP 6 2 |
| .RB "Immediately use " hwclock " to set the correct time with the" |
| .BR \%\-\-update\-drift " option." |
| .PP |
| Note: if step six uses |
| .RB \%\-\-systohc , |
| then the System Clock must be set correctly (step 6a) just before doing so. |
| .PP |
| .RB "Having " hwclock |
| calculate the drift factor is a good starting point, but for optimal |
| results it will likely need to be adjusted by directly editing the |
| .I @ADJTIME_PATH@ |
| file. Continue to test and refine the drift factor until the Hardware |
| Clock is corrected properly at startup. To check this, first make sure |
| that the System Time is correct before shutdown and then use |
| .BR \%ntpdate\ \-q ", or " \%date\ \-Ins |
| and a precision timepiece, immediately after startup. |
| .PP |
| Both clocks typically use a quartz crystal oscillator. Crystals are |
| used for reference oscillators in electronics because by most measures |
| they produce a very clean and stable sine wave. Their greatest |
| shortcoming is that they have a Positive Temperature Coefficient; |
| meaning that their frequency increases as the temperature increases and |
| vise versa. Therefore, both the Hardware and System Clock's drift rate |
| changes with intrinsic and extrinsic machine temperatures. These |
| characteristics will vary by machine depending upon its design. |
| .PP |
| Drift correction strategies are many, but as a general guide the goal |
| would be to find a longterm average. A year long average to take into |
| account seasonal ambient temperature shifts may be a good target period. |
| So perhaps the date-time advances a bit in the summer and declines a bit |
| in the winter, but at the end of a year it balances to zero. |
| .PP |
| If this is beginning to sound futile, it is not. Left on its own a |
| machine can lose 3 seconds per day or more. Accumulated drift over a |
| year may easily exceed half an hour. Using carefully crafted drift |
| corrections can make a significant improvement in a machine's ability to |
| keep reasonably good date-time. |
| . |
| .SS LOCAL vs UTC |
| Keeping the Hardware Clock in a local timescale causes inconsistent |
| daylight saving time results: |
| .IP \(bu 2 |
| If Linux is running during a daylight saving time change, the time |
| written to the Hardware Clock will be adjusted for the change. |
| .IP \(bu 2 |
| If Linux is NOT running during a daylight saving time change, the time |
| read from the Hardware Clock will NOT be adjusted for the change. |
| .PP |
| The Hardware Clock on an ISA compatible system keeps only a date and time, |
| it has no concept of timezone nor daylight saving. Therefore, when |
| .B hwclock |
| is told that it is in local time, it assumes it is in the 'correct' |
| local time and makes no adjustments to the time read from it. |
| .PP |
| Linux handles daylight saving time changes transparently only when the |
| Hardware Clock is kept in the UTC timescale. Doing so is made easy for |
| system administrators as |
| .B \%hwclock |
| uses local time for its output and as the argument to the |
| .BR \%\-\-date " option." |
| .PP |
| POSIX systems, like Linux, are designed to have the System Clock operate |
| in the UTC timescale. The Hardware Clock's purpose is to initialize the |
| System Clock, so also keeping it in UTC makes sense. |
| .PP |
| Linux does, however, attempt to accommodate the Hardware Clock being in |
| the local timescale. This is primarily for dual-booting with older |
| versions of MS Windows. From Windows 7 on, the RealTimeIsUniversal |
| registry key is supposed to be working properly so that its Hardware |
| Clock can be kept in UTC. |
| . |
| .SS POSIX vs 'RIGHT' |
| A discussion on date-time configuration would be incomplete without |
| addressing timezones, this is mostly well covered by |
| .BR tzset (3). |
| One area that seems to have no documentation is the 'right' |
| directory of the Time Zone Database, sometimes called tz or zoneinfo. |
| .PP |
| There are two separate databases in the zoneinfo system, posix |
| and 'right'. 'Right' (now named zoneinfo\-leaps) includes leap seconds and posix |
| does not. To use the 'right' database the System Clock must be set to |
| \%(UTC\ +\ leap seconds), which is equivalent to \%(TAI\ \-\ 10). This |
| allows calculating the |
| exact number of seconds between two dates that cross a leap second |
| epoch. The System Clock is then converted to the correct civil time, |
| including UTC, by using the 'right' timezone files which subtract the |
| leap seconds. Note: this configuration is considered experimental and is |
| known to have issues. |
| .PP |
| To configure a system to use a particular database all of the files |
| located in its directory must be copied to the root of |
| .IR \%/usr/share/zoneinfo . |
| Files are never used directly from the posix or 'right' subdirectories, e.g., |
| .RI \%TZ=' right/Europe/Dublin '. |
| This habit was becoming so common that the upstream zoneinfo project |
| restructured the system's file tree by moving the posix and 'right' |
| subdirectories out of the zoneinfo directory and into sibling directories: |
| .PP |
| .in +2 |
| .I /usr/share/zoneinfo |
| .br |
| .I /usr/share/zoneinfo\-posix |
| .br |
| .I /usr/share/zoneinfo\-leaps |
| .PP |
| Unfortunately, some Linux distributions are changing it back to the old |
| tree structure in their packages. So the problem of system |
| administrators reaching into the 'right' subdirectory persists. This |
| causes the system timezone to be configured to include leap seconds |
| while the zoneinfo database is still configured to exclude them. Then |
| when an application such as a World Clock needs the South_Pole timezone |
| file; or an email MTA, or |
| .B hwclock |
| needs the UTC timezone file; they fetch it from the root of |
| .I \%/usr/share/zoneinfo |
| , because that is what they are supposed to do. Those files exclude leap |
| seconds, but the System Clock now includes them, causing an incorrect |
| time conversion. |
| .PP |
| Attempting to mix and match files from these separate databases will not |
| work, because they each require the System Clock to use a different |
| timescale. The zoneinfo database must be configured to use either posix |
| or 'right', as described above. |
| . |
| .SH "ENVIRONMENT VARIABLES" |
| .I TZ |
| . |
| .SH FILES |
| .br |
| .I @ADJTIME_PATH@ |
| .br |
| .I /etc/localtime |
| .br |
| .I /dev/rtc |
| .br |
| .I /dev/rtc0 |
| .br |
| .I /dev/misc/rtc |
| .br |
| .I /dev/efirtc |
| .br |
| .I /dev/misc/efirtc |
| .br |
| .I /dev/port |
| .br |
| .I /dev/tty1 |
| .br |
| .I /proc/cpuinfo |
| . |
| .SH "SEE ALSO" |
| .BR date (1), |
| .BR adjtimex (8), |
| .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 |
| .BR \%clock (8) |
| 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 package and is available from |
| ftp://ftp.kernel.org/pub/linux/utils/util-linux/. |