mirror of https://github.com/mkerrisk/man-pages
484 lines
12 KiB
Groff
484 lines
12 KiB
Groff
.\" Page by b.hubert
|
|
.\"
|
|
.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
|
|
.\" may be freely modified and distributed
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com)
|
|
.\" added ERRORS section.
|
|
.\"
|
|
.\" Modified 2004-06-17 mtk
|
|
.\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE
|
|
.\"
|
|
.\" FIXME .
|
|
.\" See also https://bugzilla.kernel.org/show_bug.cgi?id=14303
|
|
.\" 2.6.14 adds FUTEX_WAKE_OP
|
|
.\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721
|
|
.\" Author: Jakub Jelinek <jakub@redhat.com>
|
|
.\" Date: Tue Sep 6 15:16:25 2005 -0700
|
|
.\"
|
|
.\" FIXME .
|
|
.\" 2.6.18 adds (Ingo Molnar) priority inheritance support:
|
|
.\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need
|
|
.\" to be documented in the manual page. Probably there is sufficient
|
|
.\" material in the kernel source file Documentation/pi-futex.txt.
|
|
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
|
.\" Author: Ingo Molnar <mingo@elte.hu>
|
|
.\" Date: Tue Jun 27 02:54:58 2006 -0700
|
|
.\"
|
|
.\" commit e2970f2fb6950183a34e8545faa093eb49d186e1
|
|
.\" Author: Ingo Molnar <mingo@elte.hu>
|
|
.\" Date: Tue Jun 27 02:54:47 2006 -0700
|
|
.\"
|
|
.\" See Documentation/pi-futex.txt
|
|
.\"
|
|
.\" FIXME .
|
|
.\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET
|
|
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
|
|
.\" Author: Thomas Gleixner <tglx@linutronix.de>
|
|
.\" Date: Fri Feb 1 17:45:14 2008 +0100
|
|
.\"
|
|
.\" FIXME .
|
|
.\" 2.6.31 adds FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI
|
|
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
|
|
.\" Author: Darren Hart <dvhltc@us.ibm.com>
|
|
.\" Date: Fri Apr 3 13:40:49 2009 -0700
|
|
.\"
|
|
.\" commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358
|
|
.\" Author: Darren Hart <dvhltc@us.ibm.com>
|
|
.\" Date: Mon Apr 20 22:22:22 2009 -0700
|
|
.\"
|
|
.\" See Documentation/futex-requeue-pi.txt
|
|
.\"
|
|
.TH FUTEX 2 2014-05-21 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
futex \- fast user-space locking
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.sp
|
|
.B "#include <linux/futex.h>"
|
|
.B "#include <sys/time.h>"
|
|
.sp
|
|
.BI "int futex(int *" uaddr ", int " op ", int " val \
|
|
", const struct timespec *" timeout ,
|
|
.br
|
|
.BI " int *" uaddr2 ", int " val3 );
|
|
.\" int *? void *? u32 *?
|
|
.fi
|
|
|
|
.IR Note :
|
|
There is no glibc wrapper for this system call; see NOTES.
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The
|
|
.BR futex ()
|
|
system call provides a method for
|
|
a program to wait for a value at a given address to change, and a
|
|
method to wake up anyone waiting on a particular address (while the
|
|
addresses for the same memory in separate processes may not be
|
|
equal, the kernel maps them internally so the same memory mapped in
|
|
different locations will correspond for
|
|
.BR futex ()
|
|
calls).
|
|
This system call is typically used to
|
|
implement the contended case of a lock in shared memory, as
|
|
described in
|
|
.BR futex (7).
|
|
.PP
|
|
When a
|
|
.BR futex (7)
|
|
operation did not finish uncontended in user space, a call needs to be made
|
|
to the kernel to arbitrate.
|
|
Arbitration can either mean putting the calling
|
|
process to sleep or, conversely, waking a waiting process.
|
|
.PP
|
|
Callers of this function are expected to adhere to the semantics as set out in
|
|
.BR futex (7).
|
|
As these
|
|
semantics involve writing nonportable assembly instructions, this in turn
|
|
probably means that most users will in fact be library authors and not
|
|
general application developers.
|
|
.PP
|
|
The
|
|
.I uaddr
|
|
argument needs to point to an aligned integer which stores the counter.
|
|
The operation to execute is passed via the
|
|
.I op
|
|
argument, along with a value
|
|
.IR val .
|
|
.PP
|
|
The
|
|
.I op
|
|
argument consists of two parts:
|
|
a command that specifies the operation to be performed,
|
|
bit-wise ORed with zero or or more options that
|
|
modify the behaviour of the operation.
|
|
The options that may be included in
|
|
.I op
|
|
are as follows:
|
|
.TP
|
|
.BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)"
|
|
.\" commit 34f01cc1f512fa783302982776895c73714ebbc2
|
|
This option bit can be employed with all futex operations.
|
|
It tells the kernel that the futex is process private and not shared
|
|
with another process.
|
|
This allows the kernel to choose the fast path for validating
|
|
the user-space address and avoids expensive VMA lookups,
|
|
taking reference counts on file backing store, and so on.
|
|
.TP
|
|
.BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)"
|
|
.\" commit 1acdac104668a0834cfa267de9946fac7764d486
|
|
This option bit can be employed with the
|
|
.BR FUTEX_WAIT_BITSET
|
|
and
|
|
.BR FUTEX_WAIT_REQUEUE_PI
|
|
operations (described below).
|
|
|
|
If this option is set,
|
|
the kernel treats the user space supplied timeout as an absolute
|
|
time based on
|
|
.BR CLOCK_REALTIME .
|
|
|
|
If this option is not set,
|
|
the kernel treats the user space supplied timeout as relative time.
|
|
.\" FIXME a relative time based on what clock?
|
|
.PP
|
|
The operation specified in
|
|
.I op
|
|
is one of the following:
|
|
.TP
|
|
.B FUTEX_WAIT
|
|
This operation atomically verifies that the futex address
|
|
.I uaddr
|
|
still contains the value
|
|
.IR val ,
|
|
and sleeps awaiting
|
|
.B FUTEX_WAKE
|
|
on this futex address.
|
|
If the
|
|
.I timeout
|
|
argument is non-NULL, its contents specify the duration of the wait.
|
|
(This interval will be rounded up to the system clock granularity,
|
|
and kernel scheduling delays mean that the
|
|
blocking interval may overrun by a small amount.)
|
|
If
|
|
.I timeout
|
|
is NULL, the call blocks indefinitely.
|
|
|
|
The arguments
|
|
.I uaddr2
|
|
and
|
|
.I val3
|
|
are ignored.
|
|
|
|
For
|
|
.BR futex (7),
|
|
this call is executed if decrementing the count gave a negative value
|
|
(indicating contention), and will sleep until another process releases
|
|
the futex and executes the
|
|
.B FUTEX_WAKE
|
|
operation.
|
|
.TP
|
|
.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)"
|
|
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
|
|
.\" FIXME TO complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.B FUTEX_WAKE
|
|
This operation wakes at most \fIval\fP
|
|
processes waiting on this futex address (i.e., inside
|
|
.BR FUTEX_WAIT ).
|
|
|
|
The arguments
|
|
.IR timeout ,
|
|
.I uaddr2
|
|
and
|
|
.I val3
|
|
are ignored.
|
|
|
|
For
|
|
.BR futex (7),
|
|
this is executed if incrementing
|
|
the count showed that there were waiters, once the futex value has been set
|
|
to 1 (indicating that it is available).
|
|
.TP
|
|
.BR FUTEX_WAKE_OP " (since Linux 2.6.14)"
|
|
.\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721
|
|
.\" FIXME to complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
|
|
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
|
|
.\" FIXME TO complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.BR FUTEX_LOCK_PI " (since Linux 2.6.18)"
|
|
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
|
.\" FIXME to complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)"
|
|
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
|
.\" FIXME to complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
|
|
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
|
.\" FIXME to complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.BR FUTEX_FD " (present up to and including Linux 2.6.25)"
|
|
To support asynchronous wakeups, this operation associates a file descriptor
|
|
with a futex.
|
|
.\" , suitable for .BR poll (2).
|
|
If another process executes a
|
|
.BR FUTEX_WAKE ,
|
|
the process will receive the signal number that was passed in
|
|
.IR val .
|
|
The calling process must close the returned file descriptor after use.
|
|
|
|
The arguments
|
|
.IR timeout ,
|
|
.I uaddr2
|
|
and
|
|
.I val3
|
|
are ignored.
|
|
|
|
To prevent race conditions, the caller should test if the futex has
|
|
been upped after
|
|
.B FUTEX_FD
|
|
returns.
|
|
|
|
Because it was inherently racy,
|
|
.B FUTEX_FD
|
|
has been removed from Linux 2.6.26 onward.
|
|
.TP
|
|
.BR FUTEX_REQUEUE " (since Linux 2.5.70)"
|
|
This operation was introduced in order to avoid a "thundering herd" effect
|
|
when
|
|
.B FUTEX_WAKE
|
|
is used and all processes woken up need to acquire another futex.
|
|
The argument
|
|
.I val
|
|
contains the number of waiters on
|
|
.I uaddr
|
|
that are immediately woken up.
|
|
The
|
|
.I timeout
|
|
argument is (ab)used to specify the number of waiters
|
|
that are requeued to the futex at
|
|
.IR uaddr2 ;
|
|
the kernel casts the
|
|
.I timeout
|
|
value to
|
|
.IR u32 .
|
|
.\" FIXME What are the constraints (if any) on the values of 'val' vs
|
|
.\" 'timeout' vs [the number of waites on 'uaddr']?
|
|
|
|
The argument
|
|
.I val3
|
|
is ignored.
|
|
.TP
|
|
.BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
|
|
There was a race in the intended use of
|
|
.BR FUTEX_REQUEUE ,
|
|
so
|
|
.B FUTEX_CMP_REQUEUE
|
|
was introduced.
|
|
.\" FIXME should there be a statement in the description of FUTEX_REQUEUE
|
|
.\" to say that it should be avoided in favor of FUTEX_CMP_REQUEUE?
|
|
This operation is similar to
|
|
.BR FUTEX_REQUEUE ,
|
|
but first checks whether the location
|
|
.I uaddr
|
|
still contains the value
|
|
.IR val3 .
|
|
If not, the operation fails with the error
|
|
.BR EAGAIN .
|
|
|
|
The arguments
|
|
.IR val ,
|
|
.IR uaddr ,
|
|
.IR uaddr2 ,
|
|
and
|
|
.I timeout
|
|
are as for
|
|
.BR FUTEX_REQUEUE .
|
|
.TP
|
|
.BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)"
|
|
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
|
|
.\" FIXME to complete
|
|
[As yet undocumented]
|
|
.TP
|
|
.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)"
|
|
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
|
|
.\" FIXME to complete
|
|
[As yet undocumented]
|
|
.SH RETURN VALUE
|
|
.PP
|
|
In the event of an error, all operations return \-1, and set
|
|
.I errno
|
|
to indicate the error.
|
|
The return value on success depends on the operation,
|
|
as described in the following list:
|
|
.TP
|
|
.B FUTEX_WAIT
|
|
Returns 0 if the process was woken by a
|
|
.B FUTEX_WAKE
|
|
call.
|
|
See ERRORS for the various possible error returns.
|
|
.TP
|
|
.B FUTEX_WAKE
|
|
Returns the number of processes woken up.
|
|
.TP
|
|
.B FUTEX_FD
|
|
Returns the new file descriptor associated with the futex.
|
|
.TP
|
|
.B FUTEX_REQUEUE
|
|
Returns the number of processes woken up.
|
|
.TP
|
|
.B FUTEX_CMP_REQUEUE
|
|
Returns the number of processes woken up.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EACCES
|
|
No read access to futex memory.
|
|
.TP
|
|
.B EAGAIN
|
|
.B FUTEX_CMP_REQUEUE
|
|
detected that the value pointed to by
|
|
.I uaddr
|
|
is not equal to the expected value
|
|
.IR val3 .
|
|
.\" FIXME: Is the following sentence correct?
|
|
(This probably indicates a race;
|
|
use the safe
|
|
.B FUTEX_WAKE
|
|
now.)
|
|
.TP
|
|
.B EFAULT
|
|
A required pointer argument (i.e.,
|
|
.IR uaddr ,
|
|
.IR uaddr2 ,
|
|
or
|
|
.IR timeout )
|
|
did not point to a valid user-space address.
|
|
.TP
|
|
.B EINTR
|
|
A
|
|
.B FUTEX_WAIT
|
|
operation was interrupted by a signal (see
|
|
.BR signal (7))
|
|
or a spurious wakeup.
|
|
.TP
|
|
.B EINVAL
|
|
.RB ( FUTEX_WAIT ,
|
|
.BR FUTEX_WAIT_REQUEUE_PI )
|
|
The supplied
|
|
.I timeout
|
|
argument was invalid
|
|
.RI ( tv_sec
|
|
was less than zero, or
|
|
.IR tv_nsec
|
|
was not less than 1000,000,000).
|
|
.TP
|
|
.B EINVAL
|
|
.RB ( FUTEX_WAIT ,
|
|
.BR FUTEX_WAKE ,
|
|
.BR FUTEX_REQUEUE ,
|
|
.BR FUTEX_CMP_REQUEUE )
|
|
.I uaddr
|
|
or (for
|
|
.BR FUTEX_REQUEUE
|
|
and
|
|
.BR FUTEX_CMP_REQUEUE )
|
|
.I uaddr2
|
|
does not point to a valid object\(emthat is,
|
|
the address is not 4-byte-aligned.
|
|
.TP
|
|
.B EINVAL
|
|
.RB ( FUTEX_WAKE ,
|
|
.BR FUTEX_REQUEUE ,
|
|
.BR FUTEX_CMP_REQUEUE )
|
|
The kernel detected an inconsistency between the user-space state at
|
|
.I uaddr
|
|
and the kernel state\(emthat is, it detected a waiter which waits in
|
|
.BR FUTEX_LOCK_PI .
|
|
.TP
|
|
.B EINVAL
|
|
.RB ( FUTEX_REQUEUE )
|
|
.\" FIXME tglx suggested adding this, but does this error really
|
|
.\" occur for FUTEX_REQUEUE?
|
|
.I uaddr
|
|
equals
|
|
.IR uaddr2
|
|
(i.e., an attempt was made to requeue to the same futex).
|
|
.TP
|
|
.B EINVAL
|
|
Invalid argument.
|
|
.TP
|
|
.B ENFILE
|
|
The system limit on the total number of open files has been reached.
|
|
.TP
|
|
.B ENOSYS
|
|
Invalid operation specified in
|
|
.IR op .
|
|
.TP
|
|
.B ETIMEDOUT
|
|
.RB ( FUTEX_WAIT )
|
|
The operation timed out.
|
|
.TP
|
|
.B EWOULDBLOCK
|
|
.RB ( FUTEX_WAIT )
|
|
The atomic enqueueing failed.
|
|
.TP
|
|
.B EWOULDBLOCK
|
|
.I op
|
|
was
|
|
.BR FUTEX_WAIT
|
|
and the value pointed to by
|
|
.I uaddr
|
|
was not equal to the expected value
|
|
.I val
|
|
at the time of the call.
|
|
.SH VERSIONS
|
|
.PP
|
|
Initial futex support was merged in Linux 2.5.7 but with different semantics
|
|
from what was described above.
|
|
A 4-argument system call with the semantics
|
|
described in this page was introduced in Linux 2.5.40.
|
|
In Linux 2.5.70, one argument
|
|
was added.
|
|
In Linux 2.6.7, a sixth argument was added\(emmessy, especially
|
|
on the s390 architecture.
|
|
.SH CONFORMING TO
|
|
This system call is Linux-specific.
|
|
.SH NOTES
|
|
.PP
|
|
To reiterate, bare futexes are not intended as an easy-to-use abstraction
|
|
for end-users.
|
|
(There is no wrapper function for this system call in glibc.)
|
|
Implementors are expected to be assembly literate and to have
|
|
read the sources of the futex user-space library referenced below.
|
|
.\" .SH AUTHORS
|
|
.\" .PP
|
|
.\" Futexes were designed and worked on by
|
|
.\" Hubertus Franke (IBM Thomas J. Watson Research Center),
|
|
.\" Matthew Kirkwood, Ingo Molnar (Red Hat)
|
|
.\" and Rusty Russell (IBM Linux Technology Center).
|
|
.\" This page written by bert hubert.
|
|
.SH SEE ALSO
|
|
.BR restart_syscall (2),
|
|
.BR futex (7)
|
|
.PP
|
|
\fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
|
|
(proceedings of the Ottawa Linux Symposium 2002), online at
|
|
.br
|
|
.UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002-pages-479-495.pdf
|
|
.UE
|
|
.PP
|
|
Futex example library, futex-*.tar.bz2 at
|
|
.br
|
|
.UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
|
|
.UE
|