hwclock: improve wording and formatting of man page
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
This commit is contained in:
parent
d0bdf18434
commit
df48a72161
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue