man/man2/futex.2, man/man2const/FUTEX_LOCK_PI2.2const: Split FUTEX_LOCK_PI2 from...

Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index 77fa9280a93d40c7e8dde330f7520a9cd23a1feb..ea74ea08f075d5d8317392d09fc08ee7132417f6 100644 (file)
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -235,7 +235,7 @@ This option bit can be employed only with the
 and
 (since Linux 5.14)
 .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
-.B FUTEX_LOCK_PI2
+.BR FUTEX_LOCK_PI2 (2const)
 operations.
 .IP
 If this option is set, the kernel measures the
@@ -363,7 +363,7 @@ If a futex is already acquired (i.e., has a nonzero value),
 waiters must employ the
 .BR FUTEX_LOCK_PI (2const)
 or
-.B FUTEX_LOCK_PI2
+.BR FUTEX_LOCK_PI2 (2const)
 operations to acquire the lock.
 If other threads are waiting for the lock, then the
 .B FUTEX_WAITERS
@@ -424,7 +424,7 @@ Note that the PI futex operations must be used as paired operations
 and are subject to some additional requirements:
 .IP \[bu] 3
 .BR FUTEX_LOCK_PI (2const),
-.BR FUTEX_LOCK_PI2 ,
+.BR FUTEX_LOCK_PI2 (2const),
 and
 .B FUTEX_TRYLOCK_PI
 pair with
@@ -455,22 +455,8 @@ The PI futex operations are as follows:
 .\"
 .TP
 .BR FUTEX_LOCK_PI (2const)
-.TP
-.BR FUTEX_LOCK_PI2 " (since Linux 5.14)"
-.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
-This operation is the same as
-.BR FUTEX_LOCK_PI (2const),
-except that the clock against which
-.I timeout
-is measured is selectable.
-By default, the (absolute) timeout specified in
-.I timeout
-is measured against the
-.B CLOCK_MONOTONIC
-clock.
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.\"
+.TQ
+.BR FUTEX_LOCK_PI2 (2const)
 .TP
 .BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
 .\" commit c87e2837be82df479a6bae9f155c43516d2feebc
@@ -519,7 +505,7 @@ arguments are ignored.
 This operation wakes the top priority waiter that is waiting in
 .BR FUTEX_LOCK_PI (2const)
 or
-.B FUTEX_LOCK_PI2
+.BR FUTEX_LOCK_PI2 (2const)
 on the futex address provided by the
 .I uaddr
 argument.
@@ -679,9 +665,6 @@ is set to indicate the error.
 The return value on success depends on the operation,
 as described in the following list:
 .TP
-.B FUTEX_LOCK_PI2
-Returns 0 if the futex was successfully locked.
-.TP
 .B FUTEX_TRYLOCK_PI
 Returns 0 if the futex was successfully locked.
 .TP
@@ -734,8 +717,7 @@ is not equal to the expected value
 .IR val3 .
 .TP
 .B EAGAIN
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The futex owner thread ID of
 .I uaddr
@@ -747,8 +729,7 @@ but has not yet handled the internal state cleanup.
 Try again.
 .TP
 .B EDEADLK
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The futex word at
 .I uaddr
@@ -810,8 +791,7 @@ equals
 (i.e., an attempt was made to requeue to the same futex).
 .TP
 .B EINVAL
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_UNLOCK_PI )
 The kernel detected an inconsistency between the user-space state at
 .I uaddr
@@ -861,7 +841,7 @@ that is, the kernel detected a waiter which waits on
 via
 .BR FUTEX_LOCK_PI (2const)
 or
-.B FUTEX_LOCK_PI2
+.BR FUTEX_LOCK_PI2 (2const)
 (instead of
 .BR FUTEX_WAIT_REQUEUE_PI ).
 .TP
@@ -885,8 +865,7 @@ argument is not 1.
 Invalid argument.
 .TP
 .B ENOMEM
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The kernel could not allocate memory to hold state information.
 .TP
@@ -903,11 +882,10 @@ but the accompanying operation was neither
 .BR FUTEX_WAIT_BITSET (2const),
 .BR FUTEX_WAIT_REQUEUE_PI ,
 nor
-.BR FUTEX_LOCK_PI2 .
+.BR FUTEX_LOCK_PI2 (2const).
 .TP
 .B ENOSYS
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_UNLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI ,
 .BR FUTEX_WAIT_REQUEUE_PI )
@@ -916,8 +894,7 @@ The PI-futex operations are not implemented on all architectures and
 are not supported on some CPU variants.
 .TP
 .B EPERM
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The caller is not allowed to attach itself to the futex at
 .I uaddr
@@ -932,8 +909,7 @@ the futex at
 The caller does not own the lock represented by the futex word.
 .TP
 .B ESRCH
-.RB ( FUTEX_LOCK_PI2 ,
-.BR FUTEX_TRYLOCK_PI ,
+.RB ( FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The thread ID in the futex word at
 .I uaddr

diff --git a/man/man2const/FUTEX_LOCK_PI2.2const b/man/man2const/FUTEX_LOCK_PI2.2const
new file mode 100644 (file)
index 0000000..acb7341
--- /dev/null
+++ b/man/man2const/FUTEX_LOCK_PI2.2const
@@ -0,0 +1,112 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
+.\" may be freely modified and distributed
+.\" %%%LICENSE_END
+.\"
+.TH FUTEX_LOCK_PI2 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+FUTEX_LOCK_PI2 \- lock a priority‐inheritance futex
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/futex.h>" "  /* Definition of " FUTEX_* " constants */"
+.BR "#include <sys/syscall.h>" "  /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_LOCK_PI2, 0,"
+.BI "             const struct timespec *" timeout );
+.fi
+.SH DESCRIPTION
+.TP
+.BR FUTEX_LOCK_PI2 " (since Linux 5.14)"
+.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
+This operation is the same as
+.BR FUTEX_LOCK_PI (2const),
+except that the clock against which
+.I timeout
+is measured is selectable.
+By default, the (absolute) timeout specified in
+.I timeout
+is measured against the
+.B CLOCK_MONOTONIC
+clock.
+.\"
+.SH RETURN VALUE
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.B FUTEX_LOCK_PI2
+Returns 0 if the futex was successfully locked.
+.SH ERRORS
+See
+.BR futex (2).
+.TP
+.B EAGAIN
+The futex owner thread ID of
+.I uaddr
+is about to exit,
+but has not yet handled the internal state cleanup.
+Try again.
+.TP
+.B EDEADLK
+The futex word at
+.I uaddr
+is already locked by the caller.
+.TP
+.B EFAULT
+.I timeout
+did not point to a valid user-space address.
+.TP
+.B EINVAL
+The supplied
+.I timeout
+argument was invalid
+.RI ( tv_sec
+was less than zero, or
+.I tv_nsec
+was not less than 1,000,000,000).
+.TP
+.B EINVAL
+The kernel detected an inconsistency between the user-space state at
+.I uaddr
+and the kernel state.
+This indicates either state corruption
+or that the kernel found a waiter on
+.I uaddr
+which is waiting via
+.BR FUTEX_WAIT (2const)
+or
+.BR FUTEX_WAIT_BITSET (2const).
+.TP
+.B ENOMEM
+The kernel could not allocate memory to hold state information.
+.TP
+.B ENOSYS
+A run-time check determined that the operation is not available.
+The PI-futex operations are not implemented on all architectures and
+are not supported on some CPU variants.
+.TP
+.B EPERM
+The caller is not allowed to attach itself to the futex at
+.IR uaddr .
+(This may be caused by a state corruption in user space.)
+.TP
+.B ESRCH
+The thread ID in the futex word at
+.I uaddr
+does not exist.
+.TP
+.B ETIMEDOUT
+The timeout expired before the operation completed.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.SH SEE ALSO
+.BR futex (2)