kernel对NTP的API，系统调用函数

kenrel API for NTP

kernel 提供两个API（即系统调用 system call）给应用程序NTP，去校准kernel system clock

Kernel Application Program Interface

The kernel application program interface (API) is used by the NTP protocol daemon (or equivalent) to discipline the system clock and set various parameters necessary for its correct operation. The API is used by application programs to read the system clock and determine its health and expected error values. Following is a description of the interface, as well as the control and monitoring variables involved.

The API consists of two Unix system calls, ntp_gettime() and ntp_adjtime(). The ntp_gettime() call returns the current system time in either timespec format in seconds and nanooseconds, or timeval format in seconds and microseconds, as determined by the particular operating system. In addition to the time value, this system call returns variables representing the maximum credible error and estimated error of the time value in microseconds and the current offset of International Atomic Time (TAI) relative to Universal Coordinated Time (UTC) when available. The ntp_adjtime() call is used to set and read certain kernel state variables according to a set of mode bits in the call. To set the variables requires superuser permission, but to read them requires no special permissions. Both system calls return a code indicating the current status of the system clock; that is, whether a leap second is pending or whether the clock is synchronized to a working reference source.

Following is a description of the various values used by the API, including state variables and control/status bits. Detailed calling sequences and structure definitions are in the timex.h header file included in the distribution.

adjtimex / ntp_adjtime - tune kernel clock

#man 2 adjtimex,其实kernel提供了两个system call ,用来调整kernel clock，一个是，adjtimex，一个是ntp_adjtime()

Linux uses David L. Mills’ clock adjustment algorithm (see RFC 1305). The system call adjtimex() reads and optionally sets adjustment parameters for this algorithm. It takes a pointer to a timex structure, updates kernel parameters from field values, and returns the same structure with current kernel values. This structure is declared as follows:

ntptime命令是ntpd包里的一个工具，它不是通过adjtimex系统调用对kernel clock进行调整的，而是通过，ntp_adjtime系统调用；

所以，推荐使用ntp_adjtime这个系统调用，而不是adjtimex!!!

http://man7.org/linux/man-pages/man2/adjtimex.2.html

但是原理上，这两个system call是没有区别的！！

adjtimex 和 ntp_adjtime 系统调用的返回值

RETURN VALUE top

   On success, adjtimex() and ntp_adjtime() return the clock state; that
   is, one of the following values:

   TIME_OK     Clock synchronized, no leap second adjustment pending.

   TIME_INS    Indicates that a leap second will be added at the end of
               the UTC day.

   TIME_DEL    Indicates that a leap second will be deleted at the end
               of the UTC day.

   TIME_OOP    Insertion of a leap second is in progress.

   TIME_WAIT   A leap-second insertion or deletion has been completed.
               This value will be returned until the next ADJ_STATUS
               operation clears the STA_INS and STA_DEL flags.

   TIME_ERROR  The system clock is not synchronized to a reliable
               server.  This value is returned when any of the following
               holds true:

               *  Either STA_UNSYNC or STA_CLOCKERR is set.

               *  STA_PPSSIGNAL is clear and either STA_PPSFREQ or
                  STA_PPSTIME is set.

               *  STA_PPSTIME and STA_PPSJITTER are both set.

               *  STA_PPSFREQ is set and either STA_PPSWANDER or
                  STA_PPSJITTER is set.

               The symbolic name TIME_BAD is a synonym for TIME_ERROR,
               provided for backward compatibility.

   Note that starting with Linux 3.4, the call operates asynchronously
   and the return value usually will not reflect a state change caused
   by the call itself.

   On failure, these calls return -1 and set errno.

timex 结构体

man 2 adjtimex 你会看到 timex结构体

       struct timex {
           int modes;           /* mode selector */
           long offset;         /* time offset (usec) */
           long freq;           /* frequency offset (scaled ppm) */
           long maxerror;       /* maximum error (usec) */
           long esterror;       /* estimated error (usec) */
           int status;          /* clock command/status */
           long constant;       /* pll time constant */
           long precision;      /* clock precision (usec) (read-only) */
           long tolerance;      /* clock frequency tolerance (ppm)
                                   (read-only) */
           struct timeval time; /* current time (read-only) */
           long tick;           /* usecs between clock ticks */
       };

The ntp_adjtime() System Call

The ntp_adjtime() system call is used to set and read kernel variables used by kernel. It operates using the timex structure described in the timex.h header file. This structure is used both to change the values of certain kernel variables and to return the current values. Root privilege is required to change the values. Following are the variables that can be read and written. The return codes are described in the Return Codes and the Leap-Second State Machine section on this page.

The ntp_gettime() System Call

The ntp_gettime() system call is used to read the current system time and related error variables. It uses the ntptimeval structure described in the timex.h header file. This structure includes the following variables. The return codes are described in the Return Codes and the Leap-Second State Machine section on this page.