SIGWAIT(2)

✨ SIGWAIT — okay so we're picking signals bestie ✨

Manual page for SIGWAIT, hanging out in the System Calls Manual, section 2. Yes queen, we're in the syscall section, this is libc-adjacent realness 💅

---

📚 LIBRARY

Standard C Library — aka libc, and you link it with -lc. That's the whole vibe.

---

🌸 SYNOPSIS

#include <signal.h>

int
sigwait(const sigset_t * restrict set, int * restrict sig);

Two pointers, both restrict, both iconic. One in, one out. Slay.

---

💖 DESCRIPTION

okay so here's the tea 🫖 — sigwait() is a system call that selects a set of signals, and you tell it which ones with set. Got it? Good.

So like, if none of the signals you picked are pending, sigwait() just waits — it sits there, patiently, main character energy, until one or more of those selected signals actually gets generated. Then, and this is the cute part, it atomically clears one of the selected signals from the set of pending signals — and that's either for the process or for the current thread, depending — and it sets the location that sig points to, to the signal number that got cleared. ✨

Important bestie!! The signals you specify in set should be blocked at the time you call sigwait(). Like, block them first. Don't skip this. 🙈

Now, the multi-thread situation, because of course there is one:

• If more than one thread is using sigwait() to wait for the same signal, no more than one of those threads will return from sigwait() with the signal number. Only one. Not a group thing.
• If more than a single thread is blocked in sigwait() for a signal when that signal is generated for the process, it is unspecified which of the waiting threads returns from sigwait(). Like, nobody knows. Chaos. It's giving mystery box.
• If the signal is generated for a specific thread, as by pthread_kill(), then only that thread will return. Periodt. 🎀

And about multiple pending signals in the range SIGRTMIN to SIGRTMAX — if any of those get selected, it's gonna be the lowest numbered one. That's the rule.

But the selection order between realtime and non-realtime signals, or between multiple pending non-realtime signals? Unspecified. No promises. Don't @ me. 💀

---

🛠️ IMPLEMENTATION NOTES

So sigwait() is actually implemented as a wrapper around the __sys_sigwait() system call — and that wrapper? It retries the call on EINTR error. So if it gets interrupted, it just goes again. Persistent. Iconic. 🦋

---

🎀 RETURN VALUES

• If it's successful, sigwait() returns 0 and sets the location pointed to by sig to the cleared signal number. Clean. Gorgeous. 💖
• Otherwise, an error number is returned. Not -1 shenanigans, an actual error number, bestie. Note it.

---

⚠️ ERRORS

The sigwait() system call will fail if:

• [EINVAL] — The set argument specifies one or more invalid signal numbers. Like, you put something in there that isn't a real signal. Rude. Fix your set. 🚫

---

👀 SEE ALSO

• sigaction(2)
• sigpending(2)
• sigqueue(2)
• sigsuspend(2)
• sigtimedwait(2)
• sigwaitinfo(2)
• pause(3)
• pthread_sigmask(3)

Go read those too, they're all in the same friend group. 🫶

---

⭐ STANDARDS

The sigwait() function conforms to ISO/IEC 9945-1:1996 (“POSIX.1”). Certified. Validated. A legend. 👑

---

okay bye bestie, go block your signals before you call this, I'm literally begging you 😭💜

This page came to you from Debian, dated September 6, 2013 — and yes it's still serving SIGWAIT(2), section 2, exactly where you left it. Stay hydrated, read your manpages, mwah 💅🌸