diff options
Diffstat (limited to 'man2/adjtimex.2')
| -rw-r--r-- | man2/adjtimex.2 | 596 |
1 files changed, 596 insertions, 0 deletions
diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 new file mode 100644 index 0000000..c850a3d --- /dev/null +++ b/man2/adjtimex.2 @@ -0,0 +1,596 @@ +'\" t +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" and Copyright (C) 2014, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl> +.\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH adjtimex 2 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/timex.h> +.PP +.BI "int adjtimex(struct timex *" "buf" ); +.PP +.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); +.PP +.BI "int ntp_adjtime(struct timex *" buf ); +.fi +.SH DESCRIPTION +Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905). +The system call +.BR adjtimex () +reads and optionally sets adjustment parameters for this algorithm. +It takes a pointer to a +.I timex +structure, updates kernel parameters from (selected) field values, +and returns the same structure updated with the current kernel values. +This structure is declared as follows: +.PP +.in +4n +.EX +struct timex { + int modes; /* Mode selector */ + long offset; /* Time offset; nanoseconds, if STA_NANO + status flag is set, otherwise + microseconds */ + long freq; /* Frequency offset; see NOTES for units */ + long maxerror; /* Maximum error (microseconds) */ + long esterror; /* Estimated error (microseconds) */ + int status; /* Clock command/status */ + long constant; /* PLL (phase\-locked loop) time constant */ + long precision; /* Clock precision + (microseconds, read\-only) */ + long tolerance; /* Clock frequency tolerance (read\-only); + see NOTES for units */ + struct timeval time; + /* Current time (read\-only, except for + ADJ_SETOFFSET); upon return, time.tv_usec + contains nanoseconds, if STA_NANO status + flag is set, otherwise microseconds */ + long tick; /* Microseconds between clock ticks */ + long ppsfreq; /* PPS (pulse per second) frequency + (read\-only); see NOTES for units */ + long jitter; /* PPS jitter (read\-only); nanoseconds, if + STA_NANO status flag is set, otherwise + microseconds */ + int shift; /* PPS interval duration + (seconds, read\-only) */ + long stabil; /* PPS stability (read\-only); + see NOTES for units */ + long jitcnt; /* PPS count of jitter limit exceeded + events (read\-only) */ + long calcnt; /* PPS count of calibration intervals + (read\-only) */ + long errcnt; /* PPS count of calibration errors + (read\-only) */ + long stbcnt; /* PPS count of stability limit exceeded + events (read\-only) */ + int tai; /* TAI offset, as set by previous ADJ_TAI + operation (seconds, read\-only, + since Linux 2.6.26) */ + /* Further padding bytes to allow for future expansion */ +}; +.EE +.in +.PP +The +.I modes +field determines which parameters, if any, to set. +(As described later in this page, +the constants used for +.BR ntp_adjtime () +are equivalent but differently named.) +It is a bit mask containing a +bitwise OR +combination of zero or more of the following bits: +.TP +.B ADJ_OFFSET +Set time offset from +.IR buf.offset . +Since Linux 2.6.26, +.\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 +the supplied value is clamped to the range (\-0.5s, +0.5s). +In older kernels, an +.B EINVAL +error occurs if the supplied value is out of range. +.TP +.B ADJ_FREQUENCY +Set frequency offset from +.IR buf.freq . +Since Linux 2.6.26, +.\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 +the supplied value is clamped to the range (\-32768000, +32768000). +In older kernels, an +.B EINVAL +error occurs if the supplied value is out of range. +.TP +.B ADJ_MAXERROR +Set maximum time error from +.IR buf.maxerror . +.TP +.B ADJ_ESTERROR +Set estimated time error from +.IR buf.esterror . +.TP +.B ADJ_STATUS +Set clock status bits from +.IR buf.status . +A description of these bits is provided below. +.TP +.B ADJ_TIMECONST +Set PLL time constant from +.IR buf.constant . +If the +.B STA_NANO +status flag (see below) is clear, the kernel adds 4 to this value. +.TP +.BR ADJ_SETOFFSET " (since Linux 2.6.39)" +.\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762 +.\" Author: Richard Cochran <richardcochran@gmail.com> +Add +.I buf.time +to the current time. +If +.I buf.status +includes the +.B ADJ_NANO +flag, then +.I buf.time.tv_usec +is interpreted as a nanosecond value; +otherwise it is interpreted as microseconds. +.IP +The value of +.I buf.time +is the sum of its two fields, but the +field +.I buf.time.tv_usec +must always be nonnegative. +The following example shows how to +normalize a +.I timeval +with nanosecond resolution. +.IP +.in +4n +.EX +while (buf.time.tv_usec < 0) { + buf.time.tv_sec \-= 1; + buf.time.tv_usec += 1000000000; +} +.EE +.in +.TP +.BR ADJ_MICRO " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel <zippel@linux-m68k.org> +Select microsecond resolution. +.TP +.BR ADJ_NANO " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel <zippel@linux-m68k.org> +Select nanosecond resolution. +Only one of +.B ADJ_MICRO +and +.B ADJ_NANO +should be specified. +.TP +.BR ADJ_TAI " (since Linux 2.6.26)" +.\" commit 153b5d054ac2d98ea0d86504884326b6777f683d +Set TAI (Atomic International Time) offset from +.IR buf.constant . +.IP +.B ADJ_TAI +should not be used in conjunction with +.BR ADJ_TIMECONST , +since the latter mode also employs the +.I buf.constant +field. +.IP +For a complete explanation of TAI +and the difference between TAI and UTC, see +.UR http://www.bipm.org/en/bipm/tai/tai.html +.I BIPM +.UE +.TP +.B ADJ_TICK +Set tick value from +.IR buf.tick . +.PP +Alternatively, +.I modes +can be specified as either of the following (multibit mask) values, +in which case other bits should not be specified in +.IR modes : +.\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001 +.\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!! +.TP +.B ADJ_OFFSET_SINGLESHOT +.\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001 +.\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000) +Old-fashioned +.BR adjtime (3): +(gradually) adjust time by value specified in +.IR buf.offset , +which specifies an adjustment in microseconds. +.TP +.BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)" +.\" In user space, ADJ_OFFSET_SS_READ is 0xa001 +.\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with +.\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001) +Return (in +.IR buf.offset ) +the remaining amount of time to be adjusted after an earlier +.B ADJ_OFFSET_SINGLESHOT +operation. +This feature was added in Linux 2.6.24, +.\" commit 52bfb36050c8529d9031d2c2513b281a360922ec +but did not work correctly +.\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1 +until Linux 2.6.28. +.PP +Ordinary users are restricted to a value of either 0 or +.B ADJ_OFFSET_SS_READ +for +.IR modes . +Only the superuser may set any parameters. +.PP +The +.I buf.status +field is a bit mask that is used to set and/or retrieve status +bits associated with the NTP implementation. +Some bits in the mask are both readable and settable, +while others are read-only. +.TP +.BR STA_PLL " (read-write)" +Enable phase-locked loop (PLL) updates via +.BR ADJ_OFFSET . +.TP +.BR STA_PPSFREQ " (read-write)" +Enable PPS (pulse-per-second) frequency discipline. +.TP +.BR STA_PPSTIME " (read-write)" +Enable PPS time discipline. +.TP +.BR STA_FLL " (read-write)" +Select frequency-locked loop (FLL) mode. +.TP +.BR STA_INS " (read-write)" +Insert a leap second after the last second of the UTC day, +thus extending the last minute of the day by one second. +Leap-second insertion will occur each day, so long as this flag remains set. +.\" John Stultz; +.\" Usually this is written as extending the day by one second, +.\" which is represented as: +.\" 23:59:59 +.\" 23:59:60 +.\" 00:00:00 +.\" +.\" But since posix cannot represent 23:59:60, we repeat the last second: +.\" 23:59:59 + TIME_INS +.\" 23:59:59 + TIME_OOP +.\" 00:00:00 + TIME_WAIT +.\" +.TP +.BR STA_DEL " (read-write)" +Delete a leap second at the last second of the UTC day. +.\" John Stultz: +.\" Similarly the progression here is: +.\" 23:59:57 + TIME_DEL +.\" 23:59:58 + TIME_DEL +.\" 00:00:00 + TIME_WAIT +Leap second deletion will occur each day, so long as this flag +remains set. +.\" FIXME Does there need to be a statement that it is nonsensical to set +.\" to set both STA_INS and STA_DEL? +.TP +.BR STA_UNSYNC " (read-write)" +Clock unsynchronized. +.TP +.BR STA_FREQHOLD " (read-write)" +Hold frequency. +.\" Following text from John Stultz: +Normally adjustments made via +.B ADJ_OFFSET +result in dampened frequency adjustments also being made. +So a single call corrects the current offset, +but as offsets in the same direction are made repeatedly, +the small frequency adjustments will accumulate to fix the long-term skew. +.IP +This flag prevents the small frequency adjustment from being made +when correcting for an +.B ADJ_OFFSET +value. +.\" According to the Kernel Application Program Interface document, +.\" STA_FREQHOLD is not used by the NTP version 4 daemon +.TP +.BR STA_PPSSIGNAL " (read-only)" +A valid PPS (pulse-per-second) signal is present. +.TP +.BR STA_PPSJITTER " (read-only)" +PPS signal jitter exceeded. +.TP +.BR STA_PPSWANDER " (read-only)" +PPS signal wander exceeded. +.TP +.BR STA_PPSERROR " (read-only)" +PPS signal calibration error. +.TP +.BR STA_CLOCKERR " (read-only)" +Clock hardware fault. +.\" Not set in current kernel (4.5), but checked in a few places +.TP +.BR STA_NANO " (read-only; since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel <zippel@linux-m68k.org> +Resolution (0 = microsecond, 1 = nanoseconds). +Set via +.BR ADJ_NANO , +cleared via +.BR ADJ_MICRO . +.TP +.BR STA_MODE " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel <zippel@linux-m68k.org> +Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop). +.TP +.BR STA_CLK " (read-only; since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel <zippel@linux-m68k.org> +Clock source (0 = A, 1 = B); currently unused. +.PP +Attempts to set read-only +.I status +bits are silently ignored. +.\" +.SS clock_adjtime () +The +.BR clock_adjtime () +system call (added in Linux 2.6.39) behaves like +.BR adjtimex () +but takes an additional +.I clk_id +argument to specify the particular clock on which to act. +.SS ntp_adjtime () +The +.BR ntp_adjtime () +library function +(described in the NTP "Kernel Application Program API", KAPI) +is a more portable interface for performing the same task as +.BR adjtimex (). +Other than the following points, it is identical to +.BR adjtimex (): +.IP \[bu] 3 +The constants used in +.I modes +are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus, +.BR MOD_OFFSET , +.BR MOD_FREQUENCY , +and so on), other than the exceptions noted in the following points. +.IP \[bu] +.B MOD_CLKA +is the synonym for +.BR ADJ_OFFSET_SINGLESHOT . +.IP \[bu] +.B MOD_CLKB +is the synonym for +.BR ADJ_TICK . +.IP \[bu] +The is no synonym for +.BR ADJ_OFFSET_SS_READ , +which is not described in the KAPI. +.SH RETURN VALUE +On success, +.BR adjtimex () +and +.BR ntp_adjtime () +return the clock state; that is, one of the following values: +.TP 12 +.B TIME_OK +Clock synchronized, no leap second adjustment pending. +.TP +.B TIME_INS +Indicates that a leap second will be added at the end of the UTC day. +.TP +.B TIME_DEL +Indicates that a leap second will be deleted at the end of the UTC day. +.TP +.B TIME_OOP +Insertion of a leap second is in progress. +.TP +.B TIME_WAIT +A leap-second insertion or deletion has been completed. +This value will be returned until the next +.B ADJ_STATUS +operation clears the +.B STA_INS +and +.B STA_DEL +flags. +.TP +.B TIME_ERROR +The system clock is not synchronized to a reliable server. +This value is returned when any of the following holds true: +.RS +.IP \[bu] 3 +Either +.B STA_UNSYNC +or +.B STA_CLOCKERR +is set. +.IP \[bu] +.B STA_PPSSIGNAL +is clear and either +.B STA_PPSFREQ +or +.B STA_PPSTIME +is set. +.IP \[bu] +.B STA_PPSTIME +and +.B STA_PPSJITTER +are both set. +.IP \[bu] +.B STA_PPSFREQ +is set and either +.B STA_PPSWANDER +or +.B STA_PPSJITTER +is set. +.RE +.IP +The symbolic name +.B TIME_BAD +is a synonym for +.BR TIME_ERROR , +provided for backward compatibility. +.PP +Note that starting with Linux 3.4, +.\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous +.\" operation, so we can no longer rely on the return code. +the call operates asynchronously and the return value usually will +not reflect a state change caused by the call itself. +.PP +On failure, these calls return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I buf +does not point to writable memory. +.TP +.BR EINVAL " (before Linux 2.6.26)" +An attempt was made to set +.I buf.freq +to a value outside the range (\-33554432, +33554432). +.\" From a quick glance, it appears there was no clamping or range check +.\" for buf.freq before Linux 2.0 +.TP +.BR EINVAL " (before Linux 2.6.26)" +An attempt was made to set +.I buf.offset +to a value outside the permitted range. +Before Linux 2.0, the permitted range was (\-131072, +131072). +From Linux 2.0 onwards, the permitted range was (\-512000, +512000). +.TP +.B EINVAL +An attempt was made to set +.I buf.status +to a value other than those listed above. +.TP +.B EINVAL +The +.I clk_id +given to +.BR clock_adjtime () +is invalid for one of two reasons. +Either the System-V style hard-coded +positive clock ID value is out of range, or the dynamic +.I clk_id +does not refer to a valid instance of a clock object. +See +.BR clock_gettime (2) +for a discussion of dynamic clocks. +.TP +.B EINVAL +An attempt was made to set +.I buf.tick +to a value outside the range +.RB 900000/ HZ +to +.RB 1100000/ HZ , +where +.B HZ +is the system timer interrupt frequency. +.TP +.B ENODEV +The hot-pluggable device (like USB for example) represented by a +dynamic +.I clk_id +has disappeared after its character device was opened. +See +.BR clock_gettime (2) +for a discussion of dynamic clocks. +.TP +.B EOPNOTSUPP +The given +.I clk_id +does not support adjustment. +.TP +.B EPERM +.I buf.modes +is neither 0 nor +.BR ADJ_OFFSET_SS_READ , +and the caller does not have sufficient privilege. +Under Linux, the +.B CAP_SYS_TIME +capability is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR \%ntp_adjtime () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +.TP +.BR adjtimex () +.TQ +.BR clock_adjtime () +Linux. +.PP +The preferred API for the NTP daemon is +.BR ntp_adjtime (). +.SH NOTES +In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and +.I stabil +are ppm (parts per million) with a 16-bit fractional part, +which means that a value of 1 in one of those fields +actually means 2\[ha]-16 ppm, and 2\[ha]16=65536 is 1 ppm. +This is the case for both input values (in the case of +.IR freq ) +and output values. +.PP +The leap-second processing triggered by +.B STA_INS +and +.B STA_DEL +is done by the kernel in timer context. +Thus, it will take one tick into the second +for the leap second to be inserted or deleted. +.SH SEE ALSO +.BR clock_gettime (2), +.BR clock_settime (2), +.BR settimeofday (2), +.BR adjtime (3), +.BR ntp_gettime (3), +.BR capabilities (7), +.BR time (7), +.BR adjtimex (8), +.BR hwclock (8) +.PP +.ad l +.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm +NTP "Kernel Application Program Interface" +.UE |