FUTEX_UNLOCK_PI(2const)

💅 FUTEX_UNLOCK_PI — the 2const girlie from the Linux man-pages fam

okay so bestie, welcome to FUTEX_UNLOCK_PI(2const) — yes the manual section is literally 2const, that's not a typo, that's her whole identity 💖

---

✨ NAME ✨

FUTEX_UNLOCK_PI — unlock a priority-inheritance futex 🫶

---

📚 LIBRARY 📚

Standard C library (libc, -lc) — the classic, 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_UNLOCK_PI);

like… you don't call this directly bestie, you go through the syscall wrapper. that's the vibe. 🌸

---

🦋 DESCRIPTION 🦋

So what does she do? She wakes the top priority waiter that is waiting in FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) on the futex address you handed her in the uaddr argument. That's it. That's the whole job. Iconic behavior honestly. 👑

You call this when the user-space value at uaddr cannot be changed atomically from a TID (of the owner) to 0. Like, the atomic swap just isn't working out, so the kernel has to step in and handle it. Periodt. 💅

---

⭐ RETURN VALUE ⭐

• On error, -1 is returned, and errno is set to indicate the error. 😭
• On success, FUTEX_UNLOCK_PI returns 0 if the futex was successfully unlocked. ✨

---

💀 ERRORS 💀

See futex(2) for the full lore. But here's the drama that's specific to us:

• EINVAL — the kernel detected an inconsistency between the user-space state at uaddr and the kernel state. this is giving either state corruption, or the kernel found a waiter on uaddr which is waiting via FUTEX_WAIT(2const) or FUTEX_WAIT_BITSET(2const). messy. 🙈
• 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 like, don't count on her showing up everywhere. 💔
• EPERM — the caller does not own the lock represented by the futex word. bestie you can't unlock what isn't yours, that's not how any of this works. 🔥

---

🌈 STANDARDS 🌈

Linux. that's the standard. that's the answer. 🐧

---

🧚 HISTORY 🧚

Linux 2.6.18. she's been around a minute, a true veteran of the kernel game. ⭐

---

👑 SEE ALSO 👑

• futex(2)

---

lowkey a warning but also just facts: ENOSYS means it's genuinely not available on your arch or CPU variant, and EPERM means you're not the owner — neither of those is a "try harder" situation, it's a "read the room" situation. 🫶

---

and that's the whole page bestie!! from the Linux man-pages 6.20 collection, dated 2025-05-30 — mwah, go forth and unlock your priority-inheritance futexes responsibly 💖🎀🦋