[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 <[email protected]>, Jim Van Zandt
       <[email protected]>.

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 [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]