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

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

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index b0c4b2bc1c7349b2ad9ffa915a01984c0bd52a16..98e1ca035ae0ae2fa28a7283ec809854e2fca1dc 100644 (file)
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -369,7 +369,7 @@ If other threads are waiting for the lock, then the
 .B FUTEX_WAITERS
 bit is set in the futex value;
 in this case, the lock owner must employ the
-.B FUTEX_UNLOCK_PI
+.BR FUTEX_UNLOCK_PI (2const)
 operation to release the lock.
 .P
 In the cases where callers are forced into the kernel
@@ -428,8 +428,8 @@ and are subject to some additional requirements:
 and
 .BR FUTEX_TRYLOCK_PI (2const)
 pair with
-.BR FUTEX_UNLOCK_PI .
-.B FUTEX_UNLOCK_PI
+.BR FUTEX_UNLOCK_PI (2const).
+.BR FUTEX_UNLOCK_PI (2const)
 must be called only on a futex owned by the calling thread,
 as defined by the value policy, otherwise the error
 .B EPERM
@@ -459,31 +459,8 @@ The PI futex operations are as follows:
 .BR FUTEX_LOCK_PI2 (2const)
 .TQ
 .BR FUTEX_TRYLOCK_PI (2const)
-.TP
-.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)"
-.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
-This operation wakes the top priority waiter that is waiting in
-.BR FUTEX_LOCK_PI (2const)
-or
-.BR FUTEX_LOCK_PI2 (2const)
-on the futex address provided by the
-.I uaddr
-argument.
-.IP
-This is called when the user-space value at
-.I uaddr
-cannot be changed atomically from a TID (of the owner) to 0.
-.IP
-The
-.IR uaddr2 ,
-.IR val ,
-.IR timeout ,
-and
-.I val3
-arguments are ignored.
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.\"
+.TQ
+.BR FUTEX_UNLOCK_PI (2const)
 .TP
 .BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)"
 .\" commit 52400ba946759af28442dee6265c5c0180ac7122
@@ -625,9 +602,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_UNLOCK_PI
-Returns 0 if the futex was successfully unlocked.
-.TP
 .B FUTEX_CMP_REQUEUE_PI
 Returns the total number of waiters that were woken up or
 requeued to the futex for the futex word at
@@ -743,19 +717,6 @@ equals
 (i.e., an attempt was made to requeue to the same futex).
 .TP
 .B EINVAL
-.RB ( FUTEX_UNLOCK_PI )
-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 EINVAL
 .RB ( FUTEX_CMP_REQUEUE_PI )
 The kernel detected an inconsistency between the user-space state at
 .I uaddr2
@@ -835,8 +796,7 @@ nor
 .BR FUTEX_LOCK_PI2 (2const).
 .TP
 .B ENOSYS
-.RB ( FUTEX_UNLOCK_PI ,
-.BR FUTEX_CMP_REQUEUE_PI ,
+.RB ( FUTEX_CMP_REQUEUE_PI ,
 .BR FUTEX_WAIT_REQUEUE_PI )
 A run-time check determined that the operation is not available.
 The PI-futex operations are not implemented on all architectures and
@@ -848,10 +808,6 @@ The caller is not allowed to attach itself to the futex at
 .IR uaddr2 .
 (This may be caused by a state corruption in user space.)
 .TP
-.B EPERM
-.RB ( FUTEX_UNLOCK_PI )
-The caller does not own the lock represented by the futex word.
-.TP
 .B ESRCH
 .RB ( FUTEX_CMP_REQUEUE_PI )
 The thread ID in the futex word at

diff --git a/man/man2const/FUTEX_UNLOCK_PI.2const b/man/man2const/FUTEX_UNLOCK_PI.2const
new file mode 100644 (file)
index 0000000..982c521
--- /dev/null
+++ b/man/man2const/FUTEX_UNLOCK_PI.2const
@@ -0,0 +1,74 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
+.\" may be freely modified and distributed
+.\" %%%LICENSE_END
+.\"
+.TH FUTEX_UNLOCK_PI 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+FUTEX_UNLOCK_PI \- unlock 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_UNLOCK_PI);"
+.fi
+.SH DESCRIPTION
+.TP
+.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)"
+.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
+This operation wakes the top priority waiter that is waiting in
+.BR FUTEX_LOCK_PI (2const)
+or
+.BR FUTEX_LOCK_PI2 (2const)
+on the futex address provided by the
+.I uaddr
+argument.
+.IP
+This is called when the user-space value at
+.I uaddr
+cannot be changed atomically from a TID (of the owner) to 0.
+.\"
+.SH RETURN VALUE
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.B FUTEX_UNLOCK_PI
+Returns 0 if the futex was successfully unlocked.
+.SH ERRORS
+See
+.BR futex (2).
+.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 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 does not own the lock represented by the futex word.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.SH SEE ALSO
+.BR futex (2)