FUTEX_WAIT_REQUEUE_PI(2const)

👑 FUTEX_WAIT_REQUEUE_PI — the 2const girlie 💅

okay so bestie, welcome to FUTEX_WAIT_REQUEUE_PI(2const) — yes the manual name is literally part of the title, we're fancy like that 💖. This is the futex operation that waits on a totally normal (non-PI) futex and then — plot twist — might get requeued onto a PI futex. It's giving "I was waiting over here but actually I belong over there now." ✨

---

🌸 LIBRARY

Standard C library (libc, -lc) — the classics, no cap.

---

🦋 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_REQUEUE_PI,
             uint32_t val,
             const struct timespec *timeout,
             uint32_t *uaddr2);

---

✨ DESCRIPTION ✨

So here's the vibe: you wait on a non-PI futex at uaddr, and you potentially get requeued onto a PI futex at uaddr2. How does that requeue happen? Via a FUTEX_CMP_REQUEUE_PI(2const) operation running in some other task — so it's not you doing it, it's somebody else moving you, lowkey iconic of them. 🫶

The actual wait operation on uaddr? That part is exactly the same as FUTEX_WAIT(2const). Same energy, same rules.

Now — the waiter can be yanked out of the wait on uaddr without being requeued onto uaddr2, if another task hits it with a FUTEX_WAKE(2const) operation. In that specific case, the FUTEX_WAIT_REQUEUE_PI operation fails with the error EAGAIN. Not a glitch, that's just the deal. 😭

And about timeout:

• 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. main character patience fr fr.

---

💫 RETURN VALUE

On error, -1 is returned, and errno is set to indicate the error. Rude but standard.

On success, FUTEX_WAIT_REQUEUE_PI returns 0 if the caller was successfully requeued to the futex for the futex word at uaddr2. Slay, you made it. 🎀

---

💅 ERRORS 💅

See futex(2). But also, the whole menu:

• EAGAIN or EWOULDBLOCK — The value pointed to by uaddr was not equal to the expected value val at the time of the call. It changed on you, bestie, not your fault. 🙈
• EFAULT — uaddr2 or timeout did not point to a valid user-space address.
• 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. Yes, two separate EINVALs, they're twins, keep up. 💀
• ENOSYS — A run-time check determined that the operation is not available. The PI-futex operations are not implemented on all architectures and are not supported on some CPU variants. So if it's missing on your machine, it's not you, it's the CPU. 🔥
• ETIMEDOUT — The timeout expired before the operation completed. Time ran out, the clock ate, periodt. ⭐

---

🌈 STANDARDS

Linux. That's it, that's the standard. 💜

---

🕰️ HISTORY

Linux 2.6.31 — an elder, but a legendary one. 👑

---

🍓 SEE ALSO

• futex(2)

---

lowkey reminder bestie: timeout is an absolute timeout and it has to be valid, and that uaddr2 alignment thing is four-byte-aligned or nothing. no cap. 💅

mwah 💖 that's the whole page — written by the Linux man-pages crew, version 6.20, dated 2026-02-10. go forth and futex responsibly, queen 🧚✨