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