.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995.
+.\" and Copyright (C) 2014, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl>
.\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
-.\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
-.\"
-.\" FIXME Document ADJ_MICRO and ADJ_NANO (added in Linux 2.6.26)
-.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
-.\" Author: Roman Zippel <zippel@linux-m68k.org>
-.\"
-.\" FIXME Document ADJ_SETOFFSET (added in Linux 2.6.39)
-.\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
-.\" Author: Richard Cochran <richardcochran@gmail.com>
-.\"
-.TH ADJTIMEX 2 2014-05-28 "Linux" "Linux Programmer's Manual"
+.TH ADJTIMEX 2 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
-adjtimex \- tune kernel clock
+adjtimex, ntp_adjtime \- tune kernel clock
.SH SYNOPSIS
.nf
-.BR "#define _BSD_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/timex.h>
-
+.PP
.BI "int adjtimex(struct timex *" "buf" );
+.PP
+.BI "int ntp_adjtime(struct timex *" buf );
.fi
.SH DESCRIPTION
-Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 1305).
+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 field values,
-and returns the same structure with current kernel values.
+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
-.nf
+.EX
struct timex {
- int modes; /* mode selector */
- long offset; /* time offset (usec) */
- long freq; /* frequency offset (scaled ppm) */
-.\" FIXME What is the scaling unit of timex.freq? 2^16 ?
- long maxerror; /* maximum error (usec) */
- long esterror; /* estimated error (usec) */
- int status; /* clock command/status */
- long constant; /* pll time constant */
- long precision; /* clock precision (usec) (read-only) */
- long tolerance; /* clock frequency tolerance (ppm)
- (read-only) */
- struct timeval time; /* current time (read-only) */
- long tick; /* usecs between clock ticks */
- long ppsfreq; /* pps frequency (scaled ppm) (read-only) */
- long jitter; /* pps jitter (usec) (read-only) */
- int shift; /* interval duration (sec) (read-only) */
- long stabil; /* pps stability (scaled ppm) (read-only) */
- long jitcnt; /* jitter limit exceeded (read-only) */
- long calcnt; /* calibration intervals (read-only) */
- long errcnt; /* calibration errors (read-only) */
- long stbcnt; /* stability limit exceeded (read-only) */
- int tai; /* TAI offset (s) (read-only) */
+ 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 */
};
-.fi
+.EE
.in
.PP
The
.I modes
field determines which parameters, if any, to set.
-It may contain a
+(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
.RI bitwise- or
combination of zero or more of the following bits:
+.TP
+.BR 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
+.BR 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
+.BR ADJ_MAXERROR
+Set maximum time error from
+.IR buf.maxerror .
+.TP
+.BR ADJ_ESTERROR
+Set estimated time error from
+.IR buf.esterror .
+.TP
+.BR ADJ_STATUS
+Set clock status bits from
+.IR buf.status .
+A description of these bits is provided below.
+.TP
+.BR 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.
+.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
+.BR ADJ_MICRO
+and
+.BR 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
+.BR ADJ_TAI
+should not be used in conjunction with
+.BR ADJ_TIMECONST ,
+since the latter mode also employs the
+.IR 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
+.BR ADJ_TICK
+Set tick value from
+.IR buf.tick .
.PP
-.in +4n
-.nf
-#define ADJ_OFFSET 0x0001 /* time offset */
-#define ADJ_FREQUENCY 0x0002 /* frequency offset */
-#define ADJ_MAXERROR 0x0004 /* maximum time error */
-#define ADJ_ESTERROR 0x0008 /* estimated time error */
-#define ADJ_STATUS 0x0010 /* clock status */
-#define ADJ_TIMECONST 0x0020 /* pll time constant */
-#define ADJ_TICK 0x4000 /* tick value */
-#define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime() */
-.fi
-.in
+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
+.BR 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 ():
+(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
+.BR 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 zero value for
+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.
-.br
-.ne 12v
+.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 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 adjtime ():
+.IP * 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 *
+.BR MOD_CLKA
+is the synonym for
+.BR ADJ_OFFSET_SINGLESHOT .
+.IP *
+.BR MOD_CLKB
+is the synonym for
+.BR ADJ_TICK .
+.IP *
+The is no synonym for
+.BR ADJ_OFFSET_SS_READ ,
+which is not described in the KAPI.
.SH RETURN VALUE
On success,
.BR adjtimex ()
-returns the clock state:
+and
+.BR ntp_adjtime ()
+return the clock state; that is, one of the following values:
+.TP 12
+.BR TIME_OK
+Clock synchronized, no leap second adjustment pending.
+.TP
+.BR TIME_INS
+Indicates that a leap second will be added at the end of the UTC day.
+.TP
+.BR TIME_DEL
+Indicates that a leap second will be deleted at the end of the UTC day.
+.TP
+.BR TIME_OOP
+Insertion of a leap second is in progress.
+.TP
+.BR TIME_WAIT
+A leap-second insertion or deletion has been completed.
+This value will be returned until the next
+.BR ADJ_STATUS
+operation clears the
+.B STA_INS
+and
+.B STA_DEL
+flags.
+.TP
+.BR 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 * 3
+Either
+.B STA_UNSYNC
+or
+.B STA_CLOCKERR
+is set.
+.IP *
+.B STA_PPSSIGNAL
+is clear and either
+.B STA_PPSFREQ
+or
+.B STA_PPSTIME
+is set.
+.IP *
+.B STA_PPSTIME
+and
+.B STA_PPSJITTER
+are both set.
+.IP *
+.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
-.in +4n
-.nf
-#define TIME_OK 0 /* clock synchronized */
-#define TIME_INS 1 /* insert leap second */
-#define TIME_DEL 2 /* delete leap second */
-#define TIME_OOP 3 /* leap second in progress */
-#define TIME_WAIT 4 /* leap second has occurred */
-#define TIME_BAD 5 /* clock not synchronized */
-.fi
-.in
+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,
-.BR adjtimex ()
-returns \-1 and sets
+On failure, these calls return \-1 and set
.IR errno .
.SH ERRORS
.TP
.I buf
does not point to writable memory.
.TP
-.B EINVAL
-An attempt is made to set
+.BR EINVAL " (kernels 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 in kernels before 2.0
+.TP
+.BR EINVAL " (kernels before Linux 2.6.26)"
+An attempt was made to set
.I buf.offset
-to a value outside the range \-131071 to +131071,
-or to set
+to a value outside the permitted range.
+In kernels 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,
-or to set
+to a value other than those listed above.
+.TP
+.B EINVAL
+An attempt was made to set
.I buf.tick
to a value outside the range
.RB 900000/ HZ
.TP
.B EPERM
.I buf.modes
-is nonzero and the caller does not have sufficient privilege.
-Under Linux the
+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;
+lb lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR ntp_adjtime ()
+T} Thread safety MT-Safe
+.TE
.SH CONFORMING TO
+Neither of these interfaces is described in POSIX.1
+.PP
.BR adjtimex ()
is Linux-specific and should not be used in programs
intended to be portable.
-See
-.BR adjtime (3)
-for a more portable, but less flexible,
-method of adjusting the system clock.
+.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^-16 ppm, and 2^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 settimeofday (2),
.BR adjtime (3),
+.BR ntp_gettime (3),
.BR capabilities (7),
.BR time (7),
-.BR adjtimex (8)
+.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
projects / thirdparty / man-pages.git / blobdiff