io_uring_wait_cqes(3)

💖 io_uring_wait_cqes — bestie edition 💖

okay so this is a page from the liburing manual, and it's all about io_uring_wait_cqes(3). yes the name is a mouthful, we love her anyway 🫶

---

✨ NAME ✨

io_uring_wait_cqes — literally just hanging out until one or more io_uring completion events show up 💅

---

🌸 SYNOPSIS 🌸

#include <liburing.h>

int io_uring_wait_cqes(struct io_uring *ring,
                       struct io_uring_cqe **cqe_ptr,
                       unsigned wait_nr,
                       struct __kernel_timespec *ts,
                       sigset_t *sigmask);

---

🦋 DESCRIPTION 🦋

so io_uring_wait_cqes(3) grabs you wait_nr IO completions from the queue that belongs to the ring param. and if they're not there yet? she waits for them. or she waits until the timeout ts expires, whichever comes first. no cap 🎀

the sigmask tells her which signals to block. if you set it, it's equivalent to atomically running these calls:

sigset_t origmask;

pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ret = io_uring_wait_cqes(ring, cqe, wait_nr, ts, NULL);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);

the cqe_ptr param gets filled in on success with the first CQE. and bestie, if you're calling this, you should use io_uring_for_each_cqe(3) to iterate through all the available CQEs, not just the first one. okay? okay 💜

now, if ts is specified and you're on an older kernel without IORING_FEAT_EXT_ARG, your app does not need to call io_uring_submit(3) before calling io_uring_wait_cqes(3). cute. but for newer kernels with that feature flag set, there is no implied submit when waiting for a request. so don't be out here assuming, bestie, check your kernel 😭

and if ts is NULL, then this just behaves like io_uring_wait_cqe(3) — meaning she will wait forever for an event. forever forever. iconic but also 💀

---

⭐ RETURN VALUE ⭐

• on success, io_uring_wait_cqes(3) returns 0, and the cqe_ptr param gets filled in. slay 💅
• on failure, it returns -errno. classic.
• and if a timeout occurs, it returns -ETIME. so if you see that one, that's the clock, not a bug 🕐

---

🌈 SEE ALSO 🌈

• io_uring_submit(3)
• io_uring_for_each_cqe(3)
• io_uring_wait_cqe_timeout(3)
• io_uring_wait_cqe(3)

---

and that's the whole page, bestie. this was liburing-2.1, dated November 15, 2021 — so go forth, wait on your completions, and remember: ts is NULL means forever, and forever is a long time 🦋💖✨