Man Pages

---

Back to Software Index  Manpage Top Level

Name

Synopsis

#define _BSD_SOURCE      /* See feature_test_macros(7) */#include <sys/timex.h>int
adjtimex(struct timex *buf);

Description

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

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.

Notes

Conforming to

See Also

Colophon

Table of Contents

• Name
• Synopsis
• Description
• Return Value
• Errors
• Notes
• Conforming to
• See Also
• Colophon