ntp_gettime(3)

💖 ntp_gettime(3) — Library Functions Manual 💖

okay bestie, so this is the ntp_gettime page from the Library Functions Manual, and it's genuinely so cute — two little functions that let you peek at what the system clock is doing. clock gossip. let's get into it 🕐✨

---

🌸 NAME 🌸

ntp_gettime, ntp_gettimex — get time parameters (NTP daemon interface)

---

🎀 LIBRARY 🎀

Standard C library (libc, -lc)

like, the regular one. no weird extra libs needed, we're chillin 💅

---

✨ SYNOPSIS ✨

#include <sys/timex.h>

int ntp_gettime(struct ntptimeval *ntv);
int ntp_gettimex(struct ntptimeval *ntv);

two functions, same signature, one of them just does a lil extra. slay.

---

🦋 DESCRIPTION 🦋

okay so both of these APIs hand information back to you through the ntv argument, which is a pointer to a structure that looks exactly like this:

struct ntptimeval {
    struct timeval time;    /* Current time */
    long maxerror;          /* Maximum error */
    long esterror;          /* Estimated error */
    long tai;               /* TAI offset */

    /* Further padding bytes allowing for future expansion */
};

not me being obsessed with a struct that has padding bytes in it for future ✨manifestation✨. anyway, here's what every single field is doing:

the fields, one by one 🫶

• time — the current time, expressed as a timeval structure, which itself is giving:

struct timeval {
    time_t      tv_sec;   /* Seconds since the Epoch */
    suseconds_t tv_usec;  /* Microseconds */
};

seconds plus microseconds. the classic. iconic.

• maxerror — the max error, measured in microseconds. this one can be initialized by ntp_adjtime(3), and then it gets bumped up periodically (on Linux that's every second, so, constantly, bestie) — BUT it's clamped to an upper limit. which limit? the kernel constant NTP_PHASE_MAX, whose value is 16,000. no cap... except literally there is a cap and it's 16,000 💀
• esterror — the estimated error, also in microseconds. you can set this one via ntp_adjtime(3) so it holds an estimate of the difference between the system clock and the true time. plot twist tho — this value is not used inside the kernel. it's just... sitting there. aesthetic. decorative. a little guy.
• tai — the TAI (Atomic International Time) offset.

now which function does what 👑

• ntp_gettime() gives you back an ntptimeval structure where the time, maxerror, and esterror fields are filled in.
• ntp_gettimex() does the exact same task as ntp_gettime(), but it also returns information in the tai field. so she's the overachiever. main character energy fr fr.

---

💫 RETURN VALUE 💫

the return values for ntp_gettime() and ntp_gettimex() are as for adjtimex(2).

and here's the cute part: given a correct pointer argument, these functions always succeed. they just do not miss. 🎯

ngl the "given a correct pointer argument" is doing a lot of heavy lifting there. pass it a valid pointer and you're golden. pass it nonsense and that's on you, bestie. 🙈

---

🌈 ATTRIBUTES 🌈

for an explanation of the terms used in this section, see attributes(7).

• Interface: ntp_gettime(), ntp_gettimex()
• Attribute: Thread safety
• Value: MT-Safe

translation: MT-Safe means you can call these from multiple threads and it's fine. the girls are safe. 💖

---

⭐ STANDARDS ⭐

• ntp_gettime() — NTP Kernel Application Program Interface.
• ntp_gettimex() — GNU.

one's the standard API, one's the GNU bonus track. both valid. 🫶

---

🧚 HISTORY 🧚

• ntp_gettime() — glibc 2.1.
• ntp_gettimex() — glibc 2.12.

so ntp_gettimex() is the younger sibling that showed up in glibc 2.12. she's new-ish and she brought the TAI offset with her. 🌸

---

👑 SEE ALSO 👑

adjtimex(2), ntp_adjtime(3), time(7)

NTP "Kernel Application Program Interface"

go read those next, bestie, they're the whole friend group 💅

---

mwah, that's the whole page. every flag, field, value, function, macro and reference, all of it, no crumbs left behind. 🍓

signing off with the receipts: this is from Linux man-pages 6.20, dated 2026-02-08, and the page is ntp_gettime(3). 💜✨