Re: [PATCH] futex_waitv.2: new page

[Alejandro Colomar <alx@kernel.org>]

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

On 2026-02-07T20:16:36+0100, наб wrote:
> Hi!

Hi!

> 
> On Sat, Feb 07, 2026 at 07:57:03PM +0100, Alejandro Colomar wrote:
> > On 2026-02-07T13:49:12+0100, наб wrote:
> > > +.TP
> > > +.B EINVAL
> > > +.I nr_futexes
> > > +was not between 1 and
> > > +.B FUTEX_WAITV_MAX
> > > +(128).
> > 
> > In this case I would like to see a range.  "Between" doesn't make it
> > clear whether the bounds are inclusive or exclusive or combined.
> 
> "nr_futexes was not in [1, FUTEX_WAITV_MAX (128)]."?

Yeah, that sounds quite good.

> > > +.TP
> > > +.B EAGAIN
> > > +The value pointed to by
> > > +.I uaddr
> > > +was not equal to the expected value
> > > +.I val
> > > +at the time of the call.
> > > +.IP
> > > +.BR Note :
> > > +on Linux, the symbolic names
> > > +.B EAGAIN
> > > +and
> > > +.B EWOULDBLOCK
> > > +(both of which appear in different parts of the kernel futex code)
> > > +have the same value.
> > 
> > Should we use wording like in read(2)?  It uses
> > 
> > 	.TP
> > 	.BR EAGAIN " or " EWOULDBLOCK
> > 
> > Or do you have reasons to prefer your wording?
> 
> That's what FUTEX_WAIT(2const) says and that's the most-sister page
> I copied this from (it is pretty crazy wording). But

Makes sense, thanks!

>   $ git grep 'hich appear in different'
>   man/man2/futex_waitv.2:(both of which appear in different parts of the kernel futex code)
>   man/man2const/FUTEX_WAIT.2const:(both of which appear in different parts of the kernel futex code)
>   man/man2const/FUTEX_WAIT_BITSET.2const:(both of which appear in different parts of the kernel futex code)
>   man/man2const/FUTEX_WAIT_REQUEUE_PI.2const:(both of which appear in different parts of the kernel futex code)
> so those want to get those gone as well.

Yeah, if you feel like cleaning up the wording in all of them, that
would help.  On the other hand, I would understand if you don't feel
like doing that.  Do what you prefer.  :)

> 
> > > +.SH NOTES
> > 
> > Maybe CAVEATS?
> 
> idk if it's a caveat... the futex(2) API family functionally hard-codes
> FUTEX2_SIZE_U32 into every operation and it's not a caveat there.
> And, having just seen a lot of futex kernel code, it abuses futexes
> being 4 bytes /so much/. I don't think anyone's expecting to have
> non-4-byte futexes any time soon. So this is more like a notable curio
> to explain why you need FUTEX2_SIZE_U32 at all than "beware this missing API".
> Y/N?

Agree.

> 
> > > +#include <linux/futex.h>
> > > +#include <sys/syscall.h>
> > > +#include <time.h>
> > > +#include <unistd.h>
> > > +\&
> > 
> > What's the distinction between the two include groups?
> Top 4 are for the syscall from SYNOPSIS,
> rest are for application code.

I would merge them.  After all, we already have the SYNOPSIS for that.


Cheers,
Alex

> 
> Best,



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

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