FUTEX_TRYLOCK_PI(2const)

✨ FUTEX_TRYLOCK_PI ✨

okay so bestie, welcome to futex_trylock_pi(2const) — the manual page for the little syscall operation that's like "hey kernel, please try to grab this priority-inheritance lock for me, no waiting around tho" 🫶

---

💖 NAME 💖

FUTEX_TRYLOCK_PI — try to lock a priority-inheritance futex

🎀 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_TRYLOCK_PI);

🦋 DESCRIPTION 🦋

So this op tries to acquire the lock sitting at uaddr. You only reach for it when your user-space atomic acquire already flopped because the futex word was not 0. Like, you tried, it said no, and now you're knocking on the kernel's door 🚪

And here's the tea ☕ — the kernel has access to more state information than user space does. So acquisition of the lock might actually succeed when the kernel does it, even in cases where the futex word (i.e., the state information accessible to user space) is holding stale state — specifically FUTEX_WAITERS and/or FUTEX_OWNER_DIED. This can happen when the owner of the futex straight-up died 💀 User space literally cannot handle this condition in a race-free manner, but the kernel can fix this up and acquire the futex. Iconic behaviour, honestly.

👑 RETURN VALUE 👑

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

On success, FUTEX_TRYLOCK_PI returns 0 if the futex was successfully locked. slay ✨

💅 ERRORS 💅

See futex(2).

• EAGAIN — the futex owner thread ID of uaddr is about to exit, but hasn't handled the internal state cleanup yet. Try again, bestie.
• EDEADLK — the futex word at uaddr is already locked by the caller. yes, by you. awkward 🙈
• EINVAL — the kernel detected an inconsistency between the user-space state at uaddr and the kernel state. This means either state corruption, or the kernel found a waiter on uaddr that's waiting via FUTEX_WAIT(2const) or FUTEX_WAIT_BITSET(2const).
• ENOMEM — the kernel could not allocate memory to hold state information. the budget ran out 😭
• 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 you're on the wrong chip, this is just not happening.
• 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. ghost thread 👻

🌈 STANDARDS 🌈

Linux.

⭐ HISTORY ⭐

Linux 2.6.18.

🔥 SEE ALSO 🔥

futex(2)

---

ngl if you made it this far you're lowkey a kernel girlie now 💜 go read futex(2) next, it's giving required reading, iykyk

mwah 💋 this page is from Linux man-pages 6.20, dated 2025-09-21 — periodt, that's the whole FUTEX_TRYLOCK_PI(2const) situation 🎀✨