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