From 178e3024de7e6361c1c9de896de0dbf5362e6011 Mon Sep 17 00:00:00 2001 From: Alejandro Colomar Date: Thu, 29 May 2025 01:08:31 +0200 Subject: [PATCH] man/man2/futex.2, man/man2const/FUTEX_REQUEUE.2const: Split FUTEX_REQUEUE from futex(2) Signed-off-by: Alejandro Colomar --- man/man2/futex.2 | 22 ++-------- man/man2const/FUTEX_REQUEUE.2const | 67 ++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 18 deletions(-) create mode 100644 man/man2const/FUTEX_REQUEUE.2const diff --git a/man/man2/futex.2 b/man/man2/futex.2 index 4a56c003b..ccbf707fe 100644 --- 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 index 000000000..0df4c8b81 --- /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 " " /* Definition of " FUTEX_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.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) -- 2.47.2