Re: [PATCH v5 1/2] statmount.2: New page describing the statmount syscall

[Josef Bacik <josef@toxicpanda.com>]

On Tue, Jul 09, 2024 at 07:48:54PM +0200, Alejandro Colomar wrote:
> Hi Josef,
> 
> On Tue, Jul 09, 2024 at 01:25:42PM GMT, Josef Bacik wrote:
> > Add some documentation on the new statmount syscall.
> > 
> > Signed-off-by: Josef Bacik <josef@toxicpanda.com>
> 
> It's looking good already.  Please see some comments below.
> 
> Have a lovely day!
> Alex
> 
> > ---
> >  man/man2/statmount.2 | 280 +++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 280 insertions(+)
> >  create mode 100644 man/man2/statmount.2
> > 
> > diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> > new file mode 100644
> > index 000000000..c437ea685
> > --- /dev/null
> > +++ b/man/man2/statmount.2
> > @@ -0,0 +1,280 @@
> > +'\" t
> > +.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
> > +.\"
> > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > +.\"
> > +.TH statmount 2 (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +statmount \- get a mount status
> > +.SH LIBRARY
> > +Standard C library
> > +.RI ( libc ", " \-lc )
> > +.SH SYNOPSIS
> > +.nf
> > +.BR "#include <linux/mount.h>" "  /* Definition of STATMOUNT_* constants */"
> > +.B #include <unistd.h>
> > +.P
> > +.BI "int syscall(SYS_statmount, struct mnt_id_req * " req ,
> > +.BI "            struct statmount * " smbuf ", size_t " bufsize ,
> > +.BI "            unsigned long " flags );
> > +.P
> > +.B #include <linux/mount.h>
> > +.P
> > +.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 */"
> > +.B };
> > +.P
> > +.B struct statmount {
> > +.B "    __u32 size;"
> > +.B "    __u64 mask;"
> > +.B "    __u32 sb_dev_major;"
> > +.B "    __u32 sb_dev_minor;"
> > +.B "    __u64 sb_magic;"
> > +.B "    __u32 sb_flags;"
> > +.B "    __u32 fs_type;"
> > +.B "    __u64 mnt_id;"
> > +.B "    __u64 mnt_parent_id;"
> > +.B "    __u32 mnt_id_old;"
> > +.B "    __u32 mnt_parent_id_old;"
> > +.B "    __u64 mnt_attr;"
> > +.B "    __u64 mnt_propagation;"
> > +.B "    __u64 mnt_peer_group;"
> > +.B "    __u64 mnt_master;"
> > +.B "    __u64 propagate_from;"
> > +.B "    __u32 mnt_root;"
> > +.B "    __u32 mnt_point;"
> > +.B "    char  str[];"
> > +.B };
> > +.fi
> > +.P
> > +.IR Note :
> > +glibc provides no wrapper for
> > +.BR statmount (),
> > +necessitating the use of
> > +.BR syscall (2).
> > +.SH DESCRIPTION
> > +To access a mount's status,
> > +the caller must have CAP_SYS_ADMIN in the user namespace.
> > +.P
> > +This function returns information about a mount,
> > +storing it in the buffer pointed to by
> > +.IR smbuf .
> > +The returned buffer is a
> > +.I struct statmount
> > +which is of size
> > +.I bufsize
> > +with the fields filled in as described below.
> > +.P
> > +(Note that reserved space and padding is omitted.)
> > +.SS The mnt_id_req structure
> > +.I req.size
> > +is used by the kernel to determine which
> > +.I struct\~mnt_id_req
> > +is being passed in;
> > +it should always be set to
> > +.IR sizeof(struct\~mnt_id_req) .
> > +.P
> > +.I req.mnt_id
> > +can be obtained from either
> > +.BR statx (2)
> > +using
> > +.B STATX_MNT_ID_UNIQUE
> > +or from
> > +.BR listmount (2)
> > +and is used as the identifier to query the status of the desired mount point.
> > +.P
> > +.I req.param
> > +is used to tell the kernel which fields the caller is interested in.
> > +It is an ORed combination of the following constants
> > +.P
> > +.in +4n
> > +.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 */
> > +.TE
> > +.in
> > +.P
> > +In general,
> > +the kernel does
> > +.I not
> > +reject values in
> > +.I req.param
> > +other than the above.
> > +(For an exception,
> > +see
> > +.B EINVAL
> > +in errors.)
> > +Instead,
> > +it simply informs the caller which values are supported
> > +by this kernel and filesystem via the
> > +.I statmount.mask
> > +field.
> > +Therefore,
> > +.I "do not"
> > +simply set
> > +.I req.param
> > +to
> > +.B UINT_MAX
> > +(all bits set),
> > +as one or more bits may,
> > +in the future,
> > +be used to specify an extension to the buffer.
> > +.SS The returned information
> > +The status information for the target mount is returned in the
> > +.I statmount
> > +structure pointed to by
> > +.IR smbuf .
> > +.P
> > +The fields in the
> > +.I statmount
> > +structure are:
> > +.TP
> > +.I smbuf.size
> > +The size of the returned
> > +.I smbuf
> > +structure,
> > +including any of the strings fields that were filled.
> > +.TP
> > +.I smbuf.mask
> > +The ORed combination of
> > +.BI STATMOUNT_ *
> > +flags indicating which fields were filled in and thus valid.
> > +The kernel may return fields that weren't requested,
> > +and may fail to return fields that were requested,
> > +depending on what the backing file system and kernel supports.
> > +In either case,
> > +.I req.param
> > +will not be equal to
> > +.IR mask .
> > +.TP
> > +.I smbuf.sb_dev_major
> > +.TQ
> > +.I smbuf.sb_dev_minor
> > +The device that is mounted at this mount point.
> > +.TP
> > +.I smbuf.sb_magic
> > +The file system specific super block magic.
> > +.TP
> > +.I smbuf.sb_flags
> > +The flags that are set on the super block,
> > +an ORed combination of
> > +.BR SB_RDONLY ,
> > +.BR SB_SYNCHRONOUS ,
> > +.BR SB_DIRSYNC ,
> > +.BR SB_LAZYTIME .
> > +.TP
> > +.I smbuf.fs_type
> > +The offset to the location in the
> > +.I smbuf.str
> > +buffer that contains the string representation of the mounted file system.
> > +It is a null-terminated string.
> > +.TP
> > +.I smbuf.mnt_id
> > +The unique mount ID of the mount.
> > +.TP
> > +.I smbuf.mnt_parent_id
> > +The unique mount ID of the parent mount point of this mount.
> > +If this is the root mount point then
> > +.IR smbuf.mnt_id\~==\~smbuf.parent_mount_id .
> > +.TP
> > +.I smbuf.mnt_id_old
> > +This corresponds to the mount ID that is exported by
> > +.IR /proc/ pid /mountinfo .
> > +.TP
> > +.I smbuf.mnt_parent_id_old
> > +This corresponds to the parent mount ID that is exported by
> > +.IR /proc/ pid /mountinfo .
> > +.TP
> > +.I smbuf.mnt_attr
> > +The
> > +.BI MOUNT_ATTR_ *
> > +flags set on this mount point.
> > +.TP
> > +.I smbuf.mnt_propagation
> > +The mount propagation flags,
> > +which can be one of
> > +.BR MS_SHARED ,
> > +.BR MS_SLAVE ,
> > +.BR MS_PRIVATE ,
> > +.BR MS_UNBINDABLE .
> > +.TP
> > +.I smbuf.mnt_peer_group
> > +The ID of the shared peer group.
> > +.TP
> > +.I smbuf.mnt_master
> > +The mount point receives its propagation from this mount ID.
> > +.TP
> > +.I smbuf.propagate_from
> > +The ID from the namespace we propagated from.
> > +.TP
> > +.I smbuf.mnt_root
> > +The offset to the location in the
> > +.I smbuf.str
> > +buffer that contains the string representation of the mount
> > +relative to the root of the file system.
> > +It is a NULL terminated string.
> 
> s/NULL terminated/null-terminated/
> 
> NULL is the null pointer constant.
> NUL is the ASCII name for the null byte.
> We say null-terminated, because someone (probably Michael Kerrisk)
> thought NULL and NUL were confusing.  :)
> 

This is probably worth adding to 'make check' to save you time from telling me
to do that when I screw it up again in the future.  Thanks,

Josef