mirror of https://github.com/mkerrisk/man-pages
375 lines
10 KiB
Groff
375 lines
10 KiB
Groff
.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995.
|
|
.\" and Copyright (C) 2014 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
|
|
.\"
|
|
.\" 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"
|
|
.SH NAME
|
|
adjtimex \- tune kernel clock
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.BR "#define _BSD_SOURCE" " /* See feature_test_macros(7) */"
|
|
.B #include <sys/timex.h>
|
|
|
|
.BI "int adjtimex(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 field values,
|
|
and returns the same structure with current kernel values.
|
|
This structure is declared as follows:
|
|
.PP
|
|
.in +4n
|
|
.nf
|
|
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) */
|
|
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) */
|
|
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 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 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
|
|
.in
|
|
.PP
|
|
The
|
|
.I modes
|
|
field determines which parameters, if any, to set.
|
|
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 .
|
|
.TP
|
|
.BR ADJ_FREQUENCY
|
|
Set frequency offset from
|
|
.IR buf.freq .
|
|
.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 from
|
|
.IR buf.status .
|
|
.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.29)"
|
|
.\" 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.36)"
|
|
.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
|
|
.\" Author: Roman Zippel <zippel@linux-m68k.org>
|
|
Select microsecond resolution.
|
|
.TP
|
|
.BR ADJ_NANO " (since Linux 2.6.36)"
|
|
.\" 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 .
|
|
|
|
.BR ADJ_TAI
|
|
should not be used in conjunction with
|
|
.BR ADJ_TIMECONST ,
|
|
since the latter mode also employs the
|
|
.IR buf->constant
|
|
field.
|
|
|
|
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
|
|
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 value of either 0 or
|
|
.B ADJ_OFFSET_SS_READ
|
|
for
|
|
.IR modes .
|
|
Only the superuser may set any parameters.
|
|
|
|
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
|
|
Enable phase-locked loop (PLL) updates (read-write) 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).
|
|
.TP
|
|
.BR STA_NANO " (since Linux 2.6.26)"
|
|
.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
|
|
.\" Author: Roman Zippel <zippel@linux-m68k.org>
|
|
Resolution (0 = microsecond, 1 = nanoseconds; read-only).
|
|
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; read-only).
|
|
.TP
|
|
.BR STA_CLK " (since Linux 2.6.26)"
|
|
.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
|
|
.\" Author: Roman Zippel <zippel@linux-m68k.org>
|
|
Clock source (0 = A, 1 = B; read-only).
|
|
.\" FIXME It would be helpful to have some explanation of what
|
|
.\" "Clock source" is.
|
|
.PP
|
|
Attempts to set read-only
|
|
.I status
|
|
bits are silently ignored.
|
|
.SH RETURN VALUE
|
|
On success,
|
|
.BR adjtimex ()
|
|
returns the clock state; that is, one of the following values:
|
|
.TP 12
|
|
.BR TIME_OK
|
|
Clock synchronized.
|
|
.TP
|
|
.BR TIME_INS
|
|
Insert leap second.
|
|
.TP
|
|
.BR TIME_DEL
|
|
Delete leap second.
|
|
.TP
|
|
.BR TIME_OOP
|
|
Leap second in progress.
|
|
.TP
|
|
.BR TIME_WAIT
|
|
Leap second has occurred.
|
|
.TP
|
|
.BR TIME_ERROR
|
|
Clock not synchronized.
|
|
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 .
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
.I buf
|
|
does not point to writable memory.
|
|
.TP
|
|
.B EINVAL
|
|
An attempt was made to set
|
|
.I buf.offset
|
|
to a value outside the range \-131071 to +131071,
|
|
or to set
|
|
.I buf.status
|
|
to a value other than those listed above,
|
|
or 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 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 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.
|
|
.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 settimeofday (2),
|
|
.BR adjtime (3),
|
|
.BR capabilities (7),
|
|
.BR time (7),
|
|
.BR adjtimex (8)
|