]>
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 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
1f62bc9e IV |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
14 | .\" | |
15 | .\" Since the Linux kernel and libraries are constantly changing, this | |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
1f62bc9e | 26 | .\" |
ce50b4c3 | 27 | .\" FIXME Something could be added to this page (or exit(2)) |
d316ef31 | 28 | .\" about exit_robust_list processing |
1f62bc9e | 29 | .\" |
4b8c67d9 | 30 | .TH GET_ROBUST_LIST 2 2017-09-15 Linux "Linux System Calls" |
1f62bc9e | 31 | .SH NAME |
ce50b4c3 | 32 | get_robust_list, set_robust_list \- get/set list of robust futexes |
1f62bc9e IV |
33 | .SH SYNOPSIS |
34 | .nf | |
35 | .B #include <linux/futex.h> | |
531b5b69 | 36 | .B #include <sys/types.h> |
1f62bc9e | 37 | .B #include <syscall.h> |
68e4db0a | 38 | .PP |
1f62bc9e | 39 | .BI "long get_robust_list(int " pid ", struct robust_list_head **" head_ptr , |
5a6194a4 | 40 | .BI " size_t *" len_ptr ); |
1f62bc9e IV |
41 | .BI "long set_robust_list(struct robust_list_head *" head ", size_t " len ); |
42 | .fi | |
dbfe9c70 | 43 | .PP |
45c99e3e MK |
44 | .IR Note : |
45 | There are no glibc wrappers for these system calls; see NOTES. | |
1f62bc9e | 46 | .SH DESCRIPTION |
34821bdd MK |
47 | These system calls deal with per-thread robust futex lists. |
48 | These lists are managed in user space: | |
49 | the kernel knows only about the location of the head of the list. | |
50 | A thread can inform the kernel of the location of its robust futex list using | |
51 | .BR set_robust_list (). | |
52 | The address of a thread's robust futex list can be obtained using | |
53 | .BR get_robust_list (). | |
54 | .PP | |
55 | The purpose of the robust futex list is to ensure that if a thread | |
56 | accidentally fails to unlock a futex before terminating or calling | |
57 | .BR execve (2), | |
58 | another thread that is waiting on that futex is notified that | |
59 | the former owner of the futex has died. | |
60 | This notification consists of two pieces: the | |
61 | .BR FUTEX_OWNER_DIED | |
62 | bit is set in the futex word, and the kernel performs a | |
63 | .BR futex (2) | |
64 | .BR FUTEX_WAKE | |
65 | operation on one of the threads waiting on the futex. | |
efeece04 | 66 | .PP |
1f62bc9e | 67 | The |
ce50b4c3 MK |
68 | .BR get_robust_list () |
69 | system call returns the head of the robust futex list of the thread | |
70 | whose thread ID is specified in | |
71 | .IR pid . | |
72 | If | |
73 | .I pid | |
74 | is 0, | |
75 | the head of the list for the calling thread is returned. | |
76 | The list head is stored in the location pointed to by | |
77 | .IR head_ptr . | |
78 | The size of the object pointed to by | |
79 | .I **head_ptr | |
80 | is stored in | |
81 | .IR len_ptr . | |
efeece04 | 82 | .PP |
a1c7ef56 MK |
83 | Permission to employ |
84 | .BR get_robust_list () | |
85 | is governed by a ptrace access mode | |
86 | .B PTRACE_MODE_READ_REALCREDS | |
87 | check; see | |
88 | .BR ptrace (2). | |
efeece04 | 89 | .PP |
ce50b4c3 MK |
90 | The |
91 | .BR set_robust_list () | |
92 | system call requests the kernel to record the head of the list of | |
93 | robust futexes owned by the calling thread. | |
94 | The | |
95 | .I head | |
96 | argument is the list head to record. | |
97 | The | |
1f62bc9e | 98 | .I len |
ce50b4c3 MK |
99 | argument should be |
100 | .IR sizeof(*head) . | |
47297adb | 101 | .SH RETURN VALUE |
1f62bc9e | 102 | The |
ce50b4c3 | 103 | .BR set_robust_list () |
0ab8aeec | 104 | and |
ce50b4c3 MK |
105 | .BR get_robust_list () |
106 | system calls return zero when the operation is successful, | |
1f62bc9e | 107 | an error code otherwise. |
1f62bc9e IV |
108 | .SH ERRORS |
109 | The | |
ce50b4c3 | 110 | .BR set_robust_list () |
99eccaa7 | 111 | system call can fail with the following error: |
ce50b4c3 | 112 | .TP |
0ab8aeec | 113 | .B EINVAL |
1f62bc9e | 114 | .I len |
c0a181aa MK |
115 | does not equal |
116 | .IR "sizeof(struct\ robust_list_head)" . | |
ce50b4c3 | 117 | .PP |
1f62bc9e | 118 | The |
ce50b4c3 MK |
119 | .BR get_robust_list () |
120 | system call can fail with the following errors: | |
121 | .TP | |
0ab8aeec | 122 | .B EPERM |
ce50b4c3 MK |
123 | The calling process does not have permission to see the robust futex list of |
124 | the thread with the thread ID | |
125 | .IR pid , | |
126 | and does not have the | |
127 | .BR CAP_SYS_PTRACE | |
128 | capability. | |
129 | .TP | |
0ab8aeec | 130 | .B ESRCH |
ce50b4c3 | 131 | No thread with the thread ID |
1f62bc9e | 132 | .I pid |
ce50b4c3 MK |
133 | could be found. |
134 | .TP | |
1f62bc9e | 135 | .B EFAULT |
ce50b4c3 MK |
136 | The head of the robust futex list can't be stored at the location |
137 | .IR head . | |
138 | .SH VERSIONS | |
139 | These system calls were added in Linux 2.6.17. | |
ce50b4c3 MK |
140 | .SH NOTES |
141 | These system calls are not needed by normal applications. | |
142 | No support for them is provided in glibc. | |
45c99e3e MK |
143 | In the unlikely event that you want to call them directly, use |
144 | .BR syscall (2). | |
efeece04 | 145 | .PP |
ce50b4c3 MK |
146 | A thread can have only one robust futex list; |
147 | therefore applications that wish | |
148 | to use this functionality should use the robust mutexes provided by glibc. | |
30edf187 | 149 | .PP |
6e22a606 MK |
150 | In the initial implementation, |
151 | a thread waiting on a futex was notified that the owner had died | |
152 | only if the owner terminated. | |
153 | Starting with Linux 2.6.28, | |
154 | .\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7 | |
155 | notification was extended to include the case where the owner performs an | |
156 | .BR execve (2). | |
157 | .PP | |
30edf187 MK |
158 | The thread IDs mentioned in the main text are |
159 | .I kernel | |
160 | thread IDs of the kind returned by | |
161 | .BR clone (2) | |
162 | and | |
163 | .BR gettid (2). | |
47297adb | 164 | .SH SEE ALSO |
ad5722b3 MK |
165 | .BR futex (2), |
166 | .BR pthread_mutexattr_setrobust (3) | |
efeece04 | 167 | .PP |
ce50b4c3 MK |
168 | .IR Documentation/robust-futexes.txt |
169 | and | |
173fe7e7 | 170 | .IR Documentation/robust-futex-ABI.txt |
66a9882e | 171 | in the Linux kernel source tree |
ce50b4c3 | 172 | .\" http://lwn.net/Articles/172149/ |