FUTEX_WAIT_BITSET(2const)

💖 FUTEX_WAIT_BITSET — selective futex waiting and waking 💖

okay bestie, listen up. this is the FUTEX_WAIT_BITSET(2const) page, aka the futex glow-up where you get to be selective about who you wake up. no more shouting into the void, we're doing targeted DMs now. ✨

---

🌸 NAME 🌸

FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET — selective futex waiting and waking

like, waiting and waking, but with ✨taste✨. you pick exactly who gets the notification.

🎀 LIBRARY 🎀

Standard C library (libc, -lc)

the classic. she's been here forever and she ate. 💅

💫 SYNOPSIS 💫

#include <linux/futex.h>  /* Definition of FUTEX_* constants */
#include <sys/syscall.h>  /* Definition of SYS_* constants */
#include <unistd.h>

long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAIT_BITSET, uint32_t val,
             const struct timespec *timeout, NULL,
             uint32_t val3);

long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAKE_BITSET, uint32_t val,
             NULL, NULL,
             uint32_t val3);

not me flexing two syscall signatures like it's nothing 😭 the NULL in position five is doing NOTHING and living its best life fr.

---

🦋 DESCRIPTION 🦋

💜 FUTEX_WAIT_BITSET

okay so this one is literally FUTEX_WAIT(2const) but with a lil extra something — val3 is a 32-bit bit mask that gets handed to the kernel. and here's the rule that will humble you: at least one bit must be set. not zero. never zero. (we'll get to that in ERRORS, and it is not a vibe.) 🫶

that bit mask gets stored in the kernel-internal state of the waiter. and then? see the FUTEX_WAKE_BITSET description below for the whole tea.

if timeout is not NULL, the structure it points to specifies an absolute timeout for the wait operation. if timeout is NULL, the operation can block indefinitely. so like, forever, bestie. no alarm set. 🙈

💜 FUTEX_WAKE_BITSET

this one is the same as FUTEX_WAKE(2const) except that the val3 argument provides a 32-bit bit mask to the kernel. again: at least one bit must be set. the mask is used to select which waiters should be woken up.

and the selection process? it's a bitwise AND of:

• the "wake" bit mask (that's the value in val3)
• the bit mask stored in the kernel-internal state of the waiter (the "wait" bit mask, set using FUTEX_WAIT_BITSET)

all the waiters where the AND result is nonzero get woken up. the remaining waiters are left sleeping. periodt. 😴

the effect of FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET is to allow selective wake-ups among multiple waiters that are blocked on the same futex. cute right? BUT — and this is the part where I need you to sit down — depending on the use case, using this bit-mask multiplexing feature on a futex can be less efficient than simply using multiple futexes. why? because bit-mask multiplexing requires the kernel to check all waiters on a futex, including the ones who are not interested in being woken up (i.e., they don't have the relevant bit set in their "wait" bit mask). 💀 like scrolling through the entire group chat for a message that wasn't even for you.

the constant FUTEX_BITSET_MATCH_ANY, which corresponds to all 32 bits set in the bit mask, can be used as the val3 argument for FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET. and other than the differences in how the timeout argument is handled, the FUTEX_WAIT(2const) operation is equivalent to FUTEX_WAIT_BITSET with val3 specified as FUTEX_BITSET_MATCH_ANY — that is, allow a wake-up by any waker. similarly, FUTEX_WAKE(2const) is equivalent to FUTEX_WAKE_BITSET with val3 specified as FUTEX_BITSET_MATCH_ANY — that is, wake up any waiter(s). no exclusivity, everybody's invited. 👑

---

🔥 RETURN VALUE 🔥

on error, -1 is returned, and errno is set to indicate the error. classic.

the return value on success depends on the operation, as described in the following list:

• FUTEX_WAIT_BITSET — returns 0 if the caller was woken up. see FUTEX_WAIT(2const) for how to interpret this correctly in practice (yes, really, go read it, don't just trust the zero 👀).
• FUTEX_WAKE_BITSET — returns the number of waiters that were woken up.

---

💀 ERRORS 💀

also see futex(2).

• EAGAIN or EWOULDBLOCK — (FUTEX_WAIT_BITSET) the value pointed to by uaddr was not equal to the expected value val at the time of the call.
• EFAULT — timeout did not point to a valid user-space address.
• EINTR — a FUTEX_WAIT_BITSET operation was interrupted by a signal (see signal(7)). before Linux 2.6.22, this error could also be returned for a spurious wakeup; since Linux 2.6.22, this no longer happens. glow-up confirmed. ✨
• EINVAL — the supplied timeout argument was invalid (tv_sec was less than zero, or tv_nsec was not less than 1,000,000,000).
• EINVAL — uaddr2 does not point to a valid object—that is, the address is not four-byte-aligned.
• EINVAL — the bit mask supplied in val3 is zero. (told you bestie. at least. one. bit. 😤)
• EINVAL — (FUTEX_WAKE_BITSET) the kernel detected an inconsistency between the user-space state at uaddr and the kernel state—that is, it detected a waiter which waits in FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) on uaddr.
• ETIMEDOUT — the timeout expired before the operation completed.

yes there are four separate EINVAL entries. no that is not a typo. the kernel has range. 🌈

---

⭐ STANDARDS ⭐

Linux. that's it, that's the whole standard. 💅

🎀 HISTORY 🎀

Linux 2.6.25. vintage but make it iconic.

👑 SEE ALSO 👑

futex(2)

---

and that's the whole page, bestie!! this one's from Linux man-pages 6.20, dated 2026-02-10, and it's the FUTEX_WAIT_BITSET(2const) page — go set some bits and wake exactly the right people, love you, bye 🫶💖