man/man2/futex.2, man/man2const/FUTEX_WAIT_REQUEUE_PI.2const: Split FUTEX_WAIT_REQUEU...

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

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index 57bcb624a1ef55116befd92b0f82e273e16534b4..6e99f6eec23d2e901de6b5314e54b70e203f254f 100644 (file)
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -228,7 +228,7 @@ and so on.
 .\" commit 1acdac104668a0834cfa267de9946fac7764d486
 This option bit can be employed only with the
 .BR FUTEX_WAIT_BITSET (2const),
-.BR FUTEX_WAIT_REQUEUE_PI ,
+.BR FUTEX_WAIT_REQUEUE_PI (2const),
 (since Linux 4.5)
 .\" commit 337f13046ff03717a9e99675284a817527440a49
 .BR FUTEX_WAIT (2const),
@@ -435,7 +435,7 @@ as defined by the value policy, otherwise the error
 .B EPERM
 results.
 .IP \[bu]
-.B FUTEX_WAIT_REQUEUE_PI
+.BR FUTEX_WAIT_REQUEUE_PI (2const)
 pairs with
 .BR FUTEX_CMP_REQUEUE_PI (2const).
 This must be performed from a non-PI futex to a distinct PI futex
@@ -463,47 +463,11 @@ The PI futex operations are as follows:
 .BR FUTEX_UNLOCK_PI (2const)
 .TQ
 .BR FUTEX_CMP_REQUEUE_PI (2const)
-.TP
-.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)"
-.\" commit 52400ba946759af28442dee6265c5c0180ac7122
-.\"
-Wait on a non-PI futex at
-.I uaddr
-and potentially be requeued (via a
-.BR FUTEX_CMP_REQUEUE_PI (2const)
-operation in another task) onto a PI futex at
-.IR uaddr2 .
-The wait operation on
-.I uaddr
-is the same as for
-.BR FUTEX_WAIT (2const).
-.IP
-The waiter can be removed from the wait on
-.I uaddr
-without requeueing on
-.I uaddr2
-via a
-.BR FUTEX_WAKE (2const)
-operation in another task.
-In this case, the
-.B FUTEX_WAIT_REQUEUE_PI
-operation fails with the error
-.BR EAGAIN .
-.IP
-If
-.I timeout
-is not NULL, the structure it points to specifies
-an absolute timeout for the wait operation.
-If
-.I timeout
-is NULL, the operation can block indefinitely.
-.IP
-The
-.I val3
-argument is ignored.
-.IP
+.TQ
+.BR FUTEX_WAIT_REQUEUE_PI (2const)
+.P
 The
-.B FUTEX_WAIT_REQUEUE_PI
+.BR FUTEX_WAIT_REQUEUE_PI (2const)
 and
 .BR FUTEX_CMP_REQUEUE_PI (2const)
 were added to support a fairly specific use case:
@@ -511,7 +475,7 @@ support for priority-inheritance-aware POSIX threads condition variables.
 The idea is that these operations should always be paired,
 in order to ensure that user space and the kernel remain in sync.
 Thus, in the
-.B FUTEX_WAIT_REQUEUE_PI
+.BR FUTEX_WAIT_REQUEUE_PI (2const)
 operation, the user-space application pre-specifies the target
 of the requeue that takes place in the
 .BR FUTEX_CMP_REQUEUE_PI (2const)
@@ -552,13 +516,7 @@ and
 .I errno
 is set to indicate the error.
 .P
-The return value on success depends on the operation,
-as described in the following list:
-.TP
-.B FUTEX_WAIT_REQUEUE_PI
-Returns 0 if the caller was successfully requeued to the futex for
-the futex word at
-.IR uaddr2 .
+The return value on success depends on the operation.
 .\"
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"
@@ -567,58 +525,16 @@ the futex word at
 .B EACCES
 No read access to the memory of a futex word.
 .TP
-.B EAGAIN
-.RB ( FUTEX_WAIT_REQUEUE_PI )
-The value pointed to by
-.I uaddr
-was not equal to the expected value
-.I val
-at the time of the call.
-.IP
-.BR Note :
-on Linux, the symbolic names
-.B EAGAIN
-and
-.B EWOULDBLOCK
-(both of which appear in different parts of the kernel futex code)
-have the same value.
-.TP
 .B EFAULT
 .I uaddr
 did not point to a valid user-space address.
 .TP
-.B EFAULT
-A required pointer argument (i.e.,
-.IR uaddr2 ,
-or
-.IR timeout )
-did not point to a valid user-space address.
-.TP
-.B EINVAL
-The operation in
-.I futex_op
-is one of those that employs a timeout, but 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
 .I uaddr
 does not point to a valid object\[em]that is,
 the address is not four-byte-aligned.
 .TP
 .B EINVAL
-The operation specified in
-.I futex_op
-employs
-.IR uaddr2 ,
-but it does not point to a valid object\[em]that is,
-the address is not four-byte-aligned.
-.TP
-.B EINVAL
 Invalid argument.
 .TP
 .B ENOSYS
@@ -632,22 +548,9 @@ option was specified in
 .IR futex_op ,
 but the accompanying operation was neither
 .BR FUTEX_WAIT_BITSET (2const),
-.BR FUTEX_WAIT_REQUEUE_PI ,
+.BR FUTEX_WAIT_REQUEUE_PI (2const),
 nor
 .BR FUTEX_LOCK_PI2 (2const).
-.TP
-.B ENOSYS
-.RB ( 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
-are not supported on some CPU variants.
-.TP
-.B ETIMEDOUT
-The operation in
-.I futex_op
-employed the timeout specified in
-.IR timeout ,
-and the timeout expired before the operation completed.
 .\"
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"

diff --git a/man/man2const/FUTEX_WAIT_REQUEUE_PI.2const b/man/man2const/FUTEX_WAIT_REQUEUE_PI.2const
new file mode 100644 (file)
index 0000000..6867f57
--- /dev/null
+++ b/man/man2const/FUTEX_WAIT_REQUEUE_PI.2const
@@ -0,0 +1,126 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
+.\" may be freely modified and distributed
+.\" %%%LICENSE_END
+.\"
+.TH FUTEX_WAIT_REQUEUE_PI 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+FUTEX_WAIT_REQUEUE_PI
+\-
+wait on a non-PI futex, and potentially be requeued onto a PI 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_WAIT_REQUEUE_PI,"
+.BI "             uint32_t " val ,
+.BI "             const struct timespec *" timeout ,
+.BI "             uint32_t *" uaddr2 );
+.fi
+.SH DESCRIPTION
+.TP
+.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)"
+.\" commit 52400ba946759af28442dee6265c5c0180ac7122
+.\"
+Wait on a non-PI futex at
+.I uaddr
+and potentially be requeued (via a
+.BR FUTEX_CMP_REQUEUE_PI (2const)
+operation in another task) onto a PI futex at
+.IR uaddr2 .
+The wait operation on
+.I uaddr
+is the same as for
+.BR FUTEX_WAIT (2const).
+.IP
+The waiter can be removed from the wait on
+.I uaddr
+without requeueing on
+.I uaddr2
+via a
+.BR FUTEX_WAKE (2const)
+operation in another task.
+In this case, the
+.B FUTEX_WAIT_REQUEUE_PI
+operation fails with the error
+.BR EAGAIN .
+.IP
+If
+.I timeout
+is not NULL, the structure it points to specifies
+an absolute timeout for the wait operation.
+If
+.I timeout
+is NULL, the operation can block indefinitely.
+.\"
+.SH RETURN VALUE
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.B FUTEX_WAIT_REQUEUE_PI
+Returns 0 if the caller was successfully requeued to the futex for
+the futex word at
+.IR uaddr2 .
+.\"
+.SH ERRORS
+See
+.BR futex (2).
+.TP
+.B EAGAIN
+The value pointed to by
+.I uaddr
+was not equal to the expected value
+.I val
+at the time of the call.
+.IP
+.BR Note :
+on Linux, the symbolic names
+.B EAGAIN
+and
+.B EWOULDBLOCK
+(both of which appear in different parts of the kernel futex code)
+have the same value.
+.TP
+.B EFAULT
+.I uaddr2
+or
+.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
+.I uaddr2
+does not point to a valid object\[em]that is,
+the address is not four-byte-aligned.
+.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 ETIMEDOUT
+The timeout expired before the operation completed.
+.\"
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.SH SEE ALSO
+.BR futex (2)