lib/libc/sys/ntp_adjtime.2

   1 .\"     $NetBSD: ntp_adjtime.2,v 1.6 2003/04/16 13:34:55 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Thomas Klausner.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd July 13, 2005
  31 .Dt NTP_ADJTIME 2
  32 .Os
  33 .Sh NAME
  34 .Nm ntp_adjtime ,
  35 .Nm ntp_gettime
  36 .Nd Network Time Protocol (NTP) daemon interface system calls
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/timex.h
  41 .Ft int
  42 .Fn ntp_adjtime "struct timex *"
  43 .Ft int
  44 .Fn ntp_gettime "struct ntptimeval *"
  45 .Sh DESCRIPTION
  46 The two system calls
  47 .Fn ntp_adjtime
  48 and
  49 .Fn ntp_gettime
  50 are the kernel interface to the Network Time Protocol (NTP) daemon
  51 .Xr ntpd 8 .
  52 .Pp
  53 The
  54 .Fn ntp_adjtime
  55 function is used by the NTP daemon to adjust the system clock to an
  56 externally derived time.
  57 The time offset and related variables which are set by
  58 .Fn ntp_adjtime
  59 are used by
  60 .Fn hardclock
  61 to adjust the phase and frequency of the phase- or frequency-lock loop
  62 (PLL resp. FLL) which controls the system clock.
  63 .Pp
  64 The
  65 .Fn ntp_gettime
  66 function provides the time, maximum error (sync distance) and
  67 estimated error (dispersion) to client user application programs.
  68 .Pp
  69 In the following, all variables that refer PPS are only relevant if
  70 the
  71 .Em PPS_SYNC
  72 option is enabled in the kernel.
  73 .Pp
  74 .Fn ntp_adjtime
  75 has as argument a
  76 .Va struct timex *
  77 of the following form:
  78 .Bd -literal
  79 struct timex {
  80         unsigned int modes;     /* clock mode bits (wo) */
  81         long offset;            /* time offset (us) (rw) */
  82         long freq;              /* frequency offset (scaled ppm) (rw) */
  83         long maxerror;          /* maximum error (us) (rw) */
  84         long esterror;          /* estimated error (us) (rw) */
  85         int status;             /* clock status bits (rw) */
  86         long constant;          /* pll time constant (rw) */
  87         long precision;         /* clock precision (us) (ro) */
  88         long tolerance;         /* clock frequency tolerance (scaled
  89                                  * ppm) (ro) */
  90         /*
  91          * The following read-only structure members are implemented
  92          * only if the PPS signal discipline is configured in the
  93          * kernel.
  94          */
  95         long ppsfreq;           /* pps frequency (scaled ppm) (ro) */
  96         long jitter;            /* pps jitter (us) (ro) */
  97         int shift;              /* interval duration (s) (shift) (ro) */
  98         long stabil;            /* pps stability (scaled ppm) (ro) */
  99         long jitcnt;            /* jitter limit exceeded (ro) */
 100         long calcnt;            /* calibration intervals (ro) */
 101         long errcnt;            /* calibration errors (ro) */
 102         long stbcnt;            /* stability limit exceeded (ro) */
 103 };
 104 .Ed
 105 .Pp
 106 The members of this struct have the following meanings when used as
 107 argument for
 108 .Fn ntp_adjtime :
 109 .Bl -tag -width tolerance -compact
 110 .It Fa modes
 111 Defines what settings should be changed with the current
 112 .Fn ntp_adjtime
 113 call (write-only).
 114 Bitwise OR of the following:
 115 .Bl -tag -width MOD_TIMECONST -compact -offset indent
 116 .It MOD_OFFSET
 117 set time offset
 118 .It MOD_FREQUENCY
 119 set frequency offset
 120 .It MOD_MAXERROR
 121 set maximum time error
 122 .It MOD_ESTERROR
 123 set estimated time error
 124 .It MOD_STATUS
 125 set clock status bits
 126 .It MOD_TIMECONST
 127 set PLL time constant
 128 .It MOD_CLKA
 129 set clock A
 130 .It MOD_CLKB
 131 set clock B
 132 .El
 133 .It Fa offset
 134 Time offset (in microseconds), used by the PLL/FLL to adjust the
 135 system time in small increments (read-write).
 136 .It Fa freq
 137 Frequency offset (scaled ppm) (read-write).
 138 .It Fa maxerror
 139 Maximum error (in microseconds).
 140 Initialized by an
 141 .Fn ntp_adjtime
 142 call, and increased by the kernel once each second to reflect the maximum
 143 error bound growth (read-write).
 144 .It Fa esterror
 145 Estimated error (in microseconds).
 146 Set and read by
 147 .Fn ntp_adjtime ,
 148 but unused by the kernel (read-write).
 149 .It Fa status
 150 System clock status bits (read-write).
 151 Bitwise OR of the following:
 152 .Bl -tag -width STA_PPSJITTER -compact -offset indent
 153 .It STA_PLL
 154 Enable PLL updates (read-write).
 155 .It STA_PPSFREQ
 156 Enable PPS freq discipline (read-write).
 157 .It STA_PPSTIME
 158 Enable PPS time discipline (read-write).
 159 .It STA_FLL
 160 Select frequency-lock mode (read-write).
 161 .It STA_INS
 162 Insert leap (read-write).
 163 .It STA_DEL
 164 Delete leap (read-write).
 165 .It STA_UNSYNC
 166 Clock unsynchronized (read-write).
 167 .It STA_FREQHOLD
 168 Hold frequency (read-write).
 169 .It STA_PPSSIGNAL
 170 PPS signal present (read-only).
 171 .It STA_PPSJITTER
 172 PPS signal jitter exceeded (read-only).
 173 .It STA_PPSWANDER
 174 PPS signal wander exceeded (read-only).
 175 .It STA_PPSERROR
 176 PPS signal calibration error (read-only).
 177 .It STA_CLOCKERR
 178 Clock hardware fault (read-only).
 179 .El
 180 .It Fa constant
 181 PLL time constant, determines the bandwidth, or
 182 .Dq stiffness ,
 183 of the PLL (read-write).
 184 .It Fa precision
 185 Clock precision (in microseconds).
 186 In most cases the same as the kernel tick variable (see
 187 .Xr hz 9 ) .
 188 If a precision clock counter or external time-keeping signal is available,
 189 it could be much lower (and depend on the state of the signal)
 190 (read-only).
 191 .It Fa tolerance
 192 Maximum frequency error, or tolerance of the CPU clock oscillator (scaled
 193 ppm).
 194 Ordinarily a property of the architecture, but could change under
 195 the influence of external time-keeping signals (read-only).
 196 .It Fa ppsfreq
 197 PPS frequency offset produced by the frequency median filter (scaled
 198 ppm) (read-only).
 199 .It Fa jitter
 200 PPS jitter measured by the time median filter in microseconds
 201 (read-only).
 202 .It Fa shift
 203 Logarithm to base 2 of the interval duration in seconds (PPS,
 204 read-only).
 205 .It Fa stabil
 206 PPS stability (scaled ppm); dispersion (wander) measured by the
 207 frequency median filter (read-only).
 208 .It Fa jitcnt
 209 Number of seconds that have been discarded because the jitter measured
 210 by the time median filter exceeded the limit
 211 .Em MAXTIME
 212 (PPS, read-only).
 213 .It Fa calcnt
 214 Count of calibration intervals (PPS, read-only).
 215 .It Fa errcnt
 216 Number of calibration intervals that have been discarded because the
 217 wander exceeded the limit
 218 .Em MAXFREQ
 219 or where the calibration interval jitter exceeded two ticks (PPS,
 220 read-only).
 221 .It Fa stbcnt
 222 Number of calibration intervals that have been discarded because the
 223 frequency wander exceeded the limit
 224 .Em MAXFREQ Ns /4
 225 (PPS, read-only).
 226 .El
 227 After the
 228 .Fn ntp_adjtime
 229 call, the
 230 .Va struct timex *
 231 structure contains the current values of the corresponding variables.
 232 .Pp
 233 .Fn ntp_gettime
 234 has as argument a
 235 .Va struct ntptimeval *
 236 with the following members:
 237 .Bd -literal
 238 struct ntptimeval {
 239         struct timeval time;    /* current time (ro) */
 240         long maxerror;          /* maximum error (us) (ro) */
 241         long esterror;          /* estimated error (us) (ro) */
 242 };
 243 .Ed
 244 .Pp
 245 These have the following meaning:
 246 .Bl -tag -width tolerance -compact
 247 .It Fa time
 248 Current time (read-only).
 249 .It Fa maxerror
 250 Maximum error in microseconds (read-only).
 251 .It Fa esterror
 252 Estimated error in microseconds (read-only).
 253 .El
 254 .Sh RETURN VALUES
 255 .Fn ntp_adjtime
 256 and
 257 .Fn ntp_gettime
 258 return the current state of the clock on success, or any of the errors
 259 of
 260 .Xr copyin 9
 261 and
 262 .Xr copyout 9 .
 263 .Fn ntp_adjtime
 264 may additionally return
 265 .Er EPERM
 266 if the user calling
 267 .Fn ntp_adjtime
 268 does not have sufficient permissions.
 269 .Pp
 270 Possible states of the clock are:
 271 .Bl -tag -width TIME_ERROR -compact -offset indent
 272 .It TIME_OK
 273 Everything okay, no leap second warning.
 274 .It TIME_INS
 275 .Dq insert leap second
 276 warning.
 277 At the end of the day, a leap second will be inserted after 23:59:59.
 278 .It TIME_DEL
 279 .Dq delete leap second
 280 warning.
 281 At the end of the day, second 23:59:59 will be skipped.
 282 .It TIME_OOP
 283 Leap second in progress.
 284 .It TIME_WAIT
 285 Leap second has occurred within the last few seconds.
 286 .It TIME_ERROR
 287 Clock not synchronized.
 288 .El
 289 .Sh ERRORS
 290 The
 291 .Fn ntp_adjtime
 292 system call may return
 293 .Er EPERM
 294 if the caller
 295 does not have sufficient permissions.
 296 .Sh SEE ALSO
 297 .Xr options 4 ,
 298 .Xr ntpd 8 ,
 299 .Xr hardclock 9 ,
 300 .Xr hz 9
 301 .Bl -tag -width indent
 302 .It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html
 303 .It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm
 304 .It Pa ftp://time.nist.gov/pub/leap-seconds.list
 305 .El
 306 .Sh BUGS
 307 Take note that this
 308 .Tn API
 309 is extremely complex and stateful.
 310 Users should not attempt modification without first
 311 reviewing the
 312 .Xr ntpd 8
 313 sources in depth.