[RFC PATCH 0/9] man/man2/statmount.2: Document New Features

[RFC PATCH 0/9] man/man2/statmount.2: Document New Features

[Bhavik Sachdev]

Hello Everyone!

This patchset documents all the new features added to statmount() since
the syscall was first introduced.

I did work on the STATMOUNT_BY_FD changes and I have tried my best to
understand rest of the features and document them.

I have cc'ed the authors of all these new features, please let me know
your thoughts.

This patchset is also available on github [1].

Link [1]: https://github.com/bsach64/man-pages/tree/man.2.statmount

Thanks,
bhavik

Bhavik Sachdev (9):
  man/man2/statmount.2: Document req.mnt_ns_id and STATMOUNT_MNT_NS_ID
  man/man2/statmount.2: Document STATMOUNT_MNT_OPTS
  man/man2/statmount.2: Document STATMOUNT_FS_SUBTYPE
  man/man2/statmount.2: Document STATMOUNT_SB_SOURCE
  man/man2/statmount.2: Document STATMOUNT_OPT_ARRAY
  man/man2/statmount.2: Document STATMOUNT_OPT_SEC_ARRAY
  man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}
  man/man2/statmount.2: Document STATMOUNT_SUPPORTED_MASK
  man/man2/statmount.2: Document STATMOUNT_BY_FD

 man/man2/statmount.2 | 156 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 152 insertions(+), 4 deletions(-)

-- 
2.52.0

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

[Bhavik Sachdev]

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
 .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
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

[PATCH 2/9] man/man2/statmount.2: Document STATMOUNT_MNT_OPTS

[Bhavik Sachdev]

Document STATMOUNT_MNT_OPTS flag and the corresponding field introduced
by it.

STATMOUNT_MNT_OPTS is used to get all mount options on the mount
separated by commas. Similiar to how they are displayed in
/proc/[pid]/mountinfo.

This text is based on this commit [1].

Link [1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f9af549d1fd31487bbbc666b5b158cfc940ccc17>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 8cf6775ff..8ff01075d 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -31,6 +31,7 @@ .SH SYNOPSIS
 .P
 .B struct statmount {
 .B "    __u32  size;"
+.B "    __u32  mnt_opts;"
 .B "    __u64  mask;"
 .B "    __u32  sb_dev_major;"
 .B "    __u32  sb_dev_minor;"
@@ -108,6 +109,7 @@ .SS The mnt_id_req structure
 STATMOUNT_MNT_POINT	/* Want/got mnt_point */
 STATMOUNT_FS_TYPE	/* Want/got fs_type */
 STATMOUNT_MNT_NS_ID	/* Want/got mnt_ns_id */
+STATMOUNT_MNT_OPTS	/* Want/got mnt_opts */
 .TE
 .in
 .P
@@ -160,6 +162,13 @@ .SS The returned information
 structure,
 including any of the strings fields that were filled.
 .TP
+.TP
+.I smbuf.mnt_opts
+The offset to the location in the
+.I smbuf.str
+buffer that contains a comma separated list of mount options, similiar to those in /proc/[pid]/mountinfo.
+It is a null-terminated string.
+.TP
 .I smbuf.mask
 The ORed combination of
 .BI STATMOUNT_ *
-- 
2.52.0

[PATCH 3/9] man/man2/statmount.2: Document STATMOUNT_FS_SUBTYPE

[Bhavik Sachdev]

Document STATMOUNT_FS_SUBTYPE flag and the corresponding field
introduced by it.

STATMOUNT_FS_SUBTYPE retrieves the subtype of a file system, useful for
FUSE mounts (example: fuse.sshfs, where "sshfs" is the subtype).

This work is based on this commit message [1].

Link [1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ed9d95f691c29748f21bc019de9566b698fdfab7>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 8ff01075d..462f6060e 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -50,6 +50,7 @@ .SH SYNOPSIS
 .B "    __u32  mnt_root;"
 .B "    __u32  mnt_point;"
 .B "    __u64  mnt_ns_id;"
+.B "    __u32  fs_subtype;"
 .B "    char   str[];"
 .B };
 .EE
@@ -110,6 +111,7 @@ .SS The mnt_id_req structure
 STATMOUNT_FS_TYPE	/* Want/got fs_type */
 STATMOUNT_MNT_NS_ID	/* Want/got mnt_ns_id */
 STATMOUNT_MNT_OPTS	/* Want/got mnt_opts */
+STATMOUNT_FS_SUBTYPE	/* Want/got fs_subtype */
 .TE
 .in
 .P
@@ -259,6 +261,14 @@ .SS The returned information
 .I smbuf.mnt_ns_id
 The unique ID of the mount namespace the mount belongs to.
 .TP
+.TP
+.I smbuf.fs_subtype
+The offset to the location in the
+.I smbuf.str
+buffer that contains the string representation of the file system subtype.
+This is particularly useful for disambiguating FUSE mounts.
+It is a null-terminated string.
+.TP
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

[PATCH 4/9] man/man2/statmount.2: Document STATMOUNT_SB_SOURCE

[Bhavik Sachdev]

Document STATMOUNT_SB_SOURCE flag and the corresponding field introduced
by it. This text is based on this commit message [1].

Link [1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=44010543fc8bedad172aa5b6c43480e5d2124497>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 462f6060e..8d390fc53 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -51,6 +51,7 @@ .SH SYNOPSIS
 .B "    __u32  mnt_point;"
 .B "    __u64  mnt_ns_id;"
 .B "    __u32  fs_subtype;"
+.B "    __u32  sb_source;"
 .B "    char   str[];"
 .B };
 .EE
@@ -112,6 +113,7 @@ .SS The mnt_id_req structure
 STATMOUNT_MNT_NS_ID	/* Want/got mnt_ns_id */
 STATMOUNT_MNT_OPTS	/* Want/got mnt_opts */
 STATMOUNT_FS_SUBTYPE	/* Want/got fs_subtype */
+STATMOUNT_SB_SOURCE	/* Want/got sb_source */
 .TE
 .in
 .P
@@ -269,6 +271,13 @@ .SS The returned information
 This is particularly useful for disambiguating FUSE mounts.
 It is a null-terminated string.
 .TP
+.TP
+.I smbuf.sb_source
+The offset to the location in the
+.I smbuf.str
+the source for the mount.
+It is a null-terminated string.
+.TP
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

[PATCH 5/9] man/man2/statmount.2: Document STATMOUNT_OPT_ARRAY

[Bhavik Sachdev]

Document STATMOUNT_OPT_ARRAY flag and the corresponding fields
introduced by it. This text is based on this commit message [1].

Retrieve only file system options, separated by null bytes. For security
opts STATMOUNT_OPT_SEC_ARRAY is used.

Link [1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2f4d4503e9e5ab765a7948f98bc5deef7850f607>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 8d390fc53..e9e1f28e7 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -52,6 +52,8 @@ .SH SYNOPSIS
 .B "    __u64  mnt_ns_id;"
 .B "    __u32  fs_subtype;"
 .B "    __u32  sb_source;"
+.B "    __u32  opt_num;"
+.B "    __u32  opt_array;"
 .B "    char   str[];"
 .B };
 .EE
@@ -114,6 +116,7 @@ .SS The mnt_id_req structure
 STATMOUNT_MNT_OPTS	/* Want/got mnt_opts */
 STATMOUNT_FS_SUBTYPE	/* Want/got fs_subtype */
 STATMOUNT_SB_SOURCE	/* Want/got sb_source */
+STATMOUNT_OPT_ARRAY	/* Want/got opt_... */
 .TE
 .in
 .P
@@ -278,6 +281,18 @@ .SS The returned information
 the source for the mount.
 It is a null-terminated string.
 .TP
+.TP
+.I smbuf.opt_num
+The number of filesystem options set on the mount.
+.TP
+.TP
+.I smbuf.opt_array
+The offset to the location in the
+.I smbuf.str
+buffer that contains file system options separated by null bytes.
+They can be iterated over the help of
+.IR smbuf.opt_num .
+.TP
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

[PATCH 6/9] man/man2/statmount.2: Document STATMOUNT_OPT_SEC_ARRAY

[Bhavik Sachdev]

Document STATMOUNT_OPT_SEC_ARRAY flag and the corresponding fields
introduced by it. This text is based this commit message [1].

Retrieves only security options separated by null bytes.

Link [1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=aefff51e1c2986e16f2780ca8e4c97b784800ab5>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index e9e1f28e7..4dc312ec8 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -54,6 +54,8 @@ .SH SYNOPSIS
 .B "    __u32  sb_source;"
 .B "    __u32  opt_num;"
 .B "    __u32  opt_array;"
+.B "    __u32  opt_sec_num;"
+.B "    __u32  opt_sec_array;"
 .B "    char   str[];"
 .B };
 .EE
@@ -117,6 +119,7 @@ .SS The mnt_id_req structure
 STATMOUNT_FS_SUBTYPE	/* Want/got fs_subtype */
 STATMOUNT_SB_SOURCE	/* Want/got sb_source */
 STATMOUNT_OPT_ARRAY	/* Want/got opt_... */
+STATMOUNT_OPT_SEC_ARRAY	/* Want/got opt_sec... */
 .TE
 .in
 .P
@@ -293,6 +296,17 @@ .SS The returned information
 They can be iterated over the help of
 .IR smbuf.opt_num .
 .TP
+.I smbuf.opt_sec_num
+The number of security options set on the mount.
+.TP
+.TP
+.I smbuf.opt_sec_array
+The offset to the location in the
+.I smbuf.str
+buffer that contains security options separated by null bytes.
+They can be iterated over the help of
+.IR smbuf.opt_sec_num .
+.TP
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

[PATCH 7/9] man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}

[Bhavik Sachdev]

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 | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 4dc312ec8..4ae609818 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
@@ -307,6 +313,33 @@ .SS The returned information
 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, the mount is not an idmapped mount.
+.TP
+.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 in the caller's user namespace.
+.TP
+.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
+.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.
+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.
+.TP
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

[PATCH 8/9] man/man2/statmount.2: Document STATMOUNT_SUPPORTED_MASK

[Bhavik Sachdev]

Document STATMOUNT_SUPPORTED_MASK flag and the corresponding field
introduced by it. It is used to determine the flags supported by the
current kernel. The text is based on this commit message [1].

Link [1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=8f6116b5b77b0536d2ad7482ee42bfe58b8fac01>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 4ae609818..79ee752c1 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -60,6 +60,7 @@ .SH SYNOPSIS
 .B "    __u32  mnt_uidmap;"
 .B "    __u32  mnt_gidmap_num;"
 .B "    __u32  mnt_gidmap;"
+.B "    __u64  supported_mask;"
 .B "    char   str[];"
 .B };
 .EE
@@ -126,6 +127,7 @@ .SS The mnt_id_req structure
 STATMOUNT_OPT_SEC_ARRAY	/* Want/got opt_sec... */
 STATMOUNT_MNT_UIDMAP	/* Want/got uidmap... */
 STATMOUNT_MNT_GIDMAP	/* Want/got gidmap... */
+STATMOUNT_SUPPORTED_MASK	/* Want/got supported mask flags */
 .TE
 .in
 .P
@@ -313,6 +315,7 @@ .SS The returned information
 They can be iterated over the help of
 .IR smbuf.opt_sec_num .
 .TP
+.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, the mount is not an idmapped mount.
@@ -340,6 +343,12 @@ .SS The returned information
 .IR smbuf.mnt_gidmap_num .
 The whole range of gid mappings must be resolvable in the caller's user namespace.
 .TP
+.TP
+.I smbuf.supported_mask
+The ORed combination of
+.BI STATMOUNT_ *
+flags supported by the current kernel.
+.TP
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.52.0

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

[Bhavik Sachdev]

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>
---
 man/man2/statmount.2 | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 79ee752c1..d354f988e 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -24,6 +24,7 @@ .SH SYNOPSIS
 .EX
 .B struct mnt_id_req {
 .BR "    __u32  size;" "        /* sizeof(struct mnt_id_req) */"
+.BR "    __u32  mnt_fd;" "      /* fd on the mount being queried */"
 .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 */"
@@ -86,7 +87,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.
 .P
 (Note that reserved space and padding is omitted.)
 .SS The mnt_id_req structure
@@ -97,6 +98,23 @@ .SS The mnt_id_req structure
 it should always be set to
 .IR sizeof(struct\~mnt_id_req) .
 .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.
+.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)
@@ -366,6 +384,11 @@ .SH ERRORS
 points to a location outside the process's accessible
 address space.
 .TP
+.B EBADF
+.I req.mnt_fd
+is an invalid file descriptor.
+.TP
+.TP
 .B EINVAL
 Invalid flag specified in
 .IR flags .
@@ -374,6 +397,14 @@ .SH ERRORS
 .I req
 is of insufficient size to be utilized.
 .TP
+.TP
+.B EINVAL
+.I req.mnt_id
+or
+.I req.mnt_ns_id
+was specified alongside
+.IR req.mnt_fd .
+.TP
 .B E2BIG
 .I req
 is too large.
-- 
2.52.0

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

[Andrei Vagin]

On Wed, Jan 28, 2026 at 6:06 AM Bhavik Sachdev <b.sachdev1904@gmail.com> 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>
> ---
>  man/man2/statmount.2 | 33 ++++++++++++++++++++++++++++++++-
>  1 file changed, 32 insertions(+), 1 deletion(-)
>
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index 79ee752c1..d354f988e 100644
> --- a/man/man2/statmount.2
> +++ b/man/man2/statmount.2
> @@ -24,6 +24,7 @@ .SH SYNOPSIS
>  .EX
>  .B struct mnt_id_req {
>  .BR "    __u32  size;" "        /* sizeof(struct mnt_id_req) */"
> +.BR "    __u32  mnt_fd;" "      /* fd on the mount being queried */"

struct mnt_id_req {
        __u32 size;
        union {
                __u32 mnt_ns_fd;
                __u32 mnt_fd;
        };
        __u64 mnt_id;
        __u64 param;
        __u64 mnt_ns_id;
};

Could you please document mnt_ns_fd as well?

Thanks,
Andrei

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

[Alejandro Colomar]

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