io_uring_prep_epoll_wait(3)

💖 io_uring_prep_epoll_wait — bestie edition 💖

okay so this is a page from the liburing manual, io_uring_prep_epoll_wait(3), and honestly? it's giving "letting your legacy event loop finally move on." sit down, grab a boba, we're doing this 🧋✨

✨ NAME ✨

io_uring_prep_epoll_wait — prepare an epoll wait request

🌸 SYNOPSIS 🌸

#include <sys/epoll.h>
#include <liburing.h>

void io_uring_prep_epoll_wait(struct io_uring_sqe *sqe,
                              int fd,
                              struct epoll_event *events,
                              int maxevents,
                              unsigned flags );"

(yeah the original page literally ends that synopsis with a stray " and I am not touching it, that's canon now 💅)

🦋 DESCRIPTION 🦋

So io_uring_prep_epoll_wait(3) prepares an epoll_wait request. Like, it sets up the submission queue entry sqe to wait on a maximum of maxevents events on the epoll file descriptor that fd points at, and it drops the received events into the memory that events points to. cute, clean, done 💖

What you're actually doing here is preparing an async epoll_wait(2) request. go read that man page for the deets, fr fr.

and like, why would you even want this? 👀 the use case is mostly for legacy event loops, where some file descriptors might still be living their epoll lives for readiness notifications. normally you'd have to call epoll_wait and also add the io_uring fd into that same epoll set — which is, ngl, suboptimal, because epoll doesn't give you the same fine grained batch control and wakeup reductions that io_uring does. 🙈

but by using io_uring to read epoll events? the event loop can switch over to io_uring entirely, and then it reaps the benefits of batch waiting and context switch reductions. glow up complete, main character energy, periodt 👑

🌈 RETURN VALUE 🌈

None. that's it, that's the whole vibe. nothing comes back from this function directly 🫶

💀 ERRORS 💀

the result of the operation lives in the CQE res field. check the related man page for what possible values look like.

⚠️ and listen, this part is important: synchronous system calls return -1 on failure and set errno to the actual error value, but io_uring never uses errno. instead it returns the negated errno directly in the CQE res field. so stop checking errno, bestie, it's not gonna be there 😭

🎀 SEE ALSO 🎀

• io_uring_get_sqe(3)
• io_uring_submit(3)
• epoll_wait(2)

okay that's the whole page!! 💜 this was liburing-2.10, dated March 6, 2025 — go forth and make your event loop iconic, you got this ⭐🦋💅