GETITIMER(2)

💖 GETITIMER(2) 💖

okay so bestie, we're in the System Calls Manual today and the vibe is timers. not the cute countdown-to-your-birthday kind (well, actually, kind of). we're talking interval timers, the little ticking clocks your process can set up so the kernel yells at it later. grab a snack 🍓, this one's actually fun.

---

✨ NAME ✨

getitimer, setitimer — get/set value of interval timer

📚 LIBRARY 📚

Standard C Library (libc, -lc)

🎀 SYNOPSIS 🎀

#include <sys/time.h>
#define ITIMER_REAL      0
#define ITIMER_VIRTUAL   1
#define ITIMER_PROF      2

int
getitimer(int which, struct itimerval *value);

int
setitimer(int which, const struct itimerval *value,
    struct itimerval *ovalue);

🦋 DESCRIPTION 🦋

so. every process gets three interval timers, and they're all defined in <sys/time.h>. that's the whole personality of this page.

• getitimer() — hands you back the current value of whichever timer you asked for in which, and drops it into the structure at value.
• setitimer() — sets a timer to the value you give it, and if ovalue isn't a null pointer it also gives you the previous value of that timer. two-for-one, we love to see it 💅

and a timer value? that's an itimerval structure, babes:

struct itimerval {
        struct  timeval it_interval;    /* timer interval */
        struct  timeval it_value;       /* current value */
};

okay let's decode this icon:

• if it_value is non-zero, that's the time until the next timer expiration. it's the "when do I go off" field.
• if it_interval is non-zero, that's the value used to reload it_value when the timer expires. so it's the "and then do it again every ___" field.
• setting it_value to 0 disables the timer. doesn't matter what it_interval says — zero it_value means off, periodt.
• setting it_interval to 0 means the timer gets disabled after its next expiration (assuming it_value is non-zero, obviously). one last hurrah, then it's done.

⏰ heads up: time values smaller than the resolution of the system clock get rounded up to that resolution. typically that's 10 milliseconds. so don't come crying to me about sub-10ms precision, it's giving "the clock said no."

now the three timers, main character by main character:

ITIMER_REAL — this one decrements in real time. when it expires, a SIGALRM signal gets delivered. wall-clock baby, it does not care what your process is doing.

ITIMER_VIRTUAL — this one decrements in process virtual time. it only runs while the process is actually executing. when it expires, you get a SIGVTALRM. it's the "only count my time, not the world's" timer ✨

ITIMER_PROF — this one decrements in process virtual time and while the system is running on behalf of the process. it's designed for interpreters doing statistical profiling of interpreted programs. every time it expires, SIGPROF gets delivered.

😭 and because SIGPROF can interrupt in-progress system calls, any program using ITIMER_PROF must be prepared to restart interrupted system calls. this is not optional, bestie, this is the price of admission.

one more number for you: the maximum number of seconds allowed for it_interval and it_value in setitimer() is 100000000. that's the ceiling. don't push it. 🫶

📝 NOTES 📝

three macros for messing with time values live in <sys/time.h> too:

• timerclear() — sets a time value to zero.
• timerisset() — tests if a time value is non-zero.
• timercmp() — compares two time values.

that's the whole trio. useful little guys. 🌸

🏆 RETURN VALUES 🏆

if everything went great? you get 0. iconic.

if it didn't? you get -1, and the global variable errno gets set to tell you what went wrong. (rude, but informative.)

💀 ERRORS 💀

both getitimer() and setitimer() will fail if:

• [EFAULT] — the value argument specified a bad address. 💀
• [EINVAL] — the value argument specified a time that was too large to be handled.

👀 SEE ALSO 👀

gettimeofday(2), select(2), sigaction(2), clocks(7)

📜 STANDARDS 📜

getitimer() and setitimer() conform to IEEE Std 1003.1-2001 ("POSIX.1"). ✨

⚠️ but plot twist: the later IEEE Std 1003.1-2008 ("POSIX.1") revision marked both functions as obsolescent, and it recommends using timer_gettime(2) and timer_settime(2) instead. so like… they still work, but the standards girlies are side-eyeing them. iykyk.

🕰️ HISTORY 🕰️

the getitimer() system call appeared in 4.2BSD. an elder. a legend. 👑

---

and that's the tea, bestie 💜 this page is from the Debian crew and it's dated May 1, 2020 — so go forth, set some timers, and remember to restart those interrupted system calls. slay 🎀✨