[PATCH] man/man2/statmount.2: Fix STATMOUNT_MNT_{UID,GID}MAP documentation

[PATCH] man/man2/statmount.2: Fix STATMOUNT_MNT_{UID,GID}MAP documentation

[Bhavik Sachdev]

In case of idmapped mounts and statmount(), three cases can occur:

1. The mount is not an idmapped mount. In this case, smbuf->mask will
   *not* have STATMOUNT_MNT_{UID,GID}MAP set.
2. The mount is an idmapped mount but *all* its mappings are *not*
   resolvable in the user namespace of the caller.
   In this case, smbuf->mask will have STATMOUNT_MNT_{UID,GID}MAP set
   but smbuf->mnt_{uid,gid}map_num will be 0.
3. The mount is an idmapped mount and *all* its mappings are resolvable
   in the user namespace of the caller.
   In this case, smbuf->mask will have STATMOUNT_MNT_{UID,GID}MAP set
   and mbuf->mnt_{uid,gid}map_num will be greater than 0.

The current documentation fails to differentiate between case 1 and 2
and incorrectly states that STATMOUNT_MNT_{UID,GID}MAP will be set for
non-idmapped mounts.

We can verify that the above is the case by looking at [1] and is made
explicitly clear by the comment in the implementation [2]. The case for
STATMOUNT_MNT_{UID,GID}MAP not being raised for a non-idmapped mount can
be verified by running this program [3].

[1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=37c4a9590e1efcae7749682239fc22a330d2d325>
[2]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/namespace.c#n5489>
[3]: <https://gist.github.com/bsach64/674264ec69e592f906b2713c9f95060b>

Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
Hey Alex!

My understanding of how statmount() differentiated between idmapped
mounts and non-idmapped mounts was incorrect. This patch fixes the
incorrect documentation introduced as a result.

Thanks,
Bhavik

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

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 42ca902d9..40a07181b 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -356,7 +356,8 @@ .SS The returned information
 If
 .I smbuf.mask
 has STATMOUNT_UIDMAP set and this field is 0,
-the mount is not an idmapped mount.
+then uid mappings applied on the mount cannot be resolved in the user namespace
+of the caller.
 .TP
 .IR smbuf.mnt_uidmap " (since Linux 6.15)"
 The offset to the location in the
@@ -372,7 +373,8 @@ .SS The returned information
 If
 .I smbuf.mask
 has STATMOUNT_GIDMAP set and this field is 0,
-the mount is not an idmapped mount.
+then gid mappings applied on the mount cannot be resolved in the user namespace
+of the caller.
 .TP
 .IR smbuf.mnt_gidmap " (since Linux 6.15)"
 The offset to the location in the
-- 
2.53.0

Re: [PATCH] man/man2/statmount.2: Fix STATMOUNT_MNT_{UID,GID}MAP documentation

[Alejandro Colomar]

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

Hey Bhavik!

On 2026-03-17T17:48:33+0530, Bhavik Sachdev wrote:
> In case of idmapped mounts and statmount(), three cases can occur:
> 
> 1. The mount is not an idmapped mount. In this case, smbuf->mask will
>    *not* have STATMOUNT_MNT_{UID,GID}MAP set.
> 2. The mount is an idmapped mount but *all* its mappings are *not*
>    resolvable in the user namespace of the caller.
>    In this case, smbuf->mask will have STATMOUNT_MNT_{UID,GID}MAP set
>    but smbuf->mnt_{uid,gid}map_num will be 0.
> 3. The mount is an idmapped mount and *all* its mappings are resolvable
>    in the user namespace of the caller.
>    In this case, smbuf->mask will have STATMOUNT_MNT_{UID,GID}MAP set
>    and mbuf->mnt_{uid,gid}map_num will be greater than 0.
> 
> The current documentation fails to differentiate between case 1 and 2
> and incorrectly states that STATMOUNT_MNT_{UID,GID}MAP will be set for
> non-idmapped mounts.
>
> We can verify that the above is the case by looking at [1] and is made
> explicitly clear by the comment in the implementation [2]. The case for
> STATMOUNT_MNT_{UID,GID}MAP not being raised for a non-idmapped mount can
> be verified by running this program [3].
> 
> [1]:
> <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=37c4a9590e1efcae7749682239fc22a330d2d325>
> [2]:
> <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/namespace.c#n5489>
> [3]: <https://gist.github.com/bsach64/674264ec69e592f906b2713c9f95060b>

Thanks for the example program!  I'll paste it here, to avoid others
having to go to github to read it.

	#define _GNU_SOURCE
	#include <limits.h>
	#include <errno.h>
	#include <fcntl.h>
	#include <linux/mount.h>
	#include <linux/stat.h>
	#include <stdio.h>
	#include <stdlib.h>
	#include <string.h>
	#include <sys/stat.h>
	#include <sys/syscall.h>
	#include <unistd.h>


	static int __statmount(__u64 mnt_id, __u64 mnt_ns_id, __u64 mask,
			       struct statmount *stmnt, size_t bufsize,
			       unsigned int flags)
	{
		struct mnt_id_req req = {
			.size		= MNT_ID_REQ_SIZE_VER1,
			.mnt_id		= mnt_id,
			.param		= mask,
			.mnt_ns_id	= mnt_ns_id,
		};

		return syscall(__NR_statmount, &req, stmnt, bufsize, flags);
	}

	static struct statmount *sys_statmount(__u64 mnt_id, __u64 mnt_ns_id,
					       __u64 mask, unsigned int flags)
	{
		size_t bufsize = 1 << 15;
		struct statmount *stmnt = NULL, *tmp = NULL;
		int ret;

		for (;;) {
			tmp = realloc(stmnt, bufsize);
			if (!tmp)
				goto out;

			stmnt = tmp;
			ret = __statmount(mnt_id, mnt_ns_id, mask, stmnt, bufsize, flags);
			if (!ret)
				return stmnt;

			if (errno != EOVERFLOW)
				goto out;

			bufsize <<= 1;
			if (bufsize >= UINT_MAX / 2)
				goto out;
		}

	out:
		free(stmnt);
		return NULL;
	}

	int main(void) {
		struct statmount *sm;
		struct statx stx;

		int fd = open("/tmp", O_PATH);
		if (fd < 0) {
			perror("open /tmp");
			return 1;
		}

		memset(&stx, 0, sizeof(stx));

		if (statx(fd, "", AT_EMPTY_PATH, STATX_MNT_ID_UNIQUE, &stx) < 0) {
			perror("statx");
			close(fd);
			return 1;
		}

		if (!(stx.stx_mask & STATX_MNT_ID_UNIQUE)) {
			fprintf(stderr, "STATX_MNT_ID_UNIQUE not returned by kernel\n");
			close(fd);
			return 1;
		}


		sm = sys_statmount(stx.stx_mnt_id, 0, STATMOUNT_MNT_BASIC | STATMOUNT_MNT_UIDMAP, 0);
		if (!sm) {
			close(fd);
			return 1;
		}

		if (sm->mask & STATMOUNT_MNT_UIDMAP)
			printf("this should not have happened.\n");
		else
			printf("%llu is not an idmapped mount\n", sm->mnt_id);

		close(fd);
		return 0;
	}

> 
> Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
> ---
> Hey Alex!
> 
> My understanding of how statmount() differentiated between idmapped
> mounts and non-idmapped mounts was incorrect.

Thanks for the correction!

> This patch fixes the
> incorrect documentation introduced as a result.

Thanks!  Would you mind documenting all the commits that we're fixing?
Please use Fixes tags.  See
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/trailer#n16>
and
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/git#n46>.

> 
> Thanks,
> Bhavik
> 
>  man/man2/statmount.2 | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index 42ca902d9..40a07181b 100644
> --- a/man/man2/statmount.2
> +++ b/man/man2/statmount.2
> @@ -356,7 +356,8 @@ .SS The returned information
>  If
>  .I smbuf.mask
>  has STATMOUNT_UIDMAP set and this field is 0,
> -the mount is not an idmapped mount.
> +then uid mappings applied on the mount cannot be resolved in the user namespace
> +of the caller.

Please use semantic newlines.  See man-pages(7):

$ MANWIDTH=72 man man-pages | awk '/Use semantic newlines/,/^$/'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.

In this case, I'd break the line between 'mount\ncannot'.


Have a lovely night!
Alex

>  .TP
>  .IR smbuf.mnt_uidmap " (since Linux 6.15)"
>  The offset to the location in the
> @@ -372,7 +373,8 @@ .SS The returned information
>  If
>  .I smbuf.mask
>  has STATMOUNT_GIDMAP set and this field is 0,
> -the mount is not an idmapped mount.
> +then gid mappings applied on the mount cannot be resolved in the user namespace
> +of the caller.
>  .TP
>  .IR smbuf.mnt_gidmap " (since Linux 6.15)"
>  The offset to the location in the
> -- 
> 2.53.0
> 
> 

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

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

[PATCH v2 1/2] man/man2/statmount.2: Fix STATMOUNT_MNT_{UID,GID}MAP documentation

[Bhavik Sachdev]

In case of idmapped mounts and statmount(), three cases can occur:

1. The mount is not an idmapped mount. In this case, smbuf->mask will
   *not* have STATMOUNT_MNT_{UID,GID}MAP set.
2. The mount is an idmapped mount but *all* its mappings are *not*
   resolvable in the user namespace of the caller.
   In this case, smbuf->mask will have STATMOUNT_MNT_{UID,GID}MAP set
   but smbuf->mnt_{uid,gid}map_num will be 0.
3. The mount is an idmapped mount and *all* its mappings are resolvable
   in the user namespace of the caller.
   In this case, smbuf->mask will have STATMOUNT_MNT_{UID,GID}MAP set
   and mbuf->mnt_{uid,gid}map_num will be greater than 0.

The current documentation fails to differentiate between case 1 and 2
and incorrectly states that STATMOUNT_MNT_{UID,GID}MAP will be set for
non-idmapped mounts.

We can verify that the above is the case by looking at [1] and is made
explicitly clear by the comment in the implementation [2]. The case for
STATMOUNT_MNT_{UID,GID}MAP not being raised for a non-idmapped mount can
be verified by running this program [3].

[1]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=37c4a9590e1efcae7749682239fc22a330d2d325>
[2]:
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/namespace.c#n5489>
[3]: <https://gist.github.com/bsach64/674264ec69e592f906b2713c9f95060b>

Fixes: 9968ead5 (2026-03-05; "man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}")
Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
 man/man2/statmount.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 42ca902d..78b6e9be 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -356,7 +356,8 @@ .SS The returned information
 If
 .I smbuf.mask
 has STATMOUNT_UIDMAP set and this field is 0,
-the mount is not an idmapped mount.
+then uid mappings applied on the mount
+cannot be resolved in the user namespace of the caller.
 .TP
 .IR smbuf.mnt_uidmap " (since Linux 6.15)"
 The offset to the location in the
@@ -372,7 +373,8 @@ .SS The returned information
 If
 .I smbuf.mask
 has STATMOUNT_GIDMAP set and this field is 0,
-the mount is not an idmapped mount.
+then gid mappings applied on the mount
+cannot be resolved in the user namespace of the caller.
 .TP
 .IR smbuf.mnt_gidmap " (since Linux 6.15)"
 The offset to the location in the
-- 
2.53.0

[PATCH v2 2/2] man/man2/statmount.2: Fix incorrect naming of STATMOUNT_MNT_{UID,GID}MAP flags

[Bhavik Sachdev]

STATMOUNT_UIDMAP is actually STATMOUNT_MNT_UIDMAP and STATMOUNT_GIDMAP
is STATMOUNT_MNT_GIDMAP.

Fixes: 9968ead5 (2026-03-05; "man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}")
Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
---
Hey Alex!

Found another mistake while replying to your comments!

Thanks,
Bhavik

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

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
index 78b6e9be..b6d9dc2a 100644
--- a/man/man2/statmount.2
+++ b/man/man2/statmount.2
@@ -355,7 +355,7 @@ .SS The returned information
 The number of uid mappings applied on the mount.
 If
 .I smbuf.mask
-has STATMOUNT_UIDMAP set and this field is 0,
+has STATMOUNT_MNT_UIDMAP set and this field is 0,
 then uid mappings applied on the mount
 cannot be resolved in the user namespace of the caller.
 .TP
@@ -372,7 +372,7 @@ .SS The returned information
 The number of gid mappings applied on the mount.
 If
 .I smbuf.mask
-has STATMOUNT_GIDMAP set and this field is 0,
+has STATMOUNT_MNT_GIDMAP set and this field is 0,
 then gid mappings applied on the mount
 cannot be resolved in the user namespace of the caller.
 .TP
-- 
2.53.0

Re: [PATCH v2 2/2] man/man2/statmount.2: Fix incorrect naming of STATMOUNT_MNT_{UID,GID}MAP flags

[Alejandro Colomar]

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

On 2026-03-19T12:39:12+0530, Bhavik Sachdev wrote:
> STATMOUNT_UIDMAP is actually STATMOUNT_MNT_UIDMAP and STATMOUNT_GIDMAP
> is STATMOUNT_MNT_GIDMAP.
> 
> Fixes: 9968ead5 (2026-03-05; "man/man2/statmount.2: Document STATMOUNT_{UIDMAP,GIDMAP}")
> Signed-off-by: Bhavik Sachdev <b.sachdev1904@gmail.com>
> ---
> Hey Alex!

Hi Bhavik,

> Found another mistake while replying to your comments!

Thanks!  I've applied both patches.


Have a lovely day!
Alex

> 
> Thanks,
> Bhavik
> 
>  man/man2/statmount.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> index 78b6e9be..b6d9dc2a 100644
> --- a/man/man2/statmount.2
> +++ b/man/man2/statmount.2
> @@ -355,7 +355,7 @@ .SS The returned information
>  The number of uid mappings applied on the mount.
>  If
>  .I smbuf.mask
> -has STATMOUNT_UIDMAP set and this field is 0,
> +has STATMOUNT_MNT_UIDMAP set and this field is 0,
>  then uid mappings applied on the mount
>  cannot be resolved in the user namespace of the caller.
>  .TP
> @@ -372,7 +372,7 @@ .SS The returned information
>  The number of gid mappings applied on the mount.
>  If
>  .I smbuf.mask
> -has STATMOUNT_GIDMAP set and this field is 0,
> +has STATMOUNT_MNT_GIDMAP set and this field is 0,
>  then gid mappings applied on the mount
>  cannot be resolved in the user namespace of the caller.
>  .TP
> -- 
> 2.53.0
> 

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

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