io_uring_prep_poll_add(3)

💖 io_uring_prep_poll_add — prepare a poll request 💖

okay bestie, come sit with me, we're doing liburing today and honestly? this one is so fun. it's from the liburing manual, and it's giving "let me watch this file descriptor for you, no biggie" energy. ✨

✨ SYNOPSIS ✨

#include <poll.h>
#include <liburing.h>

void io_uring_prep_poll_add(struct io_uring_sqe *sqe,
                            int fd,
                            unsigned poll_mask);

void io_uring_prep_poll_multishot(struct io_uring_sqe *sqe,
                                  int fd,
                                  unsigned poll_mask);

like, two little functions, same shape, very demure, very mindful. 🎀

🌸 DESCRIPTION 🌸

so. io_uring_prep_poll_add(3) prepares a poll request, periodt. what it does is it sets up the submission queue entry sqe to poll the file descriptor fd, and the events you're thirsting after get specified in that poll_mask argument. that's it, that's the whole vibe check. 🦋

the default behavior is a single-shot poll request. the way that works: once the event you asked for has triggered, a completion CQE gets posted, and then... nothing. no more events will be generated by that poll request. it did its one job and it clocked out. 💅

io_uring_prep_poll_multishot(3) behaves identically in terms of events, but bestie, it persists across notifications. it will repeatedly post notifications for the same registration. it's the gift that keeps on giving, no cap. 🔥

a CQE posted from a multishot poll request will have IORING_CQE_F_MORE set in the CQE flags member. that flag is basically the kernel telling you "there's more where that came from" — the application should expect more completions from this request. 👑

but listen, this part matters: if the multishot poll request gets terminated or experiences an error, that flag will not be set in the CQE. if that happens, the application should not expect further CQEs from the original request, and it must reissue a new one if it still wishes to get notifications on this file descriptor. no flag = the saga is over, you have to start a fresh request yourself. 😭

⭐ RETURN VALUE ⭐

None. nothing. void. it prepares and it dips. 🙈

💀 ERRORS 💀

the CQE res field will contain the result of the operation, which is a bitmask of the events notified — go check the poll(2) man page for the deets, iykyk.

and here's the glow-up you need to internalize: where synchronous system calls will return -1 on failure and set errno to the actual error value, io_uring never uses errno. instead it returns the negated errno directly in the CQE res field. so like, stop checking errno, she doesn't live here anymore. 🫶

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit(3)
• poll(2)
• epoll_ctl(3)

mwah 💖 that was liburing-2.2, dated March 12, 2022 — and yes she's still iconic. go forth and poll something, bestie. 🧚✨