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

Alejandro Colomar <[email protected]> Thu, 5 Mar 2026 18:19:30 +0100
Newsgroups	dev.linux.lists.criu,org.kernel.vger.linux-man
Message-ID	<aam6Yn6ZJhM9PQup@devuan>
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.

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>
signature.asc (application/pgp-signature, 833 B)