explain_poll_or_die(3)

✨ explain_poll_or_die(3) ✨

okay bestie, sit down, hydrate, because we're talking about explain_poll_or_die — a lil library function that hangs out in the Library Functions Manual and is here to wait for events on a file descriptor and then tell you all about it when things go wrong 💅

---

🎀 NAME 🎀

explain_poll_or_die — wait for some event on file descriptor and report errors

no cap, that's literally the whole job description 🫶

---

🌸 SYNOPSIS 🌸

#include <libexplain/poll.h>
int explain_poll_or_die(struct pollfd *fds, int nfds, int timeout);
int explain_poll_on_error(struct pollfd *fds, int nfds, int timeout);

two functions, one header, zero drama (well... some drama, it's in the name) ✨

---

💖 DESCRIPTION 💖

so. explain_poll_or_die is the function you call when you want to call the poll(2) system call. and if that call fails? it prints an explanation straight to stderr — and that explanation comes from the explain_poll(3) function — and then it terminates the process by calling exit(EXIT_FAILURE). yeah. it does not play. it's giving "or die" and it MEANS it 💀

meanwhile explain_poll_on_error is the chill sibling 🌈 — it also calls the poll(2) system call, and on failure it also prints an explanation to stderr (again, from explain_poll(3))... but then it still returns to the caller. no exiting. no quitting. it just comes back and hands you the news 😭

now, the args, and yes they're all passed through exactly as-is:

• fds — the fds, exactly as to be passed to the poll(2) system call. no edits, no glow-up, straight through 🦋
• nfds — the nfds, exactly as to be passed to the poll(2) system call. periodt.
• timeout — the timeout, exactly as to be passed to the poll(2) system call. it's the vibe check timer fr fr ⭐

---

👑 RETURN VALUE 👑

explain_poll_or_die only returns on success — peep poll(2) for more info on that. on failure it prints an explanation and exits, which means... it does not return. like, at all. it's gone. departed. ✈️💀

explain_poll_on_error always returns the value returned by the wrapped poll(2) system call. every time. it always comes home 🫶

---

🧚 EXAMPLE 🧚

this is how the cool kids use explain_poll_or_die:

int result = explain_poll_or_die(fds, nfds, timeout);

one line, one call, main character energy 👑

---

🌈 SEE ALSO 🌈

• poll(2) — wait for some event on a file descriptor
• explain_poll(3) — explain poll(2) errors
• exit(2) — terminate the calling process

---

💜 COPYRIGHT 💜

this whole thing is libexplain version 1.4, and the copyright belongs to Copyright (C) 2010 Peter Miller.

---

and that's the page bestie!! 🎀 iykyk — go forth, poll responsibly, and remember: explain_poll_or_die only returns on success, so if you get a return value, you ATE 💅✨ 🦋🌸💖