Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 595 insertions, 0 deletions

diff --git a/man/man2/adjtimex.2 b/man/man2/adjtimex.2
new file mode 100644
index 0000000..0e9338e
--- /dev/null
+++ b/man/man2/adjtimex.2
@@ -0,0 +1,595 @@
+'\" 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 2024-05-02 "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