]>
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 | .\" | |
bea08fec | 13 | .\" FIXME . |
4f58b197 | 14 | .\" See also https://bugzilla.kernel.org/show_bug.cgi?id=14303 |
40d5cf23 | 15 | .\" 2.6.14 adds FUTEX_WAKE_OP |
4f58b197 MK |
16 | .\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721 |
17 | .\" Author: Jakub Jelinek <jakub@redhat.com> | |
18 | .\" Date: Tue Sep 6 15:16:25 2005 -0700 | |
19 | .\" | |
bea08fec | 20 | .\" FIXME . |
c13182ef MK |
21 | .\" 2.6.18 adds (Ingo Molnar) priority inheritance support: |
22 | .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need | |
34f7665a MK |
23 | .\" to be documented in the manual page. Probably there is sufficient |
24 | .\" material in the kernel source file Documentation/pi-futex.txt. | |
4f58b197 MK |
25 | .\" commit c87e2837be82df479a6bae9f155c43516d2feebc |
26 | .\" Author: Ingo Molnar <mingo@elte.hu> | |
27 | .\" Date: Tue Jun 27 02:54:58 2006 -0700 | |
28 | .\" | |
29 | .\" commit e2970f2fb6950183a34e8545faa093eb49d186e1 | |
30 | .\" Author: Ingo Molnar <mingo@elte.hu> | |
31 | .\" Date: Tue Jun 27 02:54:47 2006 -0700 | |
32 | .\" | |
27b38e1c | 33 | .\" See Documentation/pi-futex.txt |
4f58b197 | 34 | .\" |
bea08fec | 35 | .\" FIXME . |
40d5cf23 | 36 | .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET |
4f58b197 MK |
37 | .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d |
38 | .\" Author: Thomas Gleixner <tglx@linutronix.de> | |
39 | .\" Date: Fri Feb 1 17:45:14 2008 +0100 | |
40 | .\" | |
bea08fec | 41 | .\" FIXME . |
4f58b197 MK |
42 | .\" 2.6.31 adds FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI |
43 | .\" commit 52400ba946759af28442dee6265c5c0180ac7122 | |
44 | .\" Author: Darren Hart <dvhltc@us.ibm.com> | |
45 | .\" Date: Fri Apr 3 13:40:49 2009 -0700 | |
46 | .\" | |
47 | .\" commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358 | |
48 | .\" Author: Darren Hart <dvhltc@us.ibm.com> | |
49 | .\" Date: Mon Apr 20 22:22:22 2009 -0700 | |
50 | .\" | |
51 | .\" See Documentation/futex-requeue-pi.txt | |
34f7665a | 52 | .\" |
3d155313 | 53 | .TH FUTEX 2 2014-05-21 "Linux" "Linux Programmer's Manual" |
fea681da | 54 | .SH NAME |
ce154705 | 55 | futex \- fast user-space locking |
fea681da | 56 | .SH SYNOPSIS |
9d9dc1e8 | 57 | .nf |
fea681da MK |
58 | .sp |
59 | .B "#include <linux/futex.h>" | |
fea681da MK |
60 | .B "#include <sys/time.h>" |
61 | .sp | |
9d9dc1e8 MK |
62 | .BI "int futex(int *" uaddr ", int " op ", int " val \ |
63 | ", const struct timespec *" timeout , | |
64 | .br | |
65 | .BI " int *" uaddr2 ", int " val3 ); | |
fea681da | 66 | .\" int *? void *? u32 *? |
9d9dc1e8 | 67 | .fi |
409f08b0 | 68 | |
b939d6e4 MK |
69 | .IR Note : |
70 | There is no glibc wrapper for this system call; see NOTES. | |
47297adb | 71 | .SH DESCRIPTION |
fea681da MK |
72 | .PP |
73 | The | |
e511ffb6 | 74 | .BR futex () |
fea681da MK |
75 | system call provides a method for |
76 | a program to wait for a value at a given address to change, and a | |
77 | method to wake up anyone waiting on a particular address (while the | |
78 | addresses for the same memory in separate processes may not be | |
79 | equal, the kernel maps them internally so the same memory mapped in | |
80 | different locations will correspond for | |
e511ffb6 | 81 | .BR futex () |
c13182ef | 82 | calls). |
fd3fa7ef | 83 | This system call is typically used to |
fea681da MK |
84 | implement the contended case of a lock in shared memory, as |
85 | described in | |
a8bda636 | 86 | .BR futex (7). |
fea681da | 87 | .PP |
c13182ef | 88 | When a |
a8bda636 | 89 | .BR futex (7) |
7fac88a9 | 90 | operation did not finish uncontended in user space, a call needs to be made |
c13182ef MK |
91 | to the kernel to arbitrate. |
92 | Arbitration can either mean putting the calling | |
fea681da MK |
93 | process to sleep or, conversely, waking a waiting process. |
94 | .PP | |
95 | Callers of this function are expected to adhere to the semantics as set out in | |
a8bda636 | 96 | .BR futex (7). |
fea681da | 97 | As these |
d603cc27 | 98 | semantics involve writing nonportable assembly instructions, this in turn |
fea681da MK |
99 | probably means that most users will in fact be library authors and not |
100 | general application developers. | |
101 | .PP | |
102 | The | |
103 | .I uaddr | |
104 | argument needs to point to an aligned integer which stores the counter. | |
105 | The operation to execute is passed via the | |
106 | .I op | |
c4bb193f | 107 | argument, along with a value |
fea681da MK |
108 | .IR val . |
109 | .PP | |
6be4bad7 MK |
110 | The |
111 | .I op | |
112 | argument consists of two parts: | |
113 | a command that specifies the operation to be performed, | |
114 | bit-wise ORed with zero or or more options that | |
115 | modify the behaviour of the operation. | |
fc30eb79 TG |
116 | The options that may be included in |
117 | .I op | |
118 | are as follows: | |
119 | .TP | |
120 | .BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)" | |
121 | .\" commit 34f01cc1f512fa783302982776895c73714ebbc2 | |
122 | This option bit can be employed with all futex operations. | |
123 | It tells the kernel that the futex is process private and not shared | |
124 | with another process. | |
125 | This allows the kernel to choose the fast path for validating | |
126 | the user-space address and avoids expensive VMA lookups, | |
127 | taking reference counts on file backing store, and so on. | |
2e98bbc2 TG |
128 | .TP |
129 | .BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)" | |
130 | .\" commit 1acdac104668a0834cfa267de9946fac7764d486 | |
131 | This option bit can be employed with the | |
132 | .BR FUTEX_WAIT_BITSET | |
133 | and | |
134 | .BR FUTEX_WAIT_REQUEUE_PI | |
135 | operations (described below). | |
136 | ||
137 | If this option is set, | |
138 | the kernel treats the user space supplied timeout as an absolute | |
139 | time based on | |
140 | .BR CLOCK_REALTIME . | |
141 | ||
142 | If this option is not set, | |
143 | the kernel treats the user space supplied timeout as relative time. | |
144 | ||
145 | If this is set on any other operation than the supported ones, | |
146 | the kernel returns ENOSYS! | |
6be4bad7 MK |
147 | .PP |
148 | The operation specified in | |
149 | .I op | |
150 | is one of the following: | |
fea681da MK |
151 | .TP |
152 | .B FUTEX_WAIT | |
153 | This operation atomically verifies that the futex address | |
154 | .I uaddr | |
155 | still contains the value | |
156 | .IR val , | |
682edefb MK |
157 | and sleeps awaiting |
158 | .B FUTEX_WAKE | |
159 | on this futex address. | |
c13182ef | 160 | If the |
fea681da | 161 | .I timeout |
82a6092b MK |
162 | argument is non-NULL, its contents specify the duration of the wait. |
163 | (This interval will be rounded up to the system clock granularity, | |
164 | and kernel scheduling delays mean that the | |
165 | blocking interval may overrun by a small amount.) | |
166 | If | |
167 | .I timeout | |
168 | is NULL, the call blocks indefinitely. | |
4798a7f3 | 169 | |
c13182ef | 170 | The arguments |
fea681da MK |
171 | .I uaddr2 |
172 | and | |
173 | .I val3 | |
174 | are ignored. | |
175 | ||
176 | For | |
a8bda636 | 177 | .BR futex (7), |
fea681da MK |
178 | this call is executed if decrementing the count gave a negative value |
179 | (indicating contention), and will sleep until another process releases | |
682edefb MK |
180 | the futex and executes the |
181 | .B FUTEX_WAKE | |
182 | operation. | |
fea681da MK |
183 | .TP |
184 | .B FUTEX_WAKE | |
a8d55537 | 185 | This operation wakes at most \fIval\fP |
b87dcfb9 | 186 | processes waiting on this futex address (i.e., inside |
682edefb | 187 | .BR FUTEX_WAIT ). |
4798a7f3 | 188 | |
fea681da MK |
189 | The arguments |
190 | .IR timeout , | |
191 | .I uaddr2 | |
192 | and | |
193 | .I val3 | |
194 | are ignored. | |
195 | ||
196 | For | |
a8bda636 | 197 | .BR futex (7), |
fea681da MK |
198 | this is executed if incrementing |
199 | the count showed that there were waiters, once the futex value has been set | |
200 | to 1 (indicating that it is available). | |
201 | .TP | |
da36351e | 202 | .BR FUTEX_FD " (present up to and including Linux 2.6.25)" |
fea681da MK |
203 | To support asynchronous wakeups, this operation associates a file descriptor |
204 | with a futex. | |
205 | .\" , suitable for .BR poll (2). | |
682edefb MK |
206 | If another process executes a |
207 | .BR FUTEX_WAKE , | |
208 | the process will receive the signal number that was passed in | |
fea681da MK |
209 | .IR val . |
210 | The calling process must close the returned file descriptor after use. | |
4798a7f3 | 211 | |
fea681da MK |
212 | The arguments |
213 | .IR timeout , | |
214 | .I uaddr2 | |
215 | and | |
216 | .I val3 | |
217 | are ignored. | |
218 | ||
c13182ef | 219 | To prevent race conditions, the caller should test if the futex has |
682edefb MK |
220 | been upped after |
221 | .B FUTEX_FD | |
222 | returns. | |
266a5e91 | 223 | |
da36351e | 224 | Because it was inherently racy, |
682edefb | 225 | .B FUTEX_FD |
5fab2e7c | 226 | has been removed from Linux 2.6.26 onward. |
fea681da MK |
227 | .TP |
228 | .BR FUTEX_REQUEUE " (since Linux 2.5.70)" | |
229 | This operation was introduced in order to avoid a "thundering herd" effect | |
682edefb MK |
230 | when |
231 | .B FUTEX_WAKE | |
232 | is used and all processes woken up need to acquire another futex. | |
2abb73b9 | 233 | The argument |
fea681da | 234 | .I val |
2abb73b9 TG |
235 | contains the number of waiters on |
236 | .I uaddr | |
237 | that are immediately woken up. | |
238 | The | |
fea681da | 239 | .I timeout |
2abb73b9 TG |
240 | argument is (ab)used to specify the number of waiters |
241 | that are requeued to the futex at | |
242 | .IR uaddr2 ; | |
243 | the kernel casts the | |
244 | .I timeout | |
245 | value to | |
246 | .IR u32 . | |
247 | .\" FIXME What are the constraints (if any) on the values of 'val' vs | |
248 | .\" 'timeout' vs [the number of waites on 'uaddr']? | |
249 | ||
250 | The argument | |
fea681da | 251 | .I val3 |
2abb73b9 | 252 | is ignored. |
fea681da MK |
253 | .TP |
254 | .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" | |
682edefb MK |
255 | There was a race in the intended use of |
256 | .BR FUTEX_REQUEUE , | |
257 | so | |
258 | .B FUTEX_CMP_REQUEUE | |
259 | was introduced. | |
a72a3aeb | 260 | .\" FIXME should there be a statement in the description of FUTEX_REQUEUE |
a1f47699 | 261 | .\" to say that it should be avoided in favor of FUTEX_CMP_REQUEUE? |
03433acb | 262 | This operation is similar to |
682edefb | 263 | .BR FUTEX_REQUEUE , |
fea681da MK |
264 | but first checks whether the location |
265 | .I uaddr | |
266 | still contains the value | |
267 | .IR val3 . | |
e808bba0 MK |
268 | If not, the operation fails with the error |
269 | .BR EAGAIN . | |
4798a7f3 | 270 | |
03433acb MK |
271 | The arguments |
272 | .IR val , | |
273 | .IR uaddr , | |
274 | .IR uaddr2 , | |
275 | and | |
fea681da | 276 | .I timeout |
03433acb MK |
277 | are as for |
278 | .BR FUTEX_REQUEUE . | |
47297adb | 279 | .SH RETURN VALUE |
fea681da | 280 | .PP |
e808bba0 MK |
281 | In the event of an error, all operations return \-1, and set |
282 | .I errno | |
283 | to indicate the error. | |
284 | The return value on success depends on the operation, | |
285 | as described in the following list: | |
fea681da MK |
286 | .TP |
287 | .B FUTEX_WAIT | |
682edefb MK |
288 | Returns 0 if the process was woken by a |
289 | .B FUTEX_WAKE | |
290 | call. | |
e808bba0 | 291 | See ERRORS for the various possible error returns. |
fea681da MK |
292 | .TP |
293 | .B FUTEX_WAKE | |
294 | Returns the number of processes woken up. | |
295 | .TP | |
296 | .B FUTEX_FD | |
297 | Returns the new file descriptor associated with the futex. | |
298 | .TP | |
299 | .B FUTEX_REQUEUE | |
300 | Returns the number of processes woken up. | |
301 | .TP | |
302 | .B FUTEX_CMP_REQUEUE | |
303 | Returns the number of processes woken up. | |
304 | .SH ERRORS | |
305 | .TP | |
306 | .B EACCES | |
307 | No read access to futex memory. | |
308 | .TP | |
309 | .B EAGAIN | |
682edefb | 310 | .B FUTEX_CMP_REQUEUE |
e808bba0 | 311 | detected that the value pointed to by |
9f6c40c0 МК |
312 | .I uaddr |
313 | is not equal to the expected value | |
314 | .IR val3 . | |
fd1dc4c2 | 315 | .\" FIXME: Is the following sentence correct? |
fea681da | 316 | (This probably indicates a race; |
682edefb MK |
317 | use the safe |
318 | .B FUTEX_WAKE | |
319 | now.) | |
fea681da MK |
320 | .TP |
321 | .B EFAULT | |
1ea901e8 MK |
322 | A required pointer argument (i.e., |
323 | .IR uaddr , | |
324 | .IR uaddr2 , | |
325 | or | |
326 | .IR timeout ) | |
496df304 | 327 | did not point to a valid user-space address. |
fea681da | 328 | .TP |
9f6c40c0 | 329 | .B EINTR |
e808bba0 | 330 | A |
9f6c40c0 | 331 | .B FUTEX_WAIT |
e808bba0 MK |
332 | operation was interrupted by a signal (see |
333 | .BR signal (7)) | |
334 | or a spurious wakeup. | |
9f6c40c0 | 335 | .TP |
fea681da | 336 | .B EINVAL |
fb2f4c27 MK |
337 | .RB ( FUTEX_WAIT , |
338 | .BR FUTEX_WAIT_REQUEUE_PI ) | |
339 | The supplied | |
340 | .I timeout | |
341 | argument was invalid | |
342 | .RI ( tv_sec | |
343 | was less than zero, or | |
344 | .IR tv_nsec | |
345 | was not less than 1000,000,000). | |
346 | .TP | |
347 | .B EINVAL | |
ea355b7f | 348 | .RB ( FUTEX_WAIT , |
caf1ff25 | 349 | .BR FUTEX_WAKE , |
a1f47699 MK |
350 | .BR FUTEX_REQUEUE , |
351 | .BR FUTEX_CMP_REQUEUE ) | |
51ee94be | 352 | .I uaddr |
caf1ff25 | 353 | or (for |
a1f47699 MK |
354 | .BR FUTEX_REQUEUE |
355 | and | |
356 | .BR FUTEX_CMP_REQUEUE ) | |
caf1ff25 | 357 | .I uaddr2 |
51ee94be MK |
358 | does not point to a valid object\(emthat is, |
359 | the address is not 4-byte-aligned. | |
360 | .TP | |
361 | .B EINVAL | |
bae14b6c | 362 | .RB ( FUTEX_WAKE , |
e169277f MK |
363 | .BR FUTEX_REQUEUE , |
364 | .BR FUTEX_CMP_REQUEUE ) | |
496df304 | 365 | The kernel detected an inconsistency between the user-space state at |
9534086b TG |
366 | .I uaddr |
367 | and the kernel state\(emthat is, it detected a waiter which waits in | |
368 | .BR FUTEX_LOCK_PI . | |
369 | .TP | |
370 | .B EINVAL | |
add875c0 MK |
371 | .RB ( FUTEX_REQUEUE ) |
372 | .\" FIXME tglx suggested adding this, but does this error really | |
373 | .\" occur for FUTEX_REQUEUE? | |
374 | .I uaddr | |
375 | equals | |
376 | .IR uaddr2 | |
377 | (i.e., an attempt was made to requeue to the same futex). | |
378 | .TP | |
379 | .B EINVAL | |
4832b48a | 380 | Invalid argument. |
fea681da MK |
381 | .TP |
382 | .B ENFILE | |
383 | The system limit on the total number of open files has been reached. | |
4701fc28 MK |
384 | .TP |
385 | .B ENOSYS | |
386 | Invalid operation specified in | |
387 | .IR op . | |
9f6c40c0 МК |
388 | .TP |
389 | .B ETIMEDOUT | |
d1926d78 MK |
390 | .RB ( FUTEX_WAIT ) |
391 | The operation timed out. | |
9f6c40c0 МК |
392 | .TP |
393 | .B EWOULDBLOCK | |
6b5025a6 MK |
394 | .RB ( FUTEX_WAIT ) |
395 | The atomic enqueueing failed. | |
396 | .TP | |
397 | .B EWOULDBLOCK | |
e808bba0 MK |
398 | .I op |
399 | was | |
400 | .BR FUTEX_WAIT | |
401 | and the value pointed to by | |
9f6c40c0 МК |
402 | .I uaddr |
403 | was not equal to the expected value | |
404 | .I val | |
e808bba0 | 405 | at the time of the call. |
47297adb | 406 | .SH VERSIONS |
a1d5f77c MK |
407 | .PP |
408 | Initial futex support was merged in Linux 2.5.7 but with different semantics | |
409 | from what was described above. | |
c4bb193f | 410 | A 4-argument system call with the semantics |
fd3fa7ef | 411 | described in this page was introduced in Linux 2.5.40. |
11b520ed | 412 | In Linux 2.5.70, one argument |
a1d5f77c | 413 | was added. |
11b520ed | 414 | In Linux 2.6.7, a sixth argument was added\(emmessy, especially |
a1d5f77c | 415 | on the s390 architecture. |
47297adb | 416 | .SH CONFORMING TO |
8382f16d | 417 | This system call is Linux-specific. |
47297adb | 418 | .SH NOTES |
fea681da | 419 | .PP |
fcdad7d6 | 420 | To reiterate, bare futexes are not intended as an easy-to-use abstraction |
c13182ef | 421 | for end-users. |
fcdad7d6 | 422 | (There is no wrapper function for this system call in glibc.) |
c13182ef | 423 | Implementors are expected to be assembly literate and to have |
7fac88a9 | 424 | read the sources of the futex user-space library referenced below. |
d282bb24 | 425 | .\" .SH AUTHORS |
fea681da MK |
426 | .\" .PP |
427 | .\" Futexes were designed and worked on by | |
428 | .\" Hubertus Franke (IBM Thomas J. Watson Research Center), | |
429 | .\" Matthew Kirkwood, Ingo Molnar (Red Hat) | |
430 | .\" and Rusty Russell (IBM Linux Technology Center). | |
431 | .\" This page written by bert hubert. | |
47297adb | 432 | .SH SEE ALSO |
d806bc05 | 433 | .BR restart_syscall (2), |
14d8dd3b | 434 | .BR futex (7) |
fea681da | 435 | .PP |
52087dd3 | 436 | \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP |
9b936e9e MK |
437 | (proceedings of the Ottawa Linux Symposium 2002), online at |
438 | .br | |
608bf950 SK |
439 | .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf |
440 | .UE | |
9b936e9e MK |
441 | .PP |
442 | Futex example library, futex-*.tar.bz2 at | |
443 | .br | |
a605264d | 444 | .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
608bf950 | 445 | .UE |