| .\" 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'. |
| .\" |
| .TH HWCLOCK 8 "April 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); and predict future |
| Hardware Clock values based on its drift rate. |
| .PP |
| Since v2.26 important changes were made to the |
| .B \-\-hctosys |
| function and the |
| .B \-\-directisa |
| option, and a new option |
| .B \-\-update\-drift |
| was added. See their respective descriptions below. |
| . |
| .SH FUNCTIONS |
| The following functions are mutually exclusive, only one can be given at |
| a time. If none is given, the default is \fB\-\-show\fR. |
| .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 |
| .B \-\-getepoch |
| .TQ |
| .B \-\-setepoch |
| These functions are for Alpha machines only, and are only available |
| through the Linux kernel RTC driver. |
| .sp |
| They are used to 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 the machine's BIOS sets the year |
| counter in the Hardware Clock to contain the number of full years since |
| 1952, then the kernel's Hardware Clock epoch value must be 1952. |
| .sp |
| The \fB\%\-\-setepoch\fR function requires using the |
| .B \%\-\-epoch |
| option to specify the year. For example: |
| .RS |
| .IP "" 4 |
| .B hwclock\ \-\-setepoch\ \-\-epoch=1952 |
| .PP |
| The RTC driver attempts to guess the correct epoch value, so setting it |
| may not be required. |
| .PP |
| This epoch value is used whenever |
| .B \%hwclock |
| reads or sets the Hardware Clock on an Alpha machine. For ISA machines |
| the kernel uses the fixed Hardware Clock epoch of 1900. |
| .RE |
| . |
| .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 its time to standard output in the |
| .B ISO 8601 |
| format. |
| 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@ . |
| When the |
| .B --update-drift |
| option is given, then also (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 |
| .BI \%\-\-date= date_string |
| This option must be used with the |
| .B \-\-set |
| or |
| .B \%\-\-predict |
| functions, otherwise it is ignored. |
| .RS |
| .IP "" 4 |
| .B "hwclock\ \-\-set\ \-\-date='16:45'" |
| .IP "" 4 |
| .B "hwclock\ \-\-predict\ \-\-date='2525-08-14\ 07:11:05'" |
| .PP |
| The argument must be in local time, even if you keep your Hardware Clock in |
| UTC. See the |
| .B \%\-\-localtime |
| option. Therefore, the argument should not include any timezone information. |
| It also should 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. Fractional seconds are silently dropped. This option is |
| capable of understanding many time and date formats, but the previous |
| parameters should be observed. |
| .RE |
| . |
| .TP |
| .BR \-D ", " \-\-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 in the x86 and |
| x86_64 family. 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 file, which it assumes to be driven by the Linux |
| 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 |
| .BI \-\-epoch= year |
| This option is required when using the |
| .BR \%\-\-setepoch \ function. |
| . |
| .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/rtc0 |
| .br |
| .I /dev/rtc |
| .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 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 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 systems which do not have a working rtc |
| device driver. |
| .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 mode |
| is a compile time option, so not all kernels will have this capability. |
| 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 |
| If the kernel is compiled with the \%'11\ minute\ mode' option it will |
| be active when the kernel's clock discipline is in a synchronized state. |
| When in this state, bit 6 (the bit that is set in the mask 0x0040) |
| of the kernel's |
| .I \%time_status |
| variable is unset. This value is output as the 'status' line of the |
| .BR \%adjtimex\ --print " or " \%ntptime " commands." |
| .PP |
| It takes an outside influence, like the NTP daemon |
| .BR ntpd (1), |
| to put the kernel's clock discipline into a synchronized state, and |
| therefore turn on \%'11\ minute\ mode'. |
| It can be turned off by running anything that sets the System Clock the old |
| fashioned way, including |
| .BR "\%hwclock\ \-\-hctosys" . |
| 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 |
| 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, such as |
| .BR \%ntpd "(1) or a cron job." |
| .IP \(bu 2 |
| The system timezone is configured for the correct local time. See below, under |
| .BR "POSIX vs 'RIGHT'" . |
| .IP \(bu 2 |
| Early during 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. |
| .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 coarse adjustment and |
| frequency is the fine adjustment. (For systems that do not have an |
| .BR \%adjtimex " package," |
| .BI \%ntptime\ \-f\ ppm |
| may be used 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 \%sntp ", 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 shut down for an extended period, then |
| cold drift should yield better results. |
| .PP |
| .B Steps to calculate cold drift: |
| .IP 1 2 |
| .RB "Ensure 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 |
| Shut down 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, adding the" |
| .BR \%\-\-update\-drift " option." |
| .PP |
| Note: if step 6 uses |
| .BR \%\-\-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 \%sntp ", or " \%date\ \-Ins |
| and a precision timepiece, immediately after startup. |
| .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, or by assigning a database path to the |
| .SB TZDIR |
| environment variable. |
| .SH ENVIRONMENT |
| .TP |
| .B TZ |
| If this variable is set its value takes precedence over the system |
| configured timezone. |
| .TP |
| .B TZDIR |
| If this variable is set its value takes precedence over the system |
| configured timezone database directory path. |
| .SH FILES |
| .TP |
| .I @ADJTIME_PATH@ |
| The configuration and state file for hwclock. |
| .TP |
| .I /etc/localtime |
| The system timezone file. |
| .TP |
| .I /usr/share/zoneinfo/ |
| The system timezone database directory. |
| .PP |
| Device files |
| .B hwclock |
| may try for Hardware Clock access: |
| .br |
| .I /dev/rtc0 |
| .br |
| .I /dev/rtc |
| .br |
| .I /dev/misc/rtc |
| .br |
| .I /dev/efirtc |
| .br |
| .I /dev/misc/efirtc |
| .br |
| .I /dev/port |
| .br |
| .I /dev/tty1 |
| .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 |
| https://www.kernel.org/pub/linux/utils/util-linux/. |