ualarm(3)

💖 ualarm(3) — the library functions manual, but make it cute

okay bestie, welcome to ualarm(3), a lil function from the Library Functions Manual whose whole job is schedule signal after given number of microseconds. she's giving alarm clock energy but make it micro. 🎀

---

✨ NAME ✨

ualarm — schedule signal after given number of microseconds ⏰

📚 LIBRARY 📚

Standard C library (libc, -lc) 💅

🌸 SYNOPSIS 🌸

#include <unistd.h>

useconds_t ualarm(useconds_t usecs, useconds_t interval);

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

ualarm():
    Since glibc 2.12:
        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
            || /* glibc <= 2.19: */ _BSD_SOURCE
    Before glibc 2.12:
        _BSD_SOURCE || _XOPEN_SOURCE >= 500

ngl the feature test macro section is the group chat you have to be in before you're even allowed to @ her. define the right macros or she's not answering, periodt. 🙈

---

💫 DESCRIPTION 💫

so ualarm() sends the signal SIGALRM to the process that called it, after (and not less than) usecs microseconds. not exactly usecs though bestie — that delay can get lengthened slightly by any system activity, or by the time spent processing the call itself, or by the granularity of system timers. so like, she's punctual but she's also a whole system, you know?

and unless it's caught or ignored, the SIGALRM signal will terminate the process. 💀 like, no warning, no soft launch, just gone.

if the interval argument is nonzero, further SIGALRM signals keep getting sent every interval microseconds after the first one. she's not a one-time thing, she's recurring. 🦋

---

🔥 RETURN VALUE 🔥

she returns the number of microseconds remaining for any alarm that was previously set — or 0 if no alarm was pending. so you can lowkey find out how much snooze time was left on the old one. ⏳

---

💀 ERRORS 💀

• EINTR — interrupted by a signal; see signal(7). she got distracted, rude of whatever signal did that.
• EINVAL — usecs or interval is not smaller than 1000000. (on systems where that is considered an error.) so don't be out here requesting more than a second in a function literally named micro. 💅

---

👑 ATTRIBUTES 👑

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

• ualarm() — Thread safety: MT-Safe ✨

she is MT-Safe, which is the bare minimum we ask for in a friend. 🫶

---

🌈 STANDARDS 🌈

None. literally none. she's unstandardised, she's free, she's an icon. 😌

---

📜 HISTORY 📜

4.3BSD, POSIX.1-2001. and listen — POSIX.1-2001 marks it as obsolete. removed in POSIX.1-2008. so yeah, she's vintage. 🕰️

4.3BSD, SUSv2, and POSIX do not define any errors. the error list above? that's bonus content.

POSIX.1-2001 does not specify what happens if the usecs argument is 0. on Linux (and probably most other systems), the effect is to cancel any pending alarm. so 0 is the "never mind, cancel that" button. 🙈

the type useconds_t is an unsigned integer type capable of holding integers in the range [0,1000000]. on the original BSD implementation, and in glibc before glibc 2.1, the arguments to ualarm() were instead typed as unsigned int. programs will be more portable if they never mention useconds_t explicitly — so like, just don't name-drop her, that's the move.

the interaction of this function with other timer functions such as alarm(2), sleep(3), nanosleep(2), setitimer(2), timer_create(2), timer_delete(2), timer_getoverrun(2), timer_gettime(2), timer_settime(2), usleep(3) is unspecified. ⚠️ unspecified meaning nobody promised you anything, so don't come crying when it goes feral.

🚨 REAL TALK: this function is obsolete. use setitimer(2) or POSIX interval timers (timer_create(2), etc.) instead. like genuinely bestie, she's a legacy pick, ship the newer ones. 💅

---

👀 SEE ALSO 👀

alarm(2), getitimer(2), nanosleep(2), select(2), setitimer(2), usleep(3), time(7)

---

and that's the whole page, no notes. this one's from Linux man-pages 6.20, dated 2026-02-08, and that's your ualarm(3) moment right there. slay, stay timed, and don't use obsolete functions in production, mwah 💖✨🎀