man/man2/futex.2, man/man2const/FUTEX_REQUEUE.2const: Split FUTEX_REQUEUE from futex(2)

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

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index 4a56c003bb3efe7b778c95eafc169c055d189640..ccbf707fecf18cf67ed5db8628e8890acec9b091 100644 (file)
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -262,18 +262,8 @@ is one of the following:
 .BR FUTEX_WAKE (2const)
 .TQ
 .BR FUTEX_FD (2const)
-.TP
-.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
-This operation performs the same task as
-.B FUTEX_CMP_REQUEUE
-(see below), except that no check is made using the value in
-.IR  val3 .
-(The argument
-.I val3
-is ignored.)
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.\"
+.TQ
+.BR FUTEX_REQUEUE (2const)
 .TP
 .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
 This operation first checks whether the location
@@ -342,7 +332,7 @@ operation equivalent to
 The
 .B FUTEX_CMP_REQUEUE
 operation was added as a replacement for the earlier
-.BR FUTEX_REQUEUE .
+.BR FUTEX_REQUEUE (2const).
 The difference is that the check of the value at
 .I uaddr
 can be used to ensure that requeueing happens only under certain
@@ -357,7 +347,7 @@ conditions, which allows race conditions to be avoided in certain use cases.
 .\"     Subject: Re: Add futex wrapper to glibc?
 .IP
 Both
-.B FUTEX_REQUEUE
+.BR FUTEX_REQUEUE (2const)
 and
 .B FUTEX_CMP_REQUEUE
 can be used to avoid "thundering herd" wake-ups that could occur when using
@@ -1192,9 +1182,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_REQUEUE
-Returns the number of waiters that were woken up.
-.TP
 .B FUTEX_CMP_REQUEUE
 Returns the total number of waiters that were woken up or
 requeued to the futex for the futex word at
@@ -1377,7 +1364,6 @@ equals
 .B EINVAL
 .RB ( FUTEX_WAKE_OP ,
 .BR FUTEX_WAKE_BITSET ,
-.BR FUTEX_REQUEUE ,
 .BR FUTEX_CMP_REQUEUE )
 The kernel detected an inconsistency between the user-space state at
 .I uaddr

diff --git a/man/man2const/FUTEX_REQUEUE.2const b/man/man2const/FUTEX_REQUEUE.2const
new file mode 100644 (file)
index 0000000..0df4c8b
--- /dev/null
+++ b/man/man2const/FUTEX_REQUEUE.2const
@@ -0,0 +1,67 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
+.\" may be freely modified and distributed
+.\" %%%LICENSE_END
+.\"
+.TH FUTEX_REQUEUE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+FUTEX_REQUEUE \- wake some waiters, and requeue others
+.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_REQUEUE,"
+.BI "             uint32_t " val ", uint32_t " val2 ", uint32_t *" uaddr2 );
+.fi
+.SH DESCRIPTION
+.TP
+.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
+This operation performs the same task as
+.B FUTEX_CMP_REQUEUE
+(see below), except that no check is made using the value in
+.IR  val3 .
+.\"
+.SH RETURN VALUE
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.B FUTEX_REQUEUE
+Returns the number of waiters that were woken up.
+.SH ERRORS
+See
+.BR futex (2).
+.TP
+.B EFAULT
+.I uaddr2
+did not point to a valid user-space address.
+.TP
+.B EINVAL
+.I uaddr2
+does not point to a valid object\[em]that is,
+the address is not four-byte-aligned.
+.TP
+.B EINVAL
+The kernel detected an inconsistency between the user-space state at
+.I uaddr
+and the kernel state\[em]that is, it detected a waiter which waits in
+.B FUTEX_LOCK_PI
+or
+.B FUTEX_LOCK_PI2
+on
+.IR uaddr .
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.0.
+.SH SEE ALSO
+.BR futex (2)