Debian Codegraph @

upstream/debian-trixie/man2/get_robust_list.2

raw
1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
2 .\" Written by Ivana Varekova <[email protected]>
3 .\" and Copyright (c) 2017, Michael Kerrisk <[email protected]>
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 2024-05-02 "Linux man-pages 6.9.1"
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 *" len_ptr );
25 .B long syscall(SYS_set_robust_list,
26 .BI " struct robust_list_head *" head ", size_t " len );
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 len_ptr .
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; see
75 .BR ptrace (2).
76 .P
77 The
78 .BR set_robust_list ()
79 system call requests the kernel to record the head of the list of
80 robust futexes owned by the calling thread.
81 The
82 .I head
83 argument is the list head to record.
84 The
85 .I len
86 argument should be
87 .IR sizeof(*head) .
88 .SH RETURN VALUE
89 The
90 .BR set_robust_list ()
91 and
92 .BR get_robust_list ()
93 system calls return zero when the operation is successful,
94 an error code otherwise.
95 .SH ERRORS
96 The
97 .BR set_robust_list ()
98 system call can fail with the following error:
99 .TP
100 .B EINVAL
101 .I len
102 does not equal
103 .IR "sizeof(struct\ robust_list_head)" .
104 .P
105 The
106 .BR get_robust_list ()
107 system call can fail with the following errors:
108 .TP
109 .B EFAULT
110 The head of the robust futex list can't be stored at the location
111 .IR head .
112 .TP
113 .B EPERM
114 The calling process does not have permission to see the robust futex list of
115 the thread with the thread ID
116 .IR pid ,
117 and does not have the
118 .B CAP_SYS_PTRACE
119 capability.
120 .TP
121 .B ESRCH
122 No thread with the thread ID
123 .I pid
124 could be found.
125 .SH VERSIONS
126 These system calls were added in Linux 2.6.17.
127 .SH NOTES
128 These system calls are not needed by normal applications.
129 .P
130 A thread can have only one robust futex list;
131 therefore applications that wish
132 to use this functionality should use the robust mutexes provided by glibc.
133 .P
134 In the initial implementation,
135 a thread waiting on a futex was notified that the owner had died
136 only if the owner terminated.
137 Starting with Linux 2.6.28,
138 .\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7
139 notification was extended to include the case where the owner performs an
140 .BR execve (2).
141 .P
142 The thread IDs mentioned in the main text are
143 .I kernel
144 thread IDs of the kind returned by
145 .BR clone (2)
146 and
147 .BR gettid (2).
148 .SH SEE ALSO
149 .BR futex (2),
150 .BR pthread_mutexattr_setrobust (3)
151 .P
152 .I Documentation/robust\-futexes.txt
153 and
154 .I Documentation/robust\-futex\-ABI.txt
155 in the Linux kernel source tree
156 .\" http://lwn.net/Articles/172149/