Provided by: manpages-dev_4.04-2_all bug


       adjtimex - tune kernel clock


       #define _BSD_SOURCE      /* See feature_test_macros(7) */
       #include <sys/timex.h>

       int adjtimex(struct timex *buf);


       Linux  uses  David L. Mills' clock adjustment algorithm (see RFC 5905).
       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:

           struct timex {
               int  modes;      /* Mode selector */
               long offset;     /* Time offset; nanoseconds, if STA_NANO
                                   status flag is set, otherwise microseconds */
               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 */
               long constant;   /* PLL (phase-locked loop) time constant */
               long precision;  /* Clock precision (microseconds, read-only) */
               long tolerance;  /* Clock frequency tolerance (ppm, read-only) */
               struct timeval time;
                                /* Current time (read-only, except for
                                   ADJ_SETOFFSET); upon return, time.tv_usec
                                   contains nanoseconds, if STA_NANO status
                                   flag is set, otherwise microseconds */
               long tick;       /* Microseconds between clock ticks */
               long ppsfreq;    /* PPS (pulse per second) frequency (in units
                                   of 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 (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) */
               long stbcnt;     /* PPS stability limit exceeded (read-only) */
               int tai;         /* TAI offset, as set by previous ADJ_TAI
                                   operation (seconds, read-only,
                                   since Linux 2.6.26) */
               /* Further padding bytes to allow for future expansion */

       The modes field determines which parameters, if any, to set.  It  is  a
       bit  mask  containing  a  bitwise-or combination of zero or more of the
       following bits:

              Set time offset from buf.offset.

              Set frequency offset from buf.freq.

              Set maximum time error from buf.maxerror.

              Set estimated time error from buf.esterror.

              Set clock status from buf.status.

              Set PLL time constant from buf.constant.  If the STA_NANO status
              flag (see below) is clear, the kernel adds 4 to this value.

       ADJ_SETOFFSET (since Linux 2.6.29)
              Add  buf.time  to  the current time.  If buf.status includes the
              ADJ_NANO  flag,  then  buf.time.tv_usec  is  interpreted  as   a
              nanosecond value; otherwise it is interpreted as microseconds.

       ADJ_MICRO (since Linux 2.6.36)
              Select microsecond resolution.

       ADJ_NANO (since Linux 2.6.36)
              Select   nanosecond  resolution.   Only  one  of  ADJ_MICRO  and
              ADJ_NANO should be specified.

       ADJ_TAI (since Linux 2.6.26)
              Set TAI (Atomic International Time) offset from buf->constant.

              ADJ_TAI should not be used in  conjunction  with  ADJ_TIMECONST,
              since the latter mode also employs the buf->constant field.

              For a complete explanation of TAI and the difference between TAI
              and UTC, see BIPM
              Set tick value from buf.tick.

       Alternatively, modes can  be  specified  as  either  of  the  following
       (multibit  mask)  values,  in  which  case  other  bits  should  not be
       specified in modes:

              Old-fashioned  adjtime():  (gradually)  adjust  time  by   value
              specified  in  buf.offset,  which  specifies  an  adjustment  in

       ADJ_OFFSET_SS_READ (functional since Linux 2.6.28)
              Return (in buf.offset)  the  remaining  amount  of  time  to  be
              adjusted after an earlier ADJ_OFFSET_SINGLESHOT operation.  This
              feature was added in Linux 2.6.24, but did  not  work  correctly
              until Linux 2.6.28.

       Ordinary   users   are   restricted   to   a   value  of  either  0  or
       ADJ_OFFSET_SS_READ  for  modes.   Only  the  superuser  may   set   any

       The  buf.status field is a bit mask that is used to set and/or retrieve
       status bits associated with the NTP implementation.  Some bits  in  the
       mask are both readable and settable, while others are read-only.

              Enable   phase-locked   loop   (PLL)  updates  (read-write)  via

              Enable PPS freq discipline (read-write).

              Enable PPS time discipline (read-write).

              Select frequency-locked loop (FLL) mode (read-write).

              Insert leap second (read-write).

              Delete leap second (read-write).

              Clock unsynchronized (read-write).

              Hold frequency (read-write).

              PPS signal present (read-only).

              PPS signal jitter exceeded (read-only).

              PPS signal wander exceeded (read-only).

              PPS signal calibration error (read-only).

              Clock hardware fault (read-only).

       STA_NANO (since Linux 2.6.26)
              Resolution (0 = microsecond, 1 = nanoseconds;  read-only).   Set
              via ADJ_NANO, cleared via ADJ_MICRO.

       STA_MODE (since Linux 2.6.26)
              Mode  (0  =  Phase Locked Loop, 1 = Frequency Locked Loop; read-

       STA_CLK (since Linux 2.6.26)
              Clock source (0 = A, 1 = B; read-only).

       Attempts to set read-only status bits are silently ignored.


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

       TIME_OK     Clock synchronized.

       TIME_INS    Insert leap second.

       TIME_DEL    Delete leap second.

       TIME_OOP    Leap second in progress.

       TIME_WAIT   Leap second has occurred.

       TIME_ERROR  Clock  not  synchronized.   The symbolic name TIME_BAD is a
                   synonym   for    TIME_ERROR,    provided    for    backward

       On failure, adjtimex() returns -1 and sets errno.


       EFAULT buf does not point to writable memory.

       EINVAL An  attempt  was  made  to set buf.offset to a value outside the
              range -131071 to +131071, or to set buf.status to a value  other
              than  those  listed above, or to set buf.tick to a value outside
              the range 900000/HZ to 1100000/HZ, where HZ is the system  timer
              interrupt frequency.

       EPERM  buf.modes  is  neither  0 nor ADJ_OFFSET_SS_READ, and the caller
              does  not  have  sufficient   privilege.    Under   Linux,   the
              CAP_SYS_TIME capability is required.


       In  struct timex, freq, ppsfreq, and stabil are ppm (parts per million)
       with a 16-bit fractional part, which means that a value of 1 in one  of
       those  fields  actually means 2^-16 ppm, and 2^16=65536 is 1 ppm.  This
       is the case for both input values (in the  case  of  freq)  and  output


       adjtimex()  is  Linux-specific  and  should  not  be  used  in programs
       intended to be portable.  See adjtime(3) for a more portable, but  less
       flexible, method of adjusting the system clock.


       settimeofday(2), adjtime(3), capabilities(7), time(7), adjtimex(8)


       This  page  is  part of release 4.04 of the Linux man-pages project.  A
       description of the project, information about reporting bugs,  and  the
       latest     version     of     this    page,    can    be    found    at