lib/libc/sys/ntp_adjtime.2

   1 .\"
   2 .\" Copyright (c) 2003 Tom Rhodes
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libc/sys/ntp_adjtime.2,v 1.1.2.1 2003/04/22 17:31:18 trhodes Exp $
  27 .\"
  28 .Dd April 25, 2012
  29 .Dt NTP_ADJTIME 2
  30 .Os
  31 .Sh NAME
  32 .Nm ntp_adjtime
  33 .Nd NTP daemon application interface
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/timex.h
  39 .Ft int
  40 .Fn ntp_adjtime "struct timex *tp"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn ntp_adjtime
  44 system call is used as a kernel interface
  45 for Network Time Protocol daemons like
  46 .Xr dntpd 8
  47 and
  48 .Xr ntpd 8 .
  49 Certain fields of the
  50 .Vt timex
  51 structure are interpreted in either
  52 microseconds or nanoseconds, according to the state of the
  53 .Dv STA_NANO
  54 bit in the
  55 .Va status
  56 word.
  57 .Pp
  58 In the
  59 .Dx
  60 kernel, the
  61 .Fn ntp_adjtime
  62 and
  63 .Xr ntp_gettime 2
  64 system calls can be used to determine which
  65 resolution is in use, and to select either one at any time.
  66 The resolution selected affects the scaling of certain fields in the
  67 .Fn ntp_gettime
  68 and
  69 .Fn ntp_adjtime
  70 system calls.
  71 .Pp
  72 Take note that this
  73 .Tn API
  74 is extremely complex and stateful.
  75 Users should not attempt modification without first
  76 reviewing the
  77 .Xr ntpd 8
  78 sources in depth.
  79 .Bd -literal
  80 /*
  81  * NTP daemon interface (ntp_adjtime()) - used to discipline CPU clock
  82  * oscillator and determine status.
  83  *
  84  * Note: The offset, precision and jitter members are in microseconds if
  85  * STA_NANO is zero and nanoseconds if not.
  86  */
  87 struct timex {
  88         unsigned int modes;     /* clock mode bits (wo) */
  89         long    offset;         /* time offset (ns/us) (rw) */
  90         long    freq;           /* frequency offset (scaled PPM) (rw) */
  91         long    maxerror;       /* maximum error (us) (rw) */
  92         long    esterror;       /* estimated error (us) (rw) */
  93         int     status;         /* clock status bits (rw) */
  94         long    constant;       /* poll interval (log2 s) (rw) */
  95         long    precision;      /* clock precision (ns/us) (ro) */
  96         long    tolerance;      /* clock frequency tolerance (scaled
  97                                  * PPM) (ro) */
  98         /*
  99          * The following read-only structure members are implemented
 100          * only if the PPS signal discipline is configured in the
 101          * kernel. They are included in all configurations to insure
 102          * portability.
 103          */
 104         long    ppsfreq;        /* PPS frequency (scaled PPM) (ro) */
 105         long    jitter;         /* PPS jitter (ns/us) (ro) */
 106         int     shift;          /* interval duration (s) (shift) (ro) */
 107         long    stabil;         /* PPS stability (scaled PPM) (ro) */
 108         long    jitcnt;         /* jitter limit exceeded (ro) */
 109         long    calcnt;         /* calibration intervals (ro) */
 110         long    errcnt;         /* calibration errors (ro) */
 111         long    stbcnt;         /* stability limit exceeded (ro) */
 112 };
 113 .Ed
 114 .Pp
 115 Upon successful completion,
 116 .Fn ntp_adjtime
 117 will fill the
 118 .Fa tp
 119 argument with the current clock state.
 120 .Sh RETURN VALUES
 121 .Rv -std ntp_adjtime
 122 .Pp
 123 Possible states of the clock are:
 124 .Pp
 125 .Bl -tag -compact -width ".Dv TIME_ERROR"
 126 .It Dv TIME_OK
 127 Everything okay, no leap second warning.
 128 .It Dv TIME_INS
 129 insert leap second warning.
 130 .It Dv TIME_DEL
 131 delete leap second warning.
 132 .It Dv TIME_OOP
 133 Leap second in progress.
 134 .It Dv TIME_WAIT
 135 Leap second has occurred.
 136 .It Dv TIME_ERROR
 137 Clock not synchronized.
 138 .El
 139 .Sh ERRORS
 140 The
 141 .Fn ntp_adjtime
 142 system call may return
 143 .Er EPERM
 144 if the caller
 145 does not have sufficient permissions.
 146 .Sh SEE ALSO
 147 .Xr ntp_gettime 2 ,
 148 .Xr dntpd 8 ,
 149 .Xr ntpd 8 Pq Pa net/openntpd
 150 .Sh AUTHORS
 151 This manual page was written by
 152 .An Tom Rhodes Aq trhodes@FreeBSD.org .