[PATCH v5 0/3] Add documentation for PR_FUTEX_HASH

[PATCH v5 0/3] Add documentation for PR_FUTEX_HASH

[Sebastian Andrzej Siewior]

Add some documentation of the prctl(PR_FUTEX_HASH, …) interface.
The PR_FUTEX_HASH interface has been disabled for the final v6.16
release and enabled again for v6.17.

This series updates the merged PR_FUTEX_HASH page and adds
PR_FUTEX_HASH_SET_SLOTS and PR_FUTEX_HASH_GET_SLOTS.

v4…v5: https://lore.kernel.org/all/20250602140104.2769223-1-bigeasy@linutronix.de/
  - Update merged PR_FUTEX_HASH
  - Drop PR_FUTEX_HASH_GET_IMMUTABLE, functionality has been removed.
  - Update SET_SLOTS/ GET_SLOTS based on review.

v3…v4: https://lore.kernel.org/all/20250526155523.1382465-1-bigeasy@linutronix.de/
  - Make FH_FLAG_IMMUTABLE and CONFIG_PROVE_LOCKING bold.
  - Drop one too many "Relative inset"
  - Reword return value for "GET_IMMUTABLE"
  - Reword the description of "unrelated futexes" in PR_FUTEX_HASH

v2…v3: https://lore.kernel.org/all/20250520104247.S-gVcgxM@linutronix.de/
  - Split the individual PR_FUTEX_HASH ops into their own man page.
  - Reword a sentence referring to uaddr in order to link to futex(2).
  - Address remaining review feedback such the semantic new line.

v1…v2: https://lore.kernel.org/all/20250516161422.BqmdlxlF@linutronix.de/
  - Partly reword
  - Use "semantic newlines"

Sebastian Andrzej Siewior (3):
  man/man2const/PR_FUTEX_HASH.2const: Update as of Linux v6.17-rc2
  man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document
    PR_FUTEX_HASH_SET_SLOTS
  man/man2/prctl.2, PR_FUTEX_HASH_GET_SLOTS.2const: Document
    PR_FUTEX_HASH_GET_SLOTS

 man/man2const/PR_FUTEX_HASH.2const           |  7 +-
 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const | 35 ++++++++++
 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 67 ++++++++++++++++++++
 3 files changed, 104 insertions(+), 5 deletions(-)
 create mode 100644 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
 create mode 100644 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const

-- 
2.50.1

[PATCH v5 1/3] man/man2const/PR_FUTEX_HASH.2const: Update as of Linux v6.17-rc2

[Sebastian Andrzej Siewior]

The PR_FUTEX_HASH prctl interface was updated shortly before the release
of v6.16. The changes are:
- the functionality was disabled in v6.16 and enabled v6.17-rc1 after
  some updates the address performance concerns.
- the "IMMUTABLE" functionality was removed.

Update the page accordingly.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2const/PR_FUTEX_HASH.2const | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/man/man2const/PR_FUTEX_HASH.2const b/man/man2const/PR_FUTEX_HASH.2const
index b500c943bf2cb..bc05226cd1594 100644
--- a/man/man2const/PR_FUTEX_HASH.2const
+++ b/man/man2const/PR_FUTEX_HASH.2const
@@ -44,7 +44,7 @@ since random processes can
 share in-kernel locks
 and it is not deterministic which process will be involved.
 .P
-Linux 6.16 implements a process-wide private hash which is used by all
+Linux 6.17 implements a process-wide private hash which is used by all
 .BR futex (2)
 operations that specify the
 .B FUTEX_PRIVATE_FLAG
@@ -68,8 +68,6 @@ The value in
 .I op
 is one of the options below.
 .TP
-.B PR_FUTEX_HASH_GET_IMMUTABLE
-.TQ
 .B PR_FUTEX_HASH_GET_SLOTS
 .TQ
 .B PR_FUTEX_HASH_SET_SLOTS
@@ -82,10 +80,9 @@ is set to indicate the error.
 .SH STANDARDS
 Linux.
 .SH HISTORY
-Linux 6.16.
+Linux 6.17.
 .SH SEE ALSO
 .BR prctl (2),
 .BR futex (2),
-.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
 .BR PR_FUTEX_HASH_GET_SLOTS (2const),
 .BR PR_FUTEX_HASH_SET_SLOTS (2const)
-- 
2.50.1

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

[Sebastian Andrzej Siewior]

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

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

[Sebastian Andrzej Siewior]

Reviewed-by: Alejandro Colomar <alx@kernel.org>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const | 35 ++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const

diff --git a/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
new file mode 100644
index 0000000000000..dfeffa57930ab
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
@@ -0,0 +1,35 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH PR_FUTEX_HASH_GET_SLOTS 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+PR_FUTEX_HASH_GET_SLOTS
+\-
+return 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_GET_SLOTS);
+.fi
+.SH DESCRIPTION
+Return the current size of the private hash.
+.SH RETURN VALUE
+A value of 0 means that a private hash has not been allocated
+and the global hash is in use.
+A value >0 specifies the size of the private hash.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.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

[Alejandro Colomar]

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

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/>

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

Re: [PATCH v5 1/3] man/man2const/PR_FUTEX_HASH.2const: Update as of Linux v6.17-rc2

[Alejandro Colomar]

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

Hi Sebastian,

On Tue, Aug 19, 2025 at 09:17:26AM +0200, Sebastian Andrzej Siewior wrote:
> The PR_FUTEX_HASH prctl interface was updated shortly before the release
> of v6.16. The changes are:
> - the functionality was disabled in v6.16 and enabled v6.17-rc1 after
>   some updates the address performance concerns.
> - the "IMMUTABLE" functionality was removed.
> 
> Update the page accordingly.
> 
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Thanks!  I've applied the patch.


Cheers,
Alex

> ---
>  man/man2const/PR_FUTEX_HASH.2const | 7 ++-----
>  1 file changed, 2 insertions(+), 5 deletions(-)
> 
> diff --git a/man/man2const/PR_FUTEX_HASH.2const b/man/man2const/PR_FUTEX_HASH.2const
> index b500c943bf2cb..bc05226cd1594 100644
> --- a/man/man2const/PR_FUTEX_HASH.2const
> +++ b/man/man2const/PR_FUTEX_HASH.2const
> @@ -44,7 +44,7 @@ since random processes can
>  share in-kernel locks
>  and it is not deterministic which process will be involved.
>  .P
> -Linux 6.16 implements a process-wide private hash which is used by all
> +Linux 6.17 implements a process-wide private hash which is used by all
>  .BR futex (2)
>  operations that specify the
>  .B FUTEX_PRIVATE_FLAG
> @@ -68,8 +68,6 @@ The value in
>  .I op
>  is one of the options below.
>  .TP
> -.B PR_FUTEX_HASH_GET_IMMUTABLE
> -.TQ
>  .B PR_FUTEX_HASH_GET_SLOTS
>  .TQ
>  .B PR_FUTEX_HASH_SET_SLOTS
> @@ -82,10 +80,9 @@ is set to indicate the error.
>  .SH STANDARDS
>  Linux.
>  .SH HISTORY
> -Linux 6.16.
> +Linux 6.17.
>  .SH SEE ALSO
>  .BR prctl (2),
>  .BR futex (2),
> -.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
>  .BR PR_FUTEX_HASH_GET_SLOTS (2const),
>  .BR PR_FUTEX_HASH_SET_SLOTS (2const)
> -- 
> 2.50.1
> 

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

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

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

[Alejandro Colomar]

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

Hi Sebastian,

On Tue, Aug 19, 2025 at 09:17:28AM +0200, Sebastian Andrzej Siewior wrote:
> Reviewed-by: Alejandro Colomar <alx@kernel.org>
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Thanks!  I've applied this patch.


Have a lovely day!
Alex

> ---
>  man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const | 35 ++++++++++++++++++++
>  1 file changed, 35 insertions(+)
>  create mode 100644 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
> 
> diff --git a/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
> new file mode 100644
> index 0000000000000..dfeffa57930ab
> --- /dev/null
> +++ b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
> @@ -0,0 +1,35 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH PR_FUTEX_HASH_GET_SLOTS 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +PR_FUTEX_HASH_GET_SLOTS
> +\-
> +return 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_GET_SLOTS);
> +.fi
> +.SH DESCRIPTION
> +Return the current size of the private hash.
> +.SH RETURN VALUE
> +A value of 0 means that a private hash has not been allocated
> +and the global hash is in use.
> +A value >0 specifies the size of the private hash.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.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/>

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

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

[Alejandro Colomar]

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

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/>

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

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

[Sebastian Andrzej Siewior]

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

[Alejandro Colomar]

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

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/>

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

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

[Sebastian Andrzej Siewior]

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