futex_wait(9)

📦 version 7.3.1, in nixpkgs unstable

👑 futex_wait(9) — aka the Kernel API Manual era 💅

okay so bestie, buckle up, because we're reading a futex_wait(9) manpage together and honestly? it's giving mystery novel energy. this is a kernel API manual page, and it's about to tell you how to block on uaddr with optional timeout. that's the whole vibe. that's the NAME section. periodt. ✨

🌸 SYNOPSIS 🌸

here's the signature, copied exactly, no cap, don't @ me:

int futex_wait (futex_t *uaddr , futex_t val , struct timespec *timeout
, int opflags );

it returns an int, it takes four args, and yes the line break is exactly where the original put it. we respect the formatting in this house 🫶

🎀 ARGUMENTS 🎀

okay so this is where it gets kind of iconic in a chaotic way, because this manpage is not forthcoming with the details. lowkey it's gatekeeping. here's the full tea, nothing added, nothing removed:

  • uaddr — -- undescribed -- 😭 the manpage literally does not describe it. that's it. that's the entry. bestie we are on our own here.
  • val — -- undescribed -- 🙈 yeah. also undescribed. the documentation said "no thoughts, head empty" and honestly? relatable.
  • timeout — relative timeout ⏰ this is the one (1) argument with an actual description, and it's a struct timespec * that's a relative timeout. not absolute. relative. write that down 💖 this is the main character of the ARGUMENTS section, fr fr.
  • opflags — -- undescribed -- 💀 third time's the charm and the charm is "undescribed". we love a consistent bit.
ngl the ARGUMENTS section is doing the absolute least, but that's what the page says and I'm not about to invent lore. if you want the real deets on what uaddr, val, and opflags do, the SEE ALSO section is your bestie 🔥

🦋 SEE ALSO 🦋

okay so this is the part where the manpage flexes its entire friend group. first up, there's a kernel file reference:

  • ./tools/testing/selftests/futex/include/futextest.h — that's the header file path, exactly as written, and if you're poking around the futex selftests it's right there 🎀

and then the whole futex cinematic universe, in order, because I would never rearrange your faves:

like, look at that roster. futex_wake and futex_wait are literally siblings, futex_wait_bitset is the cooler cousin, and the _pi crew (priority inheritance, iykyk) showed up in full force. the requeue girlies are all here too. it's a whole reunion 🌈💜

💀 real talk though: if you're actually calling this thing in a test, remember the manpage itself didn't describe three of the four arguments, so go read futextest.h and the sibling pages above rather than guessing. we stan reading the source. no invented behaviour on my watch, bestie ✨

and that's the page!! this absolute gem of a document lives in ./tools/testing/selftests/fute... (yes that's the truncated source line, they really just trailed off with an ellipsis, iconic honestly 😭), dated October 2026. slay, see you in the next manpage 🎀💖🦋

📦 where this page comes from