timer_getoverrun(2)

💖 timer_getoverrun — bestie, let's count your overruns 💖

okay so this one lives in the System Calls Manual, section 2 of the whole man-pages situation (iykyk), and it's the tiny little function that tells you how many timer expirations you missed while you were busy. she's small but she's important. 🎀

---

✨ NAME ✨

timer_getoverrun — get overrun count for a POSIX per-process timer

---

🧚 LIBRARY 🧚

Real-time library (librt, -lrt)

---

🌸 SYNOPSIS 🌸

#include <time.h>

int timer_getoverrun(timer_t timerid);

🦋 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

timer_getoverrun():

• _POSIX_C_SOURCE >= 199309L

---

💅 DESCRIPTION 💅

timer_getoverrun() returns the "overrun count" for the timer referred to by timerid. Basically your app can use this number to figure out exactly how many timer expirations would have happened across some time interval — like, it's accounting, but for timers. ✨ Timer overruns can pop off both when you're getting expiration notifications via signals (SIGEV_SIGNAL), and when you're getting them via threads (SIGEV_THREAD).

when notifications come through a signal 👇

overruns happen like this. Doesn't matter whether a real-time signal is being used for the timer notifications or not — the system queues at most one signal per timer. (That's literally what POSIX.1 says to do. The other option, queueing one signal for every single timer expiration, could super easily blow past the allowed limits for queued signals on the system, and then we'd all be in trouble. 💀) Now, because of system scheduling delays, or because the signal might be temporarily blocked, there can be a gap between when the notification signal is generated and when it actually gets delivered (like, caught by a signal handler) or accepted (like, using sigwaitinfo(2)). And in that lil gap? More timer expirations may occur. The timer overrun count is the number of extra timer expirations that happened between the moment the signal was generated and the moment it was delivered or accepted. slay, that's the number. 💖

when notifications come through a thread 👇

Timer overruns can also happen when expiration notifications are delivered by invoking a thread, because there can be an arbitrary delay between the timer expiring and the notification thread actually getting invoked — and in that delay? yeah. additional timer expirations. may occur. 🙈

---

🫶 RETURN VALUE 🫶

On success, timer_getoverrun() returns the overrun count of the specified timer — and bestie, that count can totally be 0 if no overruns have occurred, so don't panic. 🎀 On failure, -1 is returned, and errno is set to tell you what went wrong.

---

🔥 ERRORS 🔥

• EINVAL — timerid is not a valid timer ID.

---

🌈 VERSIONS 🌈

When timer notifications are delivered via signals (SIGEV_SIGNAL), on Linux you can also grab the overrun count through the si_overrun field of the siginfo_t structure (peep sigaction(2)). That lets an application dodge the overhead of making a system call just to get the overrun count — but heads up, it's a nonportable extension to POSIX.1. so cute but not universal. 💅

Also: POSIX.1 only ever discusses timer overruns in the context of timer notifications using signals.

---

👑 STANDARDS 👑

POSIX.1-2024.

---

⭐ HISTORY ⭐

Linux 2.6. POSIX.1-2001.

---

🍓 BUGS 🍓

POSIX.1 says that if the timer overrun count is equal to or greater than an implementation-defined maximum, DELAYTIMER_MAX, then timer_getoverrun() should return DELAYTIMER_MAX. But — before Linux 4.19, if the timer overrun value exceeded the maximum representable integer, the counter would cycle, starting over again from low values. 😭 Since Linux 4.19, timer_getoverrun() returns DELAYTIMER_MAX (which is defined as INT_MAX in <limits.h>) in this case, and the overrun value gets reset to 0. glow-up honestly. ✨

---

🎀 EXAMPLES 🎀

See timer_create(2).

---

💜 SEE ALSO 💜

clock_gettime(2), sigaction(2), signalfd(2), sigwaitinfo(2), timer_create(2), timer_delete(2), timer_settime(2), signal(7), time(7)

---

okay that's the whole page, bestie, you ate it 💅 this was Linux man-pages 6.20, dated 2025-10-29 — go forth and count those overruns, ily, bye!! 🦋✨💖