LDP: Update original to LDP v3.77

[linuxjm/LDP_man-pages.git] / original / man2 / adjtimex.2

diff --git a/original/man2/adjtimex.2 b/original/man2/adjtimex.2
index 7d5c942..ea94610 100644 (file)
--- a/original/man2/adjtimex.2
+++ b/original/man2/adjtimex.2
@@ -50,43 +50,38 @@ This structure is declared as follows:
 .in +4n
 .nf
 struct timex {
-    int  modes;       /* Mode selector */
-    long offset;      /* Time offset; nanoseconds, if STA_NANO
-                         status flag is set, otherwise
-                         microseconds */
-    long freq;        /* Frequency offset, as scaled PPM
-                         (parts per million) */
-.\" FIXME What is the scaling unit of timex.freq?  2^16 ?
-    long maxerror;    /* Maximum error (microseconds) */
-    long esterror;    /* Estimated error (microseconds) */
-    int  status;      /* Clock command/status */
-    long constant;    /* PLL (phase-locked loop) time constant */
-    long precision;   /* Clock precision (microseconds,
-                         read-only) */
-    long tolerance;   /* Clock frequency tolerance (PPM,
-                         read-only) */
+    int  modes;      /* Mode selector */
+    long offset;     /* Time offset; nanoseconds, if STA_NANO
+                        status flag is set, otherwise microseconds */
+    long freq;       /* Frequency offset, in units of 2^-16 ppm
+                        (parts per million, see NOTES below) */
+    long maxerror;   /* Maximum error (microseconds) */
+    long esterror;   /* Estimated error (microseconds) */
+    int  status;     /* Clock command/status */
+    long constant;   /* PLL (phase-locked loop) time constant */
+    long precision;  /* Clock precision (microseconds, read-only) */
+    long tolerance;  /* Clock frequency tolerance (ppm, read-only) */
     struct timeval time;
-                      /* Current time (read-only, except for
-                         ADJ_SETOFFSET); upon return, time.tv_usec
-                         contains nanoseconds, if STA_NANO status
-                         flag is set, otherwise microseconds */
-    long tick;        /* Microseconds between clock ticks */
-    long ppsfreq;     /* PPS (pulse per second) frequency
-                         (scaled PPM, read-only) */
-    long jitter;      /* PPS jitter (read-only); nanoseconds, if
-                         STA_NANO status flag is set, otherwise
-                         microseconds */
-    int  shift;       /* PPS interval duration
-                         (seconds, read-only) */
-    long stabil;      /* PPS stability (scaled PPM, read-only) */
-    long jitcnt;      /* PPS jitter limit exceeded (read-only) */
-    long calcnt;      /* PPS calibration intervals (read-only) */
-    long errcnt;      /* PPS calibration errors (read-only) */
-    long stbcnt;      /* PPS stability limit exceeded
-                         (read-only) */
-    int tai;          /* TAI offset, as set by previous ADJ_TAI
-                         operation (seconds, read-only,
-                         since Linux 2.6.26) */
+                     /* Current time (read-only, except for
+                        ADJ_SETOFFSET); upon return, time.tv_usec
+                        contains nanoseconds, if STA_NANO status
+                        flag is set, otherwise microseconds */
+    long tick;       /* Microseconds between clock ticks */
+    long ppsfreq;    /* PPS (pulse per second) frequency (in units
+                        of 2^-16 ppm\-\-see NOTES, read-only) */
+    long jitter;     /* PPS jitter (read-only); nanoseconds, if
+                        STA_NANO status flag is set, otherwise
+                        microseconds */
+    int  shift;      /* PPS interval duration (seconds, read-only) */
+    long stabil;     /* PPS stability (2^-16 ppm\-\-see NOTES,
+                        read-only) */
+    long jitcnt;     /* PPS jitter limit exceeded (read-only) */
+    long calcnt;     /* PPS calibration intervals (read-only) */
+    long errcnt;     /* PPS calibration errors (read-only) */
+    long stbcnt;     /* PPS stability limit exceeded (read-only) */
+    int tai;         /* TAI offset, as set by previous ADJ_TAI
+                        operation (seconds, read-only,
+                        since Linux 2.6.26) */
     /* Further padding bytes to allow for future expansion */
 };
 .fi
@@ -281,6 +276,8 @@ Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop; read-only).
 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 Clock source (0 = A, 1 = B; read-only).
+.\" FIXME It would be helpful to have some explanation of what
+.\"       "Clock source" is.
 .PP
 Attempts to set read-only
 .I status
@@ -305,8 +302,13 @@ Leap second in progress.
 .BR TIME_WAIT
 Leap second has occurred.
 .TP
-.BR TIME_BAD
+.BR TIME_ERROR
 Clock not synchronized.
+The symbolic name
+.B TIME_BAD
+is a synonym for
+.BR TIME_ERROR ,
+provided for backward compatibility.
 .PP
 On failure,
 .BR adjtimex ()
@@ -343,6 +345,19 @@ and the caller does not have sufficient privilege.
 Under Linux, the
 .B CAP_SYS_TIME
 capability is required.
+.SH NOTES
+In struct
+.IR timex ,
+.IR freq ,
+.IR ppsfreq ,
+and
+.I stabil
+are ppm (parts per million) with a 16-bit fractional part,
+which means that a value of 1 in one of those fields
+actually means 2^-16 ppm, and 2^16=65536 is 1 ppm.
+This is the case for both input values (in the case of
+.IR freq )
+and output values.
 .SH CONFORMING TO
 .BR adjtimex ()
 is Linux-specific and should not be used in programs
@@ -358,7 +373,7 @@ method of adjusting the system clock.
 .BR time (7),
 .BR adjtimex (8)
 .SH COLOPHON
-This page is part of release 3.76 of the Linux
+This page is part of release 3.77 of the Linux
 .I man-pages
 project.
 A description of the project,