From: Alejandro Colomar <alx@kernel.org>
Date: Tue, 27 May 2025 13:39:00 +0000 (+0200)
Subject: man/man2const/FUTEX_WAIT.2const: Tweak after split
X-Git-Tag: man-pages-6.15~43^2~25
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2425f1c6ace2a9b0ab1b35a920d707693bbe294a;p=thirdparty%2Fman-pages.git

man/man2const/FUTEX_WAIT.2const: Tweak after split

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

diff --git a/man/man2const/FUTEX_WAIT.2const b/man/man2const/FUTEX_WAIT.2const
index 9933e12d8..388f0d420 100644
--- a/man/man2const/FUTEX_WAIT.2const
+++ b/man/man2const/FUTEX_WAIT.2const
@@ -19,20 +19,18 @@ Standard C library
 .B #include <unistd.h>
 .P
 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT, uint32_t " val ,
-.BI "             const struct timespec *" timeout );
+.BI "             const struct timespec *_Nullable " timeout );
 .fi
 .SH DESCRIPTION
-.TP
-.BR FUTEX_WAIT " (since Linux 2.6.0)"
-.\" Strictly speaking, since some time in Linux 2.5.x
 This operation tests that the value at the
 futex word pointed to by the address
 .I uaddr
 still contains the expected value
 .IR val ,
 and if so, then sleeps waiting for a
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 operation on the futex word.
+.P
 The load of the value of the futex word is an atomic memory
 access (i.e., using atomic machine instructions of the respective
 architecture).
@@ -42,24 +40,25 @@ starting to sleep are performed atomically
 .\" "totally ordered" here.
 and totally ordered
 with respect to other futex operations on the same futex word.
+.P
 If the thread starts to sleep,
 it is considered a waiter on this futex word.
 If the futex value does not match
 .IR val ,
 then the call fails immediately with the error
 .BR EAGAIN .
-.IP
+.P
 The purpose of the comparison with the expected value is to prevent lost
 wake-ups.
 If another thread changed the value of the futex word after the
 calling thread decided to block based on the prior value,
 and if the other thread executed a
-.B FUTEX_WAKE
+.BR FUTEX_WAKE (2const)
 operation (or similar wake-up) after the value change and before this
 .B FUTEX_WAIT
 operation, then the calling thread will observe the
 value change and will not start to sleep.
-.IP
+.P
 If the
 .I timeout
 is not NULL, the structure it points to specifies a
@@ -69,25 +68,6 @@ and is guaranteed not to expire early.)
 If
 .I timeout
 is NULL, the call blocks indefinitely.
-.IP
-.IR Note :
-for
-.BR FUTEX_WAIT ,
-.I timeout
-is interpreted as a
-.I relative
-value.
-This differs from other futex operations, where
-.I timeout
-is interpreted as an absolute value.
-To obtain the equivalent of
-.B FUTEX_WAIT
-with an absolute timeout, employ
-.B FUTEX_WAIT_BITSET
-with
-.I val3
-specified as
-.BR FUTEX_BITSET_MATCH_ANY .
 .\" FIXME . (Torvald) I think we should remove this.  Or maybe adapt to a
 .\" different example.
 .\"
@@ -109,7 +89,7 @@ is set to indicate the error.
 .P
 On success,
 .B FUTEX_WAIT
-Returns 0 if the caller was woken up.
+returns 0 if the caller was woken up.
 Note that a wake-up can also be caused by common futex usage patterns
 in unrelated code that happened to have previously used the futex word's
 memory location (e.g., typical futex-based implementations of
@@ -164,5 +144,22 @@ The timeout expired before the operation completed.
 Linux.
 .SH HISTORY
 Linux 2.6.0.
+.\" Strictly speaking, since some time in Linux 2.5.x
+.SH CAVEATS
+.I timeout
+is interpreted as a
+.I relative
+value.
+This differs from other futex operations, where
+.I timeout
+is interpreted as an absolute value.
+To obtain the equivalent of
+.B FUTEX_WAIT
+with an absolute timeout, employ
+.BR FUTEX_WAIT_BITSET (2const)
+with
+.I val3
+specified as
+.BR FUTEX_BITSET_MATCH_ANY .
 .SH SEE ALSO
 .BR futex (2)