FUTEX_WAKE_OP(2const)

✨ FUTEX_WAKE_OP — fast user-space locking ✨

okay bestie, buckle up, we're doing futexes today and honestly?? this one is a bop. it lives in section 2const of the manual (yes, FUTEX_WAKE_OP(2const), that's the whole title, she's a constant-flavored girlie 💅).

---

📚 LIBRARY

Standard C library (libc, -lc) 🫶

---

🪄 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_WAKE_OP, uint32_t val,
             uint32_t val2, uint32_t *uaddr2,
             uint32_t val3);

---

💖 DESCRIPTION

so this op got added to the kernel to support some user-space situations where you've gotta juggle more than one futex at the same time. the most iconic example? the implementation of pthread_cond_signal(3), which needs to touch two futexes at once — the one doing the mutex thing and the one chilling in the wait queue tied to the condition variable. FUTEX_WAKE_OP lets those cases happen without setting off massive rates of contention and context switching. slay.

<tada>the vibe:</tada> FUTEX_WAKE_OP is equivalent to running the code below atomically and totally ordered with respect to other futex operations on either of the two futex words you handed over:

uint32_t oldval = *(uint32_t *) uaddr2;
*(uint32_t *) uaddr2 = oldval op oparg;
futex(uaddr, FUTEX_WAKE, val, 0, 0, 0);
if (oldval cmp cmparg)
    futex(uaddr2, FUTEX_WAKE, val2, 0, 0, 0);

put another way, FUTEX_WAKE_OP does this whole routine:

• saves the original value of the futex word at uaddr2 and performs an operation that modifies the value of the futex at uaddr2 — and this is an atomic read-modify-write memory access (i.e., it uses the atomic machine instructions of whatever architecture you're on, no shortcuts 😤)
• wakes up a maximum of val waiters on the futex for the futex word at uaddr; and
• depending on how a test of the original value of the futex word at uaddr2 goes, wakes up a maximum of val2 waiters on the futex for the futex word at uaddr2.

the operation and the comparison you want performed are both encoded in the bits of the val3 argument. picture it bestie:

+---+---+-----------+-----------+
|op |cmp|   oparg   |  cmparg   |
+---+---+-----------+-----------+
  4   4       12          12    <== # of bits

and in code form, the encoding is literally:

#define FUTEX_OP(op, oparg, cmp, cmparg) \
                (((op & 0xf) << 28) | \
                ((cmp & 0xf) << 24) | \
                ((oparg & 0xfff) << 12) | \
                (cmparg & 0xfff))

in the above, op and cmp are each one of the codes listed below 👇 the oparg and cmparg components are literal numeric values, except as noted below.

🌸 the op component

• FUTEX_OP_SET — 0 — /* uaddr2 = oparg; */
• FUTEX_OP_ADD — 1 — /* uaddr2 += oparg; */
• FUTEX_OP_OR — 2 — /* uaddr2 |= oparg; */
• FUTEX_OP_ANDN — 3 — /* uaddr2 &= ~oparg; */
• FUTEX_OP_XOR — 4 — /* uaddr2 ^= oparg; */

plus!! bitwise ORing the following value into op makes (1 << oparg) be used as the operand instead:

• FUTEX_OP_ARG_SHIFT — 8 — /* Use (1 << oparg) as operand */

🦋 the cmp field

• FUTEX_OP_CMP_EQ — 0 — /* if (oldval == cmparg) wake */
• FUTEX_OP_CMP_NE — 1 — /* if (oldval != cmparg) wake */
• FUTEX_OP_CMP_LT — 2 — /* if (oldval < cmparg) wake */
• FUTEX_OP_CMP_LE — 3 — /* if (oldval <= cmparg) wake */
• FUTEX_OP_CMP_GT — 4 — /* if (oldval > cmparg) wake */
• FUTEX_OP_CMP_GE — 5 — /* if (oldval >= cmparg) wake */

oh and, the return value of FUTEX_WAKE_OP is the sum of the number of waiters woken on the futex uaddr plus the number of waiters woken on the futex uaddr2. two futexes, one return value, it's giving efficiency 💖

---

🎀 RETURN VALUE

on error, -1 gets returned, and errno is set to tell you what went wrong 😭

on success, FUTEX_WAKE_OP returns the total number of waiters that were woken up. that's the sum of the woken waiters on the two futexes for the futex words at uaddr and uaddr2. periodt.

---

💀 ERRORS

see futex(2).

• EFAULT — uaddr2 did not point to a valid user-space address.
• EINVAL — uaddr2 does not point to a valid object — meaning the address is not four-byte-aligned.
• EINVAL — 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.

🫠 heads up bestie: both of those last two are EINVAL, so don't go assuming you can tell them apart by the error name alone. iykyk.

---

⭐ STANDARDS

Linux. 🐧

---

🧚 HISTORY

Linux 2.6.14. (ancient in timeline terms, still iconic in behavior terms ✨)

---

👑 SEE ALSO

• futex(2)

---

and that's the whole page, bestie!! 🫶 this was Linux man-pages 6.20, dated 2025-09-21 — go forth and futex responsibly, mwah 💅💖🌸