Re: [PATCH 1/9] man/man2/statmount.2: Document req.mnt_ns_id and STATMOUNT_MNT_NS_ID

[Alejandro Colomar <alx@kernel.org>]

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

Hi Bhavik,

On 2026-01-28T19:27:30+0530, Bhavik Sachdev wrote:
> Document the new mnt_ns_id parameter to struct mnt_id_req and the
> STATMOUNT_MNT_NS_ID flag.
> 
> req.mnt_ns_id can be used to query for a mount in a foreign mount
> namespace.
> 
> STATMOUNT_MNT_NS_ID can be used to retreive the mnt_ns_id of the mount
> being queried.
> 
> The mnt_ns_id parameter description is based on this commit message [1]
> and STATMOUNT_MNT_NS_ID text is based on [2].
> 
> Link [1]:
> <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=71aacb4c8c3d19da053363a5fe7538a8af082d56>
> Link [2]:
> <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=09b31295f833031c88419550172703d45c5401e3>
> 
> Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
> ---
>  man/man2/statmount.2 | 24 +++++++++++++++++++++---
>  1 file changed, 21 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index cdc96da92..8cf6775ff 100644
> --- a/man/man2/statmount.2
> +++ b/man/man2/statmount.2
> @@ -23,9 +23,10 @@ .SH SYNOPSIS
>  .P
>  .EX
>  .B struct mnt_id_req {
> -.BR "    __u32  size;" "    /* sizeof(struct mnt_id_req) */"
> -.BR "    __u64  mnt_id;" "  /* The mnt_id being queried */"
> -.BR "    __u64  param;" "   /* An ORed combination of the STATMOUNT_ constants */"
> +.BR "    __u32  size;" "        /* sizeof(struct mnt_id_req) */"
> +.BR "    __u64  mnt_id;" "      /* The mnt_id being queried */"
> +.BR "    __u64  param;" "       /* An ORed combination of the STATMOUNT_ constants */"
> +.BR "    __u32  mnt_ns_id;" "   /* The id of mnt_ns to query the mnt_id in */"
>  .B };
>  .P
>  .B struct statmount {
> @@ -47,6 +48,7 @@ .SH SYNOPSIS
>  .B "    __u64  propagate_from;"
>  .B "    __u32  mnt_root;"
>  .B "    __u32  mnt_point;"
> +.B "    __u64  mnt_ns_id;"
>  .B "    char   str[];"
>  .B };
>  .EE
> @@ -59,6 +61,9 @@ .SH SYNOPSIS
>  .SH DESCRIPTION
>  To access a mount's status,
>  the caller must have CAP_SYS_ADMIN in the user namespace.
> +In case of accessing a mount in a foreign mount namespace (specified via
> +.IR req.mnt_ns_id ),
> +the foreign mount namespace should be child of the current namespace.
>  .P
>  This function returns information about a mount,
>  storing it in the buffer pointed to by
> @@ -102,6 +107,7 @@ .SS The mnt_id_req structure
>  STATMOUNT_MNT_ROOT	/* Want/got mnt_root  */
>  STATMOUNT_MNT_POINT	/* Want/got mnt_point */
>  STATMOUNT_FS_TYPE	/* Want/got fs_type */
> +STATMOUNT_MNT_NS_ID	/* Want/got mnt_ns_id */
>  .TE
>  .in
>  .P
> @@ -130,6 +136,14 @@ .SS The mnt_id_req structure
>  as one or more bits may,
>  in the future,
>  be used to specify an extension to the buffer.
> +.P
> +.I req.mnt_ns_id
> +can be obtained from
> +.B NS_GET_MNTNS_ID
> +.BR ioctl (2)
> +operation and is used to specify a foreign mount namespace in which to query
> +.IR req.mnt_id .
> +.P

This .P is superfluous and produces a diagnostic.

>  .SS The returned information
>  The status information for the target mount is returned in the
>  .I statmount
> @@ -232,6 +246,10 @@ .SS The returned information
>  relative to the current root (ie if you are in a
>  .BR chroot ).
>  It is a null-terminated string.
> +.TP
> +.I smbuf.mnt_ns_id
> +The unique ID of the mount namespace the mount belongs to.
> +.TP

This .TP is superfluous and produces a diagnostic.

.P, .IP, and .TP introduce a new paragraph.  It doesn't make sense to
have them before a section heading.


Have a lovely day!
Alex

>  .SH RETURN VALUE
>  On success, zero is returned.
>  On error, \-1 is returned, and
> -- 
> 2.52.0
> 

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

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