futex_lock_pi_atomic(9)

💅 futex_lock_pi_atomic(9)

okay so bestie, we're diving into the Kernel API Manual today and the star of the show is futex_lock_pi_atomic — the atomic work required to acquire a pi aware futex. yes it's as serious as it sounds and yes you're gonna slay it 🫶

---

✨ NAME ✨

futex_lock_pi_atomic — Atomic work required to acquire a pi aware futex

---

🌸 SYNOPSIS 🌸

int futex_lock_pi_atomic (u32 __user *uaddr , struct futex_hash_bucket
*hb , union futex_key *key , struct futex_pi_state **ps , struct
task_struct *task , struct task_struct **exiting , int set_waiters );

---

🎀 ARGUMENTS 🎀

• uaddr — the pi futex user address 💖
• hb — the pi futex hash bucket
• key — the futex key associated with uaddr and hb
• ps — the pi_state pointer where we store the result of the lookup
• task — the task to perform the atomic lock work for. this will be "current" except in the case of requeue pi. iykyk 😌
• exiting — Pointer to store the task pointer of the owner task which is in the middle of exiting
• set_waiters — force setting the FUTEX_WAITERS bit (1) or not (0)

---

🔥 RETURN 🔥

• 0 — ready to wait;
• 1 — acquired the lock;
• <0 — error

---

🦋 DESCRIPTION 🦋

The hb->lock must be held by the caller. no cap, that's on you, not on the function 💅

exiting is only set when the return value is -EBUSY. If so, this holds a refcount on the exiting task on return and the caller needs to drop it after waiting for the exit to complete.

fr fr bestie, don't forget to drop that refcount after the exit finishes — the vibes will NOT be immaculate otherwise 😭

---

👑 SEE ALSO 👑

• Kernel file ./kernel/futex/pi.c
• fixup_pi_owner(9)

---

okay that's the whole page, you ate that 🍓✨ this iconic lil doc came from ./kernel/futex, dated October 2026, and it's the futex_lock_pi_atomic(9) Kernel API Manual entry — go forth and lock those pi aware futexes, main character 💜🦋