sys_futex_waitv(9)

💖 sys_futex_waitv — wait on a whole LIST of futexes, bestie

okay so this one is from the Kernel API Manual (section 9, kernel-space girlies rise 🙌) and honestly? it's giving "wait on multiple things at once and see which one pops off first." iconic behaviour fr fr.

---

✨ NAME ✨

sys_futex_waitv — wait on a list of futexes. not one. a list. we multitask in this house 💅

---

🌸 SYNOPSIS 🌸

long sys_futex_waitv (struct futex_waitv __user * waiters , unsigned int
nr_futexes , unsigned int flags , struct __kernel_timespec __user *
timeout , clockid_t clockid );

like, five whole arguments. she's high maintenance but she delivers 🫶

---

🎀 ARGUMENTS 🎀

• waiters — the list of futexes we're waiting on. the whole squad 💖
• nr_futexes — length of futexv. i.e. how many futexes are actually in that list, no cap.
• flags — flag for the timeout (monotonic / realtime). that's literally its whole job.
• timeout — optional absolute timeout. optional!! so if you don't feel like timing out, don't ✨
• clockid — the clock used for the timeout: realtime or monotonic. pick your fighter ⏰

---

🦋 DESCRIPTION 🦋

So you hand it an array of struct futex_waitv, right? And it waits on each uaddr. Every single one. Obsessed with the commitment.

The thread wakes up if a futex_wake is performed at any uaddr. Any of them! first one to wake her up wins the vibe check 🔥

Also super important: the syscall returns immediately if any waiter has *uaddr != val. like it's not even gonna try. she said "nope, mismatch, bye" 💀

*timeout is an optional timeout value for the operation — optional, so no pressure bestie.

Each waiter has its own individual flags. Yes, individually. And the flags argument for the syscall itself should be used solely for specifying the timeout as realtime, if needed. that's it. that's the whole assignment. Flags for private futexes, sizes, etc.? Those go on the individual flags of each waiter. don't mix them up, i'm begging 🙈

So what does it return? It returns the array index of one of the woken futexes. One of them. That's all you get, no further information is provided — and this is the messy part, so sit with me:

• any number of other futexes may also have been woken by the same event 😭
• if more than one futex was woken, the retrned index may refer to any one of them
• (it is not necessaryily the futex with the smallest index, nor the one most recently woken, nor…)

yes, "retrned" and "necessaryily" are literally how it's spelled in the source. she's keeping it real, we don't edit the queen 👑💀

so like… don't build your whole personality on that index meaning something specific. it's a hint, not a promise. periodt.

---

🌈 SEE ALSO 🌈

• Kernel file ./kernel/futex/syscalls.c — the mothership, go read it
• sys_set_robust_list(9)
• sys_get_robust_list(9)
• futex_parse_waitv(9)

---

💜 cute sign-off 💜

this lil masterpiece lives in ./kernel/futex, stamped October 2026 in the Kernel API Manual — go off, futex girlies, ily, drink some water and remember to check your uaddr != val before you wait 💖✨🎀🦋