On Wed, Jun 26, 2024 at 02:21:39PM GMT, Josef Bacik wrote:
> Add some documentation on the new statmount syscall.
>
> Signed-off-by: Josef Bacik <josef@xxxxxxxxxxxxxx>
> ---
> man/man2/statmount.2 | 285 +++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 285 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..2f85bc022
> --- /dev/null
> +++ b/man/man2/statmount.2
> @@ -0,0 +1,285 @@
> +'\" t
> +.\" Copyright (c) 2024 Josef Bacik <josef@xxxxxxxxxxxxxx>
> +.\"
> +.\" 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 * " statmountbuf ", size_t " bufsize ,
How about a shorter name? s/statmountbuf/smbuf/
> +.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,
> +you 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 statmountbuf .
> +The returned buffer is a
> +.I struct statmount
> +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 struct
> +.I mnt_id_req
> +is being passed in,
> +it should always be set to sizeof(struct mnt_id req).
There's a missing '_'. BTW, since this is inline code, it should be in
italics. See man-pages(7):
Expressions, if not written on a separate indented line, should be
specified in italics. Again, the use of nonbreaking spaces may be
appropriate if the expression is inlined with normal text.
So:
.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
> +lBl.
> +STATMOUNT_SB_BASIC /* Want/got sb_... */
> +STATMOUNT_MNT_BASIC /* Want/got mnt_... */
We normally use glob style for these things: sb_* 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
> +Note that,
> +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 statmountbuf .
> +Included in this is
> +.I size
> +which indicates the size of the
> +.I statmountbuf
> +that was filled in,
> +including any strings.
> +.I mask
> +which indicates what information in the structure has been filled in.
> +.P
> +It should be noted that 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 .
> +.P
> +Apart from
> +.I mask
> +(which is described above),
Why not describe .mask like the rest, below? That would be more
consistent, no?
> +the fields in the
> +.I statmount
> +structure are:
> +.TP
> +.I size
Please use smbuf.size, for consistency with the mnt_id_rew subsection,
which uses req.*
I like that, because it is more explicit (you don't need to check again
in which subsection you are).
> +The size of the returned
> +.I statmountbuf
> +structure.
> +.TP
> +.I sb_dev_major
> +.TQ
> +.I sb_dev_minor
> +The device that is mounted at this mount point.
> +.TP
> +.I sb_magic
> +The file system specific super block magic.
> +.TP
> +.I 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 fs_type
> +The offset to the location in the
> +.I statmount.str
> +buffer that contains the string representation of the mounted file system. It is
> +a null-terminated string.
> +.TP
> +.I mnt_id
> +The unique mount ID of the mount.
> +.TP
> +.I mnt_parent_id
> +The unique mount ID of the parent mount point of this mount.
> +If this is the root mount point then
> +.IR mnt_id\~==\~parent_mount_id .
> +.TP
> +.I mnt_id_old
> +This corresponds to the mount ID that is exported by
> +.IR /proc/ pid /mountinfo .
> +.TP
> +.I mnt_parent_id_old
> +This corresponds to the parent mount ID that is exported by
> +.IR /proc/ pid /mountinfo .
> +.TP
> +.I mnt_attr
> +The
> +.B MOUNT_ATTR_
.BI MOUNT_ATTR_ *
Have a lovely day!
Alex
> +flags set on this mount point.
> +.TP
> +.I 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 mnt_peer_group
> +The ID of the shared peer group.
> +.TP
> +.I mnt_master
> +The mount point receives its propagation from this mount ID.
> +.TP
> +.I propagate_from
> +The ID from the namespace we propagated from.
> +.TP
> +.I mnt_root
> +The offset to the location in the
> +.I statmount.str
> +buffer that contains the string representation of the mount relative to the root
> +of the file system.
> +It is a NULL terminated string.
> +.TP
> +.I mnt_point
> +The offset to the location in the
> +.I statmount.str
> +buffer that contains the string representation of the mount relative to the
> +current root (ie if you are in a
> +.BR chroot ).
> +It is a NULL terminated string.
> +.SH RETURN VALUE
> +On success, zero is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EPERM
> +Permission is denied for accessing this mount.
> +.TP
> +.B EFAULT
> +.I req
> +or
> +.I statmountbuf
> +is NULL or points to a location outside the process's
> +accessible address space.
> +.TP
> +.B EINVAL
> +Invalid flag specified in
> +.IR flags .
> +.TP
> +.B EINVAL
> +.I req
> +is of insufficient size to be utilized.
> +.B E2BIG
> +.I req
> +is too large,
> +the limit is the architectures page size.
> +.TP
> +.B EOVERFLOW
> +The size of
> +.I statmountbuf
> +is too small to contain either the
> +.IR statmountbuf.fs_type ,
> +.IR statmountbuf.mnt_root ,
> +or
> +.IR statmountbuf.mnt_point .
> +Allocate a larger buffer and retry the call.
> +.TP
> +.B ENOENT
> +The specified
> +.I req.mnt_id
> +doesn't exist.
> +.TP
> +.B ENOMEM
> +Out of memory (i.e., kernel memory).
> +.SH STANDARDS
> +Linux.
> +.SH SEE ALSO
> +.BR listmount (2),
> +.BR statx (2)
> --
> 2.43.0
>
>
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
