Re: [PATCH v3] man/man2/statmount.2: Document STATMOUNT_BY_FD
From: Alejandro Colomar <alx@kernel.org>
Date: 2026-03-04 14:58:21
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:
quoted hunk ↗ jump to hunk
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 <redacted> Message-ID: [off-list ref] Message-ID: [ref] --- Hey Alex!quoted
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
quoted hunk ↗ jump to hunk
+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>
Attachments
- signature.asc [application/pgp-signature] 833 bytes