]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Page by b.hubert - may be freely modified and distributed |
2 | .\" | |
3 | .\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com) | |
4 | .\" added ERRORS section. | |
5 | .\" | |
6 | .\" Modified 2004-06-17 mtk | |
7 | .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE | |
8 | .\" | |
34f7665a | 9 | .\" FIXME |
c13182ef MK |
10 | .\" 2.6.18 adds (Ingo Molnar) priority inheritance support: |
11 | .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need | |
34f7665a MK |
12 | .\" to be documented in the manual page. Probably there is sufficient |
13 | .\" material in the kernel source file Documentation/pi-futex.txt. | |
14 | .\" | |
d9343c5c | 15 | .TH FUTEX 2 2004-10-07 "Linux" "Linux Programmer's Manual" |
fea681da MK |
16 | .SH NAME |
17 | futex \- Fast Userspace Locking system call | |
18 | .SH SYNOPSIS | |
9d9dc1e8 | 19 | .nf |
fea681da MK |
20 | .sp |
21 | .B "#include <linux/futex.h>" | |
fea681da MK |
22 | .B "#include <sys/time.h>" |
23 | .sp | |
9d9dc1e8 MK |
24 | .BI "int futex(int *" uaddr ", int " op ", int " val \ |
25 | ", const struct timespec *" timeout , | |
26 | .br | |
27 | .BI " int *" uaddr2 ", int " val3 ); | |
fea681da | 28 | .\" int *? void *? u32 *? |
9d9dc1e8 | 29 | .fi |
fea681da MK |
30 | .SH "DESCRIPTION" |
31 | .PP | |
32 | The | |
e511ffb6 | 33 | .BR futex () |
fea681da MK |
34 | system call provides a method for |
35 | a program to wait for a value at a given address to change, and a | |
36 | method to wake up anyone waiting on a particular address (while the | |
37 | addresses for the same memory in separate processes may not be | |
38 | equal, the kernel maps them internally so the same memory mapped in | |
39 | different locations will correspond for | |
e511ffb6 | 40 | .BR futex () |
c13182ef MK |
41 | calls). |
42 | It is typically used to | |
fea681da MK |
43 | implement the contended case of a lock in shared memory, as |
44 | described in | |
a8bda636 | 45 | .BR futex (7). |
fea681da | 46 | .PP |
c13182ef | 47 | When a |
a8bda636 | 48 | .BR futex (7) |
fea681da | 49 | operation did not finish uncontended in userspace, a call needs to be made |
c13182ef MK |
50 | to the kernel to arbitrate. |
51 | Arbitration can either mean putting the calling | |
fea681da MK |
52 | process to sleep or, conversely, waking a waiting process. |
53 | .PP | |
54 | Callers of this function are expected to adhere to the semantics as set out in | |
a8bda636 | 55 | .BR futex (7). |
fea681da MK |
56 | As these |
57 | semantics involve writing non-portable assembly instructions, this in turn | |
58 | probably means that most users will in fact be library authors and not | |
59 | general application developers. | |
60 | .PP | |
61 | The | |
62 | .I uaddr | |
63 | argument needs to point to an aligned integer which stores the counter. | |
64 | The operation to execute is passed via the | |
65 | .I op | |
66 | parameter, along with a value | |
67 | .IR val . | |
68 | .PP | |
69 | Five operations are currently defined: | |
70 | .TP | |
71 | .B FUTEX_WAIT | |
72 | This operation atomically verifies that the futex address | |
73 | .I uaddr | |
74 | still contains the value | |
75 | .IR val , | |
c13182ef MK |
76 | and sleeps awaiting FUTEX_WAKE on this futex address. |
77 | If the | |
fea681da MK |
78 | .I timeout |
79 | argument is non-NULL, its contents describe the maximum | |
c13182ef MK |
80 | duration of the wait, which is infinite otherwise. |
81 | The arguments | |
fea681da MK |
82 | .I uaddr2 |
83 | and | |
84 | .I val3 | |
85 | are ignored. | |
86 | ||
87 | For | |
a8bda636 | 88 | .BR futex (7), |
fea681da MK |
89 | this call is executed if decrementing the count gave a negative value |
90 | (indicating contention), and will sleep until another process releases | |
c13182ef | 91 | the futex and executes the FUTEX_WAKE operation. |
fea681da MK |
92 | .TP |
93 | .B FUTEX_WAKE | |
94 | This operation wakes at most \fIval\fR | |
95 | processes waiting on this futex address (ie. inside FUTEX_WAIT). | |
96 | The arguments | |
97 | .IR timeout , | |
98 | .I uaddr2 | |
99 | and | |
100 | .I val3 | |
101 | are ignored. | |
102 | ||
103 | For | |
a8bda636 | 104 | .BR futex (7), |
fea681da MK |
105 | this is executed if incrementing |
106 | the count showed that there were waiters, once the futex value has been set | |
107 | to 1 (indicating that it is available). | |
108 | .TP | |
109 | .B FUTEX_FD | |
110 | To support asynchronous wakeups, this operation associates a file descriptor | |
111 | with a futex. | |
112 | .\" , suitable for .BR poll (2). | |
113 | If another process executes a FUTEX_WAKE, the process will receive the signal | |
114 | number that was passed in | |
115 | .IR val . | |
116 | The calling process must close the returned file descriptor after use. | |
117 | The arguments | |
118 | .IR timeout , | |
119 | .I uaddr2 | |
120 | and | |
121 | .I val3 | |
122 | are ignored. | |
123 | ||
c13182ef | 124 | To prevent race conditions, the caller should test if the futex has |
266a5e91 MK |
125 | been upped after FUTEX_FD returns. |
126 | ||
03751096 | 127 | .\" FIXME . Check that this flag does eventually get removed. |
266a5e91 MK |
128 | Because it is inherently racy, FUTEX_FD is scheduled for removal |
129 | in June 2007; any applications that use it should be fixed now. | |
fea681da MK |
130 | .TP |
131 | .BR FUTEX_REQUEUE " (since Linux 2.5.70)" | |
132 | This operation was introduced in order to avoid a "thundering herd" effect | |
133 | when FUTEX_WAKE is used and all processes woken up need to acquire another | |
c13182ef MK |
134 | futex. |
135 | This call wakes up | |
fea681da MK |
136 | .I val |
137 | processes, and requeues all other waiters on the futex at address | |
138 | .IR uaddr2 . | |
139 | The arguments | |
140 | .I timeout | |
141 | and | |
142 | .I val3 | |
143 | are ignored. | |
144 | .TP | |
145 | .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" | |
146 | There was a race in the intended use of FUTEX_REQUEUE, so | |
c13182ef MK |
147 | FUTEX_CMP_REQUEUE was introduced. |
148 | This is similar to FUTEX_REQUEUE, | |
fea681da MK |
149 | but first checks whether the location |
150 | .I uaddr | |
151 | still contains the value | |
152 | .IR val3 . | |
153 | If not, an error EAGAIN is returned. | |
154 | The argument | |
155 | .I timeout | |
156 | is ignored. | |
157 | .SH "RETURN VALUE" | |
158 | .PP | |
159 | Depending on which operation was executed, the returned value can have | |
160 | differing meanings. | |
161 | .TP | |
162 | .B FUTEX_WAIT | |
c13182ef MK |
163 | Returns 0 if the process was woken by a FUTEX_WAKE call. |
164 | In case of timeout, | |
165 | ETIMEDOUT is returned. | |
166 | If the futex was not equal to the expected value, | |
c057ec98 | 167 | the operation fails with the error EWOULDBLOCK. |
c13182ef | 168 | Signals (or other spurious wakeups) |
fea681da MK |
169 | cause FUTEX_WAIT to return EINTR. |
170 | .TP | |
171 | .B FUTEX_WAKE | |
172 | Returns the number of processes woken up. | |
173 | .TP | |
174 | .B FUTEX_FD | |
175 | Returns the new file descriptor associated with the futex. | |
176 | .TP | |
177 | .B FUTEX_REQUEUE | |
178 | Returns the number of processes woken up. | |
179 | .TP | |
180 | .B FUTEX_CMP_REQUEUE | |
181 | Returns the number of processes woken up. | |
182 | .SH ERRORS | |
183 | .TP | |
184 | .B EACCES | |
185 | No read access to futex memory. | |
186 | .TP | |
187 | .B EAGAIN | |
188 | FUTEX_CMP_REQUEUE found an unexpected futex value. | |
189 | (This probably indicates a race; | |
190 | use the safe FUTEX_WAKE now.) | |
191 | .TP | |
192 | .B EFAULT | |
193 | Error in getting | |
194 | .I timeout | |
195 | information from userspace. | |
196 | .TP | |
197 | .B EINVAL | |
198 | An operation was not defined or error in page alignment. | |
199 | .TP | |
200 | .B ENFILE | |
201 | The system limit on the total number of open files has been reached. | |
a1d5f77c MK |
202 | .SH "VERSIONS" |
203 | .PP | |
204 | Initial futex support was merged in Linux 2.5.7 but with different semantics | |
205 | from what was described above. | |
206 | A 4-parameter system call with the semantics | |
207 | given here was introduced in Linux 2.5.40. | |
208 | In Linux 2.5.70 one parameter | |
209 | was added. | |
210 | In Linux 2.6.7 a sixth parameter was added \(em messy, especially | |
211 | on the s390 architecture. | |
212 | .SH "CONFORMING TO" | |
213 | This system call is Linux specific. | |
fea681da MK |
214 | .SH "NOTES" |
215 | .PP | |
216 | To reiterate, bare futexes are not intended as an easy to use abstraction | |
c13182ef MK |
217 | for end-users. |
218 | Implementors are expected to be assembly literate and to have | |
fea681da MK |
219 | read the sources of the futex userspace library referenced below. |
220 | .\" .SH "AUTHORS" | |
221 | .\" .PP | |
222 | .\" Futexes were designed and worked on by | |
223 | .\" Hubertus Franke (IBM Thomas J. Watson Research Center), | |
224 | .\" Matthew Kirkwood, Ingo Molnar (Red Hat) | |
225 | .\" and Rusty Russell (IBM Linux Technology Center). | |
226 | .\" This page written by bert hubert. | |
fea681da MK |
227 | .SH "SEE ALSO" |
228 | .PP | |
c13182ef | 229 | .BR futex (7), |
fea681da | 230 | `Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' |
c13182ef | 231 | (proceedings of the Ottawa Linux Symposium 2002), |
fea681da MK |
232 | futex example library, futex-*.tar.bz2 |
233 | <URL:ftp://ftp.nl.kernel.org:/pub/linux/kernel/people/rusty/>. |