sys_clock_getres(9)

✨ sys_clock_getres(9) ✨

okay so this is a page from the Kernel API Manual (section 9, kernel developer land 🧚) and it's all about sys_clock_getres — the syscall that tells you how precise a clock actually is. let's get into it bestie 💖

---

🌸 NAME 🌸

sys_clock_getres — get the resolution of a clock ⏰✨

---

🎀 SYNOPSIS 🎀

long sys_clock_getres (const clockid_t which_clock , struct
       __kernel_timespec __user * tp );

---

💅 ARGUMENTS 💅

• which_clock — the clock you want the resolution for 🕰️
• tp — pointer to a a user space timespec64 for storage 📦

---

🦋 DESCRIPTION 🦋

so POSIX says, and I quote:

"The clock_getres function shall return the resolution of any clock. Clock resolutions are implementation-defined and cannot be set by a process. If the argument res is not NULL, the resolution of the specified clock shall be stored in the location pointed to by res. If res is NULL, the clock resolution is not returned. If the time argument of clock_settime is not a multiple of res, then the value is truncated to a multiple of res."

cute, love that for POSIX 💖 but here's the tea: because hardware is messy, the real resolution can vary wildly and can even change during runtime when the underlying devices get replaced. and the kernel can use hardware devices with different resolutions for reading the time vs. arming timers 😭 so yeah, the kernel deviates from the POSIX spec in a few ways:

1️⃣ the resolution returned to user space

for CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, CLOCK_TAI, CLOCK_REALTIME_ALARM, CLOCK_BOOTTIME_ALAREM and CLOCK_MONOTONIC_RAW, the kernel only differentiates two cases:

I) low resolution mode 🐢

when high resolution timers are disabled at compile or runtime, the resolution returned is nanoseconds per tick, which represents the precision at which timers expire.

II) high resolution mode 🐇

when high resolution timers are enabled, the resolution returned is always one nanosecond, independent of the actual resolution of the underlying hardware devices. slay.

for CLOCK_*_ALARM the actual resolution depends on system state — when the system is running, the resolution is the same as the resolution of the other clocks. during suspend, the actual resolution is the resolution of the underlying RTC device, which might be way less precise than the clockevent device used during running state 😴

for CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE the resolution returned is always nanoseconds per tick.

for CLOCK_PROCESS_CPUTIME and CLOCK_THREAD_CPUTIME the resolution returned is always one nanosecond, under the assumption that the underlying scheduler clock has a better resolution than nanoseconds per tick.

for dynamic POSIX clocks (PTP devices) the resolution returned is always one nanosecond ✨

2️⃣ affect on sys_clock_settime

the kernel does not truncate the time that's handed in to sys_clock_settime. the kernel internal timekeeping is always using nanosecond precision, independent of the clocksource device used to read the time from. the resolution of that device only affects the precision of the time returned by sys_clock_gettime 🔥

---

👑 RETURN 👑

• 0 — success 💖 tp contains the resolution
• -EINVAL — which_clock is not a valid clock ID 🙈
• -EFAULT — copying the resolution to tp faulted 💀
• -ENODEV — dynamic POSIX clock is not backed by a device 😭
• -EOPNOTSUPP — dynamic POSIX clock does not support getres 🫠

---

🌈 SEE ALSO 🌈

• kernel file ./kernel/time/posix-timers.c
• sys_timer_getoverrun(9)

---

that's the whole vibe bestie, go forth and check your clock resolutions responsibly 💜✨

— with love, from ./kernel/time, dated October 2026 🎀🦋 (kernel api manual, section 9, periodt)