[Git][NTPsec/ntpsec][master] Much-needed clarification of the system clock API.

[Eric S. Raymond]

Eric S. Raymond pushed to branch master at NTPsec / ntpsec


Commits:
f96d85a3 by Eric S. Raymond at 2016-10-01T17:28:48-04:00
Much-needed clarification of the system clock API.

- - - - -


1 changed file:

- devel/tour.txt


Changes:

=====================================
devel/tour.txt
=====================================
--- a/devel/tour.txt
+++ b/devel/tour.txt
@@ -167,9 +167,40 @@ quite a while before NTPsec removed it.
 == System call interface and the PLL ==
 
 All of ntpd's clock management is done through four system calls:
-clock_gettime(2), clock_settime(2), ntp_adjtime(2), and (on some
-systems) adjtimex().  The settimeofday(2) call from older BSD
-Unuxes (in POSIX but deprecated) is no longer used.
+clock_gettime(2), clock_settime(2), and either ntp_adjtime(2) or (on
+some systems, including Linux) adjtimex(2).
+
+The clock_gettime(2) and clock_settime(2) calls are standardized in
+POSIX; ntp_adjtime(3) and adjtimex(2) are not, exhibiting some
+variability in behavior across platforms.  Where adjtimex(2) exists
+(notably under Linux), ntp_adjtime(2) is implemented as a thin
+userspace wrapper around it.
+
+There is some confusion abroad about this interface because it has
+left a trail of abandoned experiments behind it.
+
+Older BSD systems read the clock using gettimeofday(2) 
+(in POSIX but deprecated) and set it using settimeofday(2),
+which was never standardized.  There was also an adjtime(2)
+call similar to, but less powerful than, ntp_adjtime(2)/adjtimex(2).
+None of these calls are still used in NTPsec.
+
+Also, glibc (and possibly other C libraries) implement two other
+related calls, ntp_gettime(3) and ntp_gettimex(3). These are not used
+by the NTP suite itself (except that the ntptime test program attempts
+to exercise ntp_gettime(3)), but rather are intended for time-using
+applications that also want an estimate of clock error and the
+leap-second offset.  Neither has been standardized by POSIX, and they
+have not achieved wide use in applications.
+
+Both ntp_gettime(3) and ntp_gettimex(3) can be implemented as wrappers
+around ntp_adjtime(2)/adjtimex(2).  Thus, on a Linux system, the
+library ntp_gettime(3) call could conceivably go through two levels 
+of indirection, being implemented in terms of ntp_adjtime(2) which
+is in turn implemented by adjtimex(2).
+
+Unhelpfully, the non-POSIX calls in the above assortment are very
+poorly documented.
 
 The roles of clock_gettime(2) and clock_settime(2) are simple.
 They're used for reading and setting ("stepping", in NTP jargon) the



View it on GitLab: https://gitlab.com/NTPsec/ntpsec/commit/f96d85a3e781877ee26fdc0e8c067f6443b0c40b
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20161001/e5ca434e/attachment.html>