futex(2)

1FUTEX(2)                   Linux Programmer's Manual                  FUTEX(2)
2
3
4

NAME

6       futex - Fast Userspace Locking system call
7

SYNOPSIS

9       #include <linux/futex.h>
10
11       #include <sys/time.h>
12
13       int futex(int *uaddr, int op, int val, const struct timespec *timeout,
14                 int *uaddr2, int val3);
15

DESCRIPTION

17       The  futex()  system call provides a method for a program to wait for a
18       value at a given address to change, and a  method  to  wake  up  anyone
19       waiting  on a particular address (while the addresses for the same mem‐
20       ory in separate processes may not be equal, the kernel maps them inter‐
21       nally  so the same memory mapped in different locations will correspond
22       for futex() calls).  It is typically used to  implement  the  contended
23       case of a lock in shared memory, as described in futex(7).
24
25       When  a  futex(7)  operation did not finish uncontended in userspace, a
26       call needs to be made to  the  kernel  to  arbitrate.  Arbitration  can
27       either mean putting the calling process to sleep or, conversely, waking
28       a waiting process.
29
30       Callers of this function are expected to adhere to the semantics as set
31       out  in  futex(7).   As  these  semantics  involve writing non-portable
32       assembly instructions, this in turn probably means that most users will
33       in fact be library authors and not general application developers.
34
35       The  uaddr  argument  needs to point to an aligned integer which stores
36       the counter.  The operation to execute is passed via the op  parameter,
37       along with a value val.
38
39       Five operations are currently defined:
40
41       FUTEX_WAIT
42              This  operation atomically verifies that the futex address uaddr
43              still contains the value val, and sleeps awaiting FUTEX_WAKE  on
44              this  futex  address.  If  the timeout argument is non-NULL, its
45              contents describe the maximum duration of  the  wait,  which  is
46              infinite otherwise. The arguments uaddr2 and val3 are ignored.
47
48              For  futex(7),  this  call is executed if decrementing the count
49              gave a negative value (indicating contention),  and  will  sleep
50              until  another  process  releases  the  futex  and  executes the
51              FUTEX_WAKE operation.
52
53       FUTEX_WAKE
54              This operation wakes at most val processes waiting on this futex
55              address  (ie. inside FUTEX_WAIT).  The arguments timeout, uaddr2
56              and val3 are ignored.
57
58              For futex(7), this is executed if incrementing the count  showed
59              that  there were waiters, once the futex value has been set to 1
60              (indicating that it is available).
61
62       FUTEX_FD
63              To support asynchronous wakeups,  this  operation  associates  a
64              file  descriptor  with  a  futex.  If another process executes a
65              FUTEX_WAKE, the process will receive the signal number that  was
66              passed in val.  The calling process must close the returned file
67              descriptor after use.  The arguments timeout,  uaddr2  and  val3
68              are ignored.
69
70              To  prevent race conditions, the caller should test if the futex
71              has been upped after FUTEX_FD returns.
72
73              Because it is inherently racy, FUTEX_FD is scheduled for removal
74              in June 2007; any applications that use it should be fixed now.
75
76       FUTEX_REQUEUE (since Linux 2.5.70)
77              This  operation  was  introduced in order to avoid a "thundering
78              herd" effect when FUTEX_WAKE is used and all processes woken  up
79              need to acquire another futex. This call wakes up val processes,
80              and requeues all other waiters on the futex at  address  uaddr2.
81              The arguments timeout and val3 are ignored.
82
83       FUTEX_CMP_REQUEUE (since Linux 2.6.7)
84              There  was  a  race  in  the  intended  use of FUTEX_REQUEUE, so
85              FUTEX_CMP_REQUEUE   was   introduced.   This   is   similar   to
86              FUTEX_REQUEUE, but first checks whether the location uaddr still
87              contains the value val3.  If not, an error EAGAIN  is  returned.
88              The argument timeout is ignored.
89

RETURN VALUE

91       Depending  on which operation was executed, the returned value can have
92       differing meanings.
93
94       FUTEX_WAIT
95              Returns 0 if the process was woken by a FUTEX_WAKE call. In case
96              of timeout, ETIMEDOUT is returned. If the futex was not equal to
97              the expected value, the operation returns  EWOULDBLOCK.  Signals
98              (or other spurious wakeups) cause FUTEX_WAIT to return EINTR.
99
100       FUTEX_WAKE
101              Returns the number of processes woken up.
102
103       FUTEX_FD
104              Returns the new file descriptor associated with the futex.
105
106       FUTEX_REQUEUE
107              Returns the number of processes woken up.
108
109       FUTEX_CMP_REQUEUE
110              Returns the number of processes woken up.
111

ERRORS

113       EACCES No read access to futex memory.
114
115       EAGAIN FUTEX_CMP_REQUEUE found an unexpected futex value.  (This proba‐
116              bly indicates a race; use the safe FUTEX_WAKE now.)
117
118       EFAULT Error in getting timeout information from userspace.
119
120       EINVAL An operation was not defined or error in page alignment.
121
122       ENFILE The system limit on the total number  of  open  files  has  been
123              reached.
124

NOTES

126       To  reiterate, bare futexes are not intended as an easy to use abstrac‐
127       tion for end-users. Implementors are expected to be  assembly  literate
128       and  to have read the sources of the futex userspace library referenced
129       below.
130

VERSIONS

132       Initial futex support was merged in  Linux  2.5.7  but  with  different
133       semantics from what was described above. A 4-parameter system call with
134       the semantics given here was  introduced  in  Linux  2.5.40.  In  Linux
135       2.5.70  one  parameter  was added. In Linux 2.6.7 a sixth parameter was
136       added — messy, especially on the s390 architecture.
137

CONFORMING TO

139       This system call is Linux specific.
140