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

[PATCH v2 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 v1 to v2:

- Appended Linux versions to document in which version new fields were
  introduced.
- Fixed formatting issues and wording problems pointed out by Alex
  during review.
- Reworded STATMOUNT_{UIDMAP,GIDMAP} to better explain the feature.

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

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

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 | 176 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 172 insertions(+), 4 deletions(-)

-- 
2.53.0

[PATCH v2 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 | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index cdc96da92..4ffddc43a 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
+.I req.mnt_id
+(since Linux 6.11).
 .SS The returned information
 The status information for the target mount is returned in the
 .I statmount
@@ -232,6 +246,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
+.IR smbuf.mnt_ns_id " (since Linux 6.11)"
+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 v2 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 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 4ffddc43a..c2682646c 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,14 @@ .SS The returned information
 structure,
 including any of the strings fields that were filled.
 .TP
+.IR smbuf.mnt_opts " (since Linux 6.11)"
+The offset to the location in the
+.I smbuf.str
+buffer that contains a comma separated list of mount options,
+similiar to those in
+.BR proc_pid_mountinfo (5) .
+It is a null-terminated string.
+.TP
 .I smbuf.mask
 The ORed combination of
 .BI STATMOUNT_ *
-- 
2.53.0

[PATCH v2 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 c2682646c..29080246b 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,13 @@ .SS The returned information
 .TP
 .IR smbuf.mnt_ns_id " (since Linux 6.11)"
 The unique ID of the mount namespace the mount belongs to.
+.TP
+.IR smbuf.fs_subtype " (since Linux 6.13)"
+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 v2 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 29080246b..f7a2feff9 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
@@ -268,6 +270,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
+.IR smbuf.sb_source " (since Linux 6.13)"
+The offset to the location in the
+.I smbuf.str
+that contains the source of 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 v2 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 f7a2feff9..c238a3d9f 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
@@ -276,6 +279,16 @@ .SS The returned information
 .I smbuf.str
 that contains the source of the mount.
 It is a null-terminated string.
+.TP
+.IR smbuf.opt_num " (since Linux 6.13)"
+The number of filesystem options set on the mount.
+.TP
+.IR smbuf.opt_array " (since Linux 6.13)"
+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 with 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 v2 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 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index c238a3d9f..c4200d76e 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
@@ -289,6 +292,16 @@ .SS The returned information
 buffer that contains file system options separated by null bytes.
 They can be iterated over with the help of
 .IR smbuf.opt_num .
+.TP
+.IR smbuf.opt_sec_num " (since Linux 6.13)"
+The number of security options set on the mount.
+.TP
+.IR smbuf.opt_sec_array " (since Linux 6.13)"
+The offset to the location in the
+.I smbuf.str
+buffer that contains security options separated by null bytes.
+They can be iterated over with 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 v2 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 | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index c4200d76e..e24827ad4 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
@@ -302,6 +308,38 @@ .SS The returned information
 buffer that contains security options separated by null bytes.
 They can be iterated over with the help of
 .IR smbuf.opt_sec_num .
+.TP
+.IR smbuf.mnt_uidmap_num " (since Linux 6.15)"
+The number of uid mappings applied on the mount.
+If
+.I smbuf.mask
+has STATMOUNT_UIDMAP set and this field is 0,
+the mount is not an idmapped mount.
+.TP
+.IR smbuf.mnt_uidmap " (since Linux 6.15)"
+The offset to the location in the
+.I smbuf.str
+buffer that contains uid mappings as consecutive null-terminated strings.
+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 user namespace
+of the caller.
+.TP
+.IR smbuf.mnt_gidmap_num " (since Linux 6.15)"
+The number of gid mappings applied on the mount.
+If
+.I smbuf.mask
+has STATMOUNT_GIDMAP set and this field is 0,
+the mount is not an idmapped mount.
+.TP
+.IR smbuf.mnt_gidmap " (since Linux 6.15)"
+The offset to the location in the
+.I smbuf.str
+buffer that contains gid mappings as consecutive null-terminated strings.
+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 user namespace
+of the caller.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

[PATCH v2 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 e24827ad4..7951c8391 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
@@ -340,6 +342,11 @@ .SS The returned information
 .IR smbuf.mnt_gidmap_num .
 The whole range of gid mappings must be resolvable in the user namespace
 of the caller.
+.TP
+.IR smbuf.supported_mask " (since Linux 6.15)"
+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 v2 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 | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 7951c8391..0b3a65bb3 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,16 @@ .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
+.I req.mnt_id
+(Since Linux 6.18).
+.P
 .I req.mnt_id
 can be obtained from either
 .BR statx (2)
@@ -372,6 +385,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 v2 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 | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 0b3a65bb3..761df60dc 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
@@ -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

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

[Alejandro Colomar]

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

Hi Bhavik,

On 2026-02-22T20:15:50+0530, Bhavik Sachdev wrote:
> 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 v1 to v2:
> 
> - Appended Linux versions to document in which version new fields were
>   introduced.
> - Fixed formatting issues and wording problems pointed out by Alex
>   during review.
> - Reworded STATMOUNT_{UIDMAP,GIDMAP} to better explain the feature.
> 
> 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`.
> 
> [1]: https://github.com/bsach64/man-pages/tree/man.2.statmount.v2
> 
> 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

I've applied patches 1..6.  They're in a branch:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=statmount>

I've done some amendments to patches 5 and 6, and the following ones
don't apply anymore.  Would you mind rebasing and sending the rest?


Have a lovely night!
Alex

>   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 | 176 ++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 172 insertions(+), 4 deletions(-)
> 
> -- 
> 2.53.0
> 
> 

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

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

[PATCH v2 1/4] 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>
Message-ID: <6146fa1d59006387ad7996f28f5651787125d956.1771855135.git.b.sachdev1904@gmail.com>
---
Hey Alex!

Hopefully this is what you wanted!

Thanks,
Bhavik

 man/man2/statmount.2 | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index f8d2302ef..f5a3721eb 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_{num,array} */
 STATMOUNT_OPT_SEC_ARRAY	/* Want/got opt_sec_{num,array} */
+STATMOUNT_MNT_UIDMAP	/* Want/got uidmap... */
+STATMOUNT_MNT_GIDMAP	/* Want/got gidmap... */
 .TE
 .in
 .P
@@ -302,6 +308,38 @@ .SS The returned information
 buffer that contains security options separated by null bytes.
 They can be iterated over with the help of
 .IR smbuf.opt_sec_num .
+.TP
+.IR smbuf.mnt_uidmap_num " (since Linux 6.15)"
+The number of uid mappings applied on the mount.
+If
+.I smbuf.mask
+has STATMOUNT_UIDMAP set and this field is 0,
+the mount is not an idmapped mount.
+.TP
+.IR smbuf.mnt_uidmap " (since Linux 6.15)"
+The offset to the location in the
+.I smbuf.str
+buffer that contains uid mappings as consecutive null-terminated strings.
+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 user namespace
+of the caller.
+.TP
+.IR smbuf.mnt_gidmap_num " (since Linux 6.15)"
+The number of gid mappings applied on the mount.
+If
+.I smbuf.mask
+has STATMOUNT_GIDMAP set and this field is 0,
+the mount is not an idmapped mount.
+.TP
+.IR smbuf.mnt_gidmap " (since Linux 6.15)"
+The offset to the location in the
+.I smbuf.str
+buffer that contains gid mappings as consecutive null-terminated strings.
+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 user namespace
+of the caller.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.53.0

Re: [PATCH v2 1/4] man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}

[Alejandro Colomar]

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

Hi Bhavik,

On 2026-02-23T19:40:23+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>
> Message-ID: <6146fa1d59006387ad7996f28f5651787125d956.1771855135.git.b.sachdev1904@gmail.com>
> ---
> Hey Alex!
> 
> Hopefully this is what you wanted!

Yup, that was it.  :)

I've applied patches v2 1..3.  I've done some minor amends, and patch 4
doesn't apply.  Would you mind rebasing that one?


Have a lovely day!
Alex

> 
> Thanks,
> Bhavik
> 
>  man/man2/statmount.2 | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index f8d2302ef..f5a3721eb 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_{num,array} */
>  STATMOUNT_OPT_SEC_ARRAY	/* Want/got opt_sec_{num,array} */
> +STATMOUNT_MNT_UIDMAP	/* Want/got uidmap... */
> +STATMOUNT_MNT_GIDMAP	/* Want/got gidmap... */
>  .TE
>  .in
>  .P
> @@ -302,6 +308,38 @@ .SS The returned information
>  buffer that contains security options separated by null bytes.
>  They can be iterated over with the help of
>  .IR smbuf.opt_sec_num .
> +.TP
> +.IR smbuf.mnt_uidmap_num " (since Linux 6.15)"
> +The number of uid mappings applied on the mount.
> +If
> +.I smbuf.mask
> +has STATMOUNT_UIDMAP set and this field is 0,
> +the mount is not an idmapped mount.
> +.TP
> +.IR smbuf.mnt_uidmap " (since Linux 6.15)"
> +The offset to the location in the
> +.I smbuf.str
> +buffer that contains uid mappings as consecutive null-terminated strings.
> +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 user namespace
> +of the caller.
> +.TP
> +.IR smbuf.mnt_gidmap_num " (since Linux 6.15)"
> +The number of gid mappings applied on the mount.
> +If
> +.I smbuf.mask
> +has STATMOUNT_GIDMAP set and this field is 0,
> +the mount is not an idmapped mount.
> +.TP
> +.IR smbuf.mnt_gidmap " (since Linux 6.15)"
> +The offset to the location in the
> +.I smbuf.str
> +buffer that contains gid mappings as consecutive null-terminated strings.
> +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 user namespace
> +of the caller.
>  .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 --]

[PATCH v2] 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>
Message-ID: <57c96336ccfbdc05f60b7875c315a8c1dd0d14b8.1771870334.git.b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

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

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

[Alejandro Colomar]

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

[PATCH v3] 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>
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.
+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
+(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 +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

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

[Alejandro Colomar]

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

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

[Askar Safin]

Alejandro Colomar <alx@kernel.org>:
> 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.

The term "mount object file descriptor" is probably confusing. In fact
fsmount simply creates detached mount and returns O_PATH fd, referring
to the root of the new detached mount. (Note: I'm talking about fsmount here,
not fsopen.) This fd is similar to what open(O_PATH)
creates. So probably we should just replace this "mount object file
descriptor" in fsopen(2) with "O_PATH fd".

The only difference between fd, returned by fsmount, and normal O_PATH
descriptor is that fd, returned by fsmount, has FMODE_NEED_UNMOUNT flag
on file description:
https://elixir.bootlin.com/linux/v7.0-rc1/source/fs/namespace.c#L4495 .

This FMODE_NEED_UNMOUNT means that when we close fd, the mount is unmounted.


This statmount patch refers to any fd inside mount in question. I. e. any
fd referring to any file inside the mount. This may include O_PATH descriptors
and, yes, descriptors returned by fsmount. So, current wording in this
statmount patch is correct.

-- 
Askar Safin

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

[Alejandro Colomar]

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

On 2026-03-05T03:13:37+0300, Askar Safin wrote:
> Alejandro Colomar <alx@kernel.org>:
> > 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.
> 
> The term "mount object file descriptor" is probably confusing. In fact
> fsmount simply creates detached mount and returns O_PATH fd, referring
> to the root of the new detached mount. (Note: I'm talking about fsmount here,
> not fsopen.) This fd is similar to what open(O_PATH)
> creates. So probably we should just replace this "mount object file
> descriptor" in fsopen(2) with "O_PATH fd".

Except for expanding fd by file descriptor, what you say sounds
reasonable to me.

> 
> The only difference between fd, returned by fsmount, and normal O_PATH
> descriptor is that fd, returned by fsmount, has FMODE_NEED_UNMOUNT flag
> on file description:
> https://elixir.bootlin.com/linux/v7.0-rc1/source/fs/namespace.c#L4495 .
> 
> This FMODE_NEED_UNMOUNT means that when we close fd, the mount is unmounted.
> 
> 
> This statmount patch refers to any fd inside mount in question. I. e. any
> fd referring to any file inside the mount. This may include O_PATH descriptors
> and, yes, descriptors returned by fsmount. So, current wording in this
> statmount patch is correct.

Thanks for having a look!  And thanks for confirming it's correct!


Have a lovely night!
Alex

> 
> -- 
> Askar Safin
> 

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

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

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

[Aleksa Sarai]

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

On 2026-03-05, Askar Safin <safinaskar@gmail.com> wrote:
> Alejandro Colomar <alx@kernel.org>:
> > 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.
> 
> The term "mount object file descriptor" is probably confusing. In fact
> fsmount simply creates detached mount and returns O_PATH fd, referring
> to the root of the new detached mount. (Note: I'm talking about fsmount here,
> not fsopen.) This fd is similar to what open(O_PATH)
> creates. So probably we should just replace this "mount object file
> descriptor" in fsopen(2) with "O_PATH fd".

No. From the perspective of userspace these are different types of
objects, calling them both O_PATH file descriptors is just more
confusing.

The fact that they are "just" an O_PATH to a root mount in an anonymous
namespace with FMODE_NEED_UNMOUNT is an implementation detail, users
reading the docs will be confused if we start referring to two objects
with different semantics as "O_PATH file descriptors" (especially once
you consider that O_PATH file descriptor semantics are also woefully
under-specified).

> This statmount patch refers to any fd inside mount in question. I. e. any
> fd referring to any file inside the mount. This may include O_PATH descriptors
> and, yes, descriptors returned by fsmount. So, current wording in this
> statmount patch is correct.

I agree.

-- 
Aleksa Sarai
https://www.cyphar.com/

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

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

[Alejandro Colomar]

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

Hi,

On 2026-03-04T15:58:21+0100, Alejandro Colomar wrote:
> 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>

I've applied the patch.  I've amended the few formatting issues I
reported below.  Since the only important issue was the wording one, and
Askar confirmed it's good, I took the patch.

BTW, Branden, I'm getting a diagnostic from groff:

	TROFF		.tmp/man/man2/statmount.2.pdf.set
	! (troff -mandoc -Tpdf -wbreak -rS12 -rU0  <.tmp/man/man2/statmount.2.pdf.troff 2>&1 >.tmp/man/man2/statmount.2.pdf.set) \
	| grep ^ >&2
	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2

But the PDF looks good to me.  Would you mind looking at that page and
telling me what you'd do with that diagnostic, and whether I should care
about it?


Have a lovely day!
Alex

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



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

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

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

[G. Branden Robinson]

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

[CC list trimmed way down since this is a *roff/formatting issue]

Hi Alex,

At 2026-03-05T18:19:30+0100, Alejandro Colomar wrote:
> BTW, Branden, I'm getting a diagnostic from groff:
> 
> 	TROFF		.tmp/man/man2/statmount.2.pdf.set
> 	! (troff -mandoc -Tpdf -wbreak -rS12 -rU0  <.tmp/man/man2/statmount.2.pdf.troff 2>&1 >.tmp/man/man2/statmount.2.pdf.set) \
> 	| grep ^ >&2
> 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2
> 
> But the PDF looks good to me.  Would you mind looking at that page and
> telling me what you'd do with that diagnostic, and whether I should care
> about it?

I can't reproduce this diagnostic with groff 1.23.0 or 1.24.0.

> 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2

This warning means that a row of the table might be vertically
encroaching into the footer margin; in extreme cases, might overprint
the page footer itself; and in really loony cases, format text beyond
the bottom of the page.

My copy of the document is this one:

	commit 7178f0e15db66a3616a900fc8a4007466633159b
	Author: Bhavik Sachdev <b.sachdev1904@gmail.com>
	Date:   Thu Feb 26 08:40:16 2026 +0530

$ ~/groff-1.24.0/bin/groff -t -ww -mandoc -Tpdf -rS12 -rU0 -z \
  man/man2/statmount.2 2>&1 | grep . || echo NO DIAGNOSTICS
NO DIAGNOSTICS
$ ~/groff-1.23.0/bin/groff -t -ww -mandoc -Tpdf -rS12 -rU0 -z \
  man/man2/statmount.2 2>&1 | grep . || echo NO DIAGNOSTICS
NO DIAGNOSTICS

As you can see, I've turned on _all_ warnings (`-ww`).

Looking at the table source:

$ sed -n '154,171p' man/man2/statmount.2
.TS
lB l.
STATMOUNT_SB_BASIC      /* Want/got sb_* */
STATMOUNT_MNT_BASIC     /* Want/got mnt_* */
STATMOUNT_PROPAGATE_FROM        /* Want/got propagate_from */
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 */
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_{num,array} */
STATMOUNT_OPT_SEC_ARRAY /* Want/got opt_sec_{num,array} */
STATMOUNT_MNT_UIDMAP    /* Want/got uidmap{_num,} */
STATMOUNT_MNT_GIDMAP    /* Want/got gidmap{_num,} */
STATMOUNT_SUPPORTED_MASK        /* Want/got supported mask flags */
.TE

...I don't see any reason why you should get that diagnostic.

1.  You're not using any text blocks.  Text blocks are formatted in a
    diversion and contain (line) breaks, so they can get "tall".

2.  You're not using any other features to make a table row "tall", for
    example by performing "local motion" with the `\v` escape sequence.
    Formatting equations in a table cell is the more traditional means
    of encountering this problem.

Can you reproduce this problem from the command line, without using your
Makefile?

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Branden,

On 2026-03-05T16:24:31-0600, G. Branden Robinson wrote:
> [CC list trimmed way down since this is a *roff/formatting issue]
> 
> Hi Alex,
> 
> At 2026-03-05T18:19:30+0100, Alejandro Colomar wrote:
> > BTW, Branden, I'm getting a diagnostic from groff:
> > 
> > 	TROFF		.tmp/man/man2/statmount.2.pdf.set
> > 	! (troff -mandoc -Tpdf -wbreak -rS12 -rU0  <.tmp/man/man2/statmount.2.pdf.troff 2>&1 >.tmp/man/man2/statmount.2.pdf.set) \
> > 	| grep ^ >&2
> > 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2
> > 
> > But the PDF looks good to me.  Would you mind looking at that page and
> > telling me what you'd do with that diagnostic, and whether I should care
> > about it?
> 
> I can't reproduce this diagnostic with groff 1.23.0 or 1.24.0.

Huh...  I'm reproducing it on my server, but not on my desktop.
On my server, I have:

	GNU troff (groff) version 1.23.0.1254-19a18

On my desktop, I have:

	GNU grops (groff) version 1.23.0.2695-49927

I'll assume this is a fixed issue, since the newer groff(1) from my
desktop doesn't reproduce it.

> 
> > 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2
> 
> This warning means that a row of the table might be vertically
> encroaching into the footer margin; in extreme cases, might overprint
> the page footer itself; and in really loony cases, format text beyond
> the bottom of the page.

Yeah, that's what I was expecting, but the page renders fine, and I
don't see anything near the margins, which made it weird.

> My copy of the document is this one:
> 
> 	commit 7178f0e15db66a3616a900fc8a4007466633159b
> 	Author: Bhavik Sachdev <b.sachdev1904@gmail.com>
> 	Date:   Thu Feb 26 08:40:16 2026 +0530

Yup, that's correct.

> 
> $ ~/groff-1.24.0/bin/groff -t -ww -mandoc -Tpdf -rS12 -rU0 -z \
>   man/man2/statmount.2 2>&1 | grep . || echo NO DIAGNOSTICS
> NO DIAGNOSTICS
> $ ~/groff-1.23.0/bin/groff -t -ww -mandoc -Tpdf -rS12 -rU0 -z \
>   man/man2/statmount.2 2>&1 | grep . || echo NO DIAGNOSTICS
> NO DIAGNOSTICS
> 
> As you can see, I've turned on _all_ warnings (`-ww`).
> 
> Looking at the table source:
> 
> $ sed -n '154,171p' man/man2/statmount.2
> .TS
> lB l.
> STATMOUNT_SB_BASIC      /* Want/got sb_* */
> STATMOUNT_MNT_BASIC     /* Want/got mnt_* */
> STATMOUNT_PROPAGATE_FROM        /* Want/got propagate_from */
> 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 */
> 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_{num,array} */
> STATMOUNT_OPT_SEC_ARRAY /* Want/got opt_sec_{num,array} */
> STATMOUNT_MNT_UIDMAP    /* Want/got uidmap{_num,} */
> STATMOUNT_MNT_GIDMAP    /* Want/got gidmap{_num,} */
> STATMOUNT_SUPPORTED_MASK        /* Want/got supported mask flags */
> .TE
> 
> ...I don't see any reason why you should get that diagnostic.
> 
> 1.  You're not using any text blocks.  Text blocks are formatted in a
>     diversion and contain (line) breaks, so they can get "tall".
> 
> 2.  You're not using any other features to make a table row "tall", for
>     example by performing "local motion" with the `\v` escape sequence.
>     Formatting equations in a table cell is the more traditional means
>     of encountering this problem.
> 
> Can you reproduce this problem from the command line, without using your
> Makefile?

Yup.  On my server:

	$ groff -t -ww -mandoc -Tpdf -rS12 -rU0 -z man/man2/statmount.2 2>&1 \
	| grep . \
	|| echo NO DIAGNOSTICS;
	man/man2/statmount.2:155: warning: table row does not fit on page 2

Using

	$ groff --version | tail -n1
	GNU troff (groff) version 1.23.0.1254-19a18


Have a lovely night!
Alex

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

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

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

[G. Branden Robinson]

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

Hi Alex,

At 2026-03-05T23:45:14+0100, Alejandro Colomar wrote:
> On 2026-03-05T16:24:31-0600, G. Branden Robinson wrote:
> > [CC list trimmed way down since this is a *roff/formatting issue]
> > 
> > Hi Alex,
> > 
> > At 2026-03-05T18:19:30+0100, Alejandro Colomar wrote:
> > > BTW, Branden, I'm getting a diagnostic from groff:
> > > 
> > > 	TROFF		.tmp/man/man2/statmount.2.pdf.set
> > > 	! (troff -mandoc -Tpdf -wbreak -rS12 -rU0  <.tmp/man/man2/statmount.2.pdf.troff 2>&1 >.tmp/man/man2/statmount.2.pdf.set) \
> > > 	| grep ^ >&2
> > > 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2
> > > 
> > > But the PDF looks good to me.  Would you mind looking at that page and
> > > telling me what you'd do with that diagnostic, and whether I should care
> > > about it?
> > 
> > I can't reproduce this diagnostic with groff 1.23.0 or 1.24.0.
> 
> Huh...  I'm reproducing it on my server, but not on my desktop.
> On my server, I have:
> 
> 	GNU troff (groff) version 1.23.0.1254-19a18
> 
> On my desktop, I have:
> 
> 	GNU grops (groff) version 1.23.0.2695-49927

Hmm.  Revision 19a18 is 9 May 2024, and 49927 is 22 December 2024.

Both are a little old.  :)

> I'll assume this is a fixed issue, since the newer groff(1) from my
> desktop doesn't reproduce it.

If I get stuck on the other stuff I'm working on,[1] I'll see if I can
reproduce the problem with 1.23.0.1254-19a18 and then bisect it down.

> > > 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2
> > 
> > This warning means that a row of the table might be vertically
> > encroaching into the footer margin; in extreme cases, might
> > overprint the page footer itself; and in really loony cases, format
> > text beyond the bottom of the page.
> 
> Yeah, that's what I was expecting, but the page renders fine, and I
> don't see anything near the margins, which made it weird.

The warning will issue if the table row is overset by as little as 1
"basic unit", which for PostScript and PDF is 1/72,000 of an inch.

That's 0.0000353 centimeters.  It's microscopically small.

If there's a way to get the _amount_ of overset into that diagnostic
message, it would be helpful to the document maintainer to decide
whether it's a problem they want to deal with.

Your other data explains why I couldn't reproduce it.  It could have
been a bug that got squashed between May and December of 2024.

If I find out it's still there, latent, I'll go at it with guns blazing.

Regards,
Branden

[1] largely https://savannah.gnu.org/bugs/?67978

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

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

[Bhavik Sachdev]

On Thu Mar 5, 2026 at 10:49 PM IST, Alejandro Colomar wrote:
> Hi,
>
> On 2026-03-04T15:58:21+0100, Alejandro Colomar wrote:
>> 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>
>
> I've applied the patch.  I've amended the few formatting issues I
> reported below.  Since the only important issue was the wording one, and
> Askar confirmed it's good, I took the patch.
>

Thanks Alex, Askar and Aleksa for taking a look :)

> BTW, Branden, I'm getting a diagnostic from groff:
>
> 	TROFF		.tmp/man/man2/statmount.2.pdf.set
> 	! (troff -mandoc -Tpdf -wbreak -rS12 -rU0  <.tmp/man/man2/statmount.2.pdf.troff 2>&1 >.tmp/man/man2/statmount.2.pdf.set) \
> 	| grep ^ >&2
> 	.tmp/man/man2/statmount.2:155: warning: table row does not fit on page 2
>
> But the PDF looks good to me.  Would you mind looking at that page and
> telling me what you'd do with that diagnostic, and whether I should care
> about it?
>
>
> Have a lovely day!
> Alex
>
>> > ---
>> > 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>

[PATCH v2 2/4] 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>
Message-ID: <b537e03ab73d8677a53730311b5a3c11ff29a51b.1771855135.git.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 f5a3721eb..843293e43 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_{num,array} */
 STATMOUNT_MNT_UIDMAP	/* Want/got uidmap... */
 STATMOUNT_MNT_GIDMAP	/* Want/got gidmap... */
+STATMOUNT_SUPPORTED_MASK	/* Want/got supported mask flags */
 .TE
 .in
 .P
@@ -340,6 +342,11 @@ .SS The returned information
 .IR smbuf.mnt_gidmap_num .
 The whole range of gid mappings must be resolvable in the user namespace
 of the caller.
+.TP
+.IR smbuf.supported_mask " (since Linux 6.15)"
+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 v2 3/4] 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>
Message-ID: <6577568b31ba8700214af1696d740d3b6aa1869d.1771855135.git.b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 843293e43..816ddc24b 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;" "       /* 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,16 @@ .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
+.I req.mnt_id
+(Since Linux 6.18).
+.P
 .I req.mnt_id
 can be obtained from either
 .BR statx (2)
@@ -372,6 +385,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 v2 4/4] 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>
Message-ID: <57c96336ccfbdc05f60b7875c315a8c1dd0d14b8.1771855135.git.b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 816ddc24b..73faa8ccc 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.
 .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