]>
Commit | Line | Data |
---|---|---|
8f0aff2a | 1 | .\" Page by b.hubert |
2297bf0e | 2 | .\" |
2e46a6e7 | 3 | .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) |
8f0aff2a | 4 | .\" may be freely modified and distributed |
8ff7380d | 5 | .\" %%%LICENSE_END |
fea681da MK |
6 | .\" |
7 | .\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com) | |
8 | .\" added ERRORS section. | |
9 | .\" | |
10 | .\" Modified 2004-06-17 mtk | |
11 | .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE | |
12 | .\" | |
c13182ef MK |
13 | .\" 2.6.18 adds (Ingo Molnar) priority inheritance support: |
14 | .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need | |
34f7665a MK |
15 | .\" to be documented in the manual page. Probably there is sufficient |
16 | .\" material in the kernel source file Documentation/pi-futex.txt. | |
4f58b197 MK |
17 | .\" commit c87e2837be82df479a6bae9f155c43516d2feebc |
18 | .\" Author: Ingo Molnar <mingo@elte.hu> | |
19 | .\" Date: Tue Jun 27 02:54:58 2006 -0700 | |
20 | .\" | |
21 | .\" commit e2970f2fb6950183a34e8545faa093eb49d186e1 | |
22 | .\" Author: Ingo Molnar <mingo@elte.hu> | |
23 | .\" Date: Tue Jun 27 02:54:47 2006 -0700 | |
24 | .\" | |
27b38e1c | 25 | .\" See Documentation/pi-futex.txt |
4f58b197 | 26 | .\" |
bea08fec | 27 | .\" FIXME . |
40d5cf23 | 28 | .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET |
4f58b197 MK |
29 | .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d |
30 | .\" Author: Thomas Gleixner <tglx@linutronix.de> | |
31 | .\" Date: Fri Feb 1 17:45:14 2008 +0100 | |
32 | .\" | |
bea08fec | 33 | .\" FIXME . |
4f58b197 MK |
34 | .\" 2.6.31 adds FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI |
35 | .\" commit 52400ba946759af28442dee6265c5c0180ac7122 | |
36 | .\" Author: Darren Hart <dvhltc@us.ibm.com> | |
37 | .\" Date: Fri Apr 3 13:40:49 2009 -0700 | |
38 | .\" | |
39 | .\" commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358 | |
40 | .\" Author: Darren Hart <dvhltc@us.ibm.com> | |
41 | .\" Date: Mon Apr 20 22:22:22 2009 -0700 | |
42 | .\" | |
43 | .\" See Documentation/futex-requeue-pi.txt | |
34f7665a | 44 | .\" |
3d155313 | 45 | .TH FUTEX 2 2014-05-21 "Linux" "Linux Programmer's Manual" |
fea681da | 46 | .SH NAME |
ce154705 | 47 | futex \- fast user-space locking |
fea681da | 48 | .SH SYNOPSIS |
9d9dc1e8 | 49 | .nf |
fea681da MK |
50 | .sp |
51 | .B "#include <linux/futex.h>" | |
fea681da MK |
52 | .B "#include <sys/time.h>" |
53 | .sp | |
d33602c4 MK |
54 | .BI "int futex(int *" uaddr ", int " futex_op ", int " val , |
55 | .BI " const struct timespec *" timeout , | |
9d9dc1e8 | 56 | .BI " int *" uaddr2 ", int " val3 ); |
fea681da | 57 | .\" int *? void *? u32 *? |
9d9dc1e8 | 58 | .fi |
409f08b0 | 59 | |
b939d6e4 MK |
60 | .IR Note : |
61 | There is no glibc wrapper for this system call; see NOTES. | |
47297adb | 62 | .SH DESCRIPTION |
fea681da MK |
63 | .PP |
64 | The | |
e511ffb6 | 65 | .BR futex () |
fea681da MK |
66 | system call provides a method for |
67 | a program to wait for a value at a given address to change, and a | |
68 | method to wake up anyone waiting on a particular address (while the | |
69 | addresses for the same memory in separate processes may not be | |
70 | equal, the kernel maps them internally so the same memory mapped in | |
71 | different locations will correspond for | |
e511ffb6 | 72 | .BR futex () |
c13182ef | 73 | calls). |
fd3fa7ef | 74 | This system call is typically used to |
fea681da MK |
75 | implement the contended case of a lock in shared memory, as |
76 | described in | |
a8bda636 | 77 | .BR futex (7). |
fea681da | 78 | .PP |
c13182ef | 79 | When a |
a8bda636 | 80 | .BR futex (7) |
7fac88a9 | 81 | operation did not finish uncontended in user space, a call needs to be made |
c13182ef MK |
82 | to the kernel to arbitrate. |
83 | Arbitration can either mean putting the calling | |
fea681da MK |
84 | process to sleep or, conversely, waking a waiting process. |
85 | .PP | |
86 | Callers of this function are expected to adhere to the semantics as set out in | |
a8bda636 | 87 | .BR futex (7). |
fea681da | 88 | As these |
d603cc27 | 89 | semantics involve writing nonportable assembly instructions, this in turn |
fea681da MK |
90 | probably means that most users will in fact be library authors and not |
91 | general application developers. | |
92 | .PP | |
93 | The | |
94 | .I uaddr | |
95 | argument needs to point to an aligned integer which stores the counter. | |
96 | The operation to execute is passed via the | |
97 | .I op | |
c4bb193f | 98 | argument, along with a value |
fea681da MK |
99 | .IR val . |
100 | .PP | |
6be4bad7 | 101 | The |
d33602c4 | 102 | .I futex_op |
6be4bad7 MK |
103 | argument consists of two parts: |
104 | a command that specifies the operation to be performed, | |
105 | bit-wise ORed with zero or or more options that | |
106 | modify the behaviour of the operation. | |
fc30eb79 | 107 | The options that may be included in |
d33602c4 | 108 | .I futex_op |
fc30eb79 TG |
109 | are as follows: |
110 | .TP | |
111 | .BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)" | |
112 | .\" commit 34f01cc1f512fa783302982776895c73714ebbc2 | |
113 | This option bit can be employed with all futex operations. | |
114 | It tells the kernel that the futex is process private and not shared | |
115 | with another process. | |
116 | This allows the kernel to choose the fast path for validating | |
117 | the user-space address and avoids expensive VMA lookups, | |
118 | taking reference counts on file backing store, and so on. | |
2e98bbc2 TG |
119 | .TP |
120 | .BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)" | |
121 | .\" commit 1acdac104668a0834cfa267de9946fac7764d486 | |
4a7e5b05 | 122 | This option bit can be employed only with the |
2e98bbc2 TG |
123 | .BR FUTEX_WAIT_BITSET |
124 | and | |
125 | .BR FUTEX_WAIT_REQUEUE_PI | |
126 | operations (described below). | |
127 | ||
128 | If this option is set, | |
129 | the kernel treats the user space supplied timeout as an absolute | |
130 | time based on | |
131 | .BR CLOCK_REALTIME . | |
132 | ||
133 | If this option is not set, | |
1c952cf5 MK |
134 | the kernel treats the user space supplied timeout as relative time, |
135 | .\" FIXME I added CLOCK_MONOTONIC here. Is it correct? | |
136 | measured against the | |
137 | .BR CLOCK_MONOTONIC | |
138 | clock. | |
6be4bad7 MK |
139 | .PP |
140 | The operation specified in | |
d33602c4 | 141 | .I futex_op |
6be4bad7 | 142 | is one of the following: |
fea681da | 143 | .TP |
81c9d87e MK |
144 | .BR FUTEX_WAIT " (since Linux 2.6.0)" |
145 | .\" Strictly speaking, since some time in 2.5.x | |
f065673c MK |
146 | This operation tests that the value at the |
147 | location pointed to by the futex address | |
fea681da MK |
148 | .I uaddr |
149 | still contains the value | |
150 | .IR val , | |
f065673c | 151 | and then sleeps awaiting |
682edefb | 152 | .B FUTEX_WAKE |
f065673c MK |
153 | on the futex address. |
154 | The test and sleep steps are performed atomically. | |
155 | If the futex value does not match | |
156 | .IR val , | |
157 | then the call returns immediately with the error | |
158 | .BR EWOULDBLOCK . | |
159 | .\" FIXME I added the following sentence. Please confirm that it is correct. | |
160 | The purpose of the test step is to detect races where | |
161 | another process changes that value of the futex between | |
162 | the time it was last checked and the time of the | |
163 | .BR FUTEX_WAIT | |
164 | oepration. | |
165 | ||
1909e523 | 166 | |
c13182ef | 167 | If the |
fea681da | 168 | .I timeout |
1c952cf5 MK |
169 | argument is non-NULL, its contents specify a relative timeout for the wait |
170 | .\" FIXME I added CLOCK_MONOTONIC here. Is it correct? | |
171 | measured according to the | |
172 | .BR CLOCK_MONOTONIC | |
173 | clock. | |
82a6092b MK |
174 | (This interval will be rounded up to the system clock granularity, |
175 | and kernel scheduling delays mean that the | |
176 | blocking interval may overrun by a small amount.) | |
177 | If | |
178 | .I timeout | |
179 | is NULL, the call blocks indefinitely. | |
4798a7f3 | 180 | |
c13182ef | 181 | The arguments |
fea681da MK |
182 | .I uaddr2 |
183 | and | |
184 | .I val3 | |
185 | are ignored. | |
186 | ||
187 | For | |
a8bda636 | 188 | .BR futex (7), |
fea681da MK |
189 | this call is executed if decrementing the count gave a negative value |
190 | (indicating contention), and will sleep until another process releases | |
682edefb MK |
191 | the futex and executes the |
192 | .B FUTEX_WAKE | |
193 | operation. | |
fea681da | 194 | .TP |
d67e21f5 MK |
195 | .BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)" |
196 | .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d | |
197 | .\" FIXME TO complete | |
198 | [As yet undocumented] | |
199 | .TP | |
81c9d87e MK |
200 | .BR FUTEX_WAKE " (since Linux 2.6.0)" |
201 | .\" Strictly speaking, since Linux 2.5.x | |
f065673c MK |
202 | This operation wakes at most |
203 | .I val | |
204 | processes waiting (i.e., inside | |
205 | .BR FUTEX_WAIT ) | |
206 | on the futex at the address | |
207 | .IR uaddr . | |
208 | Most commonly, | |
209 | .I val | |
210 | is specified as either 1 (wake up a single waiter) or | |
211 | .BR INT_MAX | |
212 | (wake up all waiters). | |
4798a7f3 | 213 | |
fea681da MK |
214 | The arguments |
215 | .IR timeout , | |
216 | .I uaddr2 | |
217 | and | |
218 | .I val3 | |
219 | are ignored. | |
220 | ||
221 | For | |
a8bda636 | 222 | .BR futex (7), |
fea681da MK |
223 | this is executed if incrementing |
224 | the count showed that there were waiters, once the futex value has been set | |
225 | to 1 (indicating that it is available). | |
6bac3b85 MK |
226 | .\" |
227 | .\" FIXME I added some FUTEX_WAKE_OP text, and I'd be happy if someone | |
228 | .\" checked it. | |
fea681da | 229 | .TP |
d67e21f5 MK |
230 | .BR FUTEX_WAKE_OP " (since Linux 2.6.14)" |
231 | .\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721 | |
6bac3b85 MK |
232 | .\" Author: Jakub Jelinek <jakub@redhat.com> |
233 | .\" Date: Tue Sep 6 15:16:25 2005 -0700 | |
234 | This operation was added to support some user-space use cases | |
235 | where more than one futex must be handled at the same time. | |
236 | The most notable example is the implementation of | |
237 | .BR pthread_cond_signal (3), | |
238 | which requires operations on two futexes, | |
239 | the one used to implement the mutex and the one used in the implementation | |
240 | of the wait queue associated with the condition variable. | |
241 | .BR FUTEX_WAKE_OP | |
242 | allows such cases to be implemented without leading to | |
243 | high rates of contention and context switching. | |
244 | ||
245 | The | |
246 | .BR FUTEX_WAIT_OP | |
247 | operation is equivalent to atomically executing the following code: | |
248 | ||
249 | .in +4n | |
250 | .nf | |
251 | int oldval = *(int *) uaddr2; | |
252 | *(int *) uaddr2 = oldval \fIop\fP \fIoparg\fP; | |
253 | futex(uaddr, FUTEX_WAKE, val, 0, 0, 0); | |
254 | if (oldval \fIcmp\fP \fIcmparg\fP) | |
255 | futex(uaddr2, FUTEX_WAKE, nr_wake2, 0, 0, 0); | |
256 | .fi | |
257 | .in | |
258 | ||
259 | In other words, | |
260 | .BR FUTEX_WAIT_OP | |
261 | does the following: | |
262 | .RS | |
263 | .IP * 3 | |
264 | saves the original value of the futex at | |
265 | .IR uaddr2 ; | |
266 | .IP * | |
267 | performs an operation to modify the value of the futex at | |
268 | .IR uaddr2 ; | |
269 | .IP * | |
270 | wakes up a maximum of | |
271 | .I val | |
272 | waiters on the futex | |
273 | .IR uaddr ; | |
274 | and | |
275 | .IP * | |
276 | dependent on the results of a test of the original value of the futex at | |
277 | .IR uaddr2 , | |
278 | wakes up a maximum of | |
279 | .I nr_wake2 | |
280 | waiters on the futex | |
281 | .IR uaddr2 . | |
282 | .RE | |
283 | .IP | |
284 | The | |
285 | .I nr_wake2 | |
286 | value is actually the | |
287 | .BR futex () | |
288 | .I timeout | |
289 | argument (ab)used to specify how many of the waiters on the futex at | |
290 | .IR uaddr2 | |
291 | are to be woken up; | |
292 | the kernel casts the | |
293 | .I timeout | |
294 | value to | |
295 | .IR u32 . | |
296 | ||
297 | The operation and comparison that are to be performed are encoded | |
298 | in the bits of the argument | |
299 | .IR val3 . | |
300 | Pictorially, the encoding is: | |
301 | ||
302 | .in +4n | |
303 | .nf | |
304 | +-----+-----+---------------+---------------+ | |
305 | | op | cmp | oparg | cmparg | | |
306 | +-----+-----+---------------+---------------+ | |
307 | # of bits: 4 4 12 12 | |
308 | ||
309 | .fi | |
310 | .in | |
311 | ||
312 | Expressed in code, the encoding is: | |
313 | ||
314 | .in +4n | |
315 | .nf | |
316 | #define FUTEX_OP(op, oparg, cmp, cmparg) \\ | |
317 | (((op & 0xf) << 28) | \\ | |
318 | ((cmp & 0xf) << 24) | \\ | |
319 | ((oparg & 0xfff) << 12) | \\ | |
320 | (cmparg & 0xfff)) | |
321 | .fi | |
322 | .in | |
323 | ||
324 | In the above, | |
325 | .I op | |
326 | and | |
327 | .I cmp | |
328 | are each one of the codes listed below. | |
329 | The | |
330 | .I oparg | |
331 | and | |
332 | .I cmparg | |
333 | components are literal numeric values, except as noted below. | |
334 | ||
335 | The | |
336 | .I op | |
337 | component has one of the following values: | |
338 | ||
339 | .in +4n | |
340 | .nf | |
341 | FUTEX_OP_SET 0 /* uaddr2 = oparg; */ | |
342 | FUTEX_OP_ADD 1 /* uaddr2 += oparg; */ | |
343 | FUTEX_OP_OR 2 /* uaddr2 |= oparg; */ | |
344 | FUTEX_OP_ANDN 3 /* uaddr2 &= ~oparg; */ | |
345 | FUTEX_OP_XOR 4 /* uaddr2 ^= oparg; */ | |
346 | .fi | |
347 | .in | |
348 | ||
349 | In addition, bit-wise ORing the following value into | |
350 | .I op | |
351 | causes | |
352 | .IR "(1\ <<\ oparg)" | |
353 | to be used as the operand: | |
354 | ||
355 | .in +4n | |
356 | .nf | |
357 | FUTEX_OP_ARG_SHIFT 8 /* Use (1 << oparg) as operand */ | |
358 | .fi | |
359 | .in | |
360 | ||
361 | The | |
362 | .I cmp | |
363 | field is one of the following: | |
364 | ||
365 | .in +4n | |
366 | .nf | |
367 | FUTEX_OP_CMP_EQ 0 /* if (oldval == cmparg) wake */ | |
368 | FUTEX_OP_CMP_NE 1 /* if (oldval != cmparg) wake */ | |
369 | FUTEX_OP_CMP_LT 2 /* if (oldval < cmparg) wake */ | |
370 | FUTEX_OP_CMP_LE 3 /* if (oldval <= cmparg) wake */ | |
371 | FUTEX_OP_CMP_GT 4 /* if (oldval > cmparg) wake */ | |
372 | FUTEX_OP_CMP_GE 5 /* if (oldval >= cmparg) wake */ | |
373 | .fi | |
374 | .in | |
375 | ||
376 | The return value of | |
377 | .BR FUTEX_WAKE_OP | |
378 | is the sum of the number of waiters woken on the futex | |
379 | .IR uaddr | |
380 | plus the number of waiters woken on the futex | |
381 | .IR uaddr2 . | |
d67e21f5 MK |
382 | .TP |
383 | .BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)" | |
384 | .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d | |
385 | .\" FIXME TO complete | |
386 | [As yet undocumented] | |
387 | .TP | |
388 | .BR FUTEX_LOCK_PI " (since Linux 2.6.18)" | |
389 | .\" commit c87e2837be82df479a6bae9f155c43516d2feebc | |
390 | .\" FIXME to complete | |
391 | [As yet undocumented] | |
392 | .TP | |
393 | .BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)" | |
394 | .\" commit c87e2837be82df479a6bae9f155c43516d2feebc | |
395 | .\" FIXME to complete | |
396 | [As yet undocumented] | |
397 | .TP | |
398 | .BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)" | |
399 | .\" commit c87e2837be82df479a6bae9f155c43516d2feebc | |
400 | .\" FIXME to complete | |
401 | [As yet undocumented] | |
402 | .TP | |
81c9d87e MK |
403 | .BR FUTEX_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)" |
404 | .\" Strictly speaking, from Linux 2.5.x to 2.6.25 | |
fea681da MK |
405 | To support asynchronous wakeups, this operation associates a file descriptor |
406 | with a futex. | |
407 | .\" , suitable for .BR poll (2). | |
682edefb MK |
408 | If another process executes a |
409 | .BR FUTEX_WAKE , | |
410 | the process will receive the signal number that was passed in | |
fea681da MK |
411 | .IR val . |
412 | The calling process must close the returned file descriptor after use. | |
4798a7f3 | 413 | |
fea681da MK |
414 | The arguments |
415 | .IR timeout , | |
416 | .I uaddr2 | |
417 | and | |
418 | .I val3 | |
419 | are ignored. | |
420 | ||
c13182ef | 421 | To prevent race conditions, the caller should test if the futex has |
682edefb MK |
422 | been upped after |
423 | .B FUTEX_FD | |
424 | returns. | |
266a5e91 | 425 | |
da36351e | 426 | Because it was inherently racy, |
682edefb | 427 | .B FUTEX_FD |
5fab2e7c | 428 | has been removed from Linux 2.6.26 onward. |
fea681da | 429 | .TP |
81c9d87e MK |
430 | .BR FUTEX_REQUEUE " (since Linux 2.6.0)" |
431 | .\" Strictly speaking: from Linux 2.5.70 | |
4ac63a6c MK |
432 | .\" |
433 | .\" FIXME I added this warning. Okay? | |
434 | .IR "Avoid using this operation" . | |
dd05d612 | 435 | It is broken (unavoidably racy) for its intended purpose. |
4ac63a6c MK |
436 | Use |
437 | .BR FUTEX_CMP_REQUEUE | |
438 | instead. | |
439 | ||
dd05d612 MK |
440 | This operation performs the same task as |
441 | .BR FUTEX_CMP_REQUEUE , | |
442 | except that no check is made using the value in | |
443 | .IR val3 . | |
444 | (The argument | |
fea681da | 445 | .I val3 |
dd05d612 | 446 | is ignored.) |
fea681da MK |
447 | .TP |
448 | .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" | |
3dfcc11d | 449 | This operation was added as a replacement for the earlier |
682edefb | 450 | .BR FUTEX_REQUEUE , |
3dfcc11d MK |
451 | because that operation was racy for its intended use. |
452 | ||
453 | As with | |
682edefb | 454 | .BR FUTEX_REQUEUE , |
3dfcc11d MK |
455 | the |
456 | .BR FUTEX_CMP_REQUEUE | |
457 | operation is used to avoid a "thundering herd" effect when | |
458 | .B FUTEX_WAKE | |
459 | is used and all processes woken up need to acquire another futex. | |
460 | It differs from | |
461 | .BR FUTEX_REQUEUE | |
462 | in that it first checks whether the location | |
fea681da MK |
463 | .I uaddr |
464 | still contains the value | |
465 | .IR val3 . | |
e808bba0 MK |
466 | If not, the operation fails with the error |
467 | .BR EAGAIN . | |
3dfcc11d MK |
468 | .\" FIXME I added the following sentence on rational for FUTEX_CMP_REQUEUE. |
469 | .\" Is it correct? SHould it be expanded? | |
470 | This additional feature of | |
471 | .BR FUTEX_CMP_REQUEUE | |
472 | can be used by the caller to (atomically) detect changes | |
473 | in the value of the target futex at | |
474 | .IR uaddr2 . | |
4798a7f3 | 475 | |
3dfcc11d MK |
476 | The operation wakes up a maximum of |
477 | .I val | |
478 | waiters that are waiting on the futex at | |
479 | .IR uaddr . | |
480 | If there are more than | |
481 | .I val | |
482 | waiters, then the remaining waiters are removed | |
483 | from the wait queue of the source futex at | |
484 | .I uaddr | |
485 | and added to the wait queue of the target futex at | |
486 | .IR uaddr2 . | |
487 | The | |
488 | .I timeout | |
489 | argument is (ab)used to specify a cap on the number of waiters | |
490 | that are requeued to the futex at | |
491 | .IR uaddr2 ; | |
492 | the kernel casts the | |
fea681da | 493 | .I timeout |
3dfcc11d MK |
494 | value to |
495 | .IR u32 . | |
496 | ||
497 | .\" FIXME Please review the following new paragraph to see if it is | |
498 | .\" accurate. | |
499 | Typical values to specify for | |
500 | .I val | |
501 | are 0 or or 1. | |
502 | (Specifying | |
503 | .BR INT_MAX | |
504 | is not useful, because it would make the | |
505 | .BR FUTEX_CMP_REQUEUE | |
506 | operation equivalent to | |
507 | .BR FUTEX_WAKE .) | |
508 | The cap value specified via the (abused) | |
509 | .I timeout | |
510 | argument is typically either 1 or | |
511 | .BR INT_MAX . | |
512 | (Specifying the argument as 0 is not useful, because it would make the | |
513 | .BR FUTEX_CMP_REQUEUE | |
514 | operation equivalent to | |
515 | .BR FUTEX_WAIT .) | |
d67e21f5 MK |
516 | .TP |
517 | .BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)" | |
518 | .\" commit 52400ba946759af28442dee6265c5c0180ac7122 | |
519 | .\" FIXME to complete | |
520 | [As yet undocumented] | |
521 | .TP | |
522 | .BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)" | |
523 | .\" commit 52400ba946759af28442dee6265c5c0180ac7122 | |
524 | .\" FIXME to complete | |
525 | [As yet undocumented] | |
47297adb | 526 | .SH RETURN VALUE |
fea681da | 527 | .PP |
e808bba0 MK |
528 | In the event of an error, all operations return \-1, and set |
529 | .I errno | |
530 | to indicate the error. | |
531 | The return value on success depends on the operation, | |
532 | as described in the following list: | |
fea681da MK |
533 | .TP |
534 | .B FUTEX_WAIT | |
682edefb MK |
535 | Returns 0 if the process was woken by a |
536 | .B FUTEX_WAKE | |
537 | call. | |
e808bba0 | 538 | See ERRORS for the various possible error returns. |
fea681da MK |
539 | .TP |
540 | .B FUTEX_WAKE | |
541 | Returns the number of processes woken up. | |
542 | .TP | |
543 | .B FUTEX_FD | |
544 | Returns the new file descriptor associated with the futex. | |
545 | .TP | |
546 | .B FUTEX_REQUEUE | |
547 | Returns the number of processes woken up. | |
548 | .TP | |
549 | .B FUTEX_CMP_REQUEUE | |
3dfcc11d MK |
550 | Returns the total number of processes woken up or requeued to the futex at |
551 | .IR uaddr2 . | |
552 | If this value is greater than | |
553 | .IR val , | |
554 | then difference is the number of waiters requeued to the futex at | |
555 | .IR uaddr2 . | |
519f2c3d MK |
556 | .\" |
557 | .\" FIXME Add success returns for other operations | |
fea681da MK |
558 | .SH ERRORS |
559 | .TP | |
560 | .B EACCES | |
561 | No read access to futex memory. | |
562 | .TP | |
563 | .B EAGAIN | |
682edefb | 564 | .B FUTEX_CMP_REQUEUE |
e808bba0 | 565 | detected that the value pointed to by |
9f6c40c0 МК |
566 | .I uaddr |
567 | is not equal to the expected value | |
568 | .IR val3 . | |
fd1dc4c2 | 569 | .\" FIXME: Is the following sentence correct? |
fea681da | 570 | (This probably indicates a race; |
682edefb MK |
571 | use the safe |
572 | .B FUTEX_WAKE | |
573 | now.) | |
fea681da MK |
574 | .TP |
575 | .B EFAULT | |
1ea901e8 MK |
576 | A required pointer argument (i.e., |
577 | .IR uaddr , | |
578 | .IR uaddr2 , | |
579 | or | |
580 | .IR timeout ) | |
496df304 | 581 | did not point to a valid user-space address. |
fea681da | 582 | .TP |
9f6c40c0 | 583 | .B EINTR |
e808bba0 | 584 | A |
9f6c40c0 | 585 | .B FUTEX_WAIT |
e808bba0 MK |
586 | operation was interrupted by a signal (see |
587 | .BR signal (7)) | |
588 | or a spurious wakeup. | |
9f6c40c0 | 589 | .TP |
fea681da | 590 | .B EINVAL |
fb2f4c27 MK |
591 | .RB ( FUTEX_WAIT , |
592 | .BR FUTEX_WAIT_REQUEUE_PI ) | |
593 | The supplied | |
594 | .I timeout | |
595 | argument was invalid | |
596 | .RI ( tv_sec | |
597 | was less than zero, or | |
598 | .IR tv_nsec | |
599 | was not less than 1000,000,000). | |
600 | .TP | |
601 | .B EINVAL | |
ea355b7f | 602 | .RB ( FUTEX_WAIT , |
caf1ff25 | 603 | .BR FUTEX_WAKE , |
6bac3b85 | 604 | .BR FUTEX_WAKE_OP , |
a1f47699 MK |
605 | .BR FUTEX_REQUEUE , |
606 | .BR FUTEX_CMP_REQUEUE ) | |
51ee94be | 607 | .I uaddr |
caf1ff25 | 608 | or (for |
a1f47699 MK |
609 | .BR FUTEX_REQUEUE |
610 | and | |
611 | .BR FUTEX_CMP_REQUEUE ) | |
caf1ff25 | 612 | .I uaddr2 |
51ee94be MK |
613 | does not point to a valid object\(emthat is, |
614 | the address is not 4-byte-aligned. | |
615 | .TP | |
616 | .B EINVAL | |
bae14b6c | 617 | .RB ( FUTEX_WAKE , |
e169277f MK |
618 | .BR FUTEX_REQUEUE , |
619 | .BR FUTEX_CMP_REQUEUE ) | |
496df304 | 620 | The kernel detected an inconsistency between the user-space state at |
9534086b TG |
621 | .I uaddr |
622 | and the kernel state\(emthat is, it detected a waiter which waits in | |
623 | .BR FUTEX_LOCK_PI . | |
624 | .TP | |
625 | .B EINVAL | |
add875c0 MK |
626 | .RB ( FUTEX_REQUEUE ) |
627 | .\" FIXME tglx suggested adding this, but does this error really | |
628 | .\" occur for FUTEX_REQUEUE? | |
629 | .I uaddr | |
630 | equals | |
631 | .IR uaddr2 | |
632 | (i.e., an attempt was made to requeue to the same futex). | |
633 | .TP | |
634 | .B EINVAL | |
6bac3b85 MK |
635 | .RB ( FUTEX_WAKE_OP ) |
636 | The kernel detected an inconsistency between the user-space state at | |
637 | .I uaddr | |
638 | and the kernel state; that is, it detected a waiter which waits in | |
639 | .B FUTEX_LOCK_PI | |
640 | on | |
641 | .IR uaddr . | |
642 | .TP | |
643 | .B EINVAL | |
4832b48a | 644 | Invalid argument. |
fea681da MK |
645 | .TP |
646 | .B ENFILE | |
647 | The system limit on the total number of open files has been reached. | |
4701fc28 MK |
648 | .TP |
649 | .B ENOSYS | |
650 | Invalid operation specified in | |
d33602c4 | 651 | .IR futex_op . |
9f6c40c0 | 652 | .TP |
4a7e5b05 MK |
653 | .B ENOSYS |
654 | The | |
655 | .BR FUTEX_CLOCK_REALTIME | |
656 | option was specified in | |
d33602c4 | 657 | .I futex_op , |
4a7e5b05 MK |
658 | but the accompanying operation was neither |
659 | .BR FUTEX_WAIT_BITSET | |
660 | nor | |
661 | .BR FUTEX_WAIT_REQUEUE_PI . | |
662 | .TP | |
9f6c40c0 | 663 | .B ETIMEDOUT |
d1926d78 MK |
664 | .RB ( FUTEX_WAIT ) |
665 | The operation timed out. | |
9f6c40c0 МК |
666 | .TP |
667 | .B EWOULDBLOCK | |
d33602c4 | 668 | .I futex_op |
e808bba0 MK |
669 | was |
670 | .BR FUTEX_WAIT | |
671 | and the value pointed to by | |
9f6c40c0 МК |
672 | .I uaddr |
673 | was not equal to the expected value | |
674 | .I val | |
e808bba0 | 675 | at the time of the call. |
47297adb | 676 | .SH VERSIONS |
a1d5f77c | 677 | .PP |
81c9d87e MK |
678 | Futexes were first made available in a stable kernel release |
679 | with Linux 2.6.0. | |
680 | ||
a1d5f77c MK |
681 | Initial futex support was merged in Linux 2.5.7 but with different semantics |
682 | from what was described above. | |
c4bb193f | 683 | A 4-argument system call with the semantics |
fd3fa7ef | 684 | described in this page was introduced in Linux 2.5.40. |
11b520ed | 685 | In Linux 2.5.70, one argument |
a1d5f77c | 686 | was added. |
11b520ed | 687 | In Linux 2.6.7, a sixth argument was added\(emmessy, especially |
a1d5f77c | 688 | on the s390 architecture. |
47297adb | 689 | .SH CONFORMING TO |
8382f16d | 690 | This system call is Linux-specific. |
47297adb | 691 | .SH NOTES |
fea681da | 692 | .PP |
fcdad7d6 | 693 | To reiterate, bare futexes are not intended as an easy-to-use abstraction |
c13182ef | 694 | for end-users. |
fcdad7d6 | 695 | (There is no wrapper function for this system call in glibc.) |
c13182ef | 696 | Implementors are expected to be assembly literate and to have |
7fac88a9 | 697 | read the sources of the futex user-space library referenced below. |
d282bb24 | 698 | .\" .SH AUTHORS |
fea681da MK |
699 | .\" .PP |
700 | .\" Futexes were designed and worked on by | |
701 | .\" Hubertus Franke (IBM Thomas J. Watson Research Center), | |
702 | .\" Matthew Kirkwood, Ingo Molnar (Red Hat) | |
703 | .\" and Rusty Russell (IBM Linux Technology Center). | |
704 | .\" This page written by bert hubert. | |
47297adb | 705 | .SH SEE ALSO |
d806bc05 | 706 | .BR restart_syscall (2), |
14d8dd3b | 707 | .BR futex (7) |
fea681da | 708 | .PP |
52087dd3 | 709 | \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP |
9b936e9e MK |
710 | (proceedings of the Ottawa Linux Symposium 2002), online at |
711 | .br | |
608bf950 SK |
712 | .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf |
713 | .UE | |
f42eb21b MK |
714 | |
715 | \fIFutexes Are Tricky\fP (updated in 2011), Ulrich Drepper | |
716 | .UR http://www.akkadia.org/drepper/futex.pdf | |
717 | .UE | |
9b936e9e MK |
718 | .PP |
719 | Futex example library, futex-*.tar.bz2 at | |
720 | .br | |
a605264d | 721 | .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
608bf950 | 722 | .UE |