summaryrefslogtreecommitdiffstats
path: root/man2/futex.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/futex.266
1 files changed, 33 insertions, 33 deletions
diff --git a/man2/futex.2 b/man2/futex.2
index 43b1075..2ff300b 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -19,7 +19,7 @@
.\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail
.\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242
.\"
-.TH futex 2 2023-05-03 "Linux man-pages 6.05.01"
+.TH futex 2 2023-10-31 "Linux man-pages 6.7"
.SH NAME
futex \- fast user-space locking
.SH LIBRARY
@@ -27,18 +27,18 @@ Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \
", uint32_t " val ,
.BI " const struct timespec *" timeout , \
" \fR /* or: \fBuint32_t \fIval2\fP */"
.BI " uint32_t *" uaddr2 ", uint32_t " val3 );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR futex (),
@@ -61,7 +61,7 @@ Other
.BR futex ()
operations can be used to wake any processes or threads waiting
for a particular condition.
-.PP
+.P
A futex is a 32-bit value\[em]referred to below as a
.IR "futex word" \[em]whose
address is supplied to the
@@ -80,7 +80,7 @@ virtual addresses in different processes,
but these addresses all refer to the same location in physical memory.)
In a multithreaded program, it is sufficient to place the futex word
in a global variable shared by all threads.
-.PP
+.P
When executing a futex operation that requests to block a thread,
the kernel will block only if the futex word has the value that the
calling thread supplied (as one of the arguments of the
@@ -113,7 +113,7 @@ blocking via a futex is an atomic compare-and-block operation.
.\" the reference in the following sentence
.\" See NOTES for a detailed specification of
.\" the synchronization semantics.
-.PP
+.P
One use of futexes is for implementing locks.
The state of the lock (i.e., acquired or not acquired)
can be represented as an atomically accessed flag in shared memory.
@@ -140,10 +140,10 @@ operation that wakes threads blocked on the lock flag used as a futex word
See
.BR futex (7)
for more detail on how to use futexes.
-.PP
+.P
Besides the basic wait and wake-up futex functionality, there are further
futex operations aimed at supporting more complex use cases.
-.PP
+.P
Note that
no explicit initialization or destruction is necessary to use futexes;
the kernel maintains a futex
@@ -164,7 +164,7 @@ argument;
.I val
is a value whose meaning and purpose depends on
.IR futex_op .
-.PP
+.P
The remaining arguments
.RI ( timeout ,
.IR uaddr2 ,
@@ -172,7 +172,7 @@ and
.IR val3 )
are required only for certain of the futex operations described below.
Where one of these arguments is not required, it is ignored.
-.PP
+.P
For several blocking operations, the
.I timeout
argument is a pointer to a
@@ -190,12 +190,12 @@ then to
and in the remainder of this page, this argument is referred to as
.I val2
when interpreted in this fashion.
-.PP
+.P
Where it is required, the
.I uaddr2
argument is a pointer to a second futex word that is employed
by the operation.
-.PP
+.P
The interpretation of the final integer argument,
.IR val3 ,
depends on the operation.
@@ -264,7 +264,7 @@ If this option is not set, the kernel measures the
against the
.B CLOCK_MONOTONIC
clock.
-.PP
+.P
The operation specified in
.I futex_op
is one of the following:
@@ -835,7 +835,7 @@ while tasks at an intermediate priority continuously preempt
the low-priority task from the CPU.
Consequently, the low-priority task makes no progress toward
releasing the lock, and the high-priority task remains blocked.
-.PP
+.P
Priority inheritance is a mechanism for dealing with
the priority-inversion problem.
With this mechanism, when a high-priority task becomes blocked
@@ -852,7 +852,7 @@ held by another intermediate-priority task
then both of those tasks
(or more generally, all of the tasks in a lock chain)
have their priorities raised to be the same as the high-priority task.
-.PP
+.P
From a user-space perspective,
what makes a futex PI-aware is a policy agreement (described below)
between user space and the kernel about the value of the futex word,
@@ -868,7 +868,7 @@ for the implementation of very specific IPC mechanisms.)
.\" talk about a PI aware pthread_mutex, than a PI aware futex, since
.\" there is a lot of policy and scaffolding that has to be built up
.\" around it to use it properly (this is what a PI pthread_mutex is).
-.PP
+.P
.\" mtk: The following text is drawn from the Hart/Guniguntala paper
.\" (listed in SEE ALSO), but I have reworded some pieces
.\" significantly.
@@ -899,7 +899,7 @@ FUTEX_WAITERS | TID
(Note that is invalid for a PI futex word to have no owner and
.B FUTEX_WAITERS
set.)
-.PP
+.P
With this policy in place,
a user-space application can acquire an unacquired
lock or release a lock using atomic instructions executed in user mode
@@ -910,7 +910,7 @@ Acquiring a lock simply consists of using compare-and-swap to atomically
set the futex word's value to the caller's TID if its previous value was 0.
Releasing a lock requires using compare-and-swap to set the futex word's
value to 0 if the previous value was the expected TID.
-.PP
+.P
If a futex is already acquired (i.e., has a nonzero value),
waiters must employ the
.B FUTEX_LOCK_PI
@@ -923,7 +923,7 @@ bit is set in the futex value;
in this case, the lock owner must employ the
.B FUTEX_UNLOCK_PI
operation to release the lock.
-.PP
+.P
In the cases where callers are forced into the kernel
(i.e., required to perform a
.BR futex ()
@@ -933,7 +933,7 @@ a kernel locking mechanism which implements the required
priority-inheritance semantics.
After the RT-mutex is acquired, the futex value is updated accordingly,
before the calling thread returns to user space.
-.PP
+.P
It is important to note
.\" tglx (July 2015):
.\" If there are multiple waiters on a pi futex then a wake pi operation
@@ -950,7 +950,7 @@ up in an invalid state, such as having an owner but the value being 0,
or having waiters but not having the
.B FUTEX_WAITERS
bit set.)
-.PP
+.P
If a futex has an associated RT-mutex in the kernel
(i.e., there are blocked waiters)
and the owner of the futex/RT-mutex dies unexpectedly,
@@ -969,7 +969,7 @@ the dead owner.
.\" mechanism. In that case the futex value will be set to
.\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non
.\" PI futexes.
-.PP
+.P
PI futexes are operated on by specifying one of the values listed below in
.IR futex_op .
Note that the PI futex operations must be used as paired operations
@@ -1000,7 +1000,7 @@ Additionally,
(or the error
.B EINVAL
results).
-.PP
+.P
The PI futex operations are as follows:
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -1362,7 +1362,7 @@ was invoked via
all operations return \-1 and set
.I errno
to indicate the error.
-.PP
+.P
The return value on success depends on the operation,
as described in the following list:
.TP
@@ -1742,7 +1742,7 @@ and the timeout expired before the operation completed.
Linux.
.SH HISTORY
Linux 2.6.0.
-.PP
+.P
Initial futex support was merged in Linux 2.5.7 but with different
semantics from what was described above.
A four-argument system call with the semantics
@@ -1760,7 +1760,7 @@ The two processes each write
messages to the terminal and employ a synchronization protocol
that ensures that they alternate in writing messages.
Upon running this program we see output such as the following:
-.PP
+.P
.in +4n
.EX
$ \fB./futex_demo\fP
@@ -1931,7 +1931,7 @@ main(int argc, char *argv[])
.BR pthread_mutexattr_getprotocol (3),
.BR futex (7),
.BR sched (7)
-.PP
+.P
The following kernel source files:
.IP \[bu] 3
.I Documentation/pi\-futex.txt
@@ -1943,28 +1943,28 @@ The following kernel source files:
.I Documentation/locking/rt\-mutex\-design.txt
.IP \[bu]
.I Documentation/robust\-futex\-ABI.txt
-.PP
+.P
Franke, H., Russell, R., and Kirwood, M., 2002.
\fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
(from proceedings of the Ottawa Linux Symposium 2002),
.br
.UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf
.UE
-.PP
+.P
Hart, D., 2009. \fIA futex overview and update\fP,
.UR http://lwn.net/Articles/360699/
.UE
-.PP
+.P
Hart, D.\& and Guniguntala, D., 2009.
\fIRequeue-PI: Making glibc Condvars PI-Aware\fP
(from proceedings of the 2009 Real-Time Linux Workshop),
.UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf
.UE
-.PP
+.P
Drepper, U., 2011. \fIFutexes Are Tricky\fP,
.UR http://www.akkadia.org/drepper/futex.pdf
.UE
-.PP
+.P
Futex example library, futex\-*.tar.bz2 at
.br
.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/