-
Notifications
You must be signed in to change notification settings - Fork 0
/
get_robust_list.html
253 lines (189 loc) · 7.14 KB
/
get_robust_list.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:25:48 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>GET_ROBUST_LIST</title>
</head>
<body>
<h1 align="center">GET_ROBUST_LIST</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#VERSIONS">VERSIONS</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">get_robust_list,
set_robust_list - get/set list of robust futexes</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<linux/futex.h> <br>
#include <sys/types.h> <br>
#include <syscall.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>long
get_robust_list(int</b> <i>pid</i><b>, struct
robust_list_head **</b><i>head_ptr</i><b>, <br>
size_t *</b><i>len_ptr</i><b>); <br>
long set_robust_list(struct robust_list_head
*</b><i>head</i><b>, size_t</b> <i>len</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><i>Note</i>:
There are no glibc wrappers for these system calls; see
NOTES.</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">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 using
<b>set_robust_list</b>(). The address of a thread’s
robust futex list can be obtained using
<b>get_robust_list</b>().</p>
<p style="margin-left:11%; margin-top: 1em">The purpose of
the robust futex list is to ensure that if a thread
accidentally fails to unlock a futex before terminating or
calling <b>execve</b>(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: the
<b>FUTEX_OWNER_DIED</b> bit is set in the futex word, and
the kernel performs a <b>futex</b>(2) <b>FUTEX_WAKE</b>
operation on one of the threads waiting on the futex.</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>get_robust_list</b>() system call returns the head of the
robust futex list of the thread whose thread ID is specified
in <i>pid</i>. If <i>pid</i> is 0, the head of the list for
the calling thread is returned. The list head is stored in
the location pointed to by <i>head_ptr</i>. The size of the
object pointed to by <i>**head_ptr</i> is stored in
<i>len_ptr</i>.</p>
<p style="margin-left:11%; margin-top: 1em">Permission to
employ <b>get_robust_list</b>() is governed by a ptrace
access mode <b>PTRACE_MODE_READ_REALCREDS</b> check; see
<b>ptrace</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>set_robust_list</b>() system call requests the kernel to
record the head of the list of robust futexes owned by the
calling thread. The <i>head</i> argument is the list head to
record. The <i>len</i> argument should be
<i>sizeof(*head)</i>.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>set_robust_list</b>() and <b>get_robust_list</b>() system
calls return zero when the operation is successful, an error
code otherwise.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>set_robust_list</b>() system call can fail with the
following error:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><i>len</i> does not equal
<i>sizeof(struct robust_list_head)</i>.</p> </td></tr>
</table>
<p style="margin-left:11%; margin-top: 1em">The
<b>get_robust_list</b>() system call can fail with the
following errors:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EPERM</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">The calling process does not
have permission to see the robust futex list of the thread
with the thread ID <i>pid</i>, and does not have the
<b>CAP_SYS_PTRACE</b> capability.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ESRCH</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>No thread with the thread ID <i>pid</i> could be
found.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EFAULT</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The head of the robust futex list can’t be stored
at the location <i>head</i>.</p></td></tr>
</table>
<h2>VERSIONS
<a name="VERSIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">These system
calls were added in Linux 2.6.17.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">These system
calls are not needed by normal applications. No support for
them is provided in glibc. In the unlikely event that you
want to call them directly, use <b>syscall</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<p style="margin-left:11%; margin-top: 1em">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 an
<b>execve</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">The thread IDs
mentioned in the main text are <i>kernel</i> thread IDs of
the kind returned by <b>clone</b>(2) and
<b>gettid</b>(2).</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>futex</b>(2),
<b>pthread_mutexattr_setrobust</b>(3)</p>
<p style="margin-left:11%; margin-top: 1em"><i>Documentation/robust-futexes.txt</i>
and <i>Documentation/robust-futex-ABI.txt</i> in the Linux
kernel source tree</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>