| .\" 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" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock |
| .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). |
| 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 (selected) field values, |
| and returns the same structure updated with the current kernel values. |
| This structure is declared as follows: |
| .PP |
| .in +4n |
| .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; 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 (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 |
| (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 (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, |
| since Linux 2.6.26) */ |
| /* Further padding bytes to allow for future expansion */ |
| }; |
| .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 |
| Set time offset from |
| .IR buf.offset . |
| Since Linux 2.6.26, |
| .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 |
| the supplied value is clamped to the range (\-0.5s, +0.5s). |
| In older kernels, an |
| .B EINVAL |
| error occurs if the supplied value is out of range. |
| .TP |
| .BR ADJ_FREQUENCY |
| Set frequency offset from |
| .IR buf.freq . |
| Since Linux 2.6.26, |
| .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 |
| the supplied value is clamped to the range (\-32768000, +32768000). |
| In older kernels, an |
| .B EINVAL |
| error occurs if the supplied value is out of range. |
| .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 bits from |
| .IR buf.status . |
| A description of these bits is provided below. |
| .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.39)" |
| .\" 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. |
| .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.26)" |
| .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
| .\" Author: Roman Zippel <zippel@linux-m68k.org> |
| Select microsecond resolution. |
| .TP |
| .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 |
| 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 . |
| .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 |
| .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 (3): |
| (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. |
| .PP |
| 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 " (read-write)" |
| Enable phase-locked loop (PLL) updates via |
| .BR ADJ_OFFSET . |
| .TP |
| .BR STA_PPSFREQ " (read-write)" |
| Enable PPS (pulse-per-second) frequency discipline. |
| .TP |
| .BR STA_PPSTIME " (read-write)" |
| Enable PPS time discipline. |
| .TP |
| .BR STA_FLL " (read-write)" |
| Select frequency-locked loop (FLL) mode. |
| .TP |
| .BR STA_INS " (read-write)" |
| Insert a leap second after the last second of the UTC day, |
| thus extending the last minute of the day by one second. |
| Leap-second insertion will occur each day, so long as this flag remains set. |
| .\" John Stultz; |
| .\" Usually this is written as extending the day by one second, |
| .\" which is represented as: |
| .\" 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 |
| .\" 00:00:00 + TIME_WAIT |
| .\" |
| .TP |
| .BR STA_DEL " (read-write)" |
| Delete a leap second at the last second of the UTC day. |
| .\" John Stultz: |
| .\" Similarly the progression here is: |
| .\" 23:59:57 + TIME_DEL |
| .\" 23:59:58 + TIME_DEL |
| .\" 00:00:00 + TIME_WAIT |
| 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? |
| .TP |
| .BR STA_UNSYNC " (read-write)" |
| Clock unsynchronized. |
| .TP |
| .BR STA_FREQHOLD " (read-write)" |
| Hold frequency. |
| .\" Following text from John Stultz: |
| Normally adjustments made via |
| .B ADJ_OFFSET |
| result in dampened frequency adjustments also being made. |
| 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 |
| value. |
| .\" According to the Kernel Application Program Interface document, |
| .\" STA_FREQHOLD is not used by the NTP version 4 daemon |
| .TP |
| .BR STA_PPSSIGNAL " (read-only)" |
| A valid PPS (pulse-per-second) signal is present. |
| .TP |
| .BR STA_PPSJITTER " (read-only)" |
| PPS signal jitter exceeded. |
| .TP |
| .BR STA_PPSWANDER " (read-only)" |
| PPS signal wander exceeded. |
| .TP |
| .BR STA_PPSERROR " (read-only)" |
| PPS signal calibration error. |
| .TP |
| .BR STA_CLOCKERR " (read-only)" |
| Clock hardware fault. |
| .\" Not set in current kernel (4.5), but checked in a few places |
| .TP |
| .BR STA_NANO " (read-only; since Linux 2.6.26)" |
| .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
| .\" Author: Roman Zippel <zippel@linux-m68k.org> |
| Resolution (0 = microsecond, 1 = nanoseconds). |
| 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). |
| .TP |
| .BR STA_CLK " (read-only; since Linux 2.6.26)" |
| .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
| .\" Author: Roman Zippel <zippel@linux-m68k.org> |
| Clock source (0 = A, 1 = B); currently unused. |
| .PP |
| 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 |
| .IR 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 * |
| .BR MOD_CLKA |
| is the synonym for |
| .BR ADJ_OFFSET_SINGLESHOT . |
| .IP * |
| .BR 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 () |
| and |
| .BR ntp_adjtime () |
| return the clock state; that is, one of the following values: |
| .TP 12 |
| .BR TIME_OK |
| Clock synchronized, no leap second adjustment pending. |
| .TP |
| .BR 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 UTC day. |
| .TP |
| .BR TIME_OOP |
| Insertion of a leap second is in progress. |
| .TP |
| .BR TIME_WAIT |
| A leap-second insertion or deletion has been completed. |
| This value will be returned until the next |
| .BR ADJ_STATUS |
| operation clears the |
| .B STA_INS |
| and |
| .B STA_DEL |
| flags. |
| .TP |
| .BR TIME_ERROR |
| The system clock is not synchronized to a reliable server. |
| This value is returned when any of the following holds true: |
| .RS |
| .IP * 3 |
| Either |
| .B STA_UNSYNC |
| or |
| .B STA_CLOCKERR |
| is set. |
| .IP * |
| .B STA_PPSSIGNAL |
| is clear and either |
| .B STA_PPSFREQ |
| or |
| .B STA_PPSTIME |
| is set. |
| .IP * |
| .B STA_PPSTIME |
| and |
| .B STA_PPSJITTER |
| are both set. |
| .IP * |
| .B STA_PPSFREQ |
| is set and either |
| .B STA_PPSWANDER |
| or |
| .B STA_PPSJITTER |
| is set. |
| .RE |
| .IP |
| The symbolic name |
| .B TIME_BAD |
| is a synonym for |
| .BR TIME_ERROR , |
| provided for backward compatibility. |
| .PP |
| Note that starting with Linux 3.4, |
| .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous |
| .\" operation, so we can no longer rely on the return code. |
| the call operates asynchronously and the return value usually will |
| not reflect a state change caused by the call itself. |
| .PP |
| On failure, these calls return \-1 and set |
| .IR errno |
| to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I buf |
| does not point to writable memory. |
| .TP |
| .BR EINVAL " (kernels before Linux 2.6.26)" |
| An attempt was made to set |
| .I buf.freq |
| to a value outside the range (\-33554432, +33554432). |
| .\" 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)" |
| An attempt was made to set |
| .I buf.offset |
| to a value outside the permitted range. |
| In kernels before Linux 2.0, the permitted range was (\-131072, +131072). |
| From Linux 2.0 onwards, the permitted range was (\-512000, +512000). |
| .TP |
| .B EINVAL |
| An attempt was made to set |
| .I buf.status |
| 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 |
| .RB 900000/ HZ |
| to |
| .RB 1100000/ HZ , |
| where |
| .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 |
| .BR ADJ_OFFSET_SS_READ , |
| and the caller does not have sufficient privilege. |
| 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 CONFORMING TO |
| 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 , |
| .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. |
| .PP |
| The leap-second processing triggered by |
| .B STA_INS |
| and |
| .B STA_DEL |
| 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 SEE ALSO |
| .BR clock_gettime (2), |
| .BR clock_settime (2), |
| .BR settimeofday (2), |
| .BR adjtime (3), |
| .BR ntp_gettime (3), |
| .BR capabilities (7), |
| .BR time (7), |
| .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" |
| .UE |