]>
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 | .\" | |
6b2bd256 | 9 | .\" FIXME See also https://bugzilla.kernel.org/show_bug.cgi?id=14303 |
40d5cf23 | 10 | .\" 2.6.14 adds FUTEX_WAKE_OP |
c13182ef MK |
11 | .\" 2.6.18 adds (Ingo Molnar) priority inheritance support: |
12 | .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need | |
34f7665a MK |
13 | .\" to be documented in the manual page. Probably there is sufficient |
14 | .\" material in the kernel source file Documentation/pi-futex.txt. | |
40d5cf23 | 15 | .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET |
34f7665a | 16 | .\" |
e808bba0 | 17 | .TH FUTEX 2 2012-08-13 "Linux" "Linux Programmer's Manual" |
fea681da | 18 | .SH NAME |
ce154705 | 19 | futex \- fast user-space locking |
fea681da | 20 | .SH SYNOPSIS |
9d9dc1e8 | 21 | .nf |
fea681da MK |
22 | .sp |
23 | .B "#include <linux/futex.h>" | |
fea681da MK |
24 | .B "#include <sys/time.h>" |
25 | .sp | |
9d9dc1e8 MK |
26 | .BI "int futex(int *" uaddr ", int " op ", int " val \ |
27 | ", const struct timespec *" timeout , | |
28 | .br | |
29 | .BI " int *" uaddr2 ", int " val3 ); | |
fea681da | 30 | .\" int *? void *? u32 *? |
9d9dc1e8 | 31 | .fi |
fea681da MK |
32 | .SH "DESCRIPTION" |
33 | .PP | |
34 | The | |
e511ffb6 | 35 | .BR futex () |
fea681da MK |
36 | system call provides a method for |
37 | a program to wait for a value at a given address to change, and a | |
38 | method to wake up anyone waiting on a particular address (while the | |
39 | addresses for the same memory in separate processes may not be | |
40 | equal, the kernel maps them internally so the same memory mapped in | |
41 | different locations will correspond for | |
e511ffb6 | 42 | .BR futex () |
c13182ef | 43 | calls). |
fd3fa7ef | 44 | This system call is typically used to |
fea681da MK |
45 | implement the contended case of a lock in shared memory, as |
46 | described in | |
a8bda636 | 47 | .BR futex (7). |
fea681da | 48 | .PP |
c13182ef | 49 | When a |
a8bda636 | 50 | .BR futex (7) |
7fac88a9 | 51 | operation did not finish uncontended in user space, a call needs to be made |
c13182ef MK |
52 | to the kernel to arbitrate. |
53 | Arbitration can either mean putting the calling | |
fea681da MK |
54 | process to sleep or, conversely, waking a waiting process. |
55 | .PP | |
56 | Callers of this function are expected to adhere to the semantics as set out in | |
a8bda636 | 57 | .BR futex (7). |
fea681da | 58 | As these |
d603cc27 | 59 | semantics involve writing nonportable assembly instructions, this in turn |
fea681da MK |
60 | probably means that most users will in fact be library authors and not |
61 | general application developers. | |
62 | .PP | |
63 | The | |
64 | .I uaddr | |
65 | argument needs to point to an aligned integer which stores the counter. | |
66 | The operation to execute is passed via the | |
67 | .I op | |
c4bb193f | 68 | argument, along with a value |
fea681da MK |
69 | .IR val . |
70 | .PP | |
71 | Five operations are currently defined: | |
72 | .TP | |
73 | .B FUTEX_WAIT | |
74 | This operation atomically verifies that the futex address | |
75 | .I uaddr | |
76 | still contains the value | |
77 | .IR val , | |
682edefb MK |
78 | and sleeps awaiting |
79 | .B FUTEX_WAKE | |
80 | on this futex address. | |
c13182ef | 81 | If the |
fea681da MK |
82 | .I timeout |
83 | argument is non-NULL, its contents describe the maximum | |
c13182ef MK |
84 | duration of the wait, which is infinite otherwise. |
85 | The arguments | |
fea681da MK |
86 | .I uaddr2 |
87 | and | |
88 | .I val3 | |
89 | are ignored. | |
90 | ||
91 | For | |
a8bda636 | 92 | .BR futex (7), |
fea681da MK |
93 | this call is executed if decrementing the count gave a negative value |
94 | (indicating contention), and will sleep until another process releases | |
682edefb MK |
95 | the futex and executes the |
96 | .B FUTEX_WAKE | |
97 | operation. | |
fea681da MK |
98 | .TP |
99 | .B FUTEX_WAKE | |
a8d55537 | 100 | This operation wakes at most \fIval\fP |
b87dcfb9 | 101 | processes waiting on this futex address (i.e., inside |
682edefb | 102 | .BR FUTEX_WAIT ). |
fea681da MK |
103 | The arguments |
104 | .IR timeout , | |
105 | .I uaddr2 | |
106 | and | |
107 | .I val3 | |
108 | are ignored. | |
109 | ||
110 | For | |
a8bda636 | 111 | .BR futex (7), |
fea681da MK |
112 | this is executed if incrementing |
113 | the count showed that there were waiters, once the futex value has been set | |
114 | to 1 (indicating that it is available). | |
115 | .TP | |
da36351e | 116 | .BR FUTEX_FD " (present up to and including Linux 2.6.25)" |
fea681da MK |
117 | To support asynchronous wakeups, this operation associates a file descriptor |
118 | with a futex. | |
119 | .\" , suitable for .BR poll (2). | |
682edefb MK |
120 | If another process executes a |
121 | .BR FUTEX_WAKE , | |
122 | the process will receive the signal number that was passed in | |
fea681da MK |
123 | .IR val . |
124 | The calling process must close the returned file descriptor after use. | |
125 | The arguments | |
126 | .IR timeout , | |
127 | .I uaddr2 | |
128 | and | |
129 | .I val3 | |
130 | are ignored. | |
131 | ||
c13182ef | 132 | To prevent race conditions, the caller should test if the futex has |
682edefb MK |
133 | been upped after |
134 | .B FUTEX_FD | |
135 | returns. | |
266a5e91 | 136 | |
da36351e | 137 | Because it was inherently racy, |
682edefb | 138 | .B FUTEX_FD |
5fab2e7c | 139 | has been removed from Linux 2.6.26 onward. |
fea681da MK |
140 | .TP |
141 | .BR FUTEX_REQUEUE " (since Linux 2.5.70)" | |
142 | This operation was introduced in order to avoid a "thundering herd" effect | |
682edefb MK |
143 | when |
144 | .B FUTEX_WAKE | |
145 | is used and all processes woken up need to acquire another futex. | |
c13182ef | 146 | This call wakes up |
fea681da MK |
147 | .I val |
148 | processes, and requeues all other waiters on the futex at address | |
149 | .IR uaddr2 . | |
150 | The arguments | |
151 | .I timeout | |
152 | and | |
153 | .I val3 | |
154 | are ignored. | |
155 | .TP | |
156 | .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" | |
682edefb MK |
157 | There was a race in the intended use of |
158 | .BR FUTEX_REQUEUE , | |
159 | so | |
160 | .B FUTEX_CMP_REQUEUE | |
161 | was introduced. | |
162 | This is similar to | |
163 | .BR FUTEX_REQUEUE , | |
fea681da MK |
164 | but first checks whether the location |
165 | .I uaddr | |
166 | still contains the value | |
167 | .IR val3 . | |
e808bba0 MK |
168 | If not, the operation fails with the error |
169 | .BR EAGAIN . | |
fea681da MK |
170 | The argument |
171 | .I timeout | |
172 | is ignored. | |
173 | .SH "RETURN VALUE" | |
174 | .PP | |
e808bba0 MK |
175 | In the event of an error, all operations return \-1, and set |
176 | .I errno | |
177 | to indicate the error. | |
178 | The return value on success depends on the operation, | |
179 | as described in the following list: | |
fea681da MK |
180 | .TP |
181 | .B FUTEX_WAIT | |
682edefb MK |
182 | Returns 0 if the process was woken by a |
183 | .B FUTEX_WAKE | |
184 | call. | |
e808bba0 | 185 | See ERRORS for the various possible error returns. |
fea681da MK |
186 | .TP |
187 | .B FUTEX_WAKE | |
188 | Returns the number of processes woken up. | |
189 | .TP | |
190 | .B FUTEX_FD | |
191 | Returns the new file descriptor associated with the futex. | |
192 | .TP | |
193 | .B FUTEX_REQUEUE | |
194 | Returns the number of processes woken up. | |
195 | .TP | |
196 | .B FUTEX_CMP_REQUEUE | |
197 | Returns the number of processes woken up. | |
198 | .SH ERRORS | |
199 | .TP | |
200 | .B EACCES | |
201 | No read access to futex memory. | |
202 | .TP | |
203 | .B EAGAIN | |
682edefb | 204 | .B FUTEX_CMP_REQUEUE |
e808bba0 | 205 | detected that the value pointed to by |
9f6c40c0 МК |
206 | .I uaddr |
207 | is not equal to the expected value | |
208 | .IR val3 . | |
fea681da | 209 | (This probably indicates a race; |
682edefb MK |
210 | use the safe |
211 | .B FUTEX_WAKE | |
212 | now.) | |
fea681da MK |
213 | .TP |
214 | .B EFAULT | |
e808bba0 | 215 | Error retrieving |
fea681da | 216 | .I timeout |
7fac88a9 | 217 | information from user space. |
fea681da | 218 | .TP |
9f6c40c0 | 219 | .B EINTR |
e808bba0 | 220 | A |
9f6c40c0 | 221 | .B FUTEX_WAIT |
e808bba0 MK |
222 | operation was interrupted by a signal (see |
223 | .BR signal (7)) | |
224 | or a spurious wakeup. | |
9f6c40c0 | 225 | .TP |
fea681da | 226 | .B EINVAL |
4832b48a | 227 | Invalid argument. |
fea681da MK |
228 | .TP |
229 | .B ENFILE | |
230 | The system limit on the total number of open files has been reached. | |
4701fc28 MK |
231 | .TP |
232 | .B ENOSYS | |
233 | Invalid operation specified in | |
234 | .IR op . | |
9f6c40c0 МК |
235 | .TP |
236 | .B ETIMEDOUT | |
237 | Timeout during the | |
238 | .B FUTEX_WAIT | |
239 | operation. | |
240 | .TP | |
241 | .B EWOULDBLOCK | |
e808bba0 MK |
242 | .I op |
243 | was | |
244 | .BR FUTEX_WAIT | |
245 | and the value pointed to by | |
9f6c40c0 МК |
246 | .I uaddr |
247 | was not equal to the expected value | |
248 | .I val | |
e808bba0 | 249 | at the time of the call. |
a1d5f77c MK |
250 | .SH "VERSIONS" |
251 | .PP | |
252 | Initial futex support was merged in Linux 2.5.7 but with different semantics | |
253 | from what was described above. | |
c4bb193f | 254 | A 4-argument system call with the semantics |
fd3fa7ef | 255 | described in this page was introduced in Linux 2.5.40. |
c4bb193f | 256 | In Linux 2.5.70 one argument |
a1d5f77c | 257 | was added. |
5503c85e | 258 | In Linux 2.6.7 a sixth argument was added\(emmessy, especially |
a1d5f77c MK |
259 | on the s390 architecture. |
260 | .SH "CONFORMING TO" | |
8382f16d | 261 | This system call is Linux-specific. |
fea681da MK |
262 | .SH "NOTES" |
263 | .PP | |
fcdad7d6 | 264 | To reiterate, bare futexes are not intended as an easy-to-use abstraction |
c13182ef | 265 | for end-users. |
fcdad7d6 | 266 | (There is no wrapper function for this system call in glibc.) |
c13182ef | 267 | Implementors are expected to be assembly literate and to have |
7fac88a9 | 268 | read the sources of the futex user-space library referenced below. |
fea681da MK |
269 | .\" .SH "AUTHORS" |
270 | .\" .PP | |
271 | .\" Futexes were designed and worked on by | |
272 | .\" Hubertus Franke (IBM Thomas J. Watson Research Center), | |
273 | .\" Matthew Kirkwood, Ingo Molnar (Red Hat) | |
274 | .\" and Rusty Russell (IBM Linux Technology Center). | |
275 | .\" This page written by bert hubert. | |
fea681da | 276 | .SH "SEE ALSO" |
14d8dd3b | 277 | .BR futex (7) |
fea681da | 278 | .PP |
52087dd3 | 279 | \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP |
9b936e9e MK |
280 | (proceedings of the Ottawa Linux Symposium 2002), online at |
281 | .br | |
608bf950 SK |
282 | .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf |
283 | .UE | |
9b936e9e MK |
284 | .PP |
285 | Futex example library, futex-*.tar.bz2 at | |
286 | .br | |
608bf950 SK |
287 | .UR ftp://ftp.nl.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
288 | .UE |