get_robust_list(2)

💖 get_robust_list(2) — okay bestie, let's talk robust futex lists 💖

so this is a page from the System Calls Manual (Linux girly through and through 🐧), and it's about get_robust_list and set_robust_list — the getter and the setter for your very own list of robust futexes. yeah. we're going there. stay with me 💅

---

✨ NAME ✨

get_robust_list, set_robust_list — get/set the list of robust futexes 💫

📚 LIBRARY 📚

Standard C library (libc, -lc)

🎀 SYNOPSIS 🎀

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

long syscall(SYS_get_robust_list, int pid,
             struct robust_list_head **head_ptr, size_t *sizep);
long syscall(SYS_set_robust_list,
             struct robust_list_head *head, size_t size);

okay so heads up (pun fully intended 🫶): glibc provides no wrappers for these system calls, so you literally have to go through syscall(2). no cute little helper function for you. it's giving DIY. it's giving raw dogging the kernel 💀

🌸 DESCRIPTION 🌸

These system calls deal with per-thread robust futex lists. and the tea is: these lists live in user space — the kernel only knows where the head of the list is. that's it. that's all it gets. 🙈

• A thread can tell the kernel where its robust futex list is at by using set_robust_list().
• You can grab the address of a thread's robust futex list with get_robust_list().

🦋 so what's the whole POINT of this list

The purpose of the robust futex list is to make sure that if a thread accidentally forgets to unlock a futex before it terminates or calls execve(2), any other thread waiting on that futex gets notified that the former owner has died. rip to them but somebody had to know ✨

That notification comes in two pieces, and bestie, both of them matter:

1. The FUTEX_OWNER_DIED bit gets set in the futex word.
2. The kernel performs a futex(2) FUTEX_WAKE operation on one of the threads waiting on that futex.

💜 get_robust_list()

get_robust_list() returns the head of the robust futex list of the thread whose thread ID you pass in pid.

• If pid is 0, you get the head of the list for the calling thread. (self-love fr fr 💖)
• The list head gets stored in the location pointed to by head_ptr.
• The size of the object pointed to by **head_ptr gets stored in sizep.

Permission to use get_robust_list() is governed by a ptrace access mode PTRACE_MODE_READ_REALCREDS check. see ptrace(2) for the full lore 👑

💅 set_robust_list()

set_robust_list() asks the kernel to record the head of the list of robust futexes owned by the calling thread.

• head — the list head to record.
• size — should be sizeof(*head).

🌈 RETURN VALUE 🌈

Both set_robust_list() and get_robust_list() return zero when everything worked out, and an error code otherwise. slay when zero, sad when not 😭

🔥 ERRORS 🔥

set_robust_list() can fail with:

• EINVAL — size does not equal sizeof(struct robust_list_head). yeah you gotta get that size exactly right, no rounding, no vibes-based sizing 🎀

get_robust_list() can fail with:

• EFAULT — the head of the robust futex list can't be stored at the location head.
• EPERM — the calling process does not have permission to see the robust futex list of the thread with the thread ID pid, and does not have the CAP_SYS_PTRACE capability.
• ESRCH — no thread with the thread ID pid could be found. she's not here, she never was 💀

⭐ VERSIONS ⭐

These system calls were added in Linux 2.6.17. vintage but make it functional 💫

👑 NOTES 👑

• These system calls are not needed by normal applications. (say it louder for the people in the back 📣)
• A thread can have only one robust futex list. so applications that want this functionality should really just use the robust mutexes provided by glibc. stop trying to do it yourself, bestie 🫶
• In the initial implementation, a thread waiting on a futex was notified that the owner had died only if the owner terminated. Starting with Linux 2.6.28, that notification was extended to also cover the case where the owner performs an execve(2).
• The thread IDs mentioned in the main text are kernel thread IDs, of the kind returned by clone(2) and gettid(2). important distinction, no cap 🧚

🌸 SEE ALSO 🌸

• futex(2)
• pthread_mutexattr_setrobust(3)
• Documentation/robust-futexes.rst and Documentation/robust-futex-ABI.rst in the Linux kernel source tree

---

and that's the whole page, bestie 💖 you now know more about robust futex lists than 99% of the group chat. main character kernel-knowledge energy, lowkey.

okay bye ily, this was Linux man-pages 6.20, dated 2026-02-08 🎀 go forth and syscall responsibly ✨