.\" 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
.\" 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 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
adjtimex, ntp_adjtime \- tune kernel clock
.SH SYNOPSIS
.nf
.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\ 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.
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 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 (in units
- of 2^-16 ppm\-\-see NOTES, read-only) */
+ 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) */
+ 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
since Linux 2.6.26) */
/* Further padding bytes to allow for future expansion */
};
-.fi
+.EE
.in
.PP
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
is interpreted as a nanosecond value;
otherwise it is interpreted as microseconds.
.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.
.\" 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
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
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
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)"
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.
+.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
-Neither of these interfaces is described in POSIX.1
-
-.BR adjtimex ()
-is Linux-specific and should not be used in programs
-intended to be portable.
-
-The preferred API for NTP daemon is
-.BR ntp_adjtime (3),
-which is described in the NTP KAPI documentation.
.SH SEE ALSO
.BR settimeofday (2),
.BR 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