original/man2/futex.2

   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 .\"
   9 .\" FIXME
  10 .\" 2.6.14 adds FUTEX_WAKE_OP
  11 .\" 2.6.18 adds (Ingo Molnar) priority inheritance support:
  12 .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI.  These need
  13 .\" to be documented in the manual page.  Probably there is sufficient
  14 .\" material in the kernel source file Documentation/pi-futex.txt.
  15 .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET
  16 .\"
  17 .TH FUTEX 2 2010-05-22 "Linux" "Linux Programmer's Manual"
  18 .SH NAME
  19 futex \- Fast Userspace Locking system call
  20 .SH SYNOPSIS
  21 .nf
  22 .sp
  23 .B "#include <linux/futex.h>"
  24 .B "#include <sys/time.h>"
  25 .sp
  26 .BI "int futex(int *" uaddr ", int " op ", int " val \
  27 ", const struct timespec *" timeout ,
  28 .br
  29 .BI "          int *" uaddr2 ", int " val3 );
  30 .\" int *? void *? u32 *?
  31 .fi
  32 .SH "DESCRIPTION"
  33 .PP
  34 The
  35 .BR futex ()
  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
  42 .BR futex ()
  43 calls).
  44 It is typically used to
  45 implement the contended case of a lock in shared memory, as
  46 described in
  47 .BR futex (7).
  48 .PP
  49 When a
  50 .BR futex (7)
  51 operation did not finish uncontended in userspace, a call needs to be made
  52 to the kernel to arbitrate.
  53 Arbitration can either mean putting the calling
  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
  57 .BR futex (7).
  58 As these
  59 semantics involve writing nonportable assembly instructions, this in turn
  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
  68 argument, along with a value
  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 ,
  78 and sleeps awaiting
  79 .B FUTEX_WAKE
  80 on this futex address.
  81 If the
  82 .I timeout
  83 argument is non-NULL, its contents describe the maximum
  84 duration of the wait, which is infinite otherwise.
  85 The arguments
  86 .I uaddr2
  87 and
  88 .I val3
  89 are ignored.
  90
  91 For
  92 .BR futex (7),
  93 this call is executed if decrementing the count gave a negative value
  94 (indicating contention), and will sleep until another process releases
  95 the futex and executes the
  96 .B FUTEX_WAKE
  97 operation.
  98 .TP
  99 .B FUTEX_WAKE
 100 This operation wakes at most \fIval\fP
 101 processes waiting on this futex address (i.e., inside
 102 .BR FUTEX_WAIT ).
 103 The arguments
 104 .IR timeout ,
 105 .I uaddr2
 106 and
 107 .I val3
 108 are ignored.
 109
 110 For
 111 .BR futex (7),
 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
 116 .BR FUTEX_FD " (present up to and including Linux 2.6.25)"
 117 To support asynchronous wakeups, this operation associates a file descriptor
 118 with a futex.
 119 .\" , suitable for .BR poll (2).
 120 If another process executes a
 121 .BR FUTEX_WAKE ,
 122 the process will receive the signal number that was passed in
 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
 132 To prevent race conditions, the caller should test if the futex has
 133 been upped after
 134 .B FUTEX_FD
 135 returns.
 136
 137 Because it was inherently racy,
 138 .B FUTEX_FD
 139 has been removed from Linux 2.6.26 onwards.
 140 .TP
 141 .BR FUTEX_REQUEUE " (since Linux 2.5.70)"
 142 This operation was introduced in order to avoid a "thundering herd" effect
 143 when
 144 .B FUTEX_WAKE
 145 is used and all processes woken up need to acquire another futex.
 146 This call wakes up
 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)"
 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 ,
 164 but first checks whether the location
 165 .I uaddr
 166 still contains the value
 167 .IR val3 .
 168 If not, the operation fails with the error
 169 .BR EAGAIN .
 170 The argument
 171 .I timeout
 172 is ignored.
 173 .SH "RETURN VALUE"
 174 .PP
 175 Depending on which operation was executed,
 176 the returned value for a successful call can have differing meanings.
 177 .TP
 178 .B FUTEX_WAIT
 179 Returns 0 if the process was woken by a
 180 .B FUTEX_WAKE
 181 call.
 182 In case of timeout,
 183 the operation fails with the error
 184 .BR ETIMEDOUT .
 185 If the futex was not equal to the expected value,
 186 the operation fails with the error
 187 .BR EWOULDBLOCK .
 188 Signals (see
 189 .BR signal (7))
 190 or other spurious wakeups cause
 191 .B FUTEX_WAIT
 192 to fail with the error
 193 .BR EINTR .
 194 .TP
 195 .B FUTEX_WAKE
 196 Returns the number of processes woken up.
 197 .TP
 198 .B FUTEX_FD
 199 Returns the new file descriptor associated with the futex.
 200 .TP
 201 .B FUTEX_REQUEUE
 202 Returns the number of processes woken up.
 203 .TP
 204 .B FUTEX_CMP_REQUEUE
 205 Returns the number of processes woken up.
 206 .PP
 207 In the event of an error, all operations return \-1, and set
 208 .I errno
 209 to indicate the error.
 210 .SH ERRORS
 211 .TP
 212 .B EACCES
 213 No read access to futex memory.
 214 .TP
 215 .B EAGAIN
 216 .B FUTEX_CMP_REQUEUE
 217 found an unexpected futex value.
 218 (This probably indicates a race;
 219 use the safe
 220 .B FUTEX_WAKE
 221 now.)
 222 .TP
 223 .B EFAULT
 224 Error in getting
 225 .I timeout
 226 information from userspace.
 227 .TP
 228 .B EINVAL
 229 An operation was not defined or error in page alignment.
 230 .TP
 231 .B ENFILE
 232 The system limit on the total number of open files has been reached.
 233 .TP
 234 .B ENOSYS
 235 Invalid operation specified in
 236 .IR op .
 237 .SH "VERSIONS"
 238 .PP
 239 Initial futex support was merged in Linux 2.5.7 but with different semantics
 240 from what was described above.
 241 A 4-argument system call with the semantics
 242 given here was introduced in Linux 2.5.40.
 243 In Linux 2.5.70 one argument
 244 was added.
 245 In Linux 2.6.7 a sixth argument was added \(em messy, especially
 246 on the s390 architecture.
 247 .SH "CONFORMING TO"
 248 This system call is Linux-specific.
 249 .SH "NOTES"
 250 .PP
 251 To reiterate, bare futexes are not intended as an easy-to-use abstraction
 252 for end-users.
 253 (There is no wrapper function for this system call in glibc.)
 254 Implementors are expected to be assembly literate and to have
 255 read the sources of the futex userspace library referenced below.
 256 .\" .SH "AUTHORS"
 257 .\" .PP
 258 .\" Futexes were designed and worked on by
 259 .\" Hubertus Franke (IBM Thomas J. Watson Research Center),
 260 .\" Matthew Kirkwood, Ingo Molnar (Red Hat)
 261 .\" and Rusty Russell (IBM Linux Technology Center).
 262 .\" This page written by bert hubert.
 263 .SH "SEE ALSO"
 264 .BR futex (7)
 265 .PP
 266 \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
 267 (proceedings of the Ottawa Linux Symposium 2002), online at
 268 .br
 269 http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf
 270 .PP
 271 Futex example library, futex-*.tar.bz2 at
 272 .br
 273 ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/.