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