man2/adjtimex.2

   1 .\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995.
   2 .\" and Copyright (C) 2014, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl>
  27 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"
  29 .TH ADJTIMEX 2 2014-12-31 "Linux" "Linux Programmer's Manual"
  30 .SH NAME
  31 adjtimex, ntp_adjtime \- tune kernel clock
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <sys/timex.h>
  35
  36 .BI "int adjtimex(struct timex *" "buf" );
  37
  38 .BI "int ntp_adjtime(struct timex *" buf );
  39 .fi
  40 .SH DESCRIPTION
  41 Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 5905).
  42 The system call
  43 .BR adjtimex ()
  44 reads and optionally sets adjustment parameters for this algorithm.
  45 It takes a pointer to a
  46 .I timex
  47 structure, updates kernel parameters from (selected) field values,
  48 and returns the same structure updated with the current kernel values.
  49 This structure is declared as follows:
  50 .PP
  51 .in +4n
  52 .nf
  53 struct timex {
  54     int  modes;      /* Mode selector */
  55     long offset;     /* Time offset; nanoseconds, if STA_NANO
  56                         status flag is set, otherwise
  57                         microseconds */
  58     long freq;       /* Frequency offset; see NOTES for units */
  59     long maxerror;   /* Maximum error (microseconds) */
  60     long esterror;   /* Estimated error (microseconds) */
  61     int  status;     /* Clock command/status */
  62     long constant;   /* PLL (phase-locked loop) time constant */
  63     long precision;  /* Clock precision
  64                         (microseconds, read-only) */
  65     long tolerance;  /* Clock frequency tolerance (read-only);
  66                         see NOTES for units */
  67     struct timeval time;
  68                      /* Current time (read-only, except for
  69                         ADJ_SETOFFSET); upon return, time.tv_usec
  70                         contains nanoseconds, if STA_NANO status
  71                         flag is set, otherwise microseconds */
  72     long tick;       /* Microseconds between clock ticks */
  73     long ppsfreq;    /* PPS (pulse per second) frequency
  74                         (read-only); see NOTES for units */
  75     long jitter;     /* PPS jitter (read-only); nanoseconds, if
  76                         STA_NANO status flag is set, otherwise
  77                         microseconds */
  78     int  shift;      /* PPS interval duration
  79                         (seconds, read-only) */
  80     long stabil;     /* PPS stability (read-only);
  81                         see NOTES for units */
  82     long jitcnt;     /* PPS count of jitter limit exceeded
  83                         events (read-only) */
  84     long calcnt;     /* PPS count of calibration intervals
  85                         (read-only) */
  86     long errcnt;     /* PPS count of calibration errors
  87                         (read-only) */
  88     long stbcnt;     /* PPS count of stability limit exceeded
  89                         events (read-only) */
  90     int tai;         /* TAI offset, as set by previous ADJ_TAI
  91                         operation (seconds, read-only,
  92                         since Linux 2.6.26) */
  93     /* Further padding bytes to allow for future expansion */
  94 };
  95 .fi
  96 .in
  97 .PP
  98 The
  99 .I modes
 100 field determines which parameters, if any, to set.
 101 (As described later in this page,
 102 the constants used for
 103 .BR ntp_adjtime ()
 104 are equivalent but differently named.)
 105 It is a bit mask containing a
 106 .RI bitwise- or
 107 combination of zero or more of the following bits:
 108 .TP
 109 .BR ADJ_OFFSET
 110 Set time offset from
 111 .IR buf.offset .
 112 Since Linux 2.6.26,
 113 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
 114 the supplied value is clamped to the range (\-0.5s, +0.5s).
 115 In older kernels, an
 116 .B EINVAL
 117 error occurs if the supplied value is out of range.
 118 .TP
 119 .BR ADJ_FREQUENCY
 120 Set frequency offset from
 121 .IR buf.freq .
 122 Since Linux 2.6.26,
 123 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
 124 the supplied value is clamped to the range (\-32768000, +32768000).
 125 In older kernels, an
 126 .B EINVAL
 127 error occurs if the supplied value is out of range.
 128 .TP
 129 .BR ADJ_MAXERROR
 130 Set maximum time error from
 131 .IR buf.maxerror .
 132 .TP
 133 .BR ADJ_ESTERROR
 134 Set estimated time error from
 135 .IR buf.esterror .
 136 .TP
 137 .BR ADJ_STATUS
 138 Set clock status bits from
 139 .IR buf.status .
 140 A description of these bits is provided below.
 141 .TP
 142 .BR ADJ_TIMECONST
 143 Set PLL time constant from
 144 .IR buf.constant .
 145 If the
 146 .B STA_NANO
 147 status flag (see below) is clear, the kernel adds 4 to this value.
 148 .TP
 149 .BR ADJ_SETOFFSET " (since Linux 2.6.29)"
 150 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
 151 .\" Author: Richard Cochran <richardcochran@gmail.com>
 152 Add
 153 .I buf.time
 154 to the current time.
 155 If
 156 .I buf.status
 157 includes the
 158 .B ADJ_NANO
 159 flag, then
 160 .I buf.time.tv_usec
 161 is interpreted as a nanosecond value;
 162 otherwise it is interpreted as microseconds.
 163 .TP
 164 .BR ADJ_MICRO " (since Linux 2.6.36)"
 165 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 166 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 167 Select microsecond resolution.
 168 .TP
 169 .BR ADJ_NANO " (since Linux 2.6.36)"
 170 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 171 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 172 Select nanosecond resolution.
 173 Only one of
 174 .BR ADJ_MICRO
 175 and
 176 .BR ADJ_NANO
 177 should be specified.
 178 .TP
 179 .BR ADJ_TAI " (since Linux 2.6.26)"
 180 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
 181 Set TAI (Atomic International Time) offset from
 182 .IR buf.constant .
 183
 184 .BR ADJ_TAI
 185 should not be used in conjunction with
 186 .BR ADJ_TIMECONST ,
 187 since the latter mode also employs the
 188 .IR buf.constant
 189 field.
 190
 191 For a complete explanation of TAI
 192 and the difference between TAI and UTC, see
 193 .UR http://www.bipm.org/en/bipm/tai/tai.html
 194 .I BIPM
 195 .UE
 196 .TP
 197 .BR ADJ_TICK
 198 Set tick value from
 199 .IR buf.tick .
 200 .PP
 201 Alternatively,
 202 .I modes
 203 can be specified as either of the following (multibit mask) values,
 204 in which case other bits should not be specified in
 205 .IR modes :
 206 .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
 207 .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
 208 .TP
 209 .BR ADJ_OFFSET_SINGLESHOT
 210 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
 211 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
 212 Old-fashioned
 213 .BR adjtime ():
 214 (gradually) adjust time by value specified in
 215 .IR buf.offset ,
 216 which specifies an adjustment in microseconds.
 217 .TP
 218 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
 219 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
 220 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
 221 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
 222 Return (in
 223 .IR buf.offset )
 224 the remaining amount of time to be adjusted after an earlier
 225 .BR ADJ_OFFSET_SINGLESHOT
 226 operation.
 227 This feature was added in Linux 2.6.24,
 228 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
 229 but did not work correctly
 230 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
 231 until Linux 2.6.28.
 232 .PP
 233 Ordinary users are restricted to a value of either 0 or
 234 .B ADJ_OFFSET_SS_READ
 235 for
 236 .IR modes .
 237 Only the superuser may set any parameters.
 238
 239 The
 240 .I buf.status
 241 field is a bit mask that is used to set and/or retrieve status
 242 bits associated with the NTP implementation.
 243 Some bits in the mask are both readable and settable,
 244 while others are read-only.
 245 .TP
 246 .BR STA_PLL " (read-write)"
 247 Enable phase-locked loop (PLL) updates via
 248 .BR ADJ_OFFSET .
 249 .TP
 250 .BR STA_PPSFREQ " (read-write)"
 251 Enable PPS (pulse-per-second) frequency discipline.
 252 .TP
 253 .BR STA_PPSTIME " (read-write)"
 254 Enable PPS time discipline.
 255 .TP
 256 .BR STA_FLL " (read-write)"
 257 Select frequency-locked loop (FLL) mode.
 258 .TP
 259 .BR STA_INS " (read-write)"
 260 Insert a leap second after the last second of the UTC day,
 261 thus extending the last minute of the day by one second.
 262 Leap-second insertion will occur each day, so long as this flag remains set.
 263 .\" John Stultz;
 264 .\"     Usually this is written as extending the day by one second,
 265 .\"     which is represented as:
 266 .\"        23:59:59
 267 .\"        23:59:60
 268 .\"        00:00:00
 269 .\"
 270 .\"     But since posix cannot represent 23:59:60, we repeat the last second:
 271 .\"        23:59:59 + TIME_INS
 272 .\"        23:59:59 + TIME_OOP
 273 .\"        00:00:00 + TIME_WAIT
 274 .\"
 275 .TP
 276 .BR STA_DEL " (read-write)"
 277 Delete a leap second at the last second of the UTC day.
 278 .\" John Stultz:
 279 .\"     Similarly the progression here is:
 280 .\"        23:59:57 + TIME_DEL
 281 .\"        23:59:58 + TIME_DEL
 282 .\"        00:00:00 + TIME_WAIT
 283 Leap second deletion will occur each day, so long as this flag
 284 remains set.
 285 .\" FIXME Does there need to be a statement that it is nonsensical to set
 286 .\"     to set both STA_INS and STA_DEL?
 287 .TP
 288 .BR STA_UNSYNC " (read-write)"
 289 Clock unsynchronized.
 290 .TP
 291 .BR STA_FREQHOLD " (read-write)"
 292 Hold frequency.
 293 .\" Following text from John Stultz:
 294 Normally adjustments made via
 295 .B ADJ_OFFSET
 296 result in dampened frequency adjustments also being made.
 297 So a single call corrects the current offset,
 298 but as offsets in the same direction are made repeatedly,
 299 the small frequency adjustments will accumulate to fix the long-term skew.
 300
 301 This flag prevents the small frequency adjustment from being made
 302 when correcting for an
 303 .B ADJ_OFFSET
 304 value.
 305 .\" According to the Kernel Application Program Interface document,
 306 .\" STA_FREQHOLD is not used by the NTP version 4 daemon
 307 .TP
 308 .BR STA_PPSSIGNAL " (read-only)"
 309 A valid PPS (pulse-per-second) signal is present.
 310 .TP
 311 .BR STA_PPSJITTER " (read-only)"
 312 PPS signal jitter exceeded.
 313 .TP
 314 .BR STA_PPSWANDER " (read-only)"
 315 PPS signal wander exceeded.
 316 .TP
 317 .BR STA_PPSERROR " (read-only)"
 318 PPS signal calibration error.
 319 .TP
 320 .BR STA_CLOCKERR " (read-only)"
 321 Clock hardware fault.
 322 .\" Not set in current kernel (4.5), but checked in a few places
 323 .TP
 324 .BR STA_NANO " (read-only; since Linux 2.6.26)"
 325 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 326 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 327 Resolution (0 = microsecond, 1 = nanoseconds).
 328 Set via
 329 .BR ADJ_NANO ,
 330 cleared via
 331 .BR ADJ_MICRO .
 332 .TP
 333 .BR STA_MODE " (since Linux 2.6.26)"
 334 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 335 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 336 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
 337 .TP
 338 .BR STA_CLK " (read-only; since Linux 2.6.26)"
 339 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 340 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 341 Clock source (0 = A, 1 = B); currently unused.
 342 .PP
 343 Attempts to set read-only
 344 .I status
 345 bits are silently ignored.
 346 .\"
 347 .SS ntp_adjtime ()
 348 The
 349 .BR ntp_adjtime ()
 350 library function
 351 (described in the NTP "Kernel Application Program API", KAPI)
 352 is a more portable interface for performing the same task as
 353 .BR adjtimex ().
 354 Other than the following points, it is identical to
 355 .BR adjtime ():
 356 .IP * 3
 357 The constants used in
 358 .I modes
 359 are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus,
 360 .BR MOD_OFFSET ,
 361 .BR MOD_FREQUENCY ,
 362 and so on), other than the exceptions noted in the following points.
 363 .IP *
 364 .BR MOD_CLKA
 365 is the synonym for
 366 .BR ADJ_OFFSET_SINGLESHOT .
 367 .IP *
 368 .BR MOD_CLKB
 369 is the synonym for
 370 .BR ADJ_TICK .
 371 .IP *
 372 The is no synonym for
 373 .BR ADJ_OFFSET_SS_READ ,
 374 which is not described in the KAPI.
 375 .SH RETURN VALUE
 376 On success,
 377 .BR adjtimex ()
 378 and
 379 .BR ntp_adjtime ()
 380 return the clock state; that is, one of the following values:
 381 .TP 12
 382 .BR TIME_OK
 383 Clock synchronized, no leap second adjustment pending.
 384 .TP
 385 .BR TIME_INS
 386 Indicates that a leap second will be added at the end of the UTC day.
 387 .TP
 388 .BR TIME_DEL
 389 Indicates that a leap second will be deleted at the end of the UTC day.
 390 .TP
 391 .BR TIME_OOP
 392 Insertion of a leap second is in progress.
 393 .TP
 394 .BR TIME_WAIT
 395 A leap-second insertion or deletion has been completed.
 396 This value will be returned until the next
 397 .BR ADJ_STATUS
 398 operation clears the
 399 .B STA_INS
 400 and
 401 .B STA_DEL
 402 flags.
 403 .TP
 404 .BR TIME_ERROR
 405 The system clock is not synchronized to a reliable server.
 406 This value is returned when any of the following holds true:
 407 .RS
 408 .IP * 3
 409 Either
 410 .B STA_UNSYNC
 411 or
 412 .B STA_CLOCKERR
 413 is set.
 414 .IP *
 415 .B STA_PPSSIGNAL
 416 is clear and either
 417 .B STA_PPSFREQ
 418 or
 419 .B STA_PPSTIME
 420 is set.
 421 .IP *
 422 .B STA_PPSTIME
 423 and
 424 .B STA_PPSJITTER
 425 are both set.
 426 .IP *
 427 .B STA_PPSFREQ
 428 is set and either
 429 .B STA_PPSWANDER
 430 or
 431 .B STA_PPSJITTER
 432 is set.
 433 .RE
 434 .IP
 435 The symbolic name
 436 .B TIME_BAD
 437 is a synonym for
 438 .BR TIME_ERROR ,
 439 provided for backward compatibility.
 440 .PP
 441 Note that starting with Linux 3.4,
 442 .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous
 443 .\"  operation, so we can no longer rely on the return code.
 444 the call operates asynchronously and the return value usually will
 445 not reflect a state change caused by the call itself.
 446 .PP
 447 On failure, these calls return \-1 and set
 448 .IR errno .
 449 .SH ERRORS
 450 .TP
 451 .B EFAULT
 452 .I buf
 453 does not point to writable memory.
 454 .TP
 455 .BR EINVAL " (kernels before Linux 2.6.26)"
 456 An attempt was made to set
 457 .I buf.freq
 458 to a value outside the range (\-33554432, +33554432).
 459 .\" From a quck glance, it appears there was no clamping or range check
 460 .\" for buf.freq in kernels before 2.0
 461 .TP
 462 .BR EINVAL " (kernels before Linux 2.6.26)"
 463 An attempt was made to set
 464 .I buf.offset
 465 to a value outside the permitted range.
 466 In kernels before Linux 2.0, the permitted range was (\-131072, +131072).
 467 From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
 468 .TP
 469 .B EINVAL
 470 An attempt was made to set
 471 .I buf.status
 472 to a value other than those listed above.
 473 .TP
 474 .B EINVAL
 475 An attempt was made to set
 476 .I buf.tick
 477 to a value outside the range
 478 .RB 900000/ HZ
 479 to
 480 .RB 1100000/ HZ ,
 481 where
 482 .B HZ
 483 is the system timer interrupt frequency.
 484 .TP
 485 .B EPERM
 486 .I buf.modes
 487 is neither 0 nor
 488 .BR ADJ_OFFSET_SS_READ ,
 489 and the caller does not have sufficient privilege.
 490 Under Linux, the
 491 .B CAP_SYS_TIME
 492 capability is required.
 493 .SH NOTES
 494 In struct
 495 .IR timex ,
 496 .IR freq ,
 497 .IR ppsfreq ,
 498 and
 499 .I stabil
 500 are ppm (parts per million) with a 16-bit fractional part,
 501 which means that a value of 1 in one of those fields
 502 actually means 2^-16 ppm, and 2^16=65536 is 1 ppm.
 503 This is the case for both input values (in the case of
 504 .IR freq )
 505 and output values.
 506
 507 The leap-second processing triggered vy
 508 .B STA_INS
 509 and
 510 .B STA_DEL
 511 is done by the kernel in timer context
 512 Thus, it will take one tick into the second
 513 for the leap second to be inserted or deleted.
 514 .SH ATTRIBUTES
 515 For an explanation of the terms used in this section, see
 516 .BR attributes (7).
 517 .TS
 518 allbox;
 519 lb lb lb
 520 l l l.
 521 Interface       Attribute       Value
 522 T{
 523 .BR ntp_adjtime ()
 524 T}      Thread safety   MT-Safe
 525 .TE
 526 .SH CONFORMING TO
 527 Neither of these interfaces is described in POSIX.1
 528
 529 .BR adjtimex ()
 530 is Linux-specific and should not be used in programs
 531 intended to be portable.
 532
 533 The preferred API for the NTP daemon is
 534 .BR ntp_adjtime (3).
 535 .SH SEE ALSO
 536 .BR settimeofday (2),
 537 .BR adjtime (3),
 538 .BR ntp_gettime (3),
 539 .BR capabilities (7),
 540 .BR time (7),
 541 .BR adjtimex (8)
 542
 543 .ad l
 544 .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
 545 NTP "Kernel Application Program Interface"
 546 .UE