Re: [PATCH v1 07/10] man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}

On Wed Feb 11, 2026 at 7:29 PM IST, Alejandro Colomar wrote:
> Hi Bhavik,

Hey Alex!

>
> On 2026-02-10T02:47:40+0530, Bhavik Sachdev wrote:
>> Document the STATMOUNT_{UIDMAP,GIDMAP} flags and the corresponding
>> fields introduced by them. Most of this is based on the commit message
>> provided here [1].
>> 
>> Link [1]:
>> <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=37c4a9590e1efcae7749682239fc22a330d2d325>
>> 
>> Signed-off-by: Bhavik Sachdev <[email protected]>
>> ---
>>  man/man2/statmount.2 | 34 ++++++++++++++++++++++++++++++++++
>>  1 file changed, 34 insertions(+)
>> 
>> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
>> index b7acde8f4..4da55eb38 100644
>> --- a/man/man2/statmount.2
>> +++ b/man/man2/statmount.2
>> @@ -56,6 +56,10 @@ .SH SYNOPSIS
>>  .B "    __u32  opt_array;"
>>  .B "    __u32  opt_sec_num;"
>>  .B "    __u32  opt_sec_array;"
>> +.B "    __u32  mnt_uidmap_num;"
>> +.B "    __u32  mnt_uidmap;"
>> +.B "    __u32  mnt_gidmap_num;"
>> +.B "    __u32  mnt_gidmap;"
>>  .B "    char   str[];"
>>  .B };
>>  .EE
>> @@ -120,6 +124,8 @@ .SS The mnt_id_req structure
>>  STATMOUNT_SB_SOURCE	/* Want/got sb_source */
>>  STATMOUNT_OPT_ARRAY	/* Want/got opt_... */
>>  STATMOUNT_OPT_SEC_ARRAY	/* Want/got opt_sec... */
>> +STATMOUNT_MNT_UIDMAP	/* Want/got uidmap... */
>> +STATMOUNT_MNT_GIDMAP	/* Want/got gidmap... */
>>  .TE
>>  .in
>>  .P
>> @@ -299,6 +305,34 @@ .SS The returned information
>>  buffer that contains security options separated by null bytes.
>>  They can be iterated over the help of
>>  .IR smbuf.opt_sec_num .
>> +.TP
>> +.I smbuf.mnt_uidmap_num
>> +The number of uid mappings in case of an idmapped mount.
>> +If STATMOUNT_UIDMAP was not unset and this field is 0,
>
> "If ... was not unset" is confusing.  As far as I can read, the .param
> field is an ORed combination of flags, so usually you set things,
> because otherwise you get 0.
>
> The wording seems to imply that something is set by default and I'd need
> to unset it explicitly.
>
> Am I missing something?
>
> Should this say "If ... was set"?
>

The patch implicitly refers to the smbuf.mask field, which is a ORed
combination of the flags statmount() was actually able to successfully
fill.

So, if smbuf.mask has STATMOUNT_UIDMAP set (i.e the kernel was able to
successfully get the uid mappings of the mount) and smbuf.mnt_uidmap_num
is 0, then the mount is not a idmapped mount.

The patch does a terrible job of explaining this, i will come up with
something better.

>> +the mount is not an idmapped mount.
>> +.TP
>> +.I smbuf.mnt_uidmap
>> +The offset to the location in the
>> +.I smbuf.str
>> +buffer that contains uid mappings as string array separated by null bytes.
>> +They can be iterated over with the help of
>> +.IR smbuf.mnt_uidmap_num .
>> +The whole range of uid mappings must be resolvable inthe caller's user
>
> s/inthe/in the/
>
>> +namespace.
>
> I think "the user namespace of the caller" reads better.
>

I agree.

>> +.TP
>> +.I smbuf.mnt_gidmap_num
>> +The number of gid mappings in case of an idmapped mount.
>> +If STATMOUNT_GIDMAP was not unset and this field is 0,
>> +the mount is not an idmapped mount.
>> +.TP
>> +.I smbuf.mnt_gidmap
>> +The offset to the location in the
>> +.I smbuf.str
>> +buffer that contains uid mappings as string array separated by null bytes.
>
> What do you mean by 'string array'?  Array is confusing, because it
> doesn't match the C concept of an array, since that would require all
> elements to have the same exact size.
>
> How about 'consecutive null-terminated strings'?

I agree.

>
>

I have taken a look at the rest of your comments as well, I will send
out a revision with the fixes soon!
Thanks for all your help :)

> Cheers,
> Alex
>
>> +They can be iterated over with the help of
>> +.IR smbuf.mnt_gidmap_num .
>> +The whole range of gid mappings must be resolvable in the caller's user
>> +namespace.
>>  .SH RETURN VALUE
>>  On success, zero is returned.
>>  On error, \-1 is returned, and
>> -- 
>> 2.53.0
>> 
>>