diff options
Diffstat (limited to 'man2/adjtimex.2')
| -rw-r--r-- | man2/adjtimex.2 | 595 |
1 files changed, 0 insertions, 595 deletions
diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 deleted file mode 100644 index c7c095f5e..000000000 --- a/man2/adjtimex.2 +++ /dev/null @@ -1,595 +0,0 @@ -'\" 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 (date) "Linux man-pages (unreleased)" -.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> -.P -.BI "int adjtimex(struct timex *" "buf" ); -.P -.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); -.P -.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: -.P -.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 -.P -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 . -.P -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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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 -.SH STANDARDS -.TP -.BR adjtimex () -.TQ -.BR clock_adjtime () -Linux. -.P -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. -.P -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) -.P -.ad l -.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm -NTP "Kernel Application Program Interface" -.UE |