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