POLL(2)

💅 POLL — synchronous I/O multiplexing ✨

okay bestie, sit DOWN, because this is the page where your program learns to watch a whole squad of file descriptors at once instead of standing there staring at one like a loser. it's poll, it's in section 2 of the manual, and it is literally the group chat of system calls. 🫶

---

📚 LIBRARY

Standard C Library (libc, -lc) — yeah she lives in libc, obviously. 💖

---

✨ SYNOPSIS ✨

#include <poll.h>

int
poll(struct pollfd fds[], nfds_t nfds, int timeout);

int
ppoll(struct pollfd fds[], nfds_t nfds,
    const struct timespec * restrict timeout,
    const sigset_t * restrict newsigmask);

---

🦋 DESCRIPTION 🦋

so the poll() system call 👑 looks at a whole set of file descriptors to see if some of them are ready for I/O. like, she's doing a vibe check on your entire roster at once, no cap.

the fds argument is a pointer to an array of pollfd structures, as defined in <poll.h> (shown below, bestie). the nfds argument tells her how big the fds array is.

struct pollfd {
    int    fd;       /* file descriptor */
    short  events;   /* events to look for */
    short  revents;  /* events returned */
};

and the fields of struct pollfd are, one by one:

• fd — the file descriptor you're polling. and here's the tea 🍓: if fd equals -1, then revents gets cleared (set to zero) and that pollfd is not checked at all. she's ghosted, fr fr.
• events — the events you're polling for. (see below 👇)
• revents — the events that may actually occur. (see below 👇)

the event bitmasks in events and revents have these bits, and yes we're listing every single one because nobody gets left out in this house 💜:

• POLLIN — data other than high priority data may be read without blocking. 📖
• POLLRDNORM — normal data may be read without blocking.
• POLLRDBAND — data with a non-zero priority may be read without blocking.
• POLLPRI — high priority data may be read without blocking. 🚨
• POLLOUT — the original page gives this one no description, bestie. she's just standing there. iconic mystery behaviour, iykyk. 💀
• POLLWRNORM — normal data may be written without blocking. ✍️
• POLLWRBAND — data with a non-zero priority may be written without blocking.
• POLLERR — an exceptional condition has occurred on the device or socket. this flag is always checked, even if it's not present in the events bitmask. so she shows up uninvited, every time. 🙈
• POLLHUP — the device or socket has been disconnected. this flag is always checked, even if it's not present in the events bitmask. and note: POLLHUP and POLLOUT should never be present in the revents bitmask at the same time. not them being mutually exclusive, main character energy. 😭
• POLLNVAL — the file descriptor is not open, or in capability mode the file descriptor has insufficient rights. this flag is always checked, even if it's not present in the events bitmask.

okay now the timeout part, this is important so read it twice 🔥:

if timeout is neither zero nor INFTIM (-1), it specifies a maximum interval to wait for any file descriptor to become ready, in milliseconds. if timeout is INFTIM (-1), the poll blocks indefinitely — she will wait for you forever, periodt. if timeout is zero, then poll() will return without blocking, she's got places to be. 💅

---

🌸 the ppoll() glow-up

the ppoll() system call, unlike poll(), is used to safely wait until either a set of file descriptors becomes ready or until a signal is caught. the fds and nfds arguments are identical to the analogous arguments of poll().

the timeout argument in ppoll() points to a const struct timespec which is defined in <sys/timespec.h> (shown below) rather than the int timeout used by poll(). a null pointer may be passed to indicate that ppoll() should wait indefinitely. and finally, newsigmask specifies a signal mask which is set while waiting for input. when ppoll() returns, the original signal mask is restored. she puts it back exactly how she found it, queen behaviour. 👑

struct timespec {
        time_t  tv_sec;         /* seconds */
        long    tv_nsec;        /* and nanoseconds */
};

---

🔢 RETURN VALUES 🔢

the poll() system call returns the number of descriptors that are ready for I/O, or -1 if an error occurred. if the time limit expires, poll() returns 0.

and if poll() returns with an error — including one due to an interrupted system call — the fds array will be unmodified. she doesn't leave a mess behind, that's the difference. ✨

---

🌈 COMPATIBILITY 🌈

this implementation differs from the historical one in that a given file descriptor may not cause poll() to return with an error. in cases where this would have happened in the historical implementation (e.g. trying to poll a revoke(2)ed descriptor), this implementation instead copies the events bitmask to the revents bitmask. attempting to perform I/O on this descriptor will then return an error. this behaviour is believed to be more useful. 🫶

---

💀 ERRORS 💀

an error return from poll() indicates:

• [EFAULT] — the fds argument points outside the process's allocated address space. she went looking and there was nothing there. 😭
• [EINTR] — a signal was delivered before the time limit expired and before any of the selected events occurred.
• [EINVAL] — the specified time limit is invalid. one of its components is negative or too large.

---

👀 SEE ALSO 👀

accept(2), connect(2), kqueue(2), pselect(2), read(2), recv(2), select(2), send(2), write(2)

go read those too, bestie, they're all in the same friend group. 🎀

---

⭐ STANDARDS ⭐

the poll() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). the ppoll() is not specified by POSIX. she's built different, off-script, no rules. 💅

---

📜 HISTORY 📜

the poll() function appeared in AT&T System V UNIX. this manual page and the core of the implementation was taken from NetBSD. the ppoll() function first appeared in FreeBSD 11.0.

---

🐛 BUGS 🐛

the distinction between some of the fields in the events and revents bitmasks is really not useful without STREAMS. the fields are defined for compatibility with existing software. so yeah, some of this is legacy decoration, not that deep, but we keep it anyway because backwards compatibility is a lifestyle. 💖

---

and that's the whole page, bestie!! this one came from the Debian crew and it's dated February 27, 2019 — so if you're reading it in your terminal right now, give a lil thank you to the Debian folks who formatted it, mwah 😘💜 go poll something, you got this, i believe in you fr fr ✨🦋🌸