adjtimex (2)
Leading comments
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 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" ...
NAME
adjtimex - tune kernel clockSYNOPSIS
#define _BSD_SOURCE /* See feature_test_macros(7) */ #include <sys/timex.h> int adjtimex(struct timex *buf);
DESCRIPTION
Linux uses David L. Mills' clock adjustment algorithm (see RFC 5905). The system call adjtimex() reads and optionally sets adjustment parameters for this algorithm. It takes a pointer to a timex structure, updates kernel parameters from field values, and returns the same structure with current kernel values. This structure is declared as follows:
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 */
};
The modes field determines which parameters, if any, to set. It is a bit mask containing a bitwise-or combination of zero or more of the following bits:
- ADJ_OFFSET
- Set time offset from buf.offset.
- ADJ_FREQUENCY
- Set frequency offset from buf.freq.
- ADJ_MAXERROR
- Set maximum time error from buf.maxerror.
- ADJ_ESTERROR
- Set estimated time error from buf.esterror.
- ADJ_STATUS
- Set clock status from buf.status.
- ADJ_TIMECONST
- Set PLL time constant from buf.constant. If the STA_NANO status flag (see below) is clear, the kernel adds 4 to this value.
- ADJ_SETOFFSET (since Linux 2.6.29)
- Add buf.time to the current time. If buf.status includes the ADJ_NANO flag, then buf.time.tv_usec is interpreted as a nanosecond value; otherwise it is interpreted as microseconds.
- ADJ_MICRO (since Linux 2.6.36)
- Select microsecond resolution.
- ADJ_NANO (since Linux 2.6.36)
- Select nanosecond resolution. Only one of ADJ_MICRO and ADJ_NANO should be specified.
- ADJ_TAI (since Linux 2.6.26)
-
Set TAI (Atomic International Time) offset from
buf->constant.
ADJ_TAI should not be used in conjunction with ADJ_TIMECONST, since the latter mode also employs the buf->constant field.
For a complete explanation of TAI and the difference between TAI and UTC, see BIPM - ADJ_TICK
- Set tick value from buf.tick.
Alternatively, modes can be specified as either of the following (multibit mask) values, in which case other bits should not be specified in modes:
- ADJ_OFFSET_SINGLESHOT
- Old-fashioned adjtime(): (gradually) adjust time by value specified in buf.offset, which specifies an adjustment in microseconds.
- ADJ_OFFSET_SS_READ (functional since Linux 2.6.28)
- Return (in buf.offset) the remaining amount of time to be adjusted after an earlier ADJ_OFFSET_SINGLESHOT operation. This feature was added in Linux 2.6.24, but did not work correctly until Linux 2.6.28.
Ordinary users are restricted to a value of either 0 or
ADJ_OFFSET_SS_READ
for
modes.
Only the superuser may set any parameters.
The
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.
- STA_PLL
- Enable phase-locked loop (PLL) updates (read-write) via ADJ_OFFSET.
- STA_PPSFREQ
- Enable PPS freq discipline (read-write).
- STA_PPSTIME
- Enable PPS time discipline (read-write).
- STA_FLL
- Select frequency-locked loop (FLL) mode (read-write).
- STA_INS
- Insert leap second (read-write).
- STA_DEL
- Delete leap second (read-write).
- STA_UNSYNC
- Clock unsynchronized (read-write).
- STA_FREQHOLD
- Hold frequency (read-write).
- STA_PPSSIGNAL
- PPS signal present (read-only).
- STA_PPSJITTER
- PPS signal jitter exceeded (read-only).
- STA_PPSWANDER
- PPS signal wander exceeded (read-only).
- STA_PPSERROR
- PPS signal calibration error (read-only).
- STA_CLOCKERR
- Clock hardware fault (read-only).
- STA_NANO (since Linux 2.6.26)
- Resolution (0 = microsecond, 1 = nanoseconds; read-only). Set via ADJ_NANO, cleared via ADJ_MICRO.
- STA_MODE (since Linux 2.6.26)
- Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop; read-only).
- STA_CLK (since Linux 2.6.26)
- Clock source (0 = A, 1 = B; read-only).
Attempts to set read-only status bits are silently ignored.
RETURN VALUE
On success, adjtimex() returns the clock state; that is, one of the following values:- TIME_OK
- Clock synchronized.
- TIME_INS
- Insert leap second.
- TIME_DEL
- Delete leap second.
- TIME_OOP
- Leap second in progress.
- TIME_WAIT
- Leap second has occurred.
- TIME_ERROR
- Clock not synchronized. The symbolic name TIME_BAD is a synonym for TIME_ERROR, provided for backward compatibility.
On failure, adjtimex() returns -1 and sets errno.
ERRORS
- EFAULT
- buf does not point to writable memory.
- EINVAL
- An attempt was made to set buf.offset to a value outside the range -131071 to +131071, or to set buf.status to a value other than those listed above, or to set buf.tick to a value outside the range 900000/HZ to 1100000/HZ, where HZ is the system timer interrupt frequency.
- EPERM
- buf.modes is neither 0 nor ADJ_OFFSET_SS_READ, and the caller does not have sufficient privilege. Under Linux, the CAP_SYS_TIME capability is required.