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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Sat, 03 Jan 2015 00:01:52 +0100
From:	Laurent Georget <laurent.georget@...elec.fr>
To:	linux-man <linux-man@...r.kernel.org>
CC:	linux-kernel@...r.kernel.org, Jeff Epler <jepler@...ythonic.net>,
	Richard Cochran <richardcochran@...il.com>
Subject: [PATCH 1/2] adjtimex.2: Clarify the 'ppm scaling' used in struct
 timex

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@...ythonic.net>

---
 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



Download attachment "signature.asc" of type "application/pgp-signature" (214 bytes)