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