File: libc.info,  Node: Precision Time,  Next: Setting an Alarm,  Prev: Calenda\r Time,  Up: Date and Time

Precision Time
==============

   The `net_gettime' and `ntp_adjtime' functions provide an interface
to monitor and manipulate high precision time.  These functions are
declared in `sys/timex.h'.

 - Data Type: struct ntptimeval
     This structure is used to monitor kernel time.  It contains the
     following members:
    `struct timeval time'
          This is the current time.  The `struct timeval' data type is
          described in *Note High-Resolution Calendar::.

    `long int maxerror'
          This is the maximum error, measured in microseconds.  Unless
          updated via `ntp_adjtime' periodically, this value will reach
          some platform-specific maximum value.

    `long int esterror'
          This is the estimated error, measured in microseconds.  This
          value can be set by `ntp_adjtime' to indicate the estimated
          offset of the local clock against the true time.

 - Function: int ntp_gettime (struct ntptimeval *TPTR)
     The `ntp_gettime' function sets the structure pointed to by TPTR
     to current values.  The elements of the structure afterwards
     contain the values the timer implementation in the kernel assumes.
     They might or might not be correct.  If they are not a
     `ntp_adjtime' call is necessary.

     The return value is `0' on success and other values on failure.
     The following `errno' error conditions are defined for this
     function:

    `TIME_ERROR'
          The precision clock model is not properly set up at the
          moment, thus the clock must be considered unsynchronized, and
          the values should be treated with care.

 - Data Type: struct timex
     This structure is used to control and monitor kernel time in a
     greater level of detail.  It contains the following members:
    `unsigned int modes'
          This variable controls whether and which values are set.
          Several symbolic constants have to be combined with *binary
          or* to specify the effective mode.  These constants start
          with `MOD_'.

    `long int offset'
          This value indicates the current offset of the local clock
          from the true time.  The value is given in microseconds.  If
          bit `MOD_OFFSET' is set in `modes', the offset (and possibly
          other dependent values) can be set.  The offset's absolute
          value must not exceed `MAXPHASE'.

    `long int frequency'
          This value indicates the difference in frequency between the
          true time and the local clock.  The value is expressed as
          scaled PPM (parts per million, 0.0001%).  The scaling is `1
          << SHIFT_USEC'.  The value can be set with bit
          `MOD_FREQUENCY', but the absolute value must not exceed
          `MAXFREQ'.

    `long int maxerror'
          This is the maximum error, measured in microseconds.  A new
          value can be set using bit `MOD_MAXERROR'.  Unless updated via
          `ntp_adjtime' periodically, this value will increase steadily
          and reach some platform-specific maximum value.

    `long int esterror'
          This is the estimated error, measured in microseconds.  This
          value can be set using bit `MOD_ESTERROR'.

    `int status'
          This valiable reflects the various states of the clock
          machinery.  There are symbolic constants for the significant
          bits, starting with `STA_'.  Some of these flags can be
          updated using the `MOD_STATUS' bit.

    `long int constant'
          This value represents the bandwidth or stiffness of the PLL
          (phase locked loop) implemented in the kernel.  The value can
          be changed using bit `MOD_TIMECONST'.

    `long int precision'
          This value represents the accuracy or the maximum error when
          reading the system clock.  The value is expressed in
          microseconds and can't be changed.

    `long int tolerance'
          This value represents the maximum frequency error of the
          system clock in scaled PPM.  This value is used to increase
          the `maxerror' every second.

    `long int ppsfreq'
          This is the first of a few optional variables that are
          present only if the system clock can use a PPS (pulse per
          second) signal to discipline the local clock.  The value is
          expressed in scaled PPM and it denotes the difference in
          frequency between the local clock and the PPS signal.

    `long int jitter'
          This value expresses a median filtered average of the PPS
          signal's dispersion in microseconds.

    `int int shift'
          This value is a binary exponent for the duration of the PPS
          calibration interval, ranging from `PPS_SHIFT' to
          `PPS_SHIFTMAX'.

    `long int stabil'
          This value represents the median filtered dispersion of the
          PPS frequency in scaled PPM.

    `long int jitcnt'
          This counter represents the numer of pulses where the jitter
          exceeded the allowed maximum `MAXTIME'.

    `long int calcnt'
          This counter reflects the number of successful calibration
          intervals.

    `long int errcnt'
          This counter represents the number of calibration errors
          (caused by large offsets or jitter).

    `long int stbcnt'
          This counter denotes the number of of calibrations where the
          stability exceeded the threshold.

 - Function: int ntp_adjtime (struct timex *TPTR)
     The `ntp_adjtime' function sets the structure specified by TPTR to
     current values.  In addition, values passed in TPTR can be used to
     replace existing settings.  To do this the `modes' element of the
     `struct timex' must be set appropriately.  Setting it to zero
     selects reading the current state.

     The return value is `0' on success and other values on failure.
     The following `errno' error conditions are defined for this
     function:

    `TIME_ERROR'
          The precision clock model is not properly set up at the
          moment, thus the clock must be considered unsynchronized, and
          the values should be treated with care.  Another reason could
          be that the specified new values are not allowed.

     For more details see RFC1305 (Network Time Protocol, Version 3) and
     related documents.



