TIMER_CREATE(2)

💖 TIMER_CREATE 💖

the iconic per-process timer maker — straight out of the System Calls Manual, section 2, and yes she's serving REALTIME realness 👑

---

🌸 NAME 🌸

timer_create — create a per-process timer (REALTIME)

🎀 LIBRARY 🎀

POSIX Real-time Library (librt, -lrt) — link her in, bestie, or she simply will not show up 💅

✨ SYNOPSIS ✨

#include <time.h>
#include <signal.h>

int
timer_create(clockid_t clockid, struct sigevent *restrict evp,
    timer_t *restrict timerid);

---

🦋 DESCRIPTION 🦋

okay so listen. timer_create() is the system call that creates a per-process timer using the clock you hand it — clock_id — as the timing base. slay.

She gives you back, in the spot that timerid points to, a timer ID of type timer_t. that ID is what you use to identify the timer in all your future timer requests. and it's unique within the calling process until the timer gets deleted — main character exclusivity, no cap. the specific clock, clock_id, is defined over in <time.h>. also, the timer whose ID you just got back? she arrives disarmed</> — no ticking, no drama, just vibes until you arm her.

The evp argument — if it's non-NULL — points to a sigevent structure. you allocate that yourself, and it defines the asynchronous notification that happens when the timer expires. it's giving "here's what to do when the moment comes."

If evp->sigev_notify is SIGEV_SIGNO or SIGEV_THREAD_ID, then the signal named in evp->sigev_signo gets sent to:

• the calling process — when it's SIGEV_SIGNO
• the thread whose LWP ID is evp->sigev_notify_thread_id — when it's SIGEV_THREAD_ID

and the info attached to that queued signal includes all of this 🫶:

• si_code — SI_TIMER
• si_value — the value stored in evp->sigev_value
• si_timerid — timer ID
• si_overrun — timer overrun count
• si_errno — if timer overrun is {DELAYTIMER_MAX}, an error code defined in <errno.h>

If the evp argument is NULL? literally the same as if you'd pointed evp at a sigevent structure where the sigev_notify member has the value SIGEV_SIGNAL, the sigev_signo has a default signal number (SIGALRM), and the sigev_value member has the value of the timer ID. the defaults ate, honestly.

This implementation supports a clock_id of CLOCK_REALTIME or CLOCK_MONOTONIC. that's the whole menu, bestie.

🚨 okay this next bit is the "read the fine print" moment. If evp->sigev_notify is SIGEV_THREAD and sev->sigev_notify_attributes is not NULL, and if the attribute pointed to by sev->sigev_notify_attributes has a thread stack address specified by a call to pthread_attr_setstack() or pthread_attr_setstackaddr(), then the results are unspecified if the signal is generated more than once. not a vibe. be careful out there 💀

---

🌈 RETURN VALUES 🌈

If the call succeeds, timer_create() returns zero and updates the location referenced by timerid to a timer_t, which you can then pass to the per-process timer calls. queen behavior.

If an error occurs, the system call returns a value of -1 and the global variable errno is set to indicate the error. and heads up: the value of timerid is undefined if an error occurs. don't go reading her, she's not okay 😭

---

💅 ERRORS 💅

The timer_create() system call will fail if:

• [EAGAIN] — The calling process has already created all of the timers it is allowed by this implementation. (timer cap reached, bestie, no more for you 🙈)
• [EINVAL] — The specified clock ID is not supported.
• [EINVAL] — The specified asynchronous notification method is not supported.
• [EFAULT] — Any arguments point outside the allocated address space or there is a memory protection fault.

---

👑 SEE ALSO 👑

clock_getres(2), timer_delete(2), timer_getoverrun(2), sigevent(3), siginfo(3)

the whole friend group, go say hi 💜

---

⭐ STANDARDS ⭐

The timer_create() system call conforms to IEEE Std 1003.1-2004 (“POSIX.1”). certified, stamped, official 🔥

---

🧚 HISTORY 🧚

Support for POSIX per-process timer first appeared in FreeBSD 7.0. a true OG.

---

and that's the whole page, bestie 💖 this one came to you from Debian, dated July 15, 2016 — mwah, take care of her 🎀✨