mirror of https://github.com/mkerrisk/man-pages
futex.2: Document FUTEX_LOCK_PI2
FUTEX_LOCK_PI2 is a new futex operation which was recently introduced into the Linux kernel. It works exactly like FUTEX_LOCK_PI. However, it has support for selectable clocks for timeouts. By default CLOCK_MONOTONIC is used. If FUTEX_CLOCK_REALTIME is specified then the timeout is measured against CLOCK_REALTIME. This new operation addresses an inconsistency in the futex interface: FUTEX_LOCK_PI only works with timeouts based on CLOCK_REALTIME in contrast to all the other PI operations. Document the FUTEX_LOCK_PI2 command. Signed-off-by: Kurt Kanzenbach <kurt@linutronix.de> Reviewed-by: Thomas Gleixner <tglx@linutronix.de> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
7fc5fc967d
commit
e79977aeec
53
man2/futex.2
53
man2/futex.2
|
@ -241,10 +241,13 @@ and so on.
|
||||||
This option bit can be employed only with the
|
This option bit can be employed only with the
|
||||||
.BR FUTEX_WAIT_BITSET ,
|
.BR FUTEX_WAIT_BITSET ,
|
||||||
.BR FUTEX_WAIT_REQUEUE_PI ,
|
.BR FUTEX_WAIT_REQUEUE_PI ,
|
||||||
and
|
|
||||||
(since Linux 4.5)
|
(since Linux 4.5)
|
||||||
.\" commit 337f13046ff03717a9e99675284a817527440a49
|
.\" commit 337f13046ff03717a9e99675284a817527440a49
|
||||||
.BR FUTEX_WAIT
|
.BR FUTEX_WAIT ,
|
||||||
|
and
|
||||||
|
(since Linux v5.14.0)
|
||||||
|
.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
|
||||||
|
.BR FUTEX_LOCK_PI2
|
||||||
operations.
|
operations.
|
||||||
.IP
|
.IP
|
||||||
If this option is set, the kernel measures the
|
If this option is set, the kernel measures the
|
||||||
|
@ -904,7 +907,9 @@ value to 0 if the previous value was the expected TID.
|
||||||
If a futex is already acquired (i.e., has a nonzero value),
|
If a futex is already acquired (i.e., has a nonzero value),
|
||||||
waiters must employ the
|
waiters must employ the
|
||||||
.B FUTEX_LOCK_PI
|
.B FUTEX_LOCK_PI
|
||||||
operation to acquire the lock.
|
or
|
||||||
|
.B FUTEX_LOCK_PI2
|
||||||
|
operations to acquire the lock.
|
||||||
If other threads are waiting for the lock, then the
|
If other threads are waiting for the lock, then the
|
||||||
.B FUTEX_WAITERS
|
.B FUTEX_WAITERS
|
||||||
bit is set in the futex value;
|
bit is set in the futex value;
|
||||||
|
@ -964,6 +969,8 @@ Note that the PI futex operations must be used as paired operations
|
||||||
and are subject to some additional requirements:
|
and are subject to some additional requirements:
|
||||||
.IP * 3
|
.IP * 3
|
||||||
.B FUTEX_LOCK_PI
|
.B FUTEX_LOCK_PI
|
||||||
|
,
|
||||||
|
.B FUTEX_LOCK_PI2
|
||||||
and
|
and
|
||||||
.B FUTEX_TRYLOCK_PI
|
.B FUTEX_TRYLOCK_PI
|
||||||
pair with
|
pair with
|
||||||
|
@ -1122,6 +1129,27 @@ arguments are ignored.
|
||||||
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
.\"
|
.\"
|
||||||
.TP
|
.TP
|
||||||
|
.BR FUTEX_LOCK_PI2 " (since Linux 5.14.0)"
|
||||||
|
.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
|
||||||
|
This operation works similar like
|
||||||
|
.BR FUTEX_LOCK_PI .
|
||||||
|
The only difference is the
|
||||||
|
timeout argument.
|
||||||
|
.BR FUTEX_LOCK_PI2
|
||||||
|
has support for selectable clocks.
|
||||||
|
.IP
|
||||||
|
If
|
||||||
|
.I timeout
|
||||||
|
is not NULL, the structure it points to specifies
|
||||||
|
an absolute timeout.
|
||||||
|
If
|
||||||
|
.I timeout
|
||||||
|
is NULL, the operation can block indefinitely.
|
||||||
|
.IP
|
||||||
|
.\"
|
||||||
|
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.\"
|
||||||
|
.TP
|
||||||
.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
|
.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
|
||||||
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
||||||
This operation tries to acquire the lock at
|
This operation tries to acquire the lock at
|
||||||
|
@ -1168,6 +1196,8 @@ arguments are ignored.
|
||||||
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
|
||||||
This operation wakes the top priority waiter that is waiting in
|
This operation wakes the top priority waiter that is waiting in
|
||||||
.B FUTEX_LOCK_PI
|
.B FUTEX_LOCK_PI
|
||||||
|
or
|
||||||
|
.B FUTEX_LOCK_PI2
|
||||||
on the futex address provided by the
|
on the futex address provided by the
|
||||||
.I uaddr
|
.I uaddr
|
||||||
argument.
|
argument.
|
||||||
|
@ -1379,6 +1409,9 @@ Returns the number of waiters that were woken up.
|
||||||
.B FUTEX_LOCK_PI
|
.B FUTEX_LOCK_PI
|
||||||
Returns 0 if the futex was successfully locked.
|
Returns 0 if the futex was successfully locked.
|
||||||
.TP
|
.TP
|
||||||
|
.B FUTEX_LOCK_PI2
|
||||||
|
Returns 0 if the futex was successfully locked.
|
||||||
|
.TP
|
||||||
.B FUTEX_TRYLOCK_PI
|
.B FUTEX_TRYLOCK_PI
|
||||||
Returns 0 if the futex was successfully locked.
|
Returns 0 if the futex was successfully locked.
|
||||||
.TP
|
.TP
|
||||||
|
@ -1435,6 +1468,7 @@ is not equal to the expected value
|
||||||
.TP
|
.TP
|
||||||
.BR EAGAIN
|
.BR EAGAIN
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_CMP_REQUEUE_PI )
|
.BR FUTEX_CMP_REQUEUE_PI )
|
||||||
The futex owner thread ID of
|
The futex owner thread ID of
|
||||||
|
@ -1448,6 +1482,7 @@ Try again.
|
||||||
.TP
|
.TP
|
||||||
.BR EDEADLK
|
.BR EDEADLK
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_CMP_REQUEUE_PI )
|
.BR FUTEX_CMP_REQUEUE_PI )
|
||||||
The futex word at
|
The futex word at
|
||||||
|
@ -1536,11 +1571,14 @@ The kernel detected an inconsistency between the user-space state at
|
||||||
.I uaddr
|
.I uaddr
|
||||||
and the kernel state\(emthat is, it detected a waiter which waits in
|
and the kernel state\(emthat is, it detected a waiter which waits in
|
||||||
.BR FUTEX_LOCK_PI
|
.BR FUTEX_LOCK_PI
|
||||||
|
or
|
||||||
|
.BR FUTEX_LOCK_PI2
|
||||||
on
|
on
|
||||||
.IR uaddr .
|
.IR uaddr .
|
||||||
.TP
|
.TP
|
||||||
.B EINVAL
|
.B EINVAL
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_UNLOCK_PI )
|
.BR FUTEX_UNLOCK_PI )
|
||||||
The kernel detected an inconsistency between the user-space state at
|
The kernel detected an inconsistency between the user-space state at
|
||||||
|
@ -1590,6 +1628,8 @@ that is, the kernel detected a waiter which waits on
|
||||||
.I uaddr
|
.I uaddr
|
||||||
via
|
via
|
||||||
.BR FUTEX_LOCK_PI
|
.BR FUTEX_LOCK_PI
|
||||||
|
or
|
||||||
|
.BR FUTEX_LOCK_PI2
|
||||||
(instead of
|
(instead of
|
||||||
.BR FUTEX_WAIT_REQUEUE_PI ).
|
.BR FUTEX_WAIT_REQUEUE_PI ).
|
||||||
.TP
|
.TP
|
||||||
|
@ -1618,6 +1658,7 @@ The system-wide limit on the total number of open files has been reached.
|
||||||
.TP
|
.TP
|
||||||
.BR ENOMEM
|
.BR ENOMEM
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_CMP_REQUEUE_PI )
|
.BR FUTEX_CMP_REQUEUE_PI )
|
||||||
The kernel could not allocate memory to hold state information.
|
The kernel could not allocate memory to hold state information.
|
||||||
|
@ -1634,11 +1675,13 @@ option was specified in
|
||||||
but the accompanying operation was neither
|
but the accompanying operation was neither
|
||||||
.BR FUTEX_WAIT ,
|
.BR FUTEX_WAIT ,
|
||||||
.BR FUTEX_WAIT_BITSET ,
|
.BR FUTEX_WAIT_BITSET ,
|
||||||
|
.BR FUTEX_WAIT_REQUEUE_PI ,
|
||||||
nor
|
nor
|
||||||
.BR FUTEX_WAIT_REQUEUE_PI .
|
.BR FUTEX_LOCK_PI2 .
|
||||||
.TP
|
.TP
|
||||||
.BR ENOSYS
|
.BR ENOSYS
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_UNLOCK_PI ,
|
.BR FUTEX_UNLOCK_PI ,
|
||||||
.BR FUTEX_CMP_REQUEUE_PI ,
|
.BR FUTEX_CMP_REQUEUE_PI ,
|
||||||
|
@ -1649,6 +1692,7 @@ are not supported on some CPU variants.
|
||||||
.TP
|
.TP
|
||||||
.BR EPERM
|
.BR EPERM
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_CMP_REQUEUE_PI )
|
.BR FUTEX_CMP_REQUEUE_PI )
|
||||||
The caller is not allowed to attach itself to the futex at
|
The caller is not allowed to attach itself to the futex at
|
||||||
|
@ -1665,6 +1709,7 @@ The caller does not own the lock represented by the futex word.
|
||||||
.TP
|
.TP
|
||||||
.BR ESRCH
|
.BR ESRCH
|
||||||
.RB ( FUTEX_LOCK_PI ,
|
.RB ( FUTEX_LOCK_PI ,
|
||||||
|
.BR FUTEX_LOCK_PI2 ,
|
||||||
.BR FUTEX_TRYLOCK_PI ,
|
.BR FUTEX_TRYLOCK_PI ,
|
||||||
.BR FUTEX_CMP_REQUEUE_PI )
|
.BR FUTEX_CMP_REQUEUE_PI )
|
||||||
The thread ID in the futex word at
|
The thread ID in the futex word at
|
||||||
|
|
Loading…
Reference in New Issue