io_uring_prep_futex_wake(3)

💖 io_uring_prep_futex_wake — bestie, it's a manual page 💖

okay so this is io_uring_prep_futex_wake(3) from the liburing Manual, and no cap, it's lowkey iconic once it clicks. let's get into it 🫶

---

✨ NAME ✨

io_uring_prep_futex_wake — get a futex wake request ready to go 💅

---

🦋 SYNOPSIS 🦋

#include <linux/futex.h>
#include <unistd.h>
#include <liburing.h>

void io_uring_prep_futex_wake(struct io_uring_sqe *sqe,
                              const uint32_t *futex,
                              uint64_t val,
                              uint64_t mask,
                              uint32_t futex_flags,
                              unsigned int flags);

like look at her. so many little arguments. she's giving main character energy fr fr ✨

---

🌸 DESCRIPTION 🌸

so the io_uring_prep_futex_wake(3) function literally prepares a futex wake request. that's it, that's the job. 🎀

the submission queue entry sqe gets set up for waking any waiters on the futex indicated by futex, and it wakes at most val futexes. like, don't be greedy bestie, val is the cap. 💀

futex_flags is where you drop the futex2(2) modifier flags, and the io_uring futex flags go in flags.

if you want a specific bitset for who gets to wake up — like a lil VIP list — you gotta set that in mask. and if you want literally anyone on the given futex to match, use FUTEX_BITSET_MATCH_ANY. easy. 🌈

flags is currently unused, so you must pass 0. don't get creative, there's nothing to put there. 🙈

this function prepares an async futex(2) wake request, so go peep that man page for the deets. and here's the tea: the io_uring futex wake request is similar to the FUTEX_WAKE_BITSET operation, because FUTEX_WAKE is a strict subset of that. so like... bitset is the whole vibe, wake is just a lil slice of it. 👑

available since kernel 6.7. mark your calendars bestie 🗓️✨

---

💜 RETURN VALUE 💜

None. she returns nothing. void. silent. mysterious. 💅

---

😭 ERRORS 😭

the CQE res field is gonna hold the result of the operation. on success, the value will be the index into futexv which received a wakeup. wild, right? check the related man page for what the possible error values are. 🍓

important bestie, do not skip this: 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 stop looking at errno, she's not coming. 💀✨

---

🧚 SEE ALSO 🧚

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_prep_futex_wait(3)
• io_uring_prep_futex_waitv(3)
• futex(2)
• futex2(2)

---

and that's the whole page, bestie, you ate that 💖

sign-off time: this lil masterpiece is from liburing-2.5, dated Sep 29, 2023, and it lives in the liburing Manual like the queen she is. go forth and wake those futexes responsibly, mwah 🎀👑💜