LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

futex.2: srcfix 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2015-01-17 07:00:14 +01:00
parent bdc5957afa
commit f1d2171d38
1 changed files with 37 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
man2/futex.2
View File

@ -156,7 +156,7 @@ as an absolute time based on
If this option is not set, the kernel treats
.I timeout
as relative time,
.\" FIXME I added CLOCK_MONOTONIC here. Okay?
.\" FIXME XXX I added CLOCK_MONOTONIC here. Okay?
measured against the
.BR CLOCK_MONOTONIC
clock.
@ -193,7 +193,7 @@ operation.
If the
.I timeout
argument is non-NULL, its contents specify a relative timeout for the wait,
.\" FIXME I added CLOCK_MONOTONIC here. Okay?
.\" FIXME XXX I added CLOCK_MONOTONIC here. Okay?
measured according to the
.BR CLOCK_MONOTONIC
clock.
@ -269,8 +269,7 @@ on the futex, the file descriptor indicates as being readable with
and
.BR epoll (7)
The file descriptor can be used to obtain asynchronous notifications:
if
The file descriptor can be used to obtain asynchronous notifications: if
.I val
is nonzero, then when another process or thread executes a
.BR FUTEX_WAKE ,
@ -301,7 +300,7 @@ from Linux 2.6.26 onward.
.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
.\" Strictly speaking: from Linux 2.5.70
.\"
.\" FIXME I added this warning. Okay?
.\" FIXME XXX I added this warning. Okay?
.IR "Avoid using this operation" .
It is broken (unavoidably racy) for its intended purpose.
Use
@ -583,7 +582,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 Is this paragraph that I added okay?
.\" FIXME XXX Is this paragraph that I added okay?
The effect of
.BR FUTEX_WAIT_BITSET
and
@ -656,7 +655,7 @@ then both of those task
(or more generally, all of the tasks in a lock chain)
have their priorities raised to be the same as the high-priority task.
.\" FIXME ===== Start of adapted Hart/Guniguntala text =====
.\" FIXME XXX ===== Start of adapted Hart/Guniguntala text =====
.\" The following text is drawn from the Hart/Guniguntala paper,
.\" but I have reworded some pieces significantly. Please check it.
.\"
@ -669,7 +668,7 @@ If the lock is owned, the futex value shall be the thread ID (TID; see
.BR gettid (2))
of the owning thread.
.IP *
.\" FIXME In the following line, I added "the lock is owned and". Okay?
.\" FIXME XXX In the following line, I added "the lock is owned and". Okay?
If the lock is owned and there are threads contending for the lock,
then the
.B FUTEX_WAITERS
@ -926,7 +925,14 @@ The wait operation on
is the same as
.BR FUTEX_WAIT .
.\"
.\" FIXME What does the next sentence mean?
.\" FIXME I'm not quite clear on the meaning of the following sentence.
.\" Is this trying to say that while blocked in a
.\" FUTEX_WAIT_REQUEUE_PI, it could happen that another
.\" task does a FUTEX_WAKE on uaddr that simply causes
.\" a normal wake, with the result that the FUTEX_WAIT_REQUEUE_PI
.\" does not complete? What happens then to the FUTEX_WAIT_REQUEUE_PI
.\" opertion? Does it remain blocked, or does it unblock
.\" In which case, what does user space see?
The waiter can be removed from the wait on
.I uaddr
via
@ -999,7 +1005,7 @@ then difference is the number of waiters requeued to the futex at
.IR uaddr2 .
.TP
.B FUTEX_WAKE_OP
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns the total number of waiters that were woken up.
This is the sum of the woken waiters on the two futexes at
.I uaddr
@ -1007,7 +1013,7 @@ and
.IR uaddr2 .
.TP
.B FUTEX_WAIT_BITSET
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns 0 if the caller was woken by a
.B FUTEX_WAKE
or
@ -1015,23 +1021,23 @@ or
call.
.TP
.B FUTEX_WAKE_BITSET
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns the number of waiters that were woken up.
.TP
.B FUTEX_LOCK_PI
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns 0 if the futex was successfully locked.
.TP
.B FUTEX_TRYLOCK_PI
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns 0 if the futex was successfully locked.
.TP
.B FUTEX_UNLOCK_PI
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns 0 if the futex was successfully unlocked.
.TP
.B FUTEX_CMP_REQUEUE_PI
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns the total number of waiters that were woken up or
requeued to the futex at
.IR uaddr2 .
@ -1041,7 +1047,7 @@ then difference is the number of waiters requeued to the futex at
.IR uaddr2 .
.TP
.B FUTEX_WAIT_REQUEUE_PI
.\" FIXME Is the following correct?
.\" FIXME XXX Is the following correct?
Returns 0 if the caller was successfully requeued to the futex at
.IR uaddr2 .
.\"
@ -1074,7 +1080,7 @@ use the safe
.B FUTEX_WAKE
now.)
.\"
.\" FIXME Should there be an EAGAIN case for FUTEX_TRYLOCK_PI?
.\" FIXME XXX Should there be an EAGAIN case for FUTEX_TRYLOCK_PI?
.\" It seems so, looking at the handling of the rt_mutex_trylock()
.\" call in futex_lock_pi()
.\"
@ -1092,7 +1098,7 @@ is about to exit,
but has not yet handled the internal state cleanup.
Try again.
.\"
.\" FIXME Is there not also an EAGAIN error case on 'uaddr2' for
.\" FIXME XXX Is there not also an EAGAIN error case on 'uaddr2' for
.\" FUTEX_REQUEUE and FUTEX_CMP_REQUEUE via
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EAGAIN?
@ -1104,13 +1110,17 @@ The futex at
.I uaddr
is already locked by the caller.
.\"
.\" FIXME Is there not also an EDEADLK error case on 'uaddr2' for
.\" FIXME XXX Is there not also an EDEADLK error case on 'uaddr2' for
.\" FUTEX_REQUEUE and FUTEX_CMP_REQUEUE via
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EDEADLK?
.TP
.BR EDEADLK
.\" FIXME I reworded tglx's text somewhat; is the following okay?
.\" FIXME XXX I see that kernel/locking/rtmutex.c uses EDEADLK in some places,
.\" and EDEADLOCK in others. On almost all architectures these
.\" constants are synonymous. Is there a reason that both names
.\" are used?
.RB ( FUTEX_CMP_REQUEUE_PI )
While requeueing a waiter to the PI futex at
.IR uaddr2 ,
@ -1192,9 +1202,12 @@ is zero.
.TP
.B EINVAL
.RB ( FUTEX_REQUEUE ,
.\" FIXME tglx suggested adding this, but does this error really occur for
.\" FIXME XXX tglx suggested adding this, but does this error really occur for
.\" FUTEX_REQUEUE? (The case where it occurs for FUTEX_CMP_REQUEUE_PI
.\" is obvious at the start of futex_requeue().)
.\" Darren Hart seems to agree with me that it does not occur for
.\" FUTEX_REQUEUE. If Darren and I turn out to be wrong, then
.\" FUTEX_CMP_REQUEUE probably also needs to be added here.
.BR FUTEX_CMP_REQUEUE_PI )
.I uaddr
equals
@ -1275,7 +1288,7 @@ via
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
.\" FIXME The following is a reworded version of Darren Hart's text.
.\" FIXME XXX 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
@ -1337,7 +1350,7 @@ the futex at
.IR uaddr2 ).
(This may be caused by a state corruption in user space.)
.\"
.\" FIXME Is there not also an EPERM error case on 'uaddr2' for
.\" FIXME XXX Is there not also an EPERM error case on 'uaddr2' for
.\" FUTEX_REQUEUE and FUTEX_CMP_REQUEUE via
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EPERM?
@ -1355,7 +1368,7 @@ The thread ID in the futex at
.I uaddr
does not exist.
.\"
.\" FIXME Is there not also an ESRCH error case on 'uaddr2' for
.\" FIXME XXX Is there not also an ESRCH error case on 'uaddr2' for
.\" FUTEX_REQUEUE and FUTEX_CMP_REQUEUE via
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> ESRCH?