[v5] Add documentation for PR_FUTEX_HASH

[PATCH v5 2/3] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Posted by Sebastian Andrzej Siewior 1 month, 2 weeks ago

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 67 ++++++++++++++++++++
 1 file changed, 67 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..93af27cbd5e5e
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
@@ -0,0 +1,67 @@
+.\" 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
+Specify the size of private hash to allocate.
+.RS
+.TP
+.I 0
+Use the global hash.
+This is the behaviour used before 6.17.
+.TP
+.I >0
+Specify the number of slots to allocate.
+The value must be power of two, and the lowest possible value is 2.
+The upper limit depends on the available memory in the system.
+Each slot requires 64 bytes of memory.
+Kernels compiled with
+.I CONFIG_PROVE_LOCKING
+will consume more than that.
+.RE
+.TP
+.I hash_flags
+.RS
+The argument must be 0.
+.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
+An argument is invalid.
+.TP
+.B ENOMEM
+Failed to allocate memory.
+.TP
+.B EBUSY
+The global hash is in use and can not be changed.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.17.
+.SH SEE ALSO
+.BR prctl (2),
+.BR PR_FUTEX_HASH (2const)
-- 
2.50.1

Re: [PATCH v5 2/3] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Posted by Alejandro Colomar 1 month, 2 weeks ago

Hi Sebastian,

On Tue, Aug 19, 2025 at 09:17:27AM +0200, Sebastian Andrzej Siewior wrote:
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 67 ++++++++++++++++++++
>  1 file changed, 67 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..93af27cbd5e5e
> --- /dev/null
> +++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> @@ -0,0 +1,67 @@
> +.\" 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
> +Specify the size of private hash to allocate.
> +.RS
> +.TP
> +.I 0
> +Use the global hash.
> +This is the behaviour used before 6.17.
> +.TP
> +.I >0
> +Specify the number of slots to allocate.

Should we rename hash_size to just 'n' for simplicity?  Or maybe size?

> +The value must be power of two, and the lowest possible value is 2.
> +The upper limit depends on the available memory in the system.
> +Each slot requires 64 bytes of memory.
> +Kernels compiled with
> +.I CONFIG_PROVE_LOCKING
> +will consume more than that.
> +.RE
> +.TP
> +.I hash_flags

And I guess this could be just flags, right?


Have a lovely day!
Alex

> +.RS
> +The argument must be 0.
> +.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
> +An argument is invalid.
> +.TP
> +.B ENOMEM
> +Failed to allocate memory.
> +.TP
> +.B EBUSY
> +The global hash is in use and can not be changed.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.17.
> +.SH SEE ALSO
> +.BR prctl (2),
> +.BR PR_FUTEX_HASH (2const)
> -- 
> 2.50.1
> 

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

Re: [PATCH v5 2/3] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Posted by Alejandro Colomar 1 month, 2 weeks ago

Hi Sebastian,

On Tue, Aug 19, 2025 at 01:02:42PM +0200, Alejandro Colomar wrote:
> On Tue, Aug 19, 2025 at 09:17:27AM +0200, Sebastian Andrzej Siewior wrote:
> > Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> > ---
> >  man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 67 ++++++++++++++++++++
> >  1 file changed, 67 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..93af27cbd5e5e
> > --- /dev/null
> > +++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> > @@ -0,0 +1,67 @@
> > +.\" 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 ");

I see that it is implemented in the kernel as

	static int
	futex_hash_allocate(unsigned int hash_slots, unsigned int flags)
	{
		...
	}

But PR_FUTEX_HASH is implemented as

	int
	futex_hash_prctl(unsigned long arg2, unsigned long arg3,
	    unsigned long arg4)
	{
		...
	}

Should we document is as a u_int, or a u_long?  Is that mismatch a bug,
or is it on purpose?


Cheers,
Alex

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

Re: [PATCH v5 2/3] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Posted by Sebastian Andrzej Siewior 1 month, 1 week ago

On 2025-08-19 13:19:15 [+0200], Alejandro Colomar wrote:
> Hi Sebastian,
Hi Alejandro,

> > > +.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_SET_SLOTS,
> > > +.BI "          unsigned long " hash_size ", unsigned long " hash_flags ");
> 
> I see that it is implemented in the kernel as
> 
> 	static int
> 	futex_hash_allocate(unsigned int hash_slots, unsigned int flags)
> 	{
> 		...
> 	}
> 
> But PR_FUTEX_HASH is implemented as
> 
> 	int
> 	futex_hash_prctl(unsigned long arg2, unsigned long arg3,
> 	    unsigned long arg4)
> 	{
> 		...
> 	}
> 
> Should we document is as a u_int, or a u_long?  Is that mismatch a bug,
> or is it on purpose?

The prctl() interface is long so I started with that. Internally we keep
it as an int since we don't need it that big and it avoids a hole
otherwise (but then there is a hole towards the end of the structure).
Realistically speaking 1 << 31 is the largest value that can be
specified (atm) and it will very likely lead to ENOMEM. If the user
tries the next higher value, 1 << 32, then the upper bits will be
truncated and the global hash will be requested and this will succeed.

The bug could be based on the argument type 1 << 32 will succeed but
it should not. Using 1 << 25 will request ~2GiB of memory and is a bit
far from sane.
I am bit forth and back between forcing an error for anything > 1 << 30,
or updating the docs to int. But this will be the easiest ;)
Any recommendations based on similar cases?

> Cheers,
> Alex

Sebastian

Re: [PATCH v5 2/3] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Posted by Alejandro Colomar 1 month, 1 week ago

On Thu, Aug 21, 2025 at 04:08:51PM +0200, Sebastian Andrzej Siewior wrote:
> On 2025-08-19 13:19:15 [+0200], Alejandro Colomar wrote:
> > Hi Sebastian,
> Hi Alejandro,

Hi Sebastian,

> > > > +.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_SET_SLOTS,
> > > > +.BI "          unsigned long " hash_size ", unsigned long " hash_flags ");
> > 
> > I see that it is implemented in the kernel as
> > 
> > 	static int
> > 	futex_hash_allocate(unsigned int hash_slots, unsigned int flags)
> > 	{
> > 		...
> > 	}
> > 
> > But PR_FUTEX_HASH is implemented as
> > 
> > 	int
> > 	futex_hash_prctl(unsigned long arg2, unsigned long arg3,
> > 	    unsigned long arg4)
> > 	{
> > 		...
> > 	}
> > 
> > Should we document is as a u_int, or a u_long?  Is that mismatch a bug,
> > or is it on purpose?
> 
> The prctl() interface is long so I started with that. Internally we keep
> it as an int since we don't need it that big and it avoids a hole
> otherwise (but then there is a hole towards the end of the structure).
> Realistically speaking 1 << 31 is the largest value that can be
> specified (atm) and it will very likely lead to ENOMEM. If the user
> tries the next higher value, 1 << 32, then the upper bits will be
> truncated and the global hash will be requested and this will succeed.
> 
> The bug could be based on the argument type 1 << 32 will succeed but
> it should not. Using 1 << 25 will request ~2GiB of memory and is a bit
> far from sane.
> I am bit forth and back between forcing an error for anything > 1 << 30,
> or updating the docs to int. But this will be the easiest ;)
> Any recommendations based on similar cases?

I don't remember any similar cases atm.

I guess we should document it as long, because in ABIs where it matters,
users should pass a long.  People should probably not be passing such
huge values, so we can leave it as an undocumented bug, which can be
fixed later if we ever find it to be important.

Changing the implementation from int to long if we ever need it should
be easy, as it doesn't break user space (it would rather fix it).


Have a lovely night!
Alex

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

[PATCH v6] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

Posted by Sebastian Andrzej Siewior 1 month, 1 week ago

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
v5…v6:
  - hash_size -> size
  - hash_flags -> flags

 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 67 ++++++++++++++++++++
 1 file changed, 67 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..1605c18c6985b
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
@@ -0,0 +1,67 @@
+.\" 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 " size ", unsigned long " flags ");
+.fi
+.SH DESCRIPTION
+Set the number of slots to use for the private hash.
+.TP
+.I size
+Specify the size of private hash to allocate.
+.RS
+.TP
+.I 0
+Use the global hash.
+This is the behaviour used before 6.17.
+.TP
+.I >0
+Specify the number of slots to allocate.
+The value must be power of two, and the lowest possible value is 2.
+The upper limit depends on the available memory in the system.
+Each slot requires 64 bytes of memory.
+Kernels compiled with
+.I CONFIG_PROVE_LOCKING
+will consume more than that.
+.RE
+.TP
+.I flags
+.RS
+The argument must be 0.
+.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
+An argument is invalid.
+.TP
+.B ENOMEM
+Failed to allocate memory.
+.TP
+.B EBUSY
+The global hash is in use and can not be changed.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.17.
+.SH SEE ALSO
+.BR prctl (2),
+.BR PR_FUTEX_HASH (2const)
-- 
2.50.1