ALARM(3)

🌈 NAME 🌈

okay so bestie, welcome to alarm(3) from the Library Functions Manual 💖 — this one is literally about setting a signal timer alarm. No cap, that's the whole vibe: alarm = set signal timer alarm. 🎀

📚 LIBRARY 📚

Standard C Library (libc, -lc) — that's where this lives, periodt. 🫶

✨ SYNOPSIS ✨

#include <unistd.h>

unsigned int
alarm(unsigned int seconds);

💅 DESCRIPTION 💅

⚠️ warning vibes: this interface is made obsolete by setitimer(2).

not me having to say that first 😭 — like, it's still here, but setitimer(2) is the one that made it obsolete. Keep that in mind, fr fr.

The alarm() function sets a timer to deliver the signal SIGALRM to the calling process after the specified number of seconds. ⏰💥

If an alarm has already been set with alarm() but has not been delivered, another call to alarm() will supersede the prior call. So yeah, the new one takes over — the old one doesn't get a second chance. 🙈

The request alarm(0) voids the current alarm and the signal SIGALRM will not be delivered. Zero means cancel, bestie — no signal, no drama. 🚫🔔

Due to setitimer(2) restriction the maximum number of seconds allowed is 100,000,000. That's the ceiling, okay? Don't try to be extra with a bigger number. 💀

🎀 RETURN VALUES 🎀

The return value of alarm() is the amount of time left on the timer from a previous call to alarm(). So it's like, “hey, here's what was left from last time.” 🕰️

If no alarm is currently set, the return value is 0. Lowkey simple. ✨

👀 SEE ALSO 👀

setitimer(2), sigaction(2), sigsuspend(2), signal(3), sleep(3), ualarm(3), usleep(3) — go read these too, bestie, iykyk. 💅

🦋 HISTORY 🦋

An alarm() system call appeared in the Programmer's Workbench (PWB/UNIX) and was ported to Version 7 AT&T UNIX. So it's giving ancient Unix lore. 🏛️

For 4.1cBSD, it was reimplemented as a wrapper around the setitimer(2) system call. And that's the glow-up, no cap. ✨

---

this lil page is from Debian's ALARM(3), dated April 2, 2022 — mwah, hope that helped bestie 💋🫶