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

[Alejandro Colomar <alx@kernel.org>]

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

Hi Bhavik,

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 <b.sachdev1904@gmail.com>
> ---
>  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 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.

> +.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'?


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

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

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