FUTEX_LOCK_PI(2const)

✨ FUTEX_LOCK_PI ✨

okay bestie, welcome to FUTEX_LOCK_PI(2const) — the priority-inheritance futex lock, section 2const, and yes it's giving main character energy 🔥

---

💖 NAME 💖

FUTEX_LOCK_PI — lock a priority-inheritance futex 👑

📚 LIBRARY 📚

Standard C library (libc, -lc) — shoutout to libc fr fr 🫶

🧚 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_LOCK_PI, 0,
             const struct timespec *timeout);

🌸 DESCRIPTION 🌸

So here's the vibe: you already tried to grab the lock with an atomic user-mode instruction, and it failed because the futex word had a nonzero value — specifically because it was holding the (PID-namespace-specific) TID of the lock owner. That's when you call this. No cap.

The operation peeks at the futex word sitting at the address uaddr. Two paths, bestie:

• If the value is 0, the kernel tries to atomically set the futex value to the caller's TID. slay.
• If the futex word's value is nonzero, the kernel atomically sets the FUTEX_WAITERS bit, which is basically the kernel telling the futex owner "girl you cannot unlock this in user space atomically by setting the futex value to 0." 💅

After that little move, the kernel:

1. Tries to find the thread which is associated with the owner TID. 🔍
2. Creates or reuses kernel state on behalf of the owner. (If this is the first waiter, there is no kernel state for this futex, so kernel state is created by locking the RT-mutex and the futex owner is made the owner of the RT-mutex. If there are already existing waiters, then the existing state is reused.) 🧠
3. Attaches the waiter to the futex — i.e., the waiter is enqueued on the RT-mutex waiter list. 📋

If more than one waiter exists, the enqueueing of the waiter is in descending priority order. (For the tea on priority ordering, go read the discussion of the SCHED_DEADLINE, SCHED_FIFO, and SCHED_RR scheduling policies in sched(7).) 📖

And the owner inherits either the waiter's CPU bandwidth (if the waiter is scheduled under the SCHED_DEADLINE policy) or the waiter's priority (if the waiter is scheduled under the SCHED_RR or SCHED_FIFO policy). This inheritance follows the lock chain in the case of nested locking and performs deadlock detection. iconic behavior honestly 🌀

The timeout argument gives the lock attempt a timeout. If timeout is not NULL, the structure it points to specifies an absolute timeout. If timeout is NULL, the operation will block indefinitely. 😴

💅 RETURN VALUE 💅

On error, -1 is returned, and errno is set to indicate the error. 🙈

On success, FUTEX_LOCK_PI returns 0 if the futex was successfully locked. periodt ✅

💀 ERRORS 💀

See futex(2). (go read it, iykyk)

• EAGAIN — The futex owner thread ID of uaddr is about to exit, but has not yet handled the internal state cleanup. Try again. 🔁
• EDEADLK — The futex word at uaddr is already locked by the caller. girl that's you, you already own it 😭
• EFAULT — 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 — The kernel detected an inconsistency between the user-space state at uaddr and the kernel state. This indicates either state corruption or that the kernel found a waiter on uaddr which is waiting via FUTEX_WAIT(2const) or FUTEX_WAIT_BITSET(2const). 😵
• ENOMEM — The kernel could not allocate memory to hold state information. no room bestie 🧠
• 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. lowkey tragic 💀
• EPERM — The caller is not allowed to attach itself to the futex at uaddr. (This may be caused by a state corruption in user space.) 🙅
• ESRCH — The thread ID in the futex word at uaddr does not exist. who even is she 👻
• ETIMEDOUT — The timeout expired before the operation completed. ran out of time fr fr ⌛

🌈 STANDARDS 🌈

Linux. that's it, that's the standard 🐧

🦋 HISTORY 🦋

Linux 2.6.18. vintage but make it iconic 🎀

🎀 CAVEATS 🎀

Unlike other futex(2) operations, the timeout is measured against the CLOCK_REALTIME clock. ⚠️ like, yes, really — don't @ me, that's just how it is.

👑 SEE ALSO 👑

• futex(2)

---

okay and for the cute sign-off: this gorgeous little page comes from Linux man-pages 6.20, dated 2025-12-25 🎁 — happy reading bestie, stay locked and loaded 💖✨🦋