[PATCH v1 00/10] man/man2/statmount.2: Document New Features

[PATCH v1 00/10] 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].

Changes from RFC to v1:

- Document req.mnt_ns_fd as well.
- Fix all lint errors generated by running
`make -R lint-man man/man2/statmount.2`.

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

Thanks,
bhavik

Bhavik Sachdev (10):
  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 req.mnt_ns_fd
  man/man2/statmount.2: Document STATMOUNT_BY_FD

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

-- 
2.53.0

[PATCH v1 01/10] 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 | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index cdc96da92..f5c4da122 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,13 @@ .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 .
 .SS The returned information
 The status information for the target mount is returned in the
 .I statmount
@@ -232,6 +245,9 @@ .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.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v1 02/10] 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 f5c4da122..fee37069a 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
@@ -159,6 +161,13 @@ .SS The returned information
 structure,
 including any of the strings fields that were filled.
 .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.53.0

[PATCH v1 03/10] 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 | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index fee37069a..b24b4a5fd 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
@@ -257,6 +259,13 @@ .SS The returned information
 .TP
 .I smbuf.mnt_ns_id
 The unique ID of the mount namespace the mount belongs to.
+.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.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v1 04/10] 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 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index b24b4a5fd..dd1f1f17d 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
@@ -266,6 +268,12 @@ .SS The returned information
 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
+.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.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v1 05/10] 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 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index dd1f1f17d..e47af22c3 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
@@ -274,6 +277,16 @@ .SS The returned information
 .I smbuf.str
 the source for the mount.
 It is a null-terminated string.
+.TP
+.I smbuf.opt_num
+The number of filesystem options set on the mount.
+.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 .
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v1 06/10] 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 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index e47af22c3..b7acde8f4 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
@@ -287,6 +290,15 @@ .SS The returned information
 buffer that contains file system options separated by null bytes.
 They can be iterated over the help of
 .IR smbuf.opt_num .
+.I smbuf.opt_sec_num
+The number of security options set on the mount.
+.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 .
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v1 07/10] 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 | 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,
+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
+namespace.
+.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.
+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

[PATCH v1 08/10] 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 | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 4da55eb38..0b906a334 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
@@ -333,6 +335,11 @@ .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
+.I smbuf.supported_mask
+The ORed combination of
+.BI STATMOUNT_ *
+flags supported by the current kernel.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v1 09/10] man/man2/statmount.2: Document req.mnt_ns_fd

[Bhavik Sachdev]

Document the new mnt_ns_fd parameter to struct mnt_id_req.

req.mnt_ns_fd can be used to query for a mount in a foreign mount
namespace.

The mnt_ns_fd parameter description is based on this commit message [1].

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

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

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 0b906a334..e835eb0f6 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_ns_fd;" "   /* fd of mnt_ns to query the mnt_id in */"
 .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 */"
@@ -74,7 +75,9 @@ .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 ),
+.I req.mnt_ns_id
+or
+.IR req.mnt_ns_fd ),
 the foreign mount namespace should be child of the current namespace.
 .P
 This function returns information about a mount,
@@ -97,6 +100,15 @@ .SS The mnt_id_req structure
 it should always be set to
 .IR sizeof(struct\~mnt_id_req) .
 .P
+.I req.mnt_ns_fd
+can be obtained from
+.B PIDFD_GET_MNT_NAMESPACE
+.BR ioctl (2)
+operation or by opening a file descriptor to
+.IR /proc/[pid]/ns/mnt
+and is used to specify a foreign mount namespace in which to query
+.IR req.mnt_id .
+.P
 .I req.mnt_id
 can be obtained from either
 .BR statx (2)
@@ -365,6 +377,13 @@ .SH ERRORS
 .I req
 is of insufficient size to be utilized.
 .TP
+.B EINVAL
+Both
+.I req.mnt_ns_id
+and
+.I req.mnt_ns_fd
+were set.
+.TP
 .B E2BIG
 .I req
 is too large.
-- 
2.53.0

[PATCH v1 10/10] 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 | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index e835eb0f6..484fec383 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;" "       /* An 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.
 .P
 (Note that reserved space and padding is omitted.)
 .SS The mnt_id_req structure
@@ -109,6 +112,24 @@ .SS The mnt_id_req structure
 and is used to specify a foreign mount namespace in which to query
 .IR req.mnt_id .
 .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)
@@ -384,6 +405,16 @@ .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.
 .B E2BIG
 .I req
 is too large.
-- 
2.53.0

Re: [PATCH v1 01/10] man/man2/statmount.2: Document req.mnt_ns_id and STATMOUNT_MNT_NS_ID

[Alejandro Colomar]

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

Hi Bhavik,

On 2026-02-10T02:47:34+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 | 22 +++++++++++++++++++---
>  1 file changed, 19 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index cdc96da92..f5c4da122 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,13 @@ .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

Should this ioctl(2) be documented?  I don't find it in any manual page.
You don't need to do it in this patch set, though.

> +.BR ioctl (2)
> +operation and is used to specify a foreign mount namespace in which to query
> +.IR req.mnt_id .
>  .SS The returned information
>  The status information for the target mount is returned in the
>  .I statmount
> @@ -232,6 +245,9 @@ .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

We should document the Linux version in which this was added.  It should
be something like this

.IR smbuf.mnt_ns_id " (since Linux 1.23)"


Have a lovely day!
Alex

> +The unique ID of the mount namespace the mount belongs to.
>  .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 --]

Re: [PATCH v1 02/10] man/man2/statmount.2: Document STATMOUNT_MNT_OPTS

[Alejandro Colomar]

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

Hi Bhavik,

On 2026-02-10T02:47:35+0530, Bhavik Sachdev wrote:
> 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 f5c4da122..fee37069a 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
> @@ -159,6 +161,13 @@ .SS The returned information
>  structure,
>  including any of the strings fields that were filled.
>  .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.

The path should be marked up:

	.IR /proc/ pid /mountinfo .

Though you may want to refer to proc_pid_mountinfo(5).


Cheers,
Alex

> +It is a null-terminated string.
> +.TP
>  .I smbuf.mask
>  The ORed combination of
>  .BI STATMOUNT_ *
> -- 
> 2.53.0
> 

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

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

Re: [PATCH v1 05/10] man/man2/statmount.2: Document STATMOUNT_OPT_ARRAY

[Alejandro Colomar]

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

On 2026-02-10T02:47:38+0530, Bhavik Sachdev wrote:
> 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 | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index dd1f1f17d..e47af22c3 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
> @@ -274,6 +277,16 @@ .SS The returned information
>  .I smbuf.str
>  the source for the mount.
>  It is a null-terminated string.
> +.TP
> +.I smbuf.opt_num
> +The number of filesystem options set on the mount.
> +.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

Missing word? "iterated over _with_ the help of"


Cheers,
Alex

> +.IR smbuf.opt_num .
>  .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 --]

Re: [PATCH v1 06/10] man/man2/statmount.2: Document STATMOUNT_OPT_SEC_ARRAY

[Alejandro Colomar]

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

On 2026-02-10T02:47:39+0530, Bhavik Sachdev wrote:
> 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 | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index e47af22c3..b7acde8f4 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
> @@ -287,6 +290,15 @@ .SS The returned information
>  buffer that contains file system options separated by null bytes.
>  They can be iterated over the help of
>  .IR smbuf.opt_num .
> +.I smbuf.opt_sec_num

Missing .TP above this.  You could check patches with diffman-git(1) to
check that they look good.

See for example how it shows the effects of this patch:

	$ MANWIDTH=64 diffman-git HEAD
	<standard input>:109: warning: table wider than line length minus indentation
	<standard input>:111: warning: table wider than line length minus indentation
	--- HEAD^:man/man2/statmount.2
	+++ HEAD:man/man2/statmount.2
	@@ -48,6 +48,8 @@ SYNOPSIS
		  __u32  sb_source;
		  __u32  opt_num;
		  __u32  opt_array;
	+         __u32  opt_sec_num;
	+         __u32  opt_sec_array;
		  char   str[];
	      };
	 
	@@ -93,6 +95,7 @@ DESCRIPTION
		  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... */
	 
	      In general, the kernel does not reject values in req.param
	      other than the above.  (For an exception, see EINVAL in
	@@ -218,7 +221,14 @@ DESCRIPTION
		     The offset to the location in the smbuf.str buffer
		     that contains file system options separated by null
		     bytes.  They can be iterated over the help of sm‐
	-            buf.opt_num.
	+            buf.opt_num.  smbuf.opt_sec_num The number of secu‐
	+            rity options set on the mount.
	+
	+     smbuf.opt_sec_array
	+            The offset to the location in the smbuf.str buffer
	+            that contains security options separated by null
	+            bytes.  They can be iterated over the help of sm‐
	+            buf.opt_sec_num.
	 
	 RETURN VALUE
	      On success, zero is returned.  On error, -1 is returned,

The diffman-git(1) script is part of the repository.  You can install
it with `make -R install`.  Or you can use it directly from src/bin/.


Cheers,
Alex

> +The number of security options set on the mount.
> +.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 .
>  .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 --]

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

[Alejandro Colomar]

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

Re: [PATCH v1 09/10] man/man2/statmount.2: Document req.mnt_ns_fd

[Alejandro Colomar]

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

On 2026-02-10T02:47:42+0530, Bhavik Sachdev wrote:
> Document the new mnt_ns_fd parameter to struct mnt_id_req.
> 
> req.mnt_ns_fd can be used to query for a mount in a foreign mount
> namespace.
> 
> The mnt_ns_fd parameter description is based on this commit message [1].
> 
> Link [1]:
> <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9020d0d844ad58a051f90b1e5b82ba34123925b9>
> 
> Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
> ---
>  man/man2/statmount.2 | 21 ++++++++++++++++++++-
>  1 file changed, 20 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index 0b906a334..e835eb0f6 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_ns_fd;" "   /* fd of mnt_ns to query the mnt_id in */"
>  .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 */"
> @@ -74,7 +75,9 @@ .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 ),
> +.I req.mnt_ns_id
> +or
> +.IR req.mnt_ns_fd ),
>  the foreign mount namespace should be child of the current namespace.
>  .P
>  This function returns information about a mount,
> @@ -97,6 +100,15 @@ .SS The mnt_id_req structure
>  it should always be set to
>  .IR sizeof(struct\~mnt_id_req) .
>  .P
> +.I req.mnt_ns_fd
> +can be obtained from
> +.B PIDFD_GET_MNT_NAMESPACE
> +.BR ioctl (2)
> +operation or by opening a file descriptor to
> +.IR /proc/[pid]/ns/mnt

Reformat:

	.IR /proc/ pid /ns/mnt


Cheers,
Alex

> +and is used to specify a foreign mount namespace in which to query
> +.IR req.mnt_id .
> +.P
>  .I req.mnt_id
>  can be obtained from either
>  .BR statx (2)
> @@ -365,6 +377,13 @@ .SH ERRORS
>  .I req
>  is of insufficient size to be utilized.
>  .TP
> +.B EINVAL
> +Both
> +.I req.mnt_ns_id
> +and
> +.I req.mnt_ns_fd
> +were set.
> +.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 --]

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

[Bhavik Sachdev]

On Wed Feb 11, 2026 at 7:29 PM IST, Alejandro Colomar wrote:
> Hi Bhavik,

Hey Alex!

>
> 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 patch implicitly refers to the smbuf.mask field, which is a ORed
combination of the flags statmount() was actually able to successfully
fill.

So, if smbuf.mask has STATMOUNT_UIDMAP set (i.e the kernel was able to
successfully get the uid mappings of the mount) and smbuf.mnt_uidmap_num
is 0, then the mount is not a idmapped mount.

The patch does a terrible job of explaining this, i will come up with
something better.

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

I agree.

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

I agree.

>
>

I have taken a look at the rest of your comments as well, I will send
out a revision with the fixes soon!
Thanks for all your help :)

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

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

[Alejandro Colomar]

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

On 2026-02-13T15:35:46+0530, Bhavik Sachdev wrote:
> On Wed Feb 11, 2026 at 7:29 PM IST, Alejandro Colomar wrote:
> > Hi Bhavik,
> 
> Hey Alex!

Hey Bhavik!

[...]
> I have taken a look at the rest of your comments as well, I will send
> out a revision with the fixes soon!
> Thanks for all your help :)

Thank you!  Have a lovely day!
Alex

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

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