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

[Alejandro Colomar <alx@kernel.org>]

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

Hi Bhavik,

On 2026-02-23T23:47:03+0530, Bhavik Sachdev wrote:
[...]
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index 5ac96796c..a5b135bee 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,7 @@ .SH DESCRIPTION
>  .I bufsize
>  with the fields filled in as described below.
>  .I flags
> -must be 0.
> +must either be 0 or STATMOUNT_BY_FD.

The macro should go in bold (.B, .BR) here and elsewhere.

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?


Have a lovely night!
Alex

>  .P
>  (Note that reserved space and padding is omitted.)
>  .SS The mnt_id_req structure
> @@ -110,6 +113,25 @@ .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.
> +If 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
> +(Since Linux 7.0).
> +.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
> +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 +414,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 --]