mirror of https://github.com/mkerrisk/man-pages
futex.2: srcfix
Various minor fixes to source Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
a59fca7505
commit
70b06b9033
85
man2/futex.2
85
man2/futex.2
|
|
@ -162,6 +162,9 @@ clock.
|
|||
The operation specified in
|
||||
.I futex_op
|
||||
is one of the following:
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_WAIT " (since Linux 2.6.0)"
|
||||
.\" Strictly speaking, since some time in 2.5.x
|
||||
|
|
@ -212,6 +215,9 @@ this call is executed if decrementing the count gave a negative value
|
|||
the futex and executes the
|
||||
.B FUTEX_WAKE
|
||||
operation.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_WAKE " (since Linux 2.6.0)"
|
||||
.\" Strictly speaking, since Linux 2.5.x
|
||||
|
|
@ -243,12 +249,14 @@ For
|
|||
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_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)"
|
||||
.\" Strictly speaking, from Linux 2.5.x to 2.6.25
|
||||
This operation creates a file descriptor that is associated with the futex at
|
||||
.IR uaddr .
|
||||
.\" , suitable for .BR poll (2).
|
||||
The calling process must close the returned file descriptor after use.
|
||||
When another process performs a
|
||||
.BR FUTEX_WAKE
|
||||
|
|
@ -283,6 +291,9 @@ Because it was inherently racy,
|
|||
has been removed
|
||||
.\" commit 82af7aca56c67061420d618cc5a30f0fd4106b80
|
||||
from Linux 2.6.26 onward.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
|
||||
.\" Strictly speaking: from Linux 2.5.70
|
||||
|
|
@ -301,6 +312,9 @@ except that no check is made using the value in
|
|||
(The argument
|
||||
.I val3
|
||||
is ignored.)
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
|
||||
This operation was added as a replacement for the earlier
|
||||
|
|
@ -322,8 +336,8 @@ still contains the value
|
|||
.IR val3 .
|
||||
If not, the operation fails with the error
|
||||
.BR EAGAIN .
|
||||
.\" FIXME I added the following sentence on rational for FUTEX_CMP_REQUEUE.
|
||||
.\" Is it correct? SHould it be expanded?
|
||||
.\" FIXME I added the following sentence on the rationale for
|
||||
.\" FUTEX_CMP_REQUEUE. Is it correct? Should it be expanded?
|
||||
This additional feature of
|
||||
.BR FUTEX_CMP_REQUEUE
|
||||
can be used by the caller to (atomically) detect changes
|
||||
|
|
@ -368,6 +382,8 @@ is typically either 1 or
|
|||
operation equivalent to
|
||||
.BR FUTEX_WAIT .)
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.\" FIXME I added some FUTEX_WAKE_OP text, and I'd be happy if someone
|
||||
.\" checked it.
|
||||
.TP
|
||||
|
|
@ -509,6 +525,9 @@ is the sum of the number of waiters woken on the futex
|
|||
.IR uaddr
|
||||
plus the number of waiters woken on the futex
|
||||
.IR uaddr2 .
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)"
|
||||
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
|
||||
|
|
@ -535,6 +554,9 @@ above.
|
|||
The
|
||||
.I uaddr2
|
||||
argument is ignored.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
|
||||
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
|
||||
|
|
@ -553,7 +575,7 @@ state of the waiter (the "wait" bitset that is set using
|
|||
All of the waiters for which the result of the AND is nonzero are woken up;
|
||||
the remaining waiters are left sleeping.
|
||||
|
||||
.\" FIXME please review this paragraph that I added
|
||||
.\" FIXME Is this paragraph that I added okay?
|
||||
The effect of
|
||||
.BR FUTEX_WAIT_BITSET
|
||||
and
|
||||
|
|
@ -597,6 +619,7 @@ and
|
|||
.I timeout
|
||||
arguments are ignored.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.SS Priority-inheritance futexes
|
||||
Linux supports priority-inheritance (PI) futexes in order to handle
|
||||
|
|
@ -658,7 +681,7 @@ before the calling thread returns to user space.
|
|||
|
||||
It is important to note
|
||||
.\" FIXME We need some explanation here of *why* it is important to
|
||||
.\" note this
|
||||
.\" note this
|
||||
that the kernel will update the futex value prior
|
||||
to returning to user space.
|
||||
Unlike the other futex operations described above,
|
||||
|
|
@ -666,7 +689,7 @@ the PI futex operations are designed
|
|||
for the implementation of very specific IPC mechanisms).
|
||||
.\"
|
||||
.\" FIXME We don't quite have a definition anywhere of what a PI futex
|
||||
.\" is (vs a non-PI futex). Below, we have the information of
|
||||
.\" is (vs a non-PI futex). Below, we have the information that
|
||||
.\" FUTEX_CMP_REQUEUE_PI requeues from a non-PI futex to a
|
||||
.\" PI futex, but what determines whether the futex is of one
|
||||
.\" kind of the other? We should have such a definition somewhere
|
||||
|
|
@ -680,6 +703,9 @@ for the implementation of very specific IPC mechanisms).
|
|||
|
||||
PI futexes are operated on by specifying one of the following values in
|
||||
.IR futex_op :
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_LOCK_PI " (since Linux 2.6.18)"
|
||||
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
||||
|
|
@ -699,8 +725,8 @@ because it contained the namespace-specific TID of the lock owner.
|
|||
|
||||
The operation checks the value of the futex at the address
|
||||
.IR uaddr .
|
||||
If the value is 0, then the kernel tries to atomically set the futex value to
|
||||
the caller's TID.
|
||||
If the value is 0, then the kernel tries to atomically set
|
||||
the futex value to the caller's TID.
|
||||
If that fails,
|
||||
.\" FIXME What would be the cause of failure?
|
||||
or the futex value is nonzero,
|
||||
|
|
@ -726,13 +752,13 @@ The owner inherits either the priority or the bandwidth of the waiter.
|
|||
.\"
|
||||
.\" FIXME Could I get some help translating the next sentence into
|
||||
.\" something that user-space developers (and I) can understand?
|
||||
.\" In particular, what are "nexted locks" in this context?
|
||||
.\" In particular, what are "nested locks" in this context?
|
||||
This inheritance follows the lock chain in the case of
|
||||
nested locking and performs deadlock detection.
|
||||
|
||||
.\" FIXME tglx says "The timeout argument is handled as described in
|
||||
.\" FUTEX_WAIT." However, it appears to me that this is not right.
|
||||
.\" Is the following formulation correct.
|
||||
.\" Is the following formulation correct?
|
||||
The
|
||||
.I timeout
|
||||
argument provides a timeout for the lock attempt.
|
||||
|
|
@ -765,13 +791,17 @@ arguments are ignored.
|
|||
.\" I'm not yet sure of how to describe it in the man page.)
|
||||
.\" Suggestions please!
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
|
||||
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
||||
This operation tries to acquire the futex at
|
||||
.IR uaddr .
|
||||
.\" FIXME I think it would be helpful here to say a few more words about
|
||||
.\" the difference(s) between FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI
|
||||
.\" the difference(s) between FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI.
|
||||
.\" Can someone propose something?
|
||||
.\"
|
||||
It deals with the situation where the TID value at
|
||||
.I uaddr
|
||||
is 0, but the
|
||||
|
|
@ -790,6 +820,9 @@ The
|
|||
and
|
||||
.IR val3
|
||||
arguments are ignored.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)"
|
||||
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
||||
|
|
@ -810,10 +843,12 @@ The
|
|||
and
|
||||
.IR val3
|
||||
arguments are ignored.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)"
|
||||
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
|
||||
.\" FIXME to complete
|
||||
This operation is a PI-aware variant of
|
||||
.BR FUTEX_CMP_REQUEUE .
|
||||
It requeues waiters that are blocked via
|
||||
|
|
@ -850,13 +885,20 @@ and
|
|||
.I val3
|
||||
arguments serve the same purposes as for
|
||||
.BR FUTEX_CMP_REQUEUE .
|
||||
.\"
|
||||
.\" FIXME The page at http://locklessinc.com/articles/futex_cheat_sheet/
|
||||
.\" notes that "priority-inheritance Futex to priority-inheritance
|
||||
.\" Futex requeues are currently unsupported". Do we need to say
|
||||
.\" something in the man page about that?
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.TP
|
||||
.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)"
|
||||
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
|
||||
.\"
|
||||
.\" FIXME I find the next sentence (from tglx) pretty hard to grok.
|
||||
.\" Could someone explain it a bit more.
|
||||
Wait operation to wait on a non-PI futex at
|
||||
.I uaddr
|
||||
and potentially be requeued onto a PI futex at
|
||||
|
|
@ -865,6 +907,8 @@ The wait operation on
|
|||
.I uaddr
|
||||
is the same as
|
||||
.BR FUTEX_WAIT .
|
||||
.\"
|
||||
.\" FIXME What does the next sentence mean?
|
||||
The waiter can be removed from the wait on
|
||||
.I uaddr
|
||||
via
|
||||
|
|
@ -874,7 +918,7 @@ without requeueing on
|
|||
|
||||
.\" FIXME Somewhere around here, something needs to be said about
|
||||
.\" the pairing semantics of FUTEX_CMP_REQUEUE_PI and
|
||||
.\" FUTEX_WAIT_REQUEUE_PI. (The Hart/Guniguntala paer says
|
||||
.\" FUTEX_WAIT_REQUEUE_PI. (The Hart/Guniguntala paper says
|
||||
.\" "FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI must be
|
||||
.\" paired only with each other." Could someone propose
|
||||
.\" a statement about this pairing requirement and why it
|
||||
|
|
@ -896,10 +940,13 @@ is NULL, the operation can block indefinitely.
|
|||
The
|
||||
.I val3
|
||||
argument is ignored.
|
||||
.\" FIXME Re the preceding sentence, actually 'val3' is internally set to
|
||||
.\" FIXME Re the preceding sentence... Actually 'val3' is internally set to
|
||||
.\" FUTEX_BITSET_MATCH_ANY before calling futex_wait_requeue_pi().
|
||||
.\" I'm not sure we need to say anything about this though.
|
||||
.\" Comments?
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.SH RETURN VALUE
|
||||
.PP
|
||||
In the event of an error, all operations return \-1 and set
|
||||
|
|
@ -931,8 +978,6 @@ If this value is greater than
|
|||
.IR val ,
|
||||
then difference is the number of waiters requeued to the futex at
|
||||
.IR uaddr2 .
|
||||
.\"
|
||||
.\" FIXME Add success returns for other operations
|
||||
.TP
|
||||
.B FUTEX_WAKE_OP
|
||||
.\" FIXME Is the following correct?
|
||||
|
|
@ -979,6 +1024,9 @@ then difference is the number of waiters requeued to the futex at
|
|||
.\" FIXME Is the following correct?
|
||||
Returns 0 if the caller was successfully requeued to the futex at
|
||||
.IR uaddr2 .
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EACCES
|
||||
|
|
@ -1207,7 +1255,7 @@ via
|
|||
.TP
|
||||
.B EINVAL
|
||||
.RB ( FUTEX_CMP_REQUEUE_PI )
|
||||
.\" FIXME This is a reworded version of Darren Hart's text.
|
||||
.\" FIXME The following is a reworded version of Darren Hart's text.
|
||||
.\" Please check that I did not introduce any errors.
|
||||
An attempt was made to requeue a waiter to a futex other than that
|
||||
specified by the matching
|
||||
|
|
@ -1306,6 +1354,9 @@ The operation in
|
|||
employed the timeout specified in
|
||||
.IR timeout ,
|
||||
and the timeout expired before the operation completed.
|
||||
.\"
|
||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.\"
|
||||
.SH VERSIONS
|
||||
.PP
|
||||
Futexes were first made available in a stable kernel release
|
||||
|
|
|
|||
Loading…
Reference in New Issue