summaryrefslogtreecommitdiffstats
path: root/man2/adjtimex.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/adjtimex.2')
-rw-r--r--man2/adjtimex.2595
1 files changed, 0 insertions, 595 deletions
diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
deleted file mode 100644
index e5264df..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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