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

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