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