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

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

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index f51fb9c4209109c4e0a6f95b1f488d2efab8d54f..742e0b51a6a9d478a92c54deadc26955f849654f 100644 (file)
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -258,44 +258,8 @@ is one of the following:
 .\"
 .TP
 .BR FUTEX_WAIT (2const)
-.TP
-.BR FUTEX_WAKE " (since Linux 2.6.0)"
-.\" Strictly speaking, since Linux 2.5.x
-This operation wakes at most
-.I val
-of the waiters that are waiting (e.g., inside
-.BR FUTEX_WAIT (2const))
-on the futex word at the address
-.IR uaddr .
-Most commonly,
-.I val
-is specified as either 1 (wake up a single waiter) or
-.B INT_MAX
-(wake up all waiters).
-No guarantee is provided about which waiters are awoken
-(e.g., a waiter with a higher scheduling priority is not guaranteed
-to be awoken in preference to a waiter with a lower priority).
-.IP
-The arguments
-.IR timeout ,
-.IR uaddr2 ,
-and
-.I val3
-are ignored.
-.\" FIXME . (Torvald) I think we should remove this.  Or maybe adapt to
-.\" a different example.
-.\"
-.\"     For
-.\"     .BR futex (7),
-.\"     this is executed if incrementing the count showed that
-.\"     there were waiters,
-.\"     once the futex value has been set to 1
-.\"     (indicating that it is available).
-.\"
-.\" How does "incrementing the count show that there were waiters"?
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.\"
+.TQ
+.BR FUTEX_WAKE (2const)
 .TP
 .BR FUTEX_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)"
 .\" Strictly speaking, from Linux 2.5.x to Linux 2.6.25
@@ -304,7 +268,7 @@ the futex at
 .IR uaddr .
 The caller must close the returned file descriptor after use.
 When another process or thread performs a
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 on the futex word, the file descriptor indicates as being readable with
 .BR select (2),
 .BR poll (2),
@@ -314,7 +278,7 @@ and
 The file descriptor can be used to obtain asynchronous notifications: if
 .I val
 is nonzero, then, when another process or thread executes a
-.BR FUTEX_WAKE ,
+.BR FUTEX_WAKE (2const),
 the caller will receive the signal number that was passed in
 .IR val .
 .IP
@@ -397,7 +361,7 @@ is not useful,
 because it would make the
 .B FUTEX_CMP_REQUEUE
 operation equivalent to
-.BR FUTEX_WAKE .)
+.BR FUTEX_WAKE (2const).)
 The limit value specified via
 .I val2
 is typically either 1 or
@@ -408,7 +372,7 @@ as 0 is not useful,
 because it would make the
 .B FUTEX_CMP_REQUEUE
 operation equivalent to
-.BR FUTEX_WAKE .)
+.BR FUTEX_WAKE (2const).)
 .IP
 The
 .B FUTEX_CMP_REQUEUE
@@ -432,7 +396,7 @@ Both
 and
 .B FUTEX_CMP_REQUEUE
 can be used to avoid "thundering herd" wake-ups that could occur when using
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 in cases where all of the waiters that are woken need to acquire
 another futex.
 Consider the following scenario,
@@ -452,7 +416,7 @@ unlock(A);
 .in
 .IP
 If a waker thread used
-.BR FUTEX_WAKE ,
+.BR FUTEX_WAKE (2const),
 then all waiters waiting on B would be woken up,
 and they would all try to acquire lock A.
 However, waking all of the threads in this manner would be pointless because
@@ -645,7 +609,7 @@ argument is ignored.
 .BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
 .\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
 This operation is the same as
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 except that the
 .I val3
 argument is used to provide a 32-bit bit mask to the kernel.
@@ -707,7 +671,7 @@ specified as
 .BR FUTEX_BITSET_MATCH_ANY ;
 that is, allow a wake-up by any waker.
 The
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 operation is equivalent to
 .B FUTEX_WAKE_BITSET
 with
@@ -1191,7 +1155,7 @@ The waiter can be removed from the wait on
 without requeueing on
 .I uaddr2
 via a
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 operation in another task.
 In this case, the
 .B FUTEX_WAIT_REQUEUE_PI
@@ -1263,9 +1227,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_WAKE
-Returns the number of waiters that were woken up.
-.TP
 .B FUTEX_FD
 Returns the new file descriptor associated with the futex.
 .TP
@@ -1458,8 +1419,7 @@ The signal number supplied in
 is invalid.
 .TP
 .B EINVAL
-.RB ( FUTEX_WAKE ,
-.BR FUTEX_WAKE_OP ,
+.RB ( FUTEX_WAKE_OP ,
 .BR FUTEX_WAKE_BITSET ,
 .BR FUTEX_REQUEUE ,
 .BR FUTEX_CMP_REQUEUE )

diff --git a/man/man2const/FUTEX_WAKE.2const b/man/man2const/FUTEX_WAKE.2const
new file mode 100644 (file)
index 0000000..ee62eee
--- /dev/null
+++ b/man/man2const/FUTEX_WAKE.2const
@@ -0,0 +1,78 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
+.\" may be freely modified and distributed
+.\" %%%LICENSE_END
+.\"
+.TH FUTEX_WAKE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+FUTEX_WAKE \- wake waiters that are inside FUTEX_WAIT
+.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_WAKE, uint32_t " val );
+.fi
+.SH DESCRIPTION
+.TP
+.BR FUTEX_WAKE " (since Linux 2.6.0)"
+.\" Strictly speaking, since Linux 2.5.x
+This operation wakes at most
+.I val
+of the waiters that are waiting (e.g., inside
+.BR FUTEX_WAIT (2const))
+on the futex word at the address
+.IR uaddr .
+Most commonly,
+.I val
+is specified as either 1 (wake up a single waiter) or
+.B INT_MAX
+(wake up all waiters).
+No guarantee is provided about which waiters are awoken
+(e.g., a waiter with a higher scheduling priority is not guaranteed
+to be awoken in preference to a waiter with a lower priority).
+.\" FIXME . (Torvald) I think we should remove this.  Or maybe adapt to
+.\" a different example.
+.\"
+.\"     For
+.\"     .BR futex (7),
+.\"     this is executed if incrementing the count showed that
+.\"     there were waiters,
+.\"     once the futex value has been set to 1
+.\"     (indicating that it is available).
+.\"
+.\" How does "incrementing the count show that there were waiters"?
+.\"
+.SH RETURN VALUE
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
+.P
+.B FUTEX_WAKE
+Returns the number of waiters that were woken up.
+.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\[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)