.\" 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-12-31 "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
.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, in units of 2^-16 ppm
- (parts per million, see NOTES below) */
+ 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 (ppm, read-only) */
+ 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
+ /* 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 (in units
- of 2^-16 ppm\-\-see NOTES, read-only) */
- long jitter; /* PPS jitter (read-only); nanoseconds, if
+ 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 (2^-16 ppm\-\-see NOTES,
- 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 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,
+ 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,
.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,
.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
+.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.
Return (in
.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
.\" 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
.\"
.TP
.BR STA_DEL " (read-write)"
-Delete a leap second at the last second of the day.
+Delete a leap second at the last second of the UTC day.
.\" John Stultz:
.\" Similarly the progression here is:
.\" 23:59:57 + TIME_DEL
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?
+.\" to set both STA_INS and STA_DEL?
.TP
.BR STA_UNSYNC " (read-write)"
Clock unsynchronized.
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
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
+.B 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 day.
+.B TIME_DEL
+Indicates that a leap second will be deleted at the end of the UTC day.
.TP
-.BR TIME_OOP
+.B TIME_OOP
Insertion of a leap second is in progress.
.TP
-.BR TIME_WAIT
+.B TIME_WAIT
A leap-second insertion or deletion has been completed.
This value will be returned until the next
-.BR ADJ_STATUS
+.B ADJ_STATUS
operation clears the
.B STA_INS
and
.B STA_DEL
flags.
.TP
-.BR TIME_ERROR
+.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
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
-.IR errno .
+On failure, these calls return \-1 and set
+.I errno
+to indicate the error.
.SH ERRORS
.TP
.B EFAULT
An attempt was made to set
.I buf.freq
to a value outside the range (\-33554432, +33554432).
-.\" From a quck glance, it appears there was no clamping or range check
+.\" 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)"
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
.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 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 ()
+and
+.BR clock_adjtime ()
+are Linux-specific and should not be used in programs
+intended to be portable.
+.PP
+The preferred API for the NTP daemon is
+.BR ntp_adjtime ().
.SH NOTES
In struct
.IR timex ,
This is the case for both input values (in the case of
.IR freq )
and output values.
-
-The leap-second processing triggered vy
+.PP
+The leap-second processing triggered by
.B STA_INS
and
.B STA_DEL
-is done by the kernel in timer context
+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 CONFORMING TO
-.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.
.SH SEE ALSO
+.BR clock_gettime (2),
+.BR clock_settime (2),
.BR settimeofday (2),
.BR adjtime (3),
-.\" .BR ntp_adjtime (3),
-.\" .BR ntp_gettime (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"
projects / thirdparty / man-pages.git / blobdiff