[PATCH v1 0/1] futex_waitv.2: Move text to a new PARAMETERS section

[Alejandro Colomar <alx@kernel.org>]

Hi!

Please let me know what you think of this patch?
Here's how the patch changes the page:

	$ MANWIDTH=72 diffman-git -U10 HEAD
	--- HEAD^:man/man2/futex_waitv.2
	+++ HEAD:man/man2/futex_waitv.2
	@@ -37,57 +37,103 @@ DESCRIPTION
	      ers[].uaddr[0] still contain respective expected values wait‐
	      ers[].val, and if so, sleeps waiting for a FUTEX_WAKE(2const) op‐
	      eration on any of the futex words, and returns the index of a
	      waiter whose futex was woken.
	 
	      If the thread starts to sleep, it is considered a waiter on all
	      given futex words.  If any of the futex values do not match their
	      respective waiters[].val, the call fails immediately with the er‐
	      ror EAGAIN.
	 
	-     If timeout is NULL, the call blocks indefinitely.  Otherwise,
	-     *timeout specifies a deadline measured against clock clockid.
	-     This interval will be rounded up to the system clock granularity,
	-     and is guaranteed not to expire early.
	-
	-     Futex words to monitor are given by struct futex_waitv, whose
	-     fields are analogous to FUTEX_WAIT(2const) parameters, except
	-     .__reserved must be 0 and .flags must contain one of FUTEX2_SIZE_*
	-     ORed with some of the flags below.
	-
	-     FUTEX2_SIZE_U32
	-            .val and .uaddr[] are 32‐bit unsigned integers.
	-
	-     FUTEX2_NUMA
	-            The futex word is followed by another word of the same size
	-            (.uaddr points to uintN_t[2] rather than uintN_t.  The word
	-            is given by .uaddr[1]), which can be either FUTEX_NO_NODE
	-            (all bits set) or a NUMA node number.
	-
	-            If the NUMA word is FUTEX_NO_NODE, the node number of the
	-            processor the syscall executes on is written to it.  (Ex‐
	-            cept that in an EINVAL or EFAULT condition, this happens to
	-            all waiters whose .flags have FUTEX2_NUMA set.)
	-
	-            Futexes are placed on the NUMA node given by the NUMA word.
	-            Futexes without this flag are placed on a random node.
	-
	-     FUTEX2_PRIVATE
	-            By default, the futex is shared (like FUTEX_WAIT(2const)),
	-            and can be accessed by multiple processes; this flag waits
	-            on a private futex word, where all users must use the same
	-            virtual memory map (like FUTEX_WAIT_PRIVATE; this most of‐
	-            ten means they are part of the same process).  Private fu‐
	-            texes are faster than shared ones.
	+PARAMETERS
	+   futex_waitv()
	+     waiters
	+            Futex words to monitor are given by struct futex_waitv,
	+            whose fields are similar to FUTEX_WAIT(2const) parameters.
	+
	+     n      Specify as countof(waiters).
	+
	+     timeout
	+            If timeout is NULL, the call blocks indefinitely.  Other‐
	+            wise, *timeout specifies a deadline measured against clock
	+            clockid.  This interval will be rounded up to the system
	+            clock granularity, and is guaranteed not to expire early.
	+
	+     clockid
	+            Supported clocks:
	+
	+            CLOCK_MONOTONIC
	+            CLOCK_REALTIME
	+
	+     flags  Specify as 0.
	+
	+   struct futex_waitv
	+     .val   Expected value of .uaddr[0].
	+
	+     .uaddr
	+
	+            .uaddr[0]
	+                   See FUTEX_WAIT(2const).
	+
	+            .uaddr[1]
	+                   See FUTEX2_NUMA below.  This field, if it exists,
	+                   must contain a NUMA word, which can be either FU‐
	+                   TEX_NO_NODE or a NUMA node number.
	+
	+                   If the NUMA word is FUTEX_NO_NODE, the node number
	+                   of the processor the syscall executes on is written
	+                   to it.  (Except that in an EINVAL or EFAULT condi‐
	+                   tion, this happens to all waiters whose .flags have
	+                   FUTEX2_NUMA set.)
	+
	+            Programs should assign to .uaddr by casting a pointer to
	+            uintptr_t.
	+
	+     .flags
	+            It must contain exactly one size flag ORed with zero or
	+            more of the other flags.
	+
	+            Size flags
	+
	+                   FUTEX2_SIZE_U32
	+                          .val and .uaddr[] are 32‐bit unsigned inte‐
	+                          gers.
	+
	+                   FUTEX2_SIZE_U8
	+                   FUTEX2_SIZE_U16
	+                   FUTEX2_SIZE_U64
	+                          These are defined, but not supported (EIN‐
	+                          VAL).
	+
	+            Other flags
	+
	+                   FUTEX2_NUMA
	+                          The futex word is followed by the NUMA word,
	+                          of the same size (.uaddr points to uintN_t[2]
	+                          rather than uintN_t).
	+
	+                          Futexes are placed on the NUMA node given by
	+                          the NUMA word.  Futexes without this flag are
	+                          placed on a random node.
	+
	+                   FUTEX2_PRIVATE
	+                          By default, the futex is shared (like FU‐
	+                          TEX_WAIT(2const)), and can be accessed by
	+                          multiple processes; this flag waits on a pri‐
	+                          vate futex word, where all users must use the
	+                          same virtual memory map (like FUTEX_WAIT_PRI‐
	+                          VATE; this most often means they are part of
	+                          the same process).  Private futexes are
	+                          faster than shared ones.
	 
	-     Programs should assign to .uaddr by casting a pointer to
	-     uintptr_t.
	+     .__reserved
	+            Specify as 0.
	 
	 RETURN VALUE
	      Returns an index to an arbitrary entry in waiters corresponding to
	      some woken‐up futex.  This implies no information about other
	      waiters.
	 
	      On error, -1 is returned, and errno is set to indicate the error.
	 
	 ERRORS
	      EFAULT
	@@ -106,33 +152,32 @@ ERRORS
		     ject——that is, the address is not aligned appropriately for
		     the specified FUTEX2_SIZE_*.
	 
	      EINVAL
		     flags was not 0.
	 
	      EINVAL
		     n was not in the range [1, FUTEX_WAITV_MAX].
	 
	      EINVAL
	-            timeout was not NULL and clockid was not a valid clock
	-            (CLOCK_MONOTONIC or CLOCK_REALTIME).
	+            timeout was not NULL and clockid was not a valid clock.
	 
	      EINVAL
		     *timeout is denormal (before epoch or tv_nsec not in the
		     range [0, 999'999'999]).
	 
	      EINVAL
		     Any waiters[].flags field contains an unknown flag.
	 
	      EINVAL
	-            Any waiters[].flags field is missing a FUTEX2_SIZE_* flag
	-            or has a size flag different than FUTEX2_SIZE_U32 set.
	+            Any waiters[].flags field is missing a size flag or has an
	+            unsupported one.
	 
	      EINVAL
		     Any waiters[].__reserved field is not 0.
	 
	      EINVAL
		     Any waiters[].value field has more bits set than permitted
		     than the size flags.
	 
	      EINVAL
		     FUTEX2_NUMA was set in waiters[].flags, and the NUMA word
	@@ -151,25 +196,20 @@ ERRORS
	 
	      EAGAIN or EWOULDBLOCK
		     The value in .uaddr[0] was not equal to the expected value
		     .val at the time of the call.
	 
	      EINTR  The operation was interrupted by a signal (see signal(7)).
	 
	 STANDARDS
	      Linux.
	 
	-NOTES
	-     FUTEX2_SIZE_U8, FUTEX2_SIZE_U16, and FUTEX2_SIZE_U64 where .val
	-     and .uaddr[] are 8, 16, or 64 bits are defined, but not imple‐
	-     mented (EINVAL).
	-
	 HISTORY
	      Linux 5.16.
	 
	 EXAMPLES
	      The program below executes a linear‐time operation on 10 threads,
	      displaying the results in real time, waiting at most 1 second for
	      each new result.  The first 3 threads operate on the same data
	      (complete in the same time).  ! indicates the futex that woke up
	      each futex_waitv().


What do you think?  I think the formatted page is more readable.
The source gets more complex, but I could live with that.


Cheers,
Alex


Alejandro Colomar (1):
  man/man2/futex_waitv.2: Move text to a new PARAMETERS section

 man/man2/futex_waitv.2 | 157 ++++++++++++++++++++++++++---------------
 1 file changed, 99 insertions(+), 58 deletions(-)

Range-diff against v0:
-:  ------------ > 1:  22d6ad793c4c man/man2/futex_waitv.2: Move text to a new PARAMETERS section

base-commit: ee4402e21d91c285f5f85071713985f2be7ac412
-- 
2.51.0