Re: [PATCH v4 2/4] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Alejandro Colomar
2025-06-11T08:51:09Z

[-- Attachment #1: Type: text/plain, Size: 3535 bytes --]

Hi Sebastian,

On Mon, Jun 02, 2025 at 04:01:02PM +0200, Sebastian Andrzej Siewior wrote:
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
> man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 83 ++++++++++++++++++++
> 1 file changed, 83 insertions(+)
> create mode 100644 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
>
> diff --git a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> new file mode 100644
> index 0000000000000..1f08d1bb30485
> --- /dev/null
> +++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> @@ -0,0 +1,83 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH PR_FUTEX_HASH_SET_SLOTS 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +PR_FUTEX_HASH_SET_SLOTS
> +\-
> +set the size of the private hash
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */"
> +.B #include <sys/prctl.h>
> +.P
> +.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_SET_SLOTS,
> +.BI " unsigned long " hash_size ", unsigned long " hash_flags ");
> +.fi
> +.SH DESCRIPTION
> +Set the number of slots to use for the private hash.
> +.TP
> +.I hash_size
> +Specifies the size of private hash to allocate.

s/Specifies/Specify/ for consistency with "Set" and "Use".

> +.RS
> +.TP
> +.I 0
> +Use the global hash.
> +This is the behaviour used before 6.16.
> +The operation implies the
> +.I FH_FLAG_IMMUTABLE
> +flag.
> +.TP
> +.I >0
> +Specifies the number of slots to allocate.

Same here.

> +The value must be power of two and the lowest possible value is 2.

s/two/&,/

> +The upper limit depends on the available memory in the system.
> +Each slot requires 64bytes of memory.

s/64bytes/64 bytes/

> +Kernels compiled with
> +.I CONFIG_PROVE_LOCKING
> +will consume more than that.
> +.RE
> +.TP
> +.I hash_flags
> +.RS
> +The following flags can be specified:
> +.TP
> +.I FH_FLAG_IMMUTABLE
> +The private hash can no longer be changed.
> +By using an immutable private hash
> +the kernel can avoid some accounting for the data structure.
> +This accounting is visible in benchmarks if many
> +.BR futex (2)
> +operations are invoked in parallel on different CPUs.
> +.RE
> +.RE

One RE doesn't match any RS.

> +.SH RETURN VALUE
> +On success,
> +0 is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +One of the supplied argument is invalid.

This sentence seems to have some issues about singular/plural. I can't
read it properly. I think we can simplify to

An argument is invalid.

> +.TP
> +.B ENOMEM
> +Failed to allocate memory.
> +.TP
> +.B EBUSY
> +An immutable hash is already in use
> +and can not be changed.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.16.
> +.SH SEE ALSO
> +.BR prctl (2),
> +.BR PR_FUTEX_HASH (2const),
> +.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
> +.BR PR_FUTEX_HASH_GET_SLOTS (2const)

I think we can simplify this to link just to the parents:

+.BR prctl (2),
+.BR PR_FUTEX_HASH (2const),

Since PR_FUTEX_HASH(2const) already links to all of them, we don't need
to cross link. That'll be simpler to maintain.

Have a lovely day!
Alex

> --
> 2.49.0
>

--
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]