Re: [PATCH v3] man/man2/statmount.2: Document STATMOUNT_BY_FD

[Alejandro Colomar <alx@kernel.org>]

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

Hi Bhavik,

Sorry for the delay; I had an issue with my mail provider.  It's now
resolved.

On 2026-02-26T08:40:16+0530, Bhavik Sachdev wrote:
> STATMOUNT_BY_FD introduces the ability to get information about a mount
> using a fd on the mount. This functionality is currently in linux-next
> [1].
> 
> Link [1]:
> <https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?h=next-20260126&id=d5bc4e31f2a3f301b4214858bec834c67bb2be5c>
> 
> Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
> Message-ID: <57c96336ccfbdc05f60b7875c315a8c1dd0d14b8.1771870334.git.b.sachdev1904@gmail.com>
> Message-ID: <7d4b22c595feeadb3be6df8a8781344597120f7e.1771870502.git.b.sachdev1904@gmail.com>
> ---
> Hey Alex!
> 
> > Also, should we say the same as elsewhere?:
> >	"It is an ORed combination of the following constants"
> > and then a list which contains only STATMOUNT_BY_FD?
> 
> I am not really sure that statmount flags will be a ORed combination in
> the future i.e (STATMOUNT_BY_FD | STATMOUNT_NEW_FLAG) would be something
> that is valid.
> 
> I think for now, it is better we don't do that.
> 
> Thanks,
> Bhavik
> 
>  man/man2/statmount.2 | 40 ++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 38 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index 5ac96796c..1556342de 100644
> --- a/man/man2/statmount.2
> +++ b/man/man2/statmount.2
> @@ -24,7 +24,10 @@ .SH SYNOPSIS
>  .EX
>  .B struct mnt_id_req {
>  .BR "    __u32  size;" "        /* sizeof(struct mnt_id_req) */"
> -.BR "    __u32  mnt_ns_fd;" "   /* fd of mnt_ns to query the mnt_id in */"
> +.BR "    union {"
> +.BR "           __u32  mnt_ns_fd;" "   /* fd of mnt_ns to query the mnt_id in */"
> +.BR "           __u32  mnt_fd;" "      /* fd on the mount being queried */"
> +.BR "    };"
>  .BR "    __u64  mnt_id;" "      /* The mnt_id being queried */"
>  .BR "    __u64  param;" "       /* ORed combination of the STATMOUNT_ constants */"
>  .BR "    __u32  mnt_ns_id;" "   /* The id of mnt_ns to query the mnt_id in */"
> @@ -89,7 +92,8 @@ .SH DESCRIPTION
>  .I bufsize
>  with the fields filled in as described below.
>  .I flags
> -must be 0.
> +must either be 0 or
> +.BR STATMOUNT_BY_FD .
>  .P
>  (Note that reserved space and padding is omitted.)
>  .SS The mnt_id_req structure
> @@ -110,6 +114,27 @@ .SS The mnt_id_req structure
>  .I req.mnt_id
>  (since Linux 6.18).
>  .P
> +.I req.mnt_fd
> +is a file descriptor on a mount.

Is this the same as a "mount object file descriptor" as describer in
fsopen(2)?  If so, we should use the same language, I think.

CC += Aleksa, Askar

> +If
> +.B STATMOUNT_BY_FD
> +flag is specified,
> +.I req.mnt_id
> +and
> +.I req.mnt_ns_id
> +are zeroed, the function will return information about the mount the fd is on

We always spell "file descriptor", not fd.

Aleksa, Askar, would you mind reviewing this patch?  You may have
comments on some specific terms used here, as they might relate to
fsopen(2).

> +(Since Linux 7.0).

s/Since/since/

> +.P
> +The fd can also be on a mount that has been lazily unmounted (see
> +.BR umount2 (2)
> +with
> +.BR MNT_DETACH ).
> +In this case,
> +.BR STATMOUNT_MNT_POINT

s/BR/B/

BR is for alternating bold and roman.


Other than the questios/doubts about mounts and file descriptors, and
these minor formatting/source issues (which I would have amended
otherwise), the patch looks good to me.


Have a lovely day!
Alex

> +and
> +.BR STATMOUNT_MNT_NS_ID
> +will be unset, since an unmounted mount is no longer a part of the filesystem.
> +.P
>  .I req.mnt_id
>  can be obtained from either
>  .BR statx (2)
> @@ -392,6 +417,17 @@ .SH ERRORS
>  .I req.mnt_ns_fd
>  were set.
>  .TP
> +.B EINVAL
> +.I req.mnt_id
> +or
> +.I req.mnt_ns_id
> +was specified alongside
> +.IR req.mnt_fd .
> +.TP
> +.B EBADF
> +.I req.mnt_fd
> +is an invalid file descriptor.
> +.TP
>  .B E2BIG
>  .I req
>  is too large.
> -- 
> 2.53.0
> 

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

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