3 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
4 .\" may be freely modified and distributed
7 .\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com)
8 .\" added ERRORS section.
10 .\" Modified 2004-06-17 mtk
11 .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE
14 .\" See also https://bugzilla.kernel.org/show_bug.cgi?id=14303
15 .\" 2.6.14 adds FUTEX_WAKE_OP
16 .\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721
17 .\" Author: Jakub Jelinek <jakub@redhat.com>
18 .\" Date: Tue Sep 6 15:16:25 2005 -0700
21 .\" 2.6.18 adds (Ingo Molnar) priority inheritance support:
22 .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need
23 .\" to be documented in the manual page. Probably there is sufficient
24 .\" material in the kernel source file Documentation/pi-futex.txt.
25 .\" commit c87e2837be82df479a6bae9f155c43516d2feebc
26 .\" Author: Ingo Molnar <mingo@elte.hu>
27 .\" Date: Tue Jun 27 02:54:58 2006 -0700
29 .\" commit e2970f2fb6950183a34e8545faa093eb49d186e1
30 .\" Author: Ingo Molnar <mingo@elte.hu>
31 .\" Date: Tue Jun 27 02:54:47 2006 -0700
33 .\" See Documentation/pi-futex.txt
36 .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET
37 .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
38 .\" Author: Thomas Gleixner <tglx@linutronix.de>
39 .\" Date: Fri Feb 1 17:45:14 2008 +0100
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
47 .\" commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358
48 .\" Author: Darren Hart <dvhltc@us.ibm.com>
49 .\" Date: Mon Apr 20 22:22:22 2009 -0700
51 .\" See Documentation/futex-requeue-pi.txt
53 .TH FUTEX 2 2014-05-21 "Linux" "Linux Programmer's Manual"
55 futex \- fast user-space locking
59 .B "#include <linux/futex.h>"
60 .B "#include <sys/time.h>"
62 .BI "int futex(int *" uaddr ", int " op ", int " val \
63 ", const struct timespec *" timeout ,
65 .BI " int *" uaddr2 ", int " val3 );
66 .\" int *? void *? u32 *?
69 There is no glibc wrapper for this system call; see NOTES.
74 system call provides a method for
75 a program to wait for a value at a given address to change, and a
76 method to wake up anyone waiting on a particular address (while the
77 addresses for the same memory in separate processes may not be
78 equal, the kernel maps them internally so the same memory mapped in
79 different locations will correspond for
82 This system call is typically used to
83 implement the contended case of a lock in shared memory, as
89 operation did not finish uncontended in user space, a call needs to be made
90 to the kernel to arbitrate.
91 Arbitration can either mean putting the calling
92 process to sleep or, conversely, waking a waiting process.
94 Callers of this function are expected to adhere to the semantics as set out in
97 semantics involve writing nonportable assembly instructions, this in turn
98 probably means that most users will in fact be library authors and not
99 general application developers.
103 argument needs to point to an aligned integer which stores the counter.
104 The operation to execute is passed via the
106 argument, along with a value
109 Five operations are currently defined:
112 This operation atomically verifies that the futex address
114 still contains the value
118 on this futex address.
121 argument is non-NULL, its contents specify the duration of the wait.
122 (This interval will be rounded up to the system clock granularity,
123 and kernel scheduling delays mean that the
124 blocking interval may overrun by a small amount.)
127 is NULL, the call blocks indefinitely.
136 this call is executed if decrementing the count gave a negative value
137 (indicating contention), and will sleep until another process releases
138 the futex and executes the
143 This operation wakes at most \fIval\fP
144 processes waiting on this futex address (i.e., inside
155 this is executed if incrementing
156 the count showed that there were waiters, once the futex value has been set
157 to 1 (indicating that it is available).
159 .BR FUTEX_FD " (present up to and including Linux 2.6.25)"
160 To support asynchronous wakeups, this operation associates a file descriptor
162 .\" , suitable for .BR poll (2).
163 If another process executes a
165 the process will receive the signal number that was passed in
167 The calling process must close the returned file descriptor after use.
175 To prevent race conditions, the caller should test if the futex has
180 Because it was inherently racy,
182 has been removed from Linux 2.6.26 onward.
184 .BR FUTEX_REQUEUE " (since Linux 2.5.70)"
185 This operation was introduced in order to avoid a "thundering herd" effect
188 is used and all processes woken up need to acquire another futex.
191 processes, and requeues all other waiters on the futex at address
199 .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
200 There was a race in the intended use of
207 but first checks whether the location
209 still contains the value
211 If not, the operation fails with the error
218 In the event of an error, all operations return \-1, and set
220 to indicate the error.
221 The return value on success depends on the operation,
222 as described in the following list:
225 Returns 0 if the process was woken by a
228 See ERRORS for the various possible error returns.
231 Returns the number of processes woken up.
234 Returns the new file descriptor associated with the futex.
237 Returns the number of processes woken up.
240 Returns the number of processes woken up.
244 No read access to futex memory.
248 detected that the value pointed to by
250 is not equal to the expected value
252 (This probably indicates a race;
260 information from user space.
265 operation was interrupted by a signal (see
267 or a spurious wakeup.
273 The system limit on the total number of open files has been reached.
276 Invalid operation specified in
288 and the value pointed to by
290 was not equal to the expected value
292 at the time of the call.
295 Initial futex support was merged in Linux 2.5.7 but with different semantics
296 from what was described above.
297 A 4-argument system call with the semantics
298 described in this page was introduced in Linux 2.5.40.
299 In Linux 2.5.70, one argument
301 In Linux 2.6.7, a sixth argument was added\(emmessy, especially
302 on the s390 architecture.
304 This system call is Linux-specific.
307 To reiterate, bare futexes are not intended as an easy-to-use abstraction
309 (There is no wrapper function for this system call in glibc.)
310 Implementors are expected to be assembly literate and to have
311 read the sources of the futex user-space library referenced below.
314 .\" Futexes were designed and worked on by
315 .\" Hubertus Franke (IBM Thomas J. Watson Research Center),
316 .\" Matthew Kirkwood, Ingo Molnar (Red Hat)
317 .\" and Rusty Russell (IBM Linux Technology Center).
318 .\" This page written by bert hubert.
320 .BR restart_syscall (2),
323 \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
324 (proceedings of the Ottawa Linux Symposium 2002), online at
326 .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf
329 Futex example library, futex-*.tar.bz2 at
331 .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
334 This page is part of release 3.75 of the Linux
337 A description of the project,
338 information about reporting bugs,
339 and the latest version of this page,
341 \%http://www.kernel.org/doc/man\-pages/.