diff options
Diffstat (limited to '')
| -rw-r--r-- | sys-utils/hwclock.8.in | 998 |
1 files changed, 998 insertions, 0 deletions
diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in new file mode 100644 index 0000000..dacdd27 --- /dev/null +++ b/sys-utils/hwclock.8.in @@ -0,0 +1,998 @@ +.\" 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 "July 2017" "util-linux" "System Administration" +.SH NAME +hwclock \- time clocks utility +.SH SYNOPSIS +.B hwclock +.RI [ function ] +.RI [ option ...] +. +.SH DESCRIPTION +.B hwclock +is an administration tool for the time clocks. 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 \-a, \-\-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 +.B \-\-date +option, and update the timestamps in +.IR @ADJTIME_PATH@ . +With the +.B \%\-\-update-drift +option also (re)calculate the drift factor. Try it without the option if +.BR \%\-\-set " fails. See " \%\-\-update-drift " below." +. +.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 also (re)calculate the drift factor. Try it without the option if +.BR \%\-\-systohc " fails. See " \%\-\-update-drift " below." +. +.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 +.BI \%\-\-delay= seconds +This option allows to overwrite internally used delay when set clock time. The +default is 0.5 (500ms) for rtc_cmos, for another RTC types the delay is 0. If +RTC type is impossible to determine (from sysfs) then it defaults also to 0.5 +to be backwardly compatible. +.RS +.PP +The 500ms default is based on commonly used MC146818A-compatible (x86) hardware clock. This +Hardware Clock can only be set to any integer time plus one half second. The +integer time is required because there is no interface to set or get a +fractional second. The additional half second delay is because the Hardware +Clock updates to the following second precisely 500 ms after setting the new +time. Unfortunately, this behavior is hardware specific and in same cases +another delay is required. +.RE +. +.TP +.TP +.BR \-D ", " \-\-debug +.RB Use\ \-\-verbose . +.RB The\ \%\-\-debug\ option +has been deprecated and may be repurposed or removed in a future release. +. +.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. +.RI "The minimum " year +value is 1900. The maximum is system dependent +.RB ( ULONG_MAX\ -\ 1 ). +. +.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 +.BR \-l , \ \-\-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, that is, the Clocks or +.I @ADJTIME_PATH@ +.RB ( \%\-\-verbose +is implicit with this option). +. +.TP +.B \-\-update\-drift +Update the Hardware Clock's drift factor in +.IR @ADJTIME_PATH@ . +It can only be used with +.BR \-\-set " or " \%\-\-systohc , +.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 NTP 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. +.IP \(bu 2 +Significantly increased system shutdown times (as of v2.31 when not +using +.B \%\-\-update\-drift +the RTC is not read). +.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" . +.PP +This option requires reading the Hardware Clock before setting it. If +it cannot be read, then this option will cause the set functions to fail. +This can happen, for example, if the Hardware Clock is corrupted by a +power failure. In that case, the clock must first be set without this +option. Despite it not working, the resulting drift correction factor +would be invalid anyway. +.RE +. +.TP +.BR \-v ", " \-\-verbose +Display more details about what +.B \%hwclock +is doing internally. +. +.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. +.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 +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 NTP daemon 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 NTP daemon +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 +.B "Ensure that NTP daemon 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 EXIT STATUS +One of the following exit values will be returned: +.TP +.BR EXIT_SUCCESS " ('0' on POSIX systems)" +Successful program execution. +.TP +.BR EXIT_FAILURE " ('1' on POSIX systems)" +The operation failed or the command syntax was not valid. +.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 +.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/. |