]>
Commit | Line | Data |
---|---|---|
8f0aff2a | 1 | .\" Page by b.hubert |
2e46a6e7 | 2 | .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) |
8f0aff2a | 3 | .\" may be freely modified and distributed |
2e46a6e7 | 4 | .\" %%%END_LICENSE |
fea681da MK |
5 | .\" |
6 | .\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com) | |
7 | .\" added ERRORS section. | |
8 | .\" | |
9 | .\" Modified 2004-06-17 mtk | |
10 | .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE | |
11 | .\" | |
4f58b197 MK |
12 | .\" FIXME |
13 | .\" See also https://bugzilla.kernel.org/show_bug.cgi?id=14303 | |
40d5cf23 | 14 | .\" 2.6.14 adds FUTEX_WAKE_OP |
4f58b197 MK |
15 | .\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721 |
16 | .\" Author: Jakub Jelinek <jakub@redhat.com> | |
17 | .\" Date: Tue Sep 6 15:16:25 2005 -0700 | |
18 | .\" | |
19 | .\" FIXME | |
c13182ef MK |
20 | .\" 2.6.18 adds (Ingo Molnar) priority inheritance support: |
21 | .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need | |
34f7665a MK |
22 | .\" to be documented in the manual page. Probably there is sufficient |
23 | .\" material in the kernel source file Documentation/pi-futex.txt. | |
4f58b197 MK |
24 | .\" commit c87e2837be82df479a6bae9f155c43516d2feebc |
25 | .\" Author: Ingo Molnar <mingo@elte.hu> | |
26 | .\" Date: Tue Jun 27 02:54:58 2006 -0700 | |
27 | .\" | |
28 | .\" commit e2970f2fb6950183a34e8545faa093eb49d186e1 | |
29 | .\" Author: Ingo Molnar <mingo@elte.hu> | |
30 | .\" Date: Tue Jun 27 02:54:47 2006 -0700 | |
31 | .\" | |
32 | .\" See Documentation/futex-requeue-pi.txt | |
33 | .\" | |
34 | .\" FIXME | |
40d5cf23 | 35 | .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET |
4f58b197 MK |
36 | .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d |
37 | .\" Author: Thomas Gleixner <tglx@linutronix.de> | |
38 | .\" Date: Fri Feb 1 17:45:14 2008 +0100 | |
39 | .\" | |
40 | .\" FIXME | |
41 | .\" 2.6.31 adds FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI | |
42 | .\" commit 52400ba946759af28442dee6265c5c0180ac7122 | |
43 | .\" Author: Darren Hart <dvhltc@us.ibm.com> | |
44 | .\" Date: Fri Apr 3 13:40:49 2009 -0700 | |
45 | .\" | |
46 | .\" commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358 | |
47 | .\" Author: Darren Hart <dvhltc@us.ibm.com> | |
48 | .\" Date: Mon Apr 20 22:22:22 2009 -0700 | |
49 | .\" | |
50 | .\" See Documentation/futex-requeue-pi.txt | |
34f7665a | 51 | .\" |
e808bba0 | 52 | .TH FUTEX 2 2012-08-13 "Linux" "Linux Programmer's Manual" |
fea681da | 53 | .SH NAME |
ce154705 | 54 | futex \- fast user-space locking |
fea681da | 55 | .SH SYNOPSIS |
9d9dc1e8 | 56 | .nf |
fea681da MK |
57 | .sp |
58 | .B "#include <linux/futex.h>" | |
fea681da MK |
59 | .B "#include <sys/time.h>" |
60 | .sp | |
9d9dc1e8 MK |
61 | .BI "int futex(int *" uaddr ", int " op ", int " val \ |
62 | ", const struct timespec *" timeout , | |
63 | .br | |
64 | .BI " int *" uaddr2 ", int " val3 ); | |
fea681da | 65 | .\" int *? void *? u32 *? |
9d9dc1e8 | 66 | .fi |
47297adb | 67 | .SH DESCRIPTION |
fea681da MK |
68 | .PP |
69 | The | |
e511ffb6 | 70 | .BR futex () |
fea681da MK |
71 | system call provides a method for |
72 | a program to wait for a value at a given address to change, and a | |
73 | method to wake up anyone waiting on a particular address (while the | |
74 | addresses for the same memory in separate processes may not be | |
75 | equal, the kernel maps them internally so the same memory mapped in | |
76 | different locations will correspond for | |
e511ffb6 | 77 | .BR futex () |
c13182ef | 78 | calls). |
fd3fa7ef | 79 | This system call is typically used to |
fea681da MK |
80 | implement the contended case of a lock in shared memory, as |
81 | described in | |
a8bda636 | 82 | .BR futex (7). |
fea681da | 83 | .PP |
c13182ef | 84 | When a |
a8bda636 | 85 | .BR futex (7) |
7fac88a9 | 86 | operation did not finish uncontended in user space, a call needs to be made |
c13182ef MK |
87 | to the kernel to arbitrate. |
88 | Arbitration can either mean putting the calling | |
fea681da MK |
89 | process to sleep or, conversely, waking a waiting process. |
90 | .PP | |
91 | Callers of this function are expected to adhere to the semantics as set out in | |
a8bda636 | 92 | .BR futex (7). |
fea681da | 93 | As these |
d603cc27 | 94 | semantics involve writing nonportable assembly instructions, this in turn |
fea681da MK |
95 | probably means that most users will in fact be library authors and not |
96 | general application developers. | |
97 | .PP | |
98 | The | |
99 | .I uaddr | |
100 | argument needs to point to an aligned integer which stores the counter. | |
101 | The operation to execute is passed via the | |
102 | .I op | |
c4bb193f | 103 | argument, along with a value |
fea681da MK |
104 | .IR val . |
105 | .PP | |
106 | Five operations are currently defined: | |
107 | .TP | |
108 | .B FUTEX_WAIT | |
109 | This operation atomically verifies that the futex address | |
110 | .I uaddr | |
111 | still contains the value | |
112 | .IR val , | |
682edefb MK |
113 | and sleeps awaiting |
114 | .B FUTEX_WAKE | |
115 | on this futex address. | |
c13182ef | 116 | If the |
fea681da MK |
117 | .I timeout |
118 | argument is non-NULL, its contents describe the maximum | |
c13182ef MK |
119 | duration of the wait, which is infinite otherwise. |
120 | The arguments | |
fea681da MK |
121 | .I uaddr2 |
122 | and | |
123 | .I val3 | |
124 | are ignored. | |
125 | ||
126 | For | |
a8bda636 | 127 | .BR futex (7), |
fea681da MK |
128 | this call is executed if decrementing the count gave a negative value |
129 | (indicating contention), and will sleep until another process releases | |
682edefb MK |
130 | the futex and executes the |
131 | .B FUTEX_WAKE | |
132 | operation. | |
fea681da MK |
133 | .TP |
134 | .B FUTEX_WAKE | |
a8d55537 | 135 | This operation wakes at most \fIval\fP |
b87dcfb9 | 136 | processes waiting on this futex address (i.e., inside |
682edefb | 137 | .BR FUTEX_WAIT ). |
fea681da MK |
138 | The arguments |
139 | .IR timeout , | |
140 | .I uaddr2 | |
141 | and | |
142 | .I val3 | |
143 | are ignored. | |
144 | ||
145 | For | |
a8bda636 | 146 | .BR futex (7), |
fea681da MK |
147 | this is executed if incrementing |
148 | the count showed that there were waiters, once the futex value has been set | |
149 | to 1 (indicating that it is available). | |
150 | .TP | |
da36351e | 151 | .BR FUTEX_FD " (present up to and including Linux 2.6.25)" |
fea681da MK |
152 | To support asynchronous wakeups, this operation associates a file descriptor |
153 | with a futex. | |
154 | .\" , suitable for .BR poll (2). | |
682edefb MK |
155 | If another process executes a |
156 | .BR FUTEX_WAKE , | |
157 | the process will receive the signal number that was passed in | |
fea681da MK |
158 | .IR val . |
159 | The calling process must close the returned file descriptor after use. | |
160 | The arguments | |
161 | .IR timeout , | |
162 | .I uaddr2 | |
163 | and | |
164 | .I val3 | |
165 | are ignored. | |
166 | ||
c13182ef | 167 | To prevent race conditions, the caller should test if the futex has |
682edefb MK |
168 | been upped after |
169 | .B FUTEX_FD | |
170 | returns. | |
266a5e91 | 171 | |
da36351e | 172 | Because it was inherently racy, |
682edefb | 173 | .B FUTEX_FD |
5fab2e7c | 174 | has been removed from Linux 2.6.26 onward. |
fea681da MK |
175 | .TP |
176 | .BR FUTEX_REQUEUE " (since Linux 2.5.70)" | |
177 | This operation was introduced in order to avoid a "thundering herd" effect | |
682edefb MK |
178 | when |
179 | .B FUTEX_WAKE | |
180 | is used and all processes woken up need to acquire another futex. | |
c13182ef | 181 | This call wakes up |
fea681da MK |
182 | .I val |
183 | processes, and requeues all other waiters on the futex at address | |
184 | .IR uaddr2 . | |
185 | The arguments | |
186 | .I timeout | |
187 | and | |
188 | .I val3 | |
189 | are ignored. | |
190 | .TP | |
191 | .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" | |
682edefb MK |
192 | There was a race in the intended use of |
193 | .BR FUTEX_REQUEUE , | |
194 | so | |
195 | .B FUTEX_CMP_REQUEUE | |
196 | was introduced. | |
197 | This is similar to | |
198 | .BR FUTEX_REQUEUE , | |
fea681da MK |
199 | but first checks whether the location |
200 | .I uaddr | |
201 | still contains the value | |
202 | .IR val3 . | |
e808bba0 MK |
203 | If not, the operation fails with the error |
204 | .BR EAGAIN . | |
fea681da MK |
205 | The argument |
206 | .I timeout | |
207 | is ignored. | |
47297adb | 208 | .SH RETURN VALUE |
fea681da | 209 | .PP |
e808bba0 MK |
210 | In the event of an error, all operations return \-1, and set |
211 | .I errno | |
212 | to indicate the error. | |
213 | The return value on success depends on the operation, | |
214 | as described in the following list: | |
fea681da MK |
215 | .TP |
216 | .B FUTEX_WAIT | |
682edefb MK |
217 | Returns 0 if the process was woken by a |
218 | .B FUTEX_WAKE | |
219 | call. | |
e808bba0 | 220 | See ERRORS for the various possible error returns. |
fea681da MK |
221 | .TP |
222 | .B FUTEX_WAKE | |
223 | Returns the number of processes woken up. | |
224 | .TP | |
225 | .B FUTEX_FD | |
226 | Returns the new file descriptor associated with the futex. | |
227 | .TP | |
228 | .B FUTEX_REQUEUE | |
229 | Returns the number of processes woken up. | |
230 | .TP | |
231 | .B FUTEX_CMP_REQUEUE | |
232 | Returns the number of processes woken up. | |
233 | .SH ERRORS | |
234 | .TP | |
235 | .B EACCES | |
236 | No read access to futex memory. | |
237 | .TP | |
238 | .B EAGAIN | |
682edefb | 239 | .B FUTEX_CMP_REQUEUE |
e808bba0 | 240 | detected that the value pointed to by |
9f6c40c0 МК |
241 | .I uaddr |
242 | is not equal to the expected value | |
243 | .IR val3 . | |
fea681da | 244 | (This probably indicates a race; |
682edefb MK |
245 | use the safe |
246 | .B FUTEX_WAKE | |
247 | now.) | |
fea681da MK |
248 | .TP |
249 | .B EFAULT | |
e808bba0 | 250 | Error retrieving |
fea681da | 251 | .I timeout |
7fac88a9 | 252 | information from user space. |
fea681da | 253 | .TP |
9f6c40c0 | 254 | .B EINTR |
e808bba0 | 255 | A |
9f6c40c0 | 256 | .B FUTEX_WAIT |
e808bba0 MK |
257 | operation was interrupted by a signal (see |
258 | .BR signal (7)) | |
259 | or a spurious wakeup. | |
9f6c40c0 | 260 | .TP |
fea681da | 261 | .B EINVAL |
4832b48a | 262 | Invalid argument. |
fea681da MK |
263 | .TP |
264 | .B ENFILE | |
265 | The system limit on the total number of open files has been reached. | |
4701fc28 MK |
266 | .TP |
267 | .B ENOSYS | |
268 | Invalid operation specified in | |
269 | .IR op . | |
9f6c40c0 МК |
270 | .TP |
271 | .B ETIMEDOUT | |
272 | Timeout during the | |
273 | .B FUTEX_WAIT | |
274 | operation. | |
275 | .TP | |
276 | .B EWOULDBLOCK | |
e808bba0 MK |
277 | .I op |
278 | was | |
279 | .BR FUTEX_WAIT | |
280 | and the value pointed to by | |
9f6c40c0 МК |
281 | .I uaddr |
282 | was not equal to the expected value | |
283 | .I val | |
e808bba0 | 284 | at the time of the call. |
47297adb | 285 | .SH VERSIONS |
a1d5f77c MK |
286 | .PP |
287 | Initial futex support was merged in Linux 2.5.7 but with different semantics | |
288 | from what was described above. | |
c4bb193f | 289 | A 4-argument system call with the semantics |
fd3fa7ef | 290 | described in this page was introduced in Linux 2.5.40. |
c4bb193f | 291 | In Linux 2.5.70 one argument |
a1d5f77c | 292 | was added. |
5503c85e | 293 | In Linux 2.6.7 a sixth argument was added\(emmessy, especially |
a1d5f77c | 294 | on the s390 architecture. |
47297adb | 295 | .SH CONFORMING TO |
8382f16d | 296 | This system call is Linux-specific. |
47297adb | 297 | .SH NOTES |
fea681da | 298 | .PP |
fcdad7d6 | 299 | To reiterate, bare futexes are not intended as an easy-to-use abstraction |
c13182ef | 300 | for end-users. |
fcdad7d6 | 301 | (There is no wrapper function for this system call in glibc.) |
c13182ef | 302 | Implementors are expected to be assembly literate and to have |
7fac88a9 | 303 | read the sources of the futex user-space library referenced below. |
fea681da MK |
304 | .\" .SH "AUTHORS" |
305 | .\" .PP | |
306 | .\" Futexes were designed and worked on by | |
307 | .\" Hubertus Franke (IBM Thomas J. Watson Research Center), | |
308 | .\" Matthew Kirkwood, Ingo Molnar (Red Hat) | |
309 | .\" and Rusty Russell (IBM Linux Technology Center). | |
310 | .\" This page written by bert hubert. | |
47297adb | 311 | .SH SEE ALSO |
14d8dd3b | 312 | .BR futex (7) |
fea681da | 313 | .PP |
52087dd3 | 314 | \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP |
9b936e9e MK |
315 | (proceedings of the Ottawa Linux Symposium 2002), online at |
316 | .br | |
608bf950 SK |
317 | .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf |
318 | .UE | |
9b936e9e MK |
319 | .PP |
320 | Futex example library, futex-*.tar.bz2 at | |
321 | .br | |
608bf950 SK |
322 | .UR ftp://ftp.nl.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
323 | .UE |