]>
Commit | Line | Data |
---|---|---|
1f62bc9e IV |
1 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
2 | .\" Written by Ivana Varekova <varekova@redhat.com> | |
34821bdd | 3 | .\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> |
1f62bc9e | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
1f62bc9e | 6 | .\" |
ce50b4c3 | 7 | .\" FIXME Something could be added to this page (or exit(2)) |
d316ef31 | 8 | .\" about exit_robust_list processing |
1f62bc9e | 9 | .\" |
1d767b55 | 10 | .TH GET_ROBUST_LIST 2 2021-03-22 Linux "Linux System Calls" |
1f62bc9e | 11 | .SH NAME |
ce50b4c3 | 12 | get_robust_list, set_robust_list \- get/set list of robust futexes |
04110e32 AC |
13 | .SH LIBRARY |
14 | Standard C library | |
8fc3b2cf | 15 | .RI ( libc ", " \-lc ) |
1f62bc9e IV |
16 | .SH SYNOPSIS |
17 | .nf | |
eb4a40e0 | 18 | .BR "#include <linux/futex.h>" \ |
843c0193 MK |
19 | " /* Definition of " "struct robust_list_head" " */" |
20 | .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" | |
eb4a40e0 | 21 | .B #include <unistd.h> |
68e4db0a | 22 | .PP |
eb4a40e0 AC |
23 | .BI "long syscall(SYS_get_robust_list, int " pid , |
24 | .BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr ); | |
1ae6b2c7 | 25 | .B long syscall(SYS_set_robust_list, |
eb4a40e0 | 26 | .BI " struct robust_list_head *" head ", size_t " len ); |
1f62bc9e | 27 | .fi |
bc2813df AC |
28 | .PP |
29 | .IR Note : | |
30 | glibc provides no wrappers for these system calls, | |
31 | necessitating the use of | |
32 | .BR syscall (2). | |
1f62bc9e | 33 | .SH DESCRIPTION |
34821bdd MK |
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 | .PP | |
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 | |
1ae6b2c7 | 48 | .B FUTEX_OWNER_DIED |
34821bdd MK |
49 | bit is set in the futex word, and the kernel performs a |
50 | .BR futex (2) | |
1ae6b2c7 | 51 | .B FUTEX_WAKE |
34821bdd | 52 | operation on one of the threads waiting on the futex. |
efeece04 | 53 | .PP |
1f62bc9e | 54 | The |
ce50b4c3 MK |
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 . | |
efeece04 | 69 | .PP |
a1c7ef56 MK |
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). | |
efeece04 | 76 | .PP |
ce50b4c3 MK |
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 | |
1f62bc9e | 85 | .I len |
ce50b4c3 MK |
86 | argument should be |
87 | .IR sizeof(*head) . | |
47297adb | 88 | .SH RETURN VALUE |
1f62bc9e | 89 | The |
ce50b4c3 | 90 | .BR set_robust_list () |
0ab8aeec | 91 | and |
ce50b4c3 MK |
92 | .BR get_robust_list () |
93 | system calls return zero when the operation is successful, | |
1f62bc9e | 94 | an error code otherwise. |
1f62bc9e IV |
95 | .SH ERRORS |
96 | The | |
ce50b4c3 | 97 | .BR set_robust_list () |
99eccaa7 | 98 | system call can fail with the following error: |
ce50b4c3 | 99 | .TP |
0ab8aeec | 100 | .B EINVAL |
1f62bc9e | 101 | .I len |
c0a181aa MK |
102 | does not equal |
103 | .IR "sizeof(struct\ robust_list_head)" . | |
ce50b4c3 | 104 | .PP |
1f62bc9e | 105 | The |
ce50b4c3 MK |
106 | .BR get_robust_list () |
107 | system call can fail with the following errors: | |
108 | .TP | |
49a2a105 MK |
109 | .B EFAULT |
110 | The head of the robust futex list can't be stored at the location | |
111 | .IR head . | |
112 | .TP | |
0ab8aeec | 113 | .B EPERM |
ce50b4c3 MK |
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 | |
1ae6b2c7 | 118 | .B CAP_SYS_PTRACE |
ce50b4c3 MK |
119 | capability. |
120 | .TP | |
0ab8aeec | 121 | .B ESRCH |
ce50b4c3 | 122 | No thread with the thread ID |
1f62bc9e | 123 | .I pid |
ce50b4c3 | 124 | could be found. |
ce50b4c3 MK |
125 | .SH VERSIONS |
126 | These system calls were added in Linux 2.6.17. | |
ce50b4c3 MK |
127 | .SH NOTES |
128 | These system calls are not needed by normal applications. | |
efeece04 | 129 | .PP |
ce50b4c3 MK |
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. | |
30edf187 | 133 | .PP |
6e22a606 MK |
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 | .PP | |
30edf187 MK |
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). | |
47297adb | 148 | .SH SEE ALSO |
ad5722b3 MK |
149 | .BR futex (2), |
150 | .BR pthread_mutexattr_setrobust (3) | |
efeece04 | 151 | .PP |
1ae6b2c7 | 152 | .I Documentation/robust\-futexes.txt |
ce50b4c3 | 153 | and |
1ae6b2c7 | 154 | .I Documentation/robust\-futex\-ABI.txt |
66a9882e | 155 | in the Linux kernel source tree |
ce50b4c3 | 156 | .\" http://lwn.net/Articles/172149/ |