man2/adjtimex.2

   1 .\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995.
   2 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl>
  27 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"
  29 .TH ADJTIMEX 2 2014-05-28 "Linux" "Linux Programmer's Manual"
  30 .SH NAME
  31 adjtimex \- tune kernel clock
  32 .SH SYNOPSIS
  33 .nf
  34 .BR "#define _BSD_SOURCE" "      /* See feature_test_macros(7) */"
  35 .B #include <sys/timex.h>
  36
  37 .BI "int adjtimex(struct timex *" "buf" );
  38 .fi
  39 .SH DESCRIPTION
  40 Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 1305).
  41 The system call
  42 .BR adjtimex ()
  43 reads and optionally sets adjustment parameters for this algorithm.
  44 It takes a pointer to a
  45 .I timex
  46 structure, updates kernel parameters from field values,
  47 and returns the same structure with current kernel values.
  48 This structure is declared as follows:
  49 .PP
  50 .in +4n
  51 .nf
  52 struct timex {
  53     int  modes;          /* Mode selector */
  54     long offset;         /* Time offset (microseconds) */
  55     long freq;           /* Frequency offset, as scaled PPM
  56                             (parts per million) */
  57 .\" FIXME What is the scaling unit of timex.freq?  2^16 ?
  58     long maxerror;       /* Maximum error (microseconds) */
  59     long esterror;       /* Estimated error (microseconds) */
  60     int  status;         /* Clock command/status */
  61     long constant;       /* PLL (phase-lock loop) time constant */
  62     long precision;      /* Clock precision (microseconds)
  63                             (read-only) */
  64     long tolerance;      /* Clock frequency tolerance (PPM)
  65                             (read-only) */
  66     struct timeval time; /* Current time (read-only, except
  67                             for ADJ_SETOFFSET) */
  68     long tick;           /* Usecs between clock ticks */
  69     long ppsfreq;        /* PPS frequency (scaled PPM) (read-only) */
  70     long jitter;         /* PPS jitter (microseconds)
  71                             (read-only) */
  72     int shift;           /* Interval duration (sec) (read-only) */
  73     long stabil;         /* PPS stability (scaled PPM) (read-only) */
  74     long jitcnt;         /* Jitter limit exceeded (read-only) */
  75     long calcnt;         /* Calibration intervals (read-only) */
  76     long errcnt;         /* Calibration errors (read-only) */
  77     long stbcnt;         /* Stability limit exceeded (read-only) */
  78     int tai;             /* TAI offset (sec) (read-only) */
  79 };
  80 .fi
  81 .in
  82 .PP
  83 The
  84 .I modes
  85 field determines which parameters, if any, to set.
  86 It is a bit mask containing a
  87 .RI bitwise- or
  88 combination of zero or more of the following bits:
  89 .TP
  90 .BR ADJ_OFFSET
  91 Set time offset from
  92 .IR buf.offset .
  93 .TP
  94 .BR ADJ_FREQUENCY
  95 Set frequency offset from
  96 .IR buf.freq .
  97 .TP
  98 .BR ADJ_MAXERROR
  99 Set maximum time error from
 100 .IR buf.maxerror .
 101 .TP
 102 .BR ADJ_ESTERROR
 103 Set estimated time error from
 104 .IR buf.esterror .
 105 .TP
 106 .BR ADJ_STATUS
 107 Set clock status from
 108 .IR buf.status .
 109 .TP
 110 .BR ADJ_TIMECONST
 111 Set PLL time constant from
 112 .IR buf.constant .
 113 .TP
 114 .BR ADJ_SETOFFSET " (since Linux 2.6.29)"
 115 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
 116 .\" Author: Richard Cochran <richardcochran@gmail.com>
 117 Add
 118 .I buf.time
 119 to the current time.
 120 .TP
 121 .TP
 122 .BR ADJ_MICRO " (since Linux 2.6.36)"
 123 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 124 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 125 Select microsecond resolution.
 126 .TP
 127 .BR ADJ_NANO " (since Linux 2.6.36)"
 128 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
 129 .\" Author: Roman Zippel <zippel@linux-m68k.org>
 130 Select nanosecond resolution.
 131 Only one of
 132 .BR ADJ_MICRO
 133 and
 134 .BR ADJ_NANO
 135 should be specified.
 136 .TP
 137 .BR ADJ_TAI " (since Linux 2.6.26)"
 138 TAI offset.
 139 .TP
 140 .BR ADJ_TICK
 141 Set tick value from
 142 .IR buf.tick .
 143 .PP
 144 Alternatively,
 145 .I modes
 146 can be specified as either of the following values,
 147 in which case other bits in
 148 .I modes
 149 are ignored:
 150 .TP
 151 .BR ADJ_OFFSET_SINGLESHOT
 152 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
 153 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
 154 Old-fashioned
 155 .BR adjtime ():
 156 (gradually) adjust time by value specified in
 157 .IR buf.offset ,
 158 which specifies an adjustment in microseconds.
 159 .TP
 160 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
 161 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
 162 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
 163 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
 164 Return (in
 165 .BR buf.offset )
 166 the remaining amount of time to be adjusted after an earlier
 167 .BR ADJ_OFFSET_SINGLESHOT
 168 operation.
 169 This feature was added in Linux 2.6.24,
 170 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
 171 but did not work correctly
 172 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
 173 until Linux 2.6.28.
 174 .PP
 175 Ordinary users are restricted to a value of either 0 or
 176 .B ADJ_OFFSET_SS_READ
 177 for
 178 .IR modes .
 179 Only the superuser may set any parameters.
 180
 181 In the case of
 182 .BR ADJ_TAI ,
 183 as
 184 .I buf->tai
 185 is read-only, the new value is passed through
 186 .IR buf->constant .
 187 Therefore
 188 .BR ADJ_TAI
 189 should not be used in conjunction with
 190 .BR ADJ_TIMECONST ,
 191 since the latter mode also employs the
 192 .IR buf->constant
 193 field.
 194 .PP
 195 Support for TAI (Atomic International Time)
 196 was added
 197 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
 198 in Linux 2.6.26.
 199 For a complete explanation of TAI
 200 and the difference between TAI and UTC, see
 201 .UR http://www.bipm.org/en/bipm/tai/tai.html
 202 .I BIPM
 203 .UE )
 204 .SH RETURN VALUE
 205 On success,
 206 .BR adjtimex ()
 207 returns the clock state; that is, one of the following values:
 208 .TP 12
 209 .BR TIME_OK
 210 Clock synchronized.
 211 .TP
 212 .BR TIME_INS
 213 Insert leap second.
 214 .TP
 215 .BR TIME_DEL
 216 Delete leap second.
 217 .TP
 218 .BR TIME_OOP
 219 Leap second in progress.
 220 .TP
 221 .BR TIME_WAIT
 222 Leap second has occurred.
 223 .TP
 224 .BR TIME_BAD
 225 Clock not synchronized.
 226 .PP
 227 On failure,
 228 .BR adjtimex ()
 229 returns \-1 and sets
 230 .IR errno .
 231 .SH ERRORS
 232 .TP
 233 .B EFAULT
 234 .I buf
 235 does not point to writable memory.
 236 .TP
 237 .B EINVAL
 238 An attempt was made to set
 239 .I buf.offset
 240 to a value outside the range \-131071 to +131071,
 241 or to set
 242 .I buf.status
 243 to a value other than those listed above,
 244 or to set
 245 .I buf.tick
 246 to a value outside the range
 247 .RB 900000/ HZ
 248 to
 249 .RB 1100000/ HZ ,
 250 where
 251 .B HZ
 252 is the system timer interrupt frequency.
 253 .TP
 254 .B EPERM
 255 .I buf.modes
 256 is neither 0 nor
 257 .BR ADJ_OFFSET_SS_READ ,
 258 and the caller does not have sufficient privilege.
 259 Under Linux the
 260 .B CAP_SYS_TIME
 261 capability is required.
 262 .SH CONFORMING TO
 263 .BR adjtimex ()
 264 is Linux-specific and should not be used in programs
 265 intended to be portable.
 266 See
 267 .BR adjtime (3)
 268 for a more portable, but less flexible,
 269 method of adjusting the system clock.
 270 .SH SEE ALSO
 271 .BR settimeofday (2),
 272 .BR adjtime (3),
 273 .BR capabilities (7),
 274 .BR time (7),
 275 .BR adjtimex (8)