FUTEX_FD(2const)

💖 FUTEX_FD(2const) 💖

okay bestie, so this is a page from the <italic>Linux man-pages</italic> set — section 2const to be exact — and no cap, it's a ✨ historic ✨ one. Buckle up, it's giving "vintage Linux lore". 🦋

---

🌸 NAME 🌸

FUTEX_FD — make a file descriptor that's besties with a futex 🫶

📚 LIBRARY 📚

Standard C library (libc, -lc) — the usual, she's always there for you 💅

✨ SYNOPSIS ✨

#include <linux/futex.h>  /* Definition of FUTEX_* constants */
#include <sys/syscall.h>  /* Definition of SYS_* constants */
#include <unistd.h>

[[deprecated]]
long syscall(SYS_futex, uint32_t *uaddr, FUTEX_FD, uint32_t val);

see that [[deprecated]] sitting there? yeah. she's marked. 🙈

💜 DESCRIPTION 💜

So this operation creates a file descriptor that is associated with the futex at uaddr. Simple as that. And listen — the caller must close the returned file descriptor after use. That's not optional, that's the rules, periodt. 🔥

Now the fun part: when another process or thread performs a FUTEX_WAKE(2const) on the futex word, that file descriptor shows up as being readable with select(2), poll(2), and epoll(7). Like, it's literally vibing and saying "hey, something happened" ✨

And it can also be used to obtain asynchronous notifications — here's the tea: if val is nonzero, then when another process or thread executes a FUTEX_WAKE(2const), the caller will receive the signal number that was passed in val. iconic behavior, ngl. 😭

🎀 RETURN VALUE 🎀

• On error, -1 is returned, and errno is set to indicate the error. classic. 💀
• On success, FUTEX_FD returns the new file descriptor associated with the futex. slay. 👑

⭐ ERRORS ⭐

See futex(2) for the full rundown bestie, plus these two special guests:

• EINVAL — the signal number supplied in val is invalid. like girl, that's not a real signal number 💅
• ENFILE — the system-wide limit on the total number of open files has been reached. too many open files, the whole system said "no more". 🙈

🌈 STANDARDS 🌈

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

👑 HISTORY 👑

Okay so here's the drama: FUTEX_FD lived from Linux 2.6.0 up to and including Linux 2.6.25. a whole era. 🕰️

But because it was inherently racy, FUTEX_FD has been removed from Linux 2.6.26 onward. gone. deleted. she did not survive the vibe check. 💀

⚠️ fr fr — don't try to use this on modern kernels, bestie. it's not there anymore. this is museum content. 🏛️

🦋 SEE ALSO 🦋

• futex(2)

---

and that's the whole page, bestie!! 💖 this was from the <italic>Linux man-pages</italic>, version 6.20, dated 2025-05-30 — so when you cite it, cite it cute. mwah, love u, go close your file descriptors. 🎀✨🫶