NTP_ADJTIME(2)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

🌸 NAME 🌸

okay so bestie, welcome to NTP_ADJTIME(2) from the System Calls Manual — this page is literally the kernel interface to the Network Time Protocol daemon, ntpd(8), and it covers the ntp_adjtime and ntp_gettime system calls. ✨

📚 LIBRARY 📚

Standard C Library (libc, -lc) 🫶

🛠️ SYNOPSIS 🛠️

#include <sys/timex.h>

int
ntp_adjtime(struct timex *);

int
ntp_gettime(struct ntptimeval *);

🌈 DESCRIPTION 🌈

The two system calls ntp_adjtime() and ntp_gettime() are the kernel interface to the Network Time Protocol (NTP) daemon ntpd(8). 👑

The ntp_adjtime() function is what the NTP daemon uses to adjust the system clock to an externally derived time. The time offset and related variables that get set by ntp_adjtime() are used by hardclock() to adjust the phase and frequency of the phase- or frequency-lock loop (PLL resp. FLL) that controls the system clock. This is genuinely main character clock business. 😭

The ntp_gettime() function provides the time, maximum error (sync distance) and estimated error (dispersion) to client user application programs. 🕰️

In the following, all variables that refer PPS are only relevant if the PPS_SYNC option is enabled in the kernel. no cap 💅

ntp_adjtime() has as argument a struct timex * of the following form:

struct timex {
        unsigned int modes;     /* clock mode bits (wo) */
        long offset;            /* time offset (us) (rw) */
        long freq;              /* frequency offset (scaled ppm) (rw) */
        long maxerror;          /* maximum error (us) (rw) */
        long esterror;          /* estimated error (us) (rw) */
        int status;             /* clock status bits (rw) */
        long constant;          /* pll time constant (rw) */
        long precision;         /* clock precision (us) (ro) */
        long tolerance;         /* clock frequency tolerance (scaled
                                 * ppm) (ro) */
        /*
         * The following read-only structure members are implemented
         * only if the PPS signal discipline is configured in the
         * kernel.
         */
        long ppsfreq;           /* pps frequency (scaled ppm) (ro) */
        long jitter;            /* pps jitter (us) (ro) */
        int shift;              /* interval duration (s) (shift) (ro) */
        long stabil;            /* pps stability (scaled ppm) (ro) */
        long jitcnt;            /* jitter limit exceeded (ro) */
        long calcnt;            /* calibration intervals (ro) */
        long errcnt;            /* calibration errors (ro) */
        long stbcnt;            /* stability limit exceeded (ro) */
};

The members of this struct have the following meanings when used as argument for ntp_adjtime():

  • modes — defines what settings should be changed with the current ntp_adjtime() call (write-only). It's a bitwise OR of the following:
    • MOD_OFFSET — set time offset
    • MOD_FREQUENCY — set frequency offset
    • MOD_MAXERROR — set maximum time error
    • MOD_ESTERROR — set estimated time error
    • MOD_STATUS — set clock status bits
    • MOD_TIMECONST — set PLL time constant
    • MOD_CLKA — set clock A
    • MOD_CLKB — set clock B
  • offset — time offset (in microseconds), used by the PLL/FLL to adjust the system time in small increments (read-write).
  • freq — frequency offset (scaled ppm) (read-write).
  • maxerror — maximum error (in microseconds). Initialized by an ntp_adjtime() call, and increased by the kernel once each second to reflect the maximum error bound growth (read-write).
  • esterror — estimated error (in microseconds). Set and read by ntp_adjtime(), but unused by the kernel (read-write).
  • status — system clock status bits (read-write). Bitwise OR of the following:
    • STA_PLL — enable PLL updates (read-write).
    • STA_PPSFREQ — enable PPS freq discipline (read-write).
    • STA_PPSTIME — enable PPS time discipline (read-write).
    • STA_FLL — select frequency-lock mode (read-write).
    • STA_INS — insert leap (read-write).
    • STA_DEL — delete leap (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).
  • constant — PLL time constant, determines the bandwidth, or “stiffness”, of the PLL (read-write).
  • precision — clock precision (in microseconds). In most cases the same as the kernel tick variable (see hz(9)). If a precision clock counter or external time-keeping signal is available, it could be much lower (and depend on the state of the signal) (read-only).
  • tolerance — maximum frequency error, or tolerance of the CPU clock oscillator (scaled ppm). Ordinarily a property of the architecture, but could change under the influence of external time-keeping signals (read-only).
  • ppsfreq — PPS frequency offset produced by the frequency median filter (scaled ppm) (read-only).
  • jitter — PPS jitter measured by the time median filter in microseconds (read-only).
  • shift — logarithm to base 2 of the interval duration in seconds (PPS, read-only).
  • stabil — PPS stability (scaled ppm); dispersion (wander) measured by the frequency median filter (read-only).
  • jitcnt — number of seconds that have been discarded because the jitter measured by the time median filter exceeded the limit MAXTIME (PPS, read-only).
  • calcnt — count of calibration intervals (PPS, read-only).
  • errcnt — number of calibration intervals that have been discarded because the wander exceeded the limit MAXFREQ or where the calibration interval jitter exceeded two ticks (PPS, read-only).
  • stbcnt — number of calibration intervals that have been discarded because the frequency wander exceeded the limit MAXFREQ/4 (PPS, read-only).

After the ntp_adjtime() call, the struct timex * structure contains the current values of the corresponding variables. 💖

ntp_gettime() has as argument a struct ntptimeval * with the following members:

struct ntptimeval {
        struct timeval time;    /* current time (ro) */
        long maxerror;          /* maximum error (us) (ro) */
        long esterror;          /* estimated error (us) (ro) */
};

These have the following meaning:

  • time — current time (read-only).
  • maxerror — maximum error in microseconds (read-only).
  • esterror — estimated error in microseconds (read-only).

💖 RETURN VALUES 💖

ntp_adjtime() and ntp_gettime() return the current state of the clock on success, or any of the errors of copyin(9) and copyout(9). 🫶

ntp_adjtime() may additionally return EPERM if the user calling ntp_adjtime() does not have sufficient permissions. 🙈

Possible states of the clock are:

  • TIME_OK — everything okay, no leap second warning.
  • TIME_INS — “insert leap second” warning. At the end of the day, a leap second will be inserted after 23:59:59.
  • TIME_DEL — “delete leap second” warning. At the end of the day, second 23:59:59 will be skipped.
  • TIME_OOP — leap second in progress.
  • TIME_WAIT — leap second has occurred within the last few seconds.
  • TIME_ERROR — clock not synchronized.

🚨 ERRORS 🚨

The ntp_adjtime() system call may return EPERM if the caller does not have sufficient permissions. 🔥

👀 SEE ALSO 👀

💀 BUGS 💀

Take note that this API is extremely complex and stateful. Users should not attempt modification without first reviewing the ntpd(8) sources in depth. bestie, this is not a “just vibe and change stuff” situation, fr fr 😭

💖 sign-off: Debian · March 22, 2026 · NTP_ADJTIME(2) 💖

📦 where this page comes from