mirror of https://github.com/mkerrisk/man-pages
futex.2: srcfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
bdc5957afa
commit
f1d2171d38
61
man2/futex.2
61
man2/futex.2
|
@ -156,7 +156,7 @@ as an absolute time based on
|
||||||
If this option is not set, the kernel treats
|
If this option is not set, the kernel treats
|
||||||
.I timeout
|
.I timeout
|
||||||
as relative time,
|
as relative time,
|
||||||
.\" FIXME I added CLOCK_MONOTONIC here. Okay?
|
.\" FIXME XXX I added CLOCK_MONOTONIC here. Okay?
|
||||||
measured against the
|
measured against the
|
||||||
.BR CLOCK_MONOTONIC
|
.BR CLOCK_MONOTONIC
|
||||||
clock.
|
clock.
|
||||||
|
@ -193,7 +193,7 @@ operation.
|
||||||
If the
|
If the
|
||||||
.I timeout
|
.I timeout
|
||||||
argument is non-NULL, its contents specify a relative timeout for the wait,
|
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
|
measured according to the
|
||||||
.BR CLOCK_MONOTONIC
|
.BR CLOCK_MONOTONIC
|
||||||
clock.
|
clock.
|
||||||
|
@ -269,8 +269,7 @@ on the futex, the file descriptor indicates as being readable with
|
||||||
and
|
and
|
||||||
.BR epoll (7)
|
.BR epoll (7)
|
||||||
|
|
||||||
The file descriptor can be used to obtain asynchronous notifications:
|
The file descriptor can be used to obtain asynchronous notifications: if
|
||||||
if
|
|
||||||
.I val
|
.I val
|
||||||
is nonzero, then when another process or thread executes a
|
is nonzero, then when another process or thread executes a
|
||||||
.BR FUTEX_WAKE ,
|
.BR FUTEX_WAKE ,
|
||||||
|
@ -301,7 +300,7 @@ from Linux 2.6.26 onward.
|
||||||
.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
|
.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
|
||||||
.\" Strictly speaking: from Linux 2.5.70
|
.\" 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" .
|
.IR "Avoid using this operation" .
|
||||||
It is broken (unavoidably racy) for its intended purpose.
|
It is broken (unavoidably racy) for its intended purpose.
|
||||||
Use
|
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;
|
All of the waiters for which the result of the AND is nonzero are woken up;
|
||||||
the remaining waiters are left sleeping.
|
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
|
The effect of
|
||||||
.BR FUTEX_WAIT_BITSET
|
.BR FUTEX_WAIT_BITSET
|
||||||
and
|
and
|
||||||
|
@ -656,7 +655,7 @@ then both of those task
|
||||||
(or more generally, all of the tasks in a lock chain)
|
(or more generally, all of the tasks in a lock chain)
|
||||||
have their priorities raised to be the same as the high-priority task.
|
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,
|
.\" The following text is drawn from the Hart/Guniguntala paper,
|
||||||
.\" but I have reworded some pieces significantly. Please check it.
|
.\" 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))
|
.BR gettid (2))
|
||||||
of the owning thread.
|
of the owning thread.
|
||||||
.IP *
|
.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,
|
If the lock is owned and there are threads contending for the lock,
|
||||||
then the
|
then the
|
||||||
.B FUTEX_WAITERS
|
.B FUTEX_WAITERS
|
||||||
|
@ -926,7 +925,14 @@ The wait operation on
|
||||||
is the same as
|
is the same as
|
||||||
.BR FUTEX_WAIT .
|
.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
|
The waiter can be removed from the wait on
|
||||||
.I uaddr
|
.I uaddr
|
||||||
via
|
via
|
||||||
|
@ -999,7 +1005,7 @@ then difference is the number of waiters requeued to the futex at
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAKE_OP
|
.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.
|
Returns the total number of waiters that were woken up.
|
||||||
This is the sum of the woken waiters on the two futexes at
|
This is the sum of the woken waiters on the two futexes at
|
||||||
.I uaddr
|
.I uaddr
|
||||||
|
@ -1007,7 +1013,7 @@ and
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAIT_BITSET
|
.B FUTEX_WAIT_BITSET
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME XXX Is the following correct?
|
||||||
Returns 0 if the caller was woken by a
|
Returns 0 if the caller was woken by a
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
or
|
or
|
||||||
|
@ -1015,23 +1021,23 @@ or
|
||||||
call.
|
call.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAKE_BITSET
|
.B FUTEX_WAKE_BITSET
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME XXX Is the following correct?
|
||||||
Returns the number of waiters that were woken up.
|
Returns the number of waiters that were woken up.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_LOCK_PI
|
.B FUTEX_LOCK_PI
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME XXX Is the following correct?
|
||||||
Returns 0 if the futex was successfully locked.
|
Returns 0 if the futex was successfully locked.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_TRYLOCK_PI
|
.B FUTEX_TRYLOCK_PI
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME XXX Is the following correct?
|
||||||
Returns 0 if the futex was successfully locked.
|
Returns 0 if the futex was successfully locked.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_UNLOCK_PI
|
.B FUTEX_UNLOCK_PI
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME XXX Is the following correct?
|
||||||
Returns 0 if the futex was successfully unlocked.
|
Returns 0 if the futex was successfully unlocked.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_CMP_REQUEUE_PI
|
.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
|
Returns the total number of waiters that were woken up or
|
||||||
requeued to the futex at
|
requeued to the futex at
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
|
@ -1041,7 +1047,7 @@ then difference is the number of waiters requeued to the futex at
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAIT_REQUEUE_PI
|
.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
|
Returns 0 if the caller was successfully requeued to the futex at
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
.\"
|
.\"
|
||||||
|
@ -1074,7 +1080,7 @@ use the safe
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
now.)
|
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()
|
.\" It seems so, looking at the handling of the rt_mutex_trylock()
|
||||||
.\" call in futex_lock_pi()
|
.\" call in futex_lock_pi()
|
||||||
.\"
|
.\"
|
||||||
|
@ -1092,7 +1098,7 @@ is about to exit,
|
||||||
but has not yet handled the internal state cleanup.
|
but has not yet handled the internal state cleanup.
|
||||||
Try again.
|
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 and FUTEX_CMP_REQUEUE via
|
||||||
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
||||||
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EAGAIN?
|
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EAGAIN?
|
||||||
|
@ -1104,13 +1110,17 @@ The futex at
|
||||||
.I uaddr
|
.I uaddr
|
||||||
is already locked by the caller.
|
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 and FUTEX_CMP_REQUEUE via
|
||||||
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
||||||
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EDEADLK?
|
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EDEADLK?
|
||||||
.TP
|
.TP
|
||||||
.BR EDEADLK
|
.BR EDEADLK
|
||||||
.\" FIXME I reworded tglx's text somewhat; is the following okay?
|
.\" 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 )
|
.RB ( FUTEX_CMP_REQUEUE_PI )
|
||||||
While requeueing a waiter to the PI futex at
|
While requeueing a waiter to the PI futex at
|
||||||
.IR uaddr2 ,
|
.IR uaddr2 ,
|
||||||
|
@ -1192,9 +1202,12 @@ is zero.
|
||||||
.TP
|
.TP
|
||||||
.B EINVAL
|
.B EINVAL
|
||||||
.RB ( FUTEX_REQUEUE ,
|
.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
|
.\" FUTEX_REQUEUE? (The case where it occurs for FUTEX_CMP_REQUEUE_PI
|
||||||
.\" is obvious at the start of futex_requeue().)
|
.\" 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 )
|
.BR FUTEX_CMP_REQUEUE_PI )
|
||||||
.I uaddr
|
.I uaddr
|
||||||
equals
|
equals
|
||||||
|
@ -1275,7 +1288,7 @@ via
|
||||||
.TP
|
.TP
|
||||||
.B EINVAL
|
.B EINVAL
|
||||||
.RB ( FUTEX_CMP_REQUEUE_PI )
|
.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.
|
.\" Please check that I did not introduce any errors.
|
||||||
An attempt was made to requeue a waiter to a futex other than that
|
An attempt was made to requeue a waiter to a futex other than that
|
||||||
specified by the matching
|
specified by the matching
|
||||||
|
@ -1337,7 +1350,7 @@ the futex at
|
||||||
.IR uaddr2 ).
|
.IR uaddr2 ).
|
||||||
(This may be caused by a state corruption in user space.)
|
(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 and FUTEX_CMP_REQUEUE via
|
||||||
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
||||||
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EPERM?
|
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> EPERM?
|
||||||
|
@ -1355,7 +1368,7 @@ The thread ID in the futex at
|
||||||
.I uaddr
|
.I uaddr
|
||||||
does not exist.
|
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 and FUTEX_CMP_REQUEUE via
|
||||||
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
.\" futex_requeue() ==> futex_proxy_trylock_atomic() ==>
|
||||||
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> ESRCH?
|
.\" futex_lock_pi_atomic() ==> attach_to_pi_owner() ==> ESRCH?
|
||||||
|
|
Loading…
Reference in New Issue