Debian Codegraph @

upstream/debian-unstable/man2/get_robust_list.2

raw
1 .\" Copyright 2006, Red Hat, Inc
2 .\" Copyright 2017, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" FIXME Something could be added to this page (or exit(2))
8 .\" about exit_robust_list processing
9 .\"
10 .TH get_robust_list 2 2026-02-08 "Linux man-pages 6.18"
11 .SH NAME
12 get_robust_list, set_robust_list \- get/set list of robust futexes
13 .SH LIBRARY
14 Standard C library
15 .RI ( libc ,\~ \-lc )
16 .SH SYNOPSIS
17 .nf
18 .BR "#include <linux/futex.h>" \
19 " /* Definition of " "struct robust_list_head" " */"
20 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
21 .B #include <unistd.h>
22 .P
23 .BI "long syscall(SYS_get_robust_list, int " pid ,
24 .BI " struct robust_list_head **" head_ptr ", size_t *" sizep );
25 .B long syscall(SYS_set_robust_list,
26 .BI " struct robust_list_head *" head ", size_t " size );
27 .fi
28 .P
29 .IR Note :
30 glibc provides no wrappers for these system calls,
31 necessitating the use of
32 .BR syscall (2).
33 .SH DESCRIPTION
34 These system calls deal with per-thread robust futex lists.
35 These lists are managed in user space:
36 the kernel knows only about the location of the head of the list.
37 A thread can inform the kernel of the location of its robust futex list using
38 .BR set_robust_list ().
39 The address of a thread's robust futex list can be obtained using
40 .BR get_robust_list ().
41 .P
42 The purpose of the robust futex list is to ensure that if a thread
43 accidentally fails to unlock a futex before terminating or calling
44 .BR execve (2),
45 another thread that is waiting on that futex is notified that
46 the former owner of the futex has died.
47 This notification consists of two pieces: the
48 .B FUTEX_OWNER_DIED
49 bit is set in the futex word, and the kernel performs a
50 .BR futex (2)
51 .B FUTEX_WAKE
52 operation on one of the threads waiting on the futex.
53 .P
54 The
55 .BR get_robust_list ()
56 system call returns the head of the robust futex list of the thread
57 whose thread ID is specified in
58 .IR pid .
59 If
60 .I pid
61 is 0,
62 the head of the list for the calling thread is returned.
63 The list head is stored in the location pointed to by
64 .IR head_ptr .
65 The size of the object pointed to by
66 .I **head_ptr
67 is stored in
68 .IR sizep .
69 .P
70 Permission to employ
71 .BR get_robust_list ()
72 is governed by a ptrace access mode
73 .B PTRACE_MODE_READ_REALCREDS
74 check;
75 see
76 .BR ptrace (2).
77 .P
78 The
79 .BR set_robust_list ()
80 system call requests the kernel to record the head of the list of
81 robust futexes owned by the calling thread.
82 The
83 .I head
84 argument is the list head to record.
85 The
86 .I size
87 argument should be
88 .IR sizeof(*head) .
89 .SH RETURN VALUE
90 The
91 .BR set_robust_list ()
92 and
93 .BR get_robust_list ()
94 system calls return zero when the operation is successful,
95 an error code otherwise.
96 .SH ERRORS
97 The
98 .BR set_robust_list ()
99 system call can fail with the following error:
100 .TP
101 .B EINVAL
102 .I size
103 does not equal
104 .IR "sizeof(struct\ robust_list_head)" .
105 .P
106 The
107 .BR get_robust_list ()
108 system call can fail with the following errors:
109 .TP
110 .B EFAULT
111 The head of the robust futex list can't be stored at the location
112 .IR head .
113 .TP
114 .B EPERM
115 The calling process does not have permission to see the robust futex list of
116 the thread with the thread ID
117 .IR pid ,
118 and does not have the
119 .B CAP_SYS_PTRACE
120 capability.
121 .TP
122 .B ESRCH
123 No thread with the thread ID
124 .I pid
125 could be found.
126 .SH VERSIONS
127 These system calls were added in Linux 2.6.17.
128 .SH NOTES
129 These system calls are not needed by normal applications.
130 .P
131 A thread can have only one robust futex list;
132 therefore applications that wish
133 to use this functionality should use the robust mutexes provided by glibc.
134 .P
135 In the initial implementation,
136 a thread waiting on a futex was notified that the owner had died
137 only if the owner terminated.
138 Starting with Linux 2.6.28,
139 .\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7
140 notification was extended to include the case where the owner performs an
141 .BR execve (2).
142 .P
143 The thread IDs mentioned in the main text are
144 .I kernel
145 thread IDs of the kind returned by
146 .BR clone (2)
147 and
148 .BR gettid (2).
149 .SH SEE ALSO
150 .BR futex (2),
151 .BR pthread_mutexattr_setrobust (3)
152 .P
153 .I Documentation/robust\-futexes.rst
154 and
155 .I Documentation/robust\-futex\-ABI.rst
156 in the Linux kernel source tree
157 .\" http://lwn.net/Articles/172149/