Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx> --- sys-utils/hwclock.8.in | 74 ++++++++++++++++++++++++------------------------ 1 files changed, 37 insertions(+), 37 deletions(-) diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in index 30f191b..0c654a5 100644 --- a/sys-utils/hwclock.8.in +++ b/sys-utils/hwclock.8.in @@ -1,4 +1,4 @@ -.TH HWCLOCK 8 "July 2014" "util-linux" "System Administration" +.TH HWCLOCK 8 "October 2014" "util-linux" "System Administration" .SH NAME hwclock \- query or set the hardware clock (RTC) .SH SYNOPSIS @@ -27,10 +27,14 @@ It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or Since v2.26 .B hwclock \-\-hctosys -automatically compensates time read from the Hardware Clock to account for -systematic drift before using it to set the System Clock. Therefore, -\fB\-\-adjust\fR is no longer necessary during boot. This functionality makes -hwclock usable early in the boot process when the root filesystem is read-only. +does a better job at setting the System Clock: it no longer simply copies +the time from the Hardware Clock to the System Clock, but sets the System +Clock to a drift-compensated time. (That is: it reads the Hardware Clock, +applies a compensation for the systematic drift to this read time, and +then sets the System Clock to the resulting value.) +Therefore it is no longer necessary to run \fBhwclock --adjust\fR before +doing \fBhwclock --hctosys\fR, and thus \fBhwclock\fR can be used very +early on in the boot process when the root filesystem is still read-only. .SH FUNCTIONS You need exactly one of the following options to tell @@ -101,9 +105,8 @@ When used in a startup script, making it the first caller of .BR settimeofday (2) from boot, it will set the NTP 11 minute mode time scale via the .I persistent_clock_is_local -kernel variable. See the discussion below, under -.B Automatic Hardware Clock Synchronization by the -.BR Kernel. +kernel variable. See the discussion below, under +.BR "Automatic Hardware Clock Synchronization by the Kernel" . .sp This is a good option to use in one of the system startup scripts. .sp @@ -358,15 +361,13 @@ else. This is useful, especially in conjunction with in learning about the internal operations of hwclock. .TP -.B \-\-update\-drift +.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. -See the discussion below, under -.B The Adjust -.BR Function. +See the discussion below, under \fBThe Adjust Function\fR. .TP .BR \-u , \ \-\-utc @@ -442,8 +443,7 @@ 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 -.B Automatic Hardware Clock Synchronization by the -.BR Kernel. +.BR "Automatic Hardware Clock Synchronization by the Kernel" . .PP .B hwclock sets the kernel timezone to the value indicated by TZ and/or @@ -551,35 +551,35 @@ keeps a file, that keeps some historical information. This is called the adjtime file. .PP Suppose you start with no adjtime file. You issue a -.I hwclock \-\-set +.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. -5 days later, the clock has gained 10 seconds, so you issue the -.I hwclock \-\-set \-\-update\-drift +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 -.I hwclock \-\-adjust +.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 goes by and you issue another -.IR "hwclock \-\-adjust" . +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 -.I \-\-update\-drift +.B \-\-update-drift option with -.IR \-\-set\ or \ \-\-systohc , +.BR \-\-set\ or \ \-\-systohc , the systematic drift rate is (re)calculated based on how long it has been since the last calibration, how long it has been since the last adjustment, what drift rate was assumed in any intervening @@ -589,19 +589,19 @@ drift factor is then saved in .PP A small amount of error creeps in when the Hardware Clock is set, so -.I \-\-adjust +.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 -.I \-\-adjust +.B \-\-adjust will make the adjustment including any fractional amount. .PP -.IR "hwclock \-\-hctosys" +.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 Time. It does not share the 1 second -limitation of --adjust, and will correct sub-second drift values immediately. +limitation of \fB--adjust\fR, and will correct sub-second drift values immediately. It does not change the Hardware Clock time or the adjtime file. This may -eliminate the need to use --adjust, unless something else on the system needs +eliminate the need to use \fB--adjust\fR, unless something else on the system needs the Hardware Clock to be compensated. The drift compensation can be inhibited by using the .B --noadjfile @@ -613,14 +613,14 @@ in remembering information from one invocation to the next. .PP The format of the adjtime file is, in ASCII: .PP -Line 1: 3 numbers, separated by blanks: 1) systematic drift rate in -seconds per day, floating point decimal; 2) Resulting number of +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: 1 number: Resulting number of seconds since 1969 UTC of most +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 @@ -650,28 +650,28 @@ network or to a radio clock hooked up to your system. See RFC 1305.) This mode (we'll call it "11 minute mode") is off until something turns it on. The ntp daemon ntpd is one thing that turns it on. You can turn it off by running anything, including -.IR "hwclock \-\-hctosys" , +.BR "hwclock \-\-hctosys" , that sets the System Time 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 If your system runs with 11 minute mode on, it may need -.I hwclock \-\-hctosys +.B hwclock \-\-hctosys in a startup script, especially if the Hardware Clock is configured to to use the local timescale. The first user space command to set the System Clock informs the -kernel what timescale the Hardware Clock is using. This happens via the +kernel what timescale the Hardware Clock is using. This happens via the .I persistent_clock_is_local -kernel variable. If -.I hwclock \-\-hctosys +kernel variable. If +.B hwclock \-\-hctosys 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 +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. Don't use -.I hwclock \-\-adjust +.B hwclock \-\-adjust with 11 minute mode. You'll just make a mess. .SS ISA Hardware Clock Century value -- 1.7.0.4 -- To unsubscribe from this list: send the line "unsubscribe util-linux" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
