original/man2/futex.2

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