.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995.
-.\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" 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
-.\" modify it under the terms of the GNU General Public License as
-.\" published by the Free Software Foundation; either version 2 of
-.\" the License, or (at your option) any later version.
-.\"
-.\" The GNU General Public License's references to "object code"
-.\" and "executables" are to be interpreted as the output of any
-.\" document formatting or typesetting system, including
-.\" intermediate and printed output.
-.\"
-.\" This manual is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, see
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
+.\" 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 2014-05-28 "Linux" "Linux Programmer's Manual"
+.TH ADJTIMEX 2 (date) "Linux man-pages (unreleased)"
.SH NAME
-adjtimex \- tune kernel clock
+adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
.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 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).
+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; nanoseconds, if STA_NANO
- status flag is set, otherwise
- microseconds */
- long freq; /* Frequency offset, as scaled PPM
- (parts per million) */
-.\" FIXME What is the scaling unit of timex.freq? 2^16 ?
- 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 (PPM,
- 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
- (scaled PPM, read-only) */
- 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 (scaled PPM, read-only) */
- long jitcnt; /* PPS jitter limit exceeded (read-only) */
- long calcnt; /* PPS calibration intervals (read-only) */
- long errcnt; /* PPS calibration errors (read-only) */
- long stbcnt; /* PPS stability limit exceeded
- (read-only) */
- int tai; /* TAI offset, as set by previous ADJ_TAI
- operation (seconds, read-only,
- since Linux 2.6.26) */
+ /* 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.
+(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
+.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
-.BR ADJ_FREQUENCY
+.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
-.BR ADJ_MAXERROR
+.B ADJ_MAXERROR
Set maximum time error from
.IR buf.maxerror .
.TP
-.BR ADJ_ESTERROR
+.B ADJ_ESTERROR
Set estimated time error from
.IR buf.esterror .
.TP
-.BR ADJ_STATUS
-Set clock status from
+.B ADJ_STATUS
+Set clock status bits from
.IR buf.status .
+A description of these bits is provided below.
.TP
-.BR ADJ_TIMECONST
+.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.29)"
+.BR ADJ_SETOFFSET " (since Linux 2.6.39)"
.\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
.\" Author: Richard Cochran <richardcochran@gmail.com>
Add
.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.36)"
+.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.36)"
+.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
+.B ADJ_MICRO
and
-.BR ADJ_NANO
+.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 .
-
-.BR ADJ_TAI
+.IR buf.constant .
+.IP
+.B ADJ_TAI
should not be used in conjunction with
.BR ADJ_TIMECONST ,
since the latter mode also employs the
-.IR buf->constant
+.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
-.BR ADJ_TICK
+.B ADJ_TICK
Set tick value from
.IR buf.tick .
.PP
.\" 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
+.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 ():
+.BR adjtime (3):
(gradually) adjust time by value specified in
.IR buf.offset ,
which specifies an adjustment in microseconds.
.\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
.\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
Return (in
-.BR buf.offset )
+.IR buf.offset )
the remaining amount of time to be adjusted after an earlier
-.BR ADJ_OFFSET_SINGLESHOT
+.B ADJ_OFFSET_SINGLESHOT
operation.
This feature was added in Linux 2.6.24,
.\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
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
Some bits in the mask are both readable and settable,
while others are read-only.
.TP
-.BR STA_PLL
-Enable phase-locked loop (PLL) updates (read-write) via
+.BR STA_PLL " (read-write)"
+Enable phase-locked loop (PLL) updates via
.BR ADJ_OFFSET .
.TP
-.BR STA_PPSFREQ
-Enable PPS freq discipline (read-write).
-.TP
-.BR STA_PPSTIME
-Enable PPS time discipline (read-write).
-.TP
-.BR STA_FLL
-Select frequency-locked loop (FLL) mode (read-write).
-.TP
-.BR STA_INS
-Insert leap second (read-write).
-.TP
-.BR STA_DEL
-Delete leap second (read-write).
-.TP
-.BR STA_UNSYNC
-Clock unsynchronized (read-write).
-.TP
-.BR STA_FREQHOLD
-Hold frequency (read-write).
-.TP
-.BR STA_PPSSIGNAL
-PPS signal present (read-only).
-.TP
-.BR STA_PPSJITTER
-PPS signal jitter exceeded (read-only).
-.TP
-.BR STA_PPSWANDER
-PPS signal wander exceeded (read-only).
-.TP
-.BR STA_PPSERROR
-PPS signal calibration error (read-only).
-.TP
-.BR STA_CLOCKERR
-Clock hardware fault (read-only).
+.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_NANO " (since Linux 2.6.26)"
+.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; read-only).
+Resolution (0 = microsecond, 1 = nanoseconds).
Set via
.BR ADJ_NANO ,
cleared via
.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; read-only).
+Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
.TP
-.BR STA_CLK " (since Linux 2.6.26)"
+.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; read-only).
+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 * 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 *
+.B MOD_CLKA
+is the synonym for
+.BR ADJ_OFFSET_SINGLESHOT .
+.IP *
+.B 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; that is, one of the following values:
+and
+.BR ntp_adjtime ()
+return the clock state; that is, one of the following values:
.TP 12
-.BR TIME_OK
-Clock synchronized.
+.B TIME_OK
+Clock synchronized, no leap second adjustment pending.
.TP
-.BR TIME_INS
-Insert leap second.
+.B TIME_INS
+Indicates that a leap second will be added at the end of the UTC day.
.TP
-.BR TIME_DEL
-Delete leap second.
+.B TIME_DEL
+Indicates that a leap second will be deleted at the end of the UTC day.
.TP
-.BR TIME_OOP
-Leap second in progress.
+.B TIME_OOP
+Insertion of a leap second is in progress.
.TP
-.BR TIME_WAIT
-Leap second has occurred.
-.TP
-.BR TIME_BAD
-Clock not synchronized.
+.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 * 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
-On failure,
-.BR adjtimex ()
-returns \-1 and sets
-.IR errno .
+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
-.B EINVAL
+.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
+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
.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
Under Linux, the
.B CAP_SYS_TIME
capability is required.
-.SH CONFORMING TO
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR ntp_adjtime ()
+T} Thread safety MT-Safe
+.TE
+.hy
+.ad
+.sp 1
+.SH STANDARDS
+None of these interfaces is described in POSIX.1
+.PP
.BR adjtimex ()
-is Linux-specific and should not be used in programs
+and
+.BR clock_adjtime ()
+are 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 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 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