[PATCH 1/2] adjtimex.2: Clarify the 'ppm scaling' used in struct timex

[Laurent Georget]

Hi,

this is the last version of a new series of patchs for adjtimex.2.
Please ignore all previous versions of this series.

This patch makes explicit and clarifies the unit used for fields "freq", "ppsfreq" and "stabil" in struct timex.
It closes a FIXME in the man page.

Reviewed-By: Jeff Epler <jepler@xxxxxxxxxxxxxx>

---
 man2/adjtimex.2 | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 18823c8..ff4b23e 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -54,9 +54,8 @@ struct timex {
     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 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 */
@@ -72,13 +71,13 @@ struct timex {
                          flag is set, otherwise microseconds */
     long tick;        /* Microseconds between clock ticks */
     long ppsfreq;     /* PPS (pulse per second) frequency
-                         (scaled PPM, read-only) */
+                         (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 (scaled PPM, 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) */
@@ -343,6 +342,18 @@ 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-bits fractional part, which means that a
+value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 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
-- 
2.0.4

Attachment: signature.asc
Description: OpenPGP digital signature