| .\" Hey Emacs! This file is -*- nroff -*- source. |
| .\" |
| .\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. |
| .\" |
| .\" 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, write to the Free |
| .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, |
| .\" USA. |
| .\" |
| .\" 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> |
| .\" |
| .\" FIXME 2.6.29 added ADJ_SETOFFSET |
| .\" |
| .TH ADJTIMEX 2 2004-05-27 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| adjtimex \- tune kernel clock |
| .SH SYNOPSIS |
| .B #include <sys/timex.h> |
| .sp |
| .BI "int adjtimex(struct timex *" "buf" ); |
| .SH DESCRIPTION |
| Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 1305). |
| 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 (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 */ |
| }; |
| .fi |
| .in |
| .PP |
| The |
| .I modes |
| field determines which parameters, if any, to set. |
| It may contain a |
| .RI bitwise- or |
| combination of zero or more of the following bits: |
| .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 |
| .PP |
| Ordinary users are restricted to a zero value for |
| .IR mode . |
| Only the superuser may set any parameters. |
| .br |
| .ne 12v |
| .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 |
| .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 is 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.mode |
| is nonzero and the caller does not have sufficient privilege. |
| Under Linux the |
| .B CAP_SYS_TIME |
| capability is required. |
| .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) |