HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |VERSIONS |NOTES |SEE ALSO |COLOPHON | |
get_robust_list(2) System Calls Manualget_robust_list(2)get_robust_list, set_robust_list - get/set list of robust futexes
Standard C library (libc,-lc)
#include <linux/futex.h>/* Definition ofstruct robust_list_head*/#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(SYS_get_robust_list, intpid,struct robust_list_head **head_ptr, size_t *sizep);long syscall(SYS_set_robust_list,struct robust_list_head *head, size_tsize);Note: glibc provides no wrappers for these system calls, necessitating the use ofsyscall(2).
These system calls deal with per-thread robust futex lists. These lists are managed in user space: the kernel knows only about the location of the head of the list. A thread can inform the kernel of the location of its robust futex list usingset_robust_list(). The address of a thread's robust futex list can be obtained usingget_robust_list(). The purpose of the robust futex list is to ensure that if a thread accidentally fails to unlock a futex before terminating or callingexecve(2), another thread that is waiting on that futex is notified that the former owner of the futex has died. This notification consists of two pieces: theFUTEX_OWNER_DIEDbit is set in the futex word, and the kernel performs afutex(2)FUTEX_WAKEoperation on one of the threads waiting on the futex. Theget_robust_list() system call returns the head of the robust futex list of the thread whose thread ID is specified inpid. Ifpid is 0, the head of the list for the calling thread is returned. The list head is stored in the location pointed to byhead_ptr. The size of the object pointed to by**head_ptr is stored insizep. Permission to employget_robust_list() is governed by a ptrace access modePTRACE_MODE_READ_REALCREDScheck; seeptrace(2). Theset_robust_list() system call requests the kernel to record the head of the list of robust futexes owned by the calling thread. Thehead argument is the list head to record. Thesize argument should besizeof(*head).
Theset_robust_list() andget_robust_list() system calls return zero when the operation is successful, an error code otherwise.
Theset_robust_list() system call can fail with the following error:EINVALsize does not equalsizeof(struct robust_list_head). Theget_robust_list() system call can fail with the following errors:EFAULTThe head of the robust futex list can't be stored at the locationhead.EPERMThe calling process does not have permission to see the robust futex list of the thread with the thread IDpid, and does not have theCAP_SYS_PTRACEcapability.ESRCHNo thread with the thread IDpid could be found.
These system calls were added in Linux 2.6.17.
These system calls are not needed by normal applications. A thread can have only one robust futex list; therefore applications that wish to use this functionality should use the robust mutexes provided by glibc. 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, notification was extended to include the case where the owner performs anexecve(2). The thread IDs mentioned in the main text arekernel thread IDs of the kind returned byclone(2) andgettid(2).
futex(2),pthread_mutexattr_setrobust(3)Documentation/robust-futexes.txt andDocumentation/robust-futex-ABI.txt in the Linux kernel source tree
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17get_robust_list(2)Pages that refer to this page:execve(2), futex(2), gettid(2), ptrace(2), syscalls(2), exit(3), pthread_mutexattr_setrobust(3), capabilities(7), futex(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |