io_wait(3)

💖 io_wait(3) 💖

okay bestie, so this one's from the Library Functions Manual, and it's about the little function that just... sits there and waits for something to happen. iconic behavior honestly.

---

✨ NAME ✨

io_wait — wait for events 🌸

---

✨ SYNTAX ✨

#include <libowfat/io.h>

void io_wait();

---

✨ DESCRIPTION ✨

so io_wait() does the vibe check on all the descriptors your program is interested in, to see whether any of them are ready 👀

and if none of them are ready? it tries to pause until one of them <em>is</em> ready. the way that it's literally just being polite — it doesn't wanna hog CPU time and steal cycles away from all the other programs running on the same computer. considerate queen 🫶

io_wait is also super aware of timeouts: if a descriptor hits its timeout, and your program is interested in reading from or writing to that descriptor, then io_wait will return promptly. no ghosting, no delay, it comes back right on cue ✨

but bestie, real talk: under some circumstances, io_wait will return even though <strong>no interesting descriptors are ready</strong>. so do NOT assume a descriptor is ready merely because io_wait has returned. fr fr. that's a trap. 💀

and here's another thing: io_wait is not interrupted by the delivery of a signal. programs that <em>expect</em> interruption are unreliable — they will block if the same signal is delivered a moment before io_wait. 😭 the correct way to handle signals is with the self-pipe trick. that's the move. iykyk.

---

🎀 NOTE 🎀

depending on the underlying operating system primitive, there's a potential race condition you gotta be aware of, no cap.

some event notification mechanisms — for example, kqueue on BSD and epoll on Linux — will return <strong>multiple events</strong>. so if your application operates on pairs of file descriptors (a proxy server maybe 👑), and an error on one descriptor can lead to closing the other descriptor, then an outstanding event on that other descriptor can <em>still</em> be queued for delivery to you.

🙈 be prepared to receive events for a descriptor that has already been closed. yes, really. it's giving "haunted by the ghost of a fd past."

---

🌈 SEE ALSO 🌈

• io_waituntil(3)
• io_check(3)
• io_wantread(3)
• io_wantwrite(3)
• io_fd(3)

---

okay that's the whole page, periodt 💅 this came out of the Library Functions Manual — that's the source, that's the whole vibe, and there's no date stamp on this one so we're just rolling with the era-less energy. go forth and wait for events responsibly, bestie 💜🦋