[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Feedback
Hi.
I clicked on "man Pages" link at the top of your homepage, and found:
...The Linux man Pages (version 1.31) for sections 2, 3, 4, 5, 7, and 9 are
available here (with some translations). Section 1 and 8 man pages (i.e.,
user commands) are available with the corresponding software packages...
I'm not exactly sure what you mean by "...available with the corresponding
software packages...", but I'd like to comment on a man page in section 8,
specifically "adjtimex", anyway. This is the man page I found I my system,
but I also found exactly the same thing just by searching "the web":
ADJTIMEX(8) ADJTIMEX(8)
NAME
adjtimex - display or set the kernel time variables
SYNOPSIS
adjtimex [option]...
DESCRIPTION
This program gives you raw access to the kernel time vari
ables. For a machine connected to the Internet, or
equipped with a precision oscillator or radio clock, the
best way to regulate the system clock is with ntpd(8).
For a standalone or intermittently connected machine, you
may use adjtimex instead to at least correct for system
atic drift.
Anyone may print out the time variables, but only the
superuser may change them.
If your computer can be connected to the net, you might
run ntpd for at least several hours and use adjtimex
--print to learn what values of tick and freq it settled
on. Alternately, you could estimate values using the CMOS
clock as a reference (see the --compare and --adjust
switches). You could then add a line to rc.local invoking
adjtimex to set those parameters each time you reboot.
OPTIONS
Options may be introduced by either - or --, and unique
abbreviations may be used. Here is a summary of the
options, grouped by type. Explanations follow.
Get/Set Kernel Time Parameters
-p --print -t --tick val -f newfreq --frequency
newfreq -o val --offset val -s adjustment
--singleshot adjustment -m val --maxerr val -e val
--esterror val -T val --timeconstant val
Estimate Systematic Drifts
-c[count] --compare[=count] -a[count]
--adjust[=count] -i tim --interval tim -l file
--logfile file -h timeserver --host timeserver -w
--watch -r[file] --review[=file] -u --utc
Informative Output
--help -v --version
-p, --print
Print the current values of the kernel time
variables. NOTE: The time is "raw", and may be off
by up to one timer tick (10 msec). "status" gives
the value of the time_status variable in the
kernel. For Linux 1.0 and 1.2 kernels, the value
is as follows:
0 clock is synchronized (so the kernel should
periodically set the CMOS clock to match the
system clock)
1 inserting a leap second at midnight
2 deleting a leap second at midnight
3 leap second in progress
4 leap second has occurred
5 clock not externally synchronized (so the
kernel should leave the CMOS clock alone)
For Linux 2.0 kernels, the value is a sum of these:
1 PLL updates enabled
2 PPS freq discipline enabled
4 PPS time discipline enabled
8 frequency-lock mode enabled
16 inserting leap second
32 deleting leap second
64 clock unsynchronized
128 holding frequency
256 PPS signal present
512 PPS signal jitter exceeded
1024 PPS signal wander exceeded
2048 PPS signal calibration error
4096 clock hardware fault
-t val, --tick val
Set the number of microseconds that should be added
to the system time for each kernel tick interrupt.
There are supposed to be 100 ticks per second, so
val should be close to 10000. Increasing val by 1
speeds up the system clock by about 100 ppm, or
8.64 sec/day. tick must be in the range
9000...11000.
-f newfreq, --frequency newfreq
Set the system clock frequency offset to newfreq.
newfreq can be negative or positive, and gives a
much finer adjustment than the --tick switch. The
value is scaled such that newfreq = 1<<16 speeds up
the system clock by about 1 ppm, or .0864 sec/day.
Thus, --tick 10000 --frequency 6553600 is about the
same as --tick 10001 --frequency 0. newfreq must
be in the range -6553600...6553600, allowing
maximum adjustments of plus or minus 100 ppm.
-s adj, --singleshot adj
Slew the system clock by adj usec. (Its rate is
changed temporarily by about 1 part in 2000.)
-o adj, --offset adj
Add a time offset of adj usec. The kernel code
adjusts the time gradually by adj, notes how long
it has been since the last time offset, and then
adjusts the frequency offset to correct for the
apparent drift. adj must be in the range
-512000...512000.
-m val, --maxerror val
Set maximum error (usec).
-e val, --esterror val
Set estimated error (usec). The maximum and
estimated error are not used by the kernel. They
are merely made available to user processes via the
adjtimex(2) system call.
-t val, --timeconstant val
Set phase locked loop (PLL) time constant. val
determines the bandwidth or "stiffness" of the PLL.
The effective PLL time constant will be a multiple
of (1 << val). For room-temperature quartz
oscillators, David Mills recommends the value 2,
which corresponds to a PLL time constant of about
900 sec and a maximum update interval of about 64
sec. The maximum update interval scales directly
with the time constant, so that at the maximum time
constant of 6, the update interval can be as large
as 1024 sec.
Values of val between zero and 2 give quick
convergence; values between 2 and 6 can be used to
reduce network load, but at a modest cost in
accuracy.
-c[count], --compare[=count]
Periodically compare the system clock with the CMOS
clock. After the first two calls, print values for
tick and frequency offset that would bring the
system clock into approximate agreement with the
CMOS clock. CMOS clock readings are adjusted for
systematic drift using using the correction in
/etc/adjtime -- see hwclock(8). The interval
between comparisons is 10 seconds, unless changed
by the --interval switch. The optional argument is
the number of comparisons. (If the argument is
supplied, the "=" is required.)
-a[count], --adjust[=count]
Same as --compare, except the recommended values
are actually installed after every other
comparison.
-i tim, --interval tim
Set the interval in seconds between clock
comparisons for the --compare and --adjust options.
-u, --utc
The CMOS clock is set to UTC (universal time)
rather than local time.
-l[file], --log[=file]
Save the current values of the system and CMOS
clocks, and optionally a reference time, to file
(default /var/log/clocks.log). The reference time
is taken from a network timeserver (see the --host
switch) or supplied by the user (see the --watch
switch).
-h timeserver, --host timeserver
Use ntpdate to query the given timeserver for the
current time. This will fail if timeserver is not
running a Network Time Protocol (NTP) server, or if
that server is not synchronized. Implies --log.
-w, --watch
Ask for a keypress when the user knows the time,
then ask what that time was, and its approximate
accuracy. Implies --log.
-r[file], --review[=file]
Review the clock log file (default
/var/log/clocks.log) and estimate, if possible, the
rates of the CMOS and system clocks. Calculate
least-squares rates using all suitable log entries.
Suggest corrections to adjust for systematic drift.
-h, --help
Print the program options.
-v, --version
Print the program version.
EXAMPLES
If your system clock gained 8 seconds in 24 hours, you
could set the tick to 9999, and then it would lose 0.64
seconds a day (that is, 1 tick unit = 8.64 seconds per
day). To correct the rest of the error, you could set the
frequency offset to (1<<16)*0.64/.0864 = 485452. Thus,
putting the following in rc.local would approximately
correct the system clock:
adjtimex --tick 9999 --freq 485452
NOTES
adjtimex adjusts only the system clock -- the one that
runs while the computer is powered up. To set or regulate
the CMOS clock, see hwclock(8).
AUTHORS
Steven S. Dick <ssd@nevets.oau.org>, Jim Van Zandt
<jrv@vanzandt.mv.com>.
SEE ALSO
date(1L), gettimeofday(2), settimeofday(2), hwclock(8),
ntpdate(8), ntpd(8), /usr/src/linux/include/linux/timex.h,
/usr/src/linux/include/linux/sched.h,
/usr/src/linux/kernel/time.c,
/usr/src/linux/kernel/sched.c
October 24, 1998 1
Initially I was puzzled by the "1<<16" which appears in a couple of places.
I eventually figured out that it had to be "2 to the 16" (65536), but I still
didn't know how to get 65536 out of "1<<16". Fortunately, the authors were
listed at the bottom of the man page along with their email address, so I
wrote to them. They both wrote back to tell me that "<<" is the "C" left
shift operator.
I don't think that belongs in the man page. First of all, I seriously doubt
that even 1 in 10,000 Unix Sys Admins care what the value is for the scaling
of the "newfreq" option. I mean they do need to know what the value is, but
they certainly don't care that it happens to be "2 to the16".
I think there would be much to be gained, clairity-wise, by replacing "1<<16"
with 65536. The very very few who might care that happens to be "2 to the
16" will easily recognize that that is what 65536 is. When you use the
'adjtimex --frequency value' command, "value" must be supplied as a decimal
number, so the scaling factor mentioned in the man page ought to be decimal
as well.
Documention should strive for clarity, not "cuteness".
Regards,
Richard Lambert
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org