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-12-12 "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 specify the duration of the wait.
 120 (This interval will be rounded up to the system clock granularity,
 121 and kernel scheduling delays mean that the
 122 blocking interval may overrun by a small amount.)
 123 If
 124 .I timeout
 125 is NULL, the call blocks indefinitely.
 126 The arguments
 127 .I uaddr2
 128 and
 129 .I val3
 130 are ignored.
 131
 132 For
 133 .BR futex (7),
 134 this call is executed if decrementing the count gave a negative value
 135 (indicating contention), and will sleep until another process releases
 136 the futex and executes the
 137 .B FUTEX_WAKE
 138 operation.
 139 .TP
 140 .B FUTEX_WAKE
 141 This operation wakes at most \fIval\fP
 142 processes waiting on this futex address (i.e., inside
 143 .BR FUTEX_WAIT ).
 144 The arguments
 145 .IR timeout ,
 146 .I uaddr2
 147 and
 148 .I val3
 149 are ignored.
 150
 151 For
 152 .BR futex (7),
 153 this is executed if incrementing
 154 the count showed that there were waiters, once the futex value has been set
 155 to 1 (indicating that it is available).
 156 .TP
 157 .BR FUTEX_FD " (present up to and including Linux 2.6.25)"
 158 To support asynchronous wakeups, this operation associates a file descriptor
 159 with a futex.
 160 .\" , suitable for .BR poll (2).
 161 If another process executes a
 162 .BR FUTEX_WAKE ,
 163 the process will receive the signal number that was passed in
 164 .IR val .
 165 The calling process must close the returned file descriptor after use.
 166 The arguments
 167 .IR timeout ,
 168 .I uaddr2
 169 and
 170 .I val3
 171 are ignored.
 172
 173 To prevent race conditions, the caller should test if the futex has
 174 been upped after
 175 .B FUTEX_FD
 176 returns.
 177
 178 Because it was inherently racy,
 179 .B FUTEX_FD
 180 has been removed from Linux 2.6.26 onward.
 181 .TP
 182 .BR FUTEX_REQUEUE " (since Linux 2.5.70)"
 183 This operation was introduced in order to avoid a "thundering herd" effect
 184 when
 185 .B FUTEX_WAKE
 186 is used and all processes woken up need to acquire another futex.
 187 This call wakes up
 188 .I val
 189 processes, and requeues all other waiters on the futex at address
 190 .IR uaddr2 .
 191 The arguments
 192 .I timeout
 193 and
 194 .I val3
 195 are ignored.
 196 .TP
 197 .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
 198 There was a race in the intended use of
 199 .BR FUTEX_REQUEUE ,
 200 so
 201 .B FUTEX_CMP_REQUEUE
 202 was introduced.
 203 This is similar to
 204 .BR FUTEX_REQUEUE ,
 205 but first checks whether the location
 206 .I uaddr
 207 still contains the value
 208 .IR val3 .
 209 If not, the operation fails with the error
 210 .BR EAGAIN .
 211 The argument
 212 .I timeout
 213 is ignored.
 214 .SH RETURN VALUE
 215 .PP
 216 In the event of an error, all operations return \-1, and set
 217 .I errno
 218 to indicate the error.
 219 The return value on success depends on the operation,
 220 as described in the following list:
 221 .TP
 222 .B FUTEX_WAIT
 223 Returns 0 if the process was woken by a
 224 .B FUTEX_WAKE
 225 call.
 226 See ERRORS for the various possible error returns.
 227 .TP
 228 .B FUTEX_WAKE
 229 Returns the number of processes woken up.
 230 .TP
 231 .B FUTEX_FD
 232 Returns the new file descriptor associated with the futex.
 233 .TP
 234 .B FUTEX_REQUEUE
 235 Returns the number of processes woken up.
 236 .TP
 237 .B FUTEX_CMP_REQUEUE
 238 Returns the number of processes woken up.
 239 .SH ERRORS
 240 .TP
 241 .B EACCES
 242 No read access to futex memory.
 243 .TP
 244 .B EAGAIN
 245 .B FUTEX_CMP_REQUEUE
 246 detected that the value pointed to by
 247 .I uaddr
 248 is not equal to the expected value
 249 .IR val3 .
 250 (This probably indicates a race;
 251 use the safe
 252 .B FUTEX_WAKE
 253 now.)
 254 .TP
 255 .B EFAULT
 256 Error retrieving
 257 .I timeout
 258 information from user space.
 259 .TP
 260 .B EINTR
 261 A
 262 .B FUTEX_WAIT
 263 operation was interrupted by a signal (see
 264 .BR signal (7))
 265 or a spurious wakeup.
 266 .TP
 267 .B EINVAL
 268 Invalid argument.
 269 .TP
 270 .B ENFILE
 271 The system limit on the total number of open files has been reached.
 272 .TP
 273 .B ENOSYS
 274 Invalid operation specified in
 275 .IR op .
 276 .TP
 277 .B ETIMEDOUT
 278 Timeout during the
 279 .B FUTEX_WAIT
 280 operation.
 281 .TP
 282 .B EWOULDBLOCK
 283 .I op
 284 was
 285 .BR FUTEX_WAIT
 286 and the value pointed to by
 287 .I uaddr
 288 was not equal to the expected value
 289 .I val
 290 at the time of the call.
 291 .SH VERSIONS
 292 .PP
 293 Initial futex support was merged in Linux 2.5.7 but with different semantics
 294 from what was described above.
 295 A 4-argument system call with the semantics
 296 described in this page was introduced in Linux 2.5.40.
 297 In Linux 2.5.70 one argument
 298 was added.
 299 In Linux 2.6.7 a sixth argument was added\(emmessy, especially
 300 on the s390 architecture.
 301 .SH CONFORMING TO
 302 This system call is Linux-specific.
 303 .SH NOTES
 304 .PP
 305 To reiterate, bare futexes are not intended as an easy-to-use abstraction
 306 for end-users.
 307 (There is no wrapper function for this system call in glibc.)
 308 Implementors are expected to be assembly literate and to have
 309 read the sources of the futex user-space library referenced below.
 310 .\" .SH "AUTHORS"
 311 .\" .PP
 312 .\" Futexes were designed and worked on by
 313 .\" Hubertus Franke (IBM Thomas J. Watson Research Center),
 314 .\" Matthew Kirkwood, Ingo Molnar (Red Hat)
 315 .\" and Rusty Russell (IBM Linux Technology Center).
 316 .\" This page written by bert hubert.
 317 .SH SEE ALSO
 318 .BR restart_syscall (2),
 319 .BR futex (7)
 320 .PP
 321 \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
 322 (proceedings of the Ottawa Linux Symposium 2002), online at
 323 .br
 324 .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf
 325 .UE
 326 .PP
 327 Futex example library, futex-*.tar.bz2 at
 328 .br
 329 .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
 330 .UE
 331 .SH COLOPHON
 332 This page is part of release 3.64 of the Linux
 333 .I man-pages
 334 project.
 335 A description of the project,
 336 and information about reporting bugs,
 337 can be found at
 338 \%http://www.kernel.org/doc/man\-pages/.