futex_wait_setup(9)

📦 version 7.3.1, in nixpkgs unstable

💖 futex_wait_setup(9) 💖

okay so bestie, welcome to the Kernel API Manual page for futex_wait_setup(9) — yes that's the literal title, we're doing this, and honestly it's lowkey iconic that you're even here. grab a snack 🍓

✨ NAME ✨

futex_wait_setup — the "get ready to wait on a futex" pre-game ritual 🎀

🌸 SYNOPSIS 🌸

int futex_wait_setup (u32 __user *uaddr , u32 val , unsigned int flags ,
struct futex_q *q , union futex_key *key2 , struct task_struct *task );

ngl, look at all those parameters. main character energy fr fr 👑

🦋 ARGUMENTS 🦋

  • uaddr — the futex userspace address. like, where the actual futex lives in userspace 💅
  • val — the expected value. the vibe we're checking against ✨
  • flags — futex flags (FLAGS_SHARED, etc.). FLAGS_SHARED is literally called out by name in the original, so yes it gets a shoutout 🫶
  • q — the associated futex_q. its designated buddy 😭
  • key2 — the second futex_key, used if this is for requeue PI. only relevant in that case, iykyk 🔥
  • task — the task that's queueing up this futex. the one doing the queueing 👑

💜 DESCRIPTION 💜

kay so here's the whole thing: it sets up the futex_q and locates the hash_bucket. then it gets the futex value and compares it against the expected value. atomic faults? handled internally, no cap, we don't make it your problem 🙈

and the big one — return with the hb lock held on success, and unlocked on failure. that's the contract, bestie, do not forget it 💀

⭐ RETURN ⭐

  • 0 — uaddr contains val and the hb has been locked 🎉 slay
  • <0 — on error, and the hb is unlocked. a possible reason: the uaddr can not be read, does not contain the expected value, or is not properly aligned. three whole ways to fail, iconic of it honestly 😭

🌈 SEE ALSO 🌈

go read the kernel file ./kernel/futex/waitwake.c and then these besties:

ok tiny warning moment: on that 0 return you are holding the hb lock, so please please please remember to do something about it. and <0 means it's already unlocked — don't go unlocking a lock you don't hold, that's not the vibe 💅

and that's the page!! from ./kernel/futex, dated October 2026, in the Kernel API Manual 💖 bye bestie, go wait on that futex responsibly 🧚🌸

📦 where this page comes from