rfc1589.txt

来自「著名的RFC文档,其中有一些文档是已经翻译成中文的的.」· 文本 代码 · 共 1,332 行 · 第 1/5 页

                   No Leap       Leap Insert    Leap Delete
                   UTC NTP         UTC NTP        UTC NTP
              ---------------------------------------------
              23:59:58|398    23:59:58|398   23:59:58|398
                      |               |              |
              23:59:59|399    23:59:59|399   00:00:00|400
                      |               |              |
              00:00:00|400    23:59:60|399   00:00:01|401
                      |               |              |
              00:00:01|401    00:00:00|400   00:00:02|402
                      |               |              |
              00:00:02|402    00:00:01|401   00:00:03|403
                      |               |              |

      To determine local midnight without fuss, the kernel code simply
      finds the residue of the time.tv_sec (or time.tv_sec + 1) value
      mod 86,400, but this requires a messy divide. Probably a better
      way to do this is to initialize an auxiliary counter in the
      settimeofday() routine using an ugly divide and increment the
      counter at the same time the time.tv_sec is incremented in the
      timer interrupt routine. For future embellishment.

4. Programming Model and Interfaces

   This section describes the programming model for the synchronization
   daemon and user application programs. The ideas are based on
   suggestions from Jeff Mogul and Philip Gladstone and a similar
   interface designed by the latter. It is important to point out that
   the functionality of the original Unix adjtime() system call is
   preserved, so that the modified kernel will work as the unmodified
   one, should the new features not be in use. In this case the
   ntp_adjtime() system call can still be used to read and write kernel
   variables that might be used by a synchronization daemon other than
   NTP, for example.

   4.1. The ntp_gettime() System Call

      The syntax and semantics of the ntp_gettime() call are given in
      the following fragment of the timex.h header file. This file is
      identical, except for the SHIFT_HZ define, in the SunOS, Ultrix
      and OSF/1 kernel distributions. (The SHIFT_HZ define represents
      the logarithm to the base 2 of the clock oscillator frequency
      specific to each system type.) Note that the timex.h file calls
      the syscall.h system header file, which must be modified to define
      the SYS_ntp_gettime system call specific to each system type. The
      kernel distributions include directions on how to do this.





Mills                                                          [Page 20]

RFC 1589         Kernel Model for Precision Timekeeping       March 1994


      /*
       * This header file defines the Network Time Protocol (NTP)
       * interfaces for user and daemon application programs. These are
       * implemented using private system calls and data structures and
       * require specific kernel support.
       *
       * NAME
       *   ntp_gettime - NTP user application interface
       *
       * SYNOPSIS
       *   #include <sys/timex.h>
       *
       *   int system call(SYS_ntp_gettime, tptr)
       *
       *   int SYS_ntp_gettime     defined in syscall.h header file
       *   struct ntptimeval *tptr pointer to ntptimeval structure
       *
       * NTP user interface - used to read kernel clock values
       * Note: maximum error = NTP synch distance = dispersion + delay /
       * 2
       * estimated error = NTP dispersion.
       */
      struct ntptimeval {
           struct timeval time;    /* current time */
           long maxerror;          /* maximum error (us) */
           long esterror;          /* estimated error (us) */
      };

      The ntp_gettime() system call returns three values in the
      ntptimeval structure: the current time in unix timeval format plus
      the maximum and estimated errors in microseconds. While the 32-bit
      long data type limits the error quantities to something more than
      an hour, in practice this is not significant, since the protocol
      itself will declare an unsynchronized condition well below that
      limit. In the NTP Version 3 specification, if the protocol
      computes either of these values in excess of 16 seconds, they are
      clamped to that value and the system clock declared
      unsynchronized.

      Following is a detailed description of the ntptimeval structure
      members.










Mills                                                          [Page 21]

RFC 1589         Kernel Model for Precision Timekeeping       March 1994


      struct timeval time;    /* current time */

         This member returns the current system time, expressed as a
         Unix timeval structure. The timeval structure consists of two
         32-bit words; the first returns the number of seconds past 1
         January 1970, while the second returns the number of
         microseconds.

      long maxerror;          /* maximum error (us) */

         This member returns the time_maxerror kernel variable in
         microseconds. See the entry for this variable in section 5 for
         additional information.

      long esterror;          /* estimated error (us) */

         This member returns the time_esterror kernel variable in
         microseconds. See the entry for this variable in section 5 for
         additional information.
































Mills                                                          [Page 22]

RFC 1589         Kernel Model for Precision Timekeeping       March 1994


   4.2. The ntp_adjtime() System Call

      The syntax and semantics of the ntp_adjtime() call are given in
      the following fragment of the timex.h header file. Note that, as
      in the ntp_gettime() system call, the syscall.h system header file
      must be modified to define the SYS_ntp_adjtime system call
      specific to each system type.

      /*
       * NAME
       *   ntp_adjtime - NTP daemon application interface
       *
       * SYNOPSIS
       *   #include <sys/timex.h>
       *
       *   int system call(SYS_ntp_adjtime, mode, tptr)
       *
       *   int SYS_ntp_adjtime     defined in syscall.h header file
       *   struct timex *tptr      pointer to timex structure
       *
       * NTP daemon interface - used to discipline kernel clock
       * oscillator
       */
      struct timex {
          int mode;                /* mode selector */
          long offset;             /* time offset (us) */
          long frequency;          /* frequency offset (scaled ppm) */
          long maxerror;           /* maximum error (us) */
          long esterror;           /* estimated error (us) */
          int status;              /* clock command/status */
          long time_constant;      /* pll time constant */
          long precision;          /* clock precision (us) (read only)
                                    */
          long tolerance;          /* clock frequency tolerance (scaled
                                    * ppm) (read only) */
          /*
           * The following read-only structure members are implemented
           * only if the PPS signal discipline is configured in the
           * kernel.
           */
          long ybar;               /* frequency estimate (scaled ppm) */
          long disp;               /* dispersion estimate (scaled ppm)
                                    */
          int shift;               /* interval duration (s) (shift) */
          long calcnt;             /* calibration intervals */
          long jitcnt;             /* jitter limit exceeded */
          long discnt;             /* dispersion limit exceeded */
      };



Mills                                                          [Page 23]

RFC 1589         Kernel Model for Precision Timekeeping       March 1994


      The ntp_adjtime() system call is used to read and write certain
      time-related kernel variables summarized in this and subsequent
      sections. Writing these variables can only be done in superuser
      mode. To write a variable, the mode structure member is set with
      one or more bits, one of which is assigned each of the following
      variables in turn. The current values for all variables are
      returned in any case; therefore, a mode argument of zero means to
      return these values without changing anything.

      Following is a description of the timex structure members.

      int mode;               /* mode selector */

         This is a bit-coded variable selecting one or more structure
         members, with one bit assigned each member. If a bit is set,
         the value of the associated member variable is copied to the
         corresponding kernel variable; if not, the member is ignored.
         The bits are assigned as given in the following fragment of the
         timex.h header file. Note that the precision and tolerance are
         determined by the kernel and cannot be changed by
         ntp_adjtime().

         /*
          * Mode codes (timex.mode)
          */
         #define ADJ_OFFSET       0x0001    /* time offset */
         #define ADJ_FREQUENCY    0x0002    /* frequency offset */
         #define ADJ_MAXERROR     0x0004    /* maximum time error */
         #define ADJ_ESTERROR     0x0008    /* estimated time error */
         #define ADJ_STATUS       0x0010    /* clock status */
         #define ADJ_TIMECONST    0x0020    /* pll time constant */

      long offset;            /* time offset (us) */

         If selected, this member replaces the value of the time_offset
         kernel variable in microseconds. The absolute value must be
         less than MAXPHASE microseconds defined in the timex.h header
         file. See the