.\" 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
.\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl>
.\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.\" FIXME 2.6.26 added ADJ_TAI
-.\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
-.\" FIXME 2.6.26 added ADJ_MICOR and ADJ_NANO
-.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
-.\" Author: Roman Zippel <zippel@linux-m68k.org>
-.\" FIXME 2.6.39 added ADJ_SETOFFSET
-.\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
-.\" Author: Richard Cochran <richardcochran@gmail.com>
-.\"
-.TH ADJTIMEX 2 2014-05-28 "Linux" "Linux Programmer's Manual"
+.TH ADJTIMEX 2 2014-12-31 "Linux" "Linux Programmer's Manual"
.SH NAME
adjtimex \- tune kernel clock
.SH SYNOPSIS
.BI "int adjtimex(struct timex *" "buf" );
.fi
.SH DESCRIPTION
-Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 1305).
+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.
.in +4n
.nf
struct timex {
- int modes; /* mode selector */
- long offset; /* time offset (usec) */
- long freq; /* frequency offset (scaled ppm) */
-.\" FIXME -- what is the scaling unit? 2^16 ?
- long maxerror; /* maximum error (usec) */
- long esterror; /* estimated error (usec) */
- int status; /* clock command/status */
- long constant; /* pll time constant */
- long precision; /* clock precision (usec) (read-only) */
- long tolerance; /* clock frequency tolerance (ppm)
- (read-only) */
- struct timeval time; /* current time (read-only) */
- long tick; /* usecs between clock ticks */
+ 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
The
.I modes
field determines which parameters, if any, to set.
-It may contain a
+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
-.in +4n
-.nf
-#define ADJ_OFFSET 0x0001 /* time offset */
-#define ADJ_FREQUENCY 0x0002 /* frequency offset */
-#define ADJ_MAXERROR 0x0004 /* maximum time error */
-#define ADJ_ESTERROR 0x0008 /* estimated time error */
-#define ADJ_STATUS 0x0010 /* clock status */
-#define ADJ_TIMECONST 0x0020 /* pll time constant */
-#define ADJ_TICK 0x4000 /* tick value */
-#define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime() */
-.fi
-.in
+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 zero value for
+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.
-.br
-.ne 12v
+
+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:
-.PP
-.in +4n
-.nf
-#define TIME_OK 0 /* clock synchronized */
-#define TIME_INS 1 /* insert leap second */
-#define TIME_DEL 2 /* delete leap second */
-#define TIME_OOP 3 /* leap second in progress */
-#define TIME_WAIT 4 /* leap second has occurred */
-#define TIME_BAD 5 /* clock not synchronized */
-.fi
-.in
+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 ()
does not point to writable memory.
.TP
.B EINVAL
-An attempt is made to set
+An attempt was made to set
.I buf.offset
to a value outside the range \-131071 to +131071,
or to set
.TP
.B EPERM
.I buf.modes
-is nonzero and the caller does not have sufficient privilege.
-Under Linux the
+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
.BR time (7),
.BR adjtimex (8)
.SH COLOPHON
-This page is part of release 3.68 of the Linux
+This page is part of release 3.79 of the Linux
.I man-pages
project.
A description of the project,
OSDN Git Service
