iopause(3)

💅 iopause(3) — Library Functions Manual 💅

okay so bestie, this is iopause(3) from the Library Functions Manual, and we're gonna get you comfy with it. it's giving “wait for your file descriptors to be ready” energy, and honestly? iconic. ✨

---

✨ NAME ✨

iopause — and that's literally the whole description line, bestie: just iopause -. The original leaves the dash dangling, so we are not inventing a summary. periodt. 💅

---

🌸 SYNTAX 🌸

#include <libowfat/iopause.h>

int iopause(iopause_fd** x,unsigned int len,
            struct taia deadline,struct taia stamp);

copy it character for character, bestie — we do not freestyle signatures around here 🫶

---

🦋 DESCRIPTION 🦋

So iopause checks for file descriptor readability or writability as specified by x[0].fd, x[0].events, x[1].fd, x[1].events, ..., x[len-1].fd, x[len-1].events. yes, the whole lineup. 💖

Here's the vibe check:

• If x[i].events includes the bit IOPAUSE_READ, iopause checks for readability of the descriptor x[i].fd.
• If x[i].events includes the bit IOPAUSE_WRITE, iopause checks for writability of the descriptor x[i].fd.
• Other bits in x[i].events have undefined effects — do not mess with them and expect a cute result 💀

iopause sets the IOPAUSE_READ bit in x[i].revents if it finds that x[i].fd is readable, and it sets the IOPAUSE_WRITE bit in x[i].revents if it finds that x[i].fd is writable.

⚠️ Beware, bestie: readability and writability may be destroyed at any moment by other processes with access to the same ofile that x[i].fd refers to. so like… it was readable a second ago, and then the world moved on. no cap. 😭

If there is no readability or writability to report, iopause waits until deadline for something to happen. iopause will return before deadline if a descriptor becomes readable or writable, or an interrupting signal arrives, or some system-defined amount of time passes. and it sets revents in any case. always. 💅

🚨 You must put a current timestamp into stamp before calling iopause. not optional, not a suggestion, not a “later” thing — do it before the call, bestie. 🫶

---

👑 IMPLEMENTATION NOTES 👑

The current implementation of iopause uses the poll function if that is available. On some systems, poll needs to dynamically allocate kernel memory; when not much memory is available, iopause will return immediately, and will report (often incorrectly) that no descriptors are readable or writable. This is a kernel bug, and the author is literally encouraging vendors to fix it — periodt. 🔥

If poll is not available, iopause uses the select function. This function cannot see descriptor numbers past a system-defined limit, typically 256 or 1024; iopause will artificially pretend that those descriptors are never readable or writable. so yeah, those high-numbered fds are getting ghosted 🙈

Future implementations of iopause may work around these problems on some systems, at the expense of chewing up all available CPU time. like, all of it. CPU said “please no” 💀

Both poll and select use relative timeouts rather than absolute deadlines. Some kernels round the timeout down to a multiple of 10 milliseconds; this can burn quite a bit of CPU time as the deadline approaches. iopause compensates for this by adding 20 milliseconds to the timeout. little timing cushion, little slay ⭐

---

🌈 SEE ALSO 🌈

• select(2)
• poll(3)
• taia_now(3)

---

okay that's the whole page, bestie! footer vibes: iopause(3) and the Library Functions Manual — no date or version is printed in this copy, so we're not making one up. mwah 💋🫶