[PATCH v5 0/2] man-pages: add documentation for statmount/listmount

[PATCH v5 0/2] man-pages: add documentation for statmount/listmount

[Josef Bacik]

V4: https://lore.kernel.org/linux-fsdevel/cover.1719840964.git.josef@toxicpanda.com/
V3: https://lore.kernel.org/linux-fsdevel/cover.1719425922.git.josef@toxicpanda.com/
V2: https://lore.kernel.org/linux-fsdevel/cover.1719417184.git.josef@toxicpanda.com/
V1: https://lore.kernel.org/linux-fsdevel/cover.1719341580.git.josef@toxicpanda.com/

v4->v5:
- Described bufsize.
- Moved the general description of some of the fields to under the field labels
  themselves, and generally reworked everything to be more specific.
- Addressed the various formatting/wording review comments.

v3->v4:
- Addressed review comments.

v2->v3:
- Removed a spurious \t comment in listmount.2 (took me a while to figure out
  why it was needed in statmount.2 but not listmount.2, it's because it lets you
  know that there's a TS in the manpage).
- Fixed some unbalanced " in both pages
- Removed a EE in the nf section which is apparently not needed

v1->v2:
- Dropped the statx patch as Alejandro already took it (thanks!)
- Reworked everything to use semantic newlines
- Addressed all of the comments on the statmount.2 man page

Josef

Josef Bacik (2):
  statmount.2: New page describing the statmount syscall
  listmount.2: New page describing the listmount syscall

 man/man2/listmount.2 | 111 +++++++++++++++++
 man/man2/statmount.2 | 280 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 391 insertions(+)
 create mode 100644 man/man2/listmount.2
 create mode 100644 man/man2/statmount.2

-- 
2.43.0

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

[Josef Bacik]

Add some documentation on the new statmount syscall.

Signed-off-by: Josef Bacik <josef@toxicpanda.com>
---
 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.
+.TP
+.I smbuf.mnt_point
+The offset to the location in the
+.I smbuf.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 smbuf
+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.
+.TP
+.B EOVERFLOW
+The size of
+.I smbuf
+is too small to contain either the
+.IR smbuf.fs_type ,
+.IR smbuf.mnt_root ,
+or
+.IR smbuf.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

[PATCH v5 2/2] listmount.2: New page describing the listmount syscall

[Josef Bacik]

Add some documentation for the new listmount syscall.

Signed-off-by: Josef Bacik <josef@toxicpanda.com>
---
 man/man2/listmount.2 | 111 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 man/man2/listmount.2

diff --git a/man/man2/listmount.2 b/man/man2/listmount.2
new file mode 100644
index 000000000..a86f59a6d
--- /dev/null
+++ b/man/man2/listmount.2
@@ -0,0 +1,111 @@
+.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH listmount 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+listmount \- get a list of mount ID's
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/mount.h>" "  /* Definition of struct mnt_id_req constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_listmount, struct mnt_id_req * " req ,
+.BI "            u64 * " mnt_ids ", size_t " nr_mnt_ids ,
+.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 parent mnt_id being searched */"
+.BR "    __u64 param;" "   /* The next mnt_id we want to find */"
+.B };
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR listmount (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+To access the mounts in your namespace,
+you must have CAP_SYS_ADMIN in the user namespace.
+.P
+This function returns a list of mount IDs under the
+.BR req.mnt_id .
+This is meant to be used in conjuction with
+.BR statmount (2)
+in order to provide a way to iterate and discover mounted file systems.
+.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).
+.P
+.I req.mnt_id
+is the parent mnt_id that we will list from,
+which can either be
+.B LSMT_ROOT
+which means the root mount of the current mount namespace,
+or a mount ID obtained from either
+.BR statx (2)
+using
+.B STATX_MNT_ID_UNIQUE
+or from
+.BR listmount (2) .
+.P
+.I req.param
+is used to tell the kernel what mount ID to start the list from.
+This is useful if multiple calls to
+.BR listmount (2)
+are required.
+This can be set to the last mount ID returned + 1 in order to
+resume from a previous spot in the list.
+.SH RETURN VALUE
+On success, the number of entries filled into
+.I mnt_ids
+is returned, 0 if there are no more mounts left.
+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 mnt_ids
+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 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 statmount (2),
+.BR statx (2)
-- 
2.43.0

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 8744 bytes --]

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.  :)

> +.TP
> +.I smbuf.mnt_point
> +The offset to the location in the
> +.I smbuf.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.

s/NULL terminated/null-terminated/

> +.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 smbuf
> +is NULL or points to a location outside the process's

NULL actually points to a location outside the accessible address space.
We can simplify and not mention NULL.

Normally, I use the _Nullable qualifier on function prototypes that
accept NULL.  See for example recvfrom(2).  If it's not used, passing
NULL is Undefined Behavior.

> +accessible address space.
> +.TP
> +.B EINVAL
> +Invalid flag specified in
> +.IR flags .
> +.TP
> +.B EINVAL
> +.I req
> +is of insufficient size to be utilized.

.TP

> +.B E2BIG
> +.I req
> +is too large.
> +.TP
> +.B EOVERFLOW
> +The size of
> +.I smbuf
> +is too small to contain either the
> +.IR smbuf.fs_type ,
> +.IR smbuf.mnt_root ,
> +or
> +.IR smbuf.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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3760 bytes --]

On Tue, Jul 09, 2024 at 01:25:43PM GMT, Josef Bacik wrote:
> Add some documentation for the new listmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>
> ---
>  man/man2/listmount.2 | 111 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 111 insertions(+)
>  create mode 100644 man/man2/listmount.2
> 
> diff --git a/man/man2/listmount.2 b/man/man2/listmount.2
> new file mode 100644
> index 000000000..a86f59a6d
> --- /dev/null
> +++ b/man/man2/listmount.2
> @@ -0,0 +1,111 @@
> +.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH listmount 2 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +listmount \- get a list of mount ID's
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ", " \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/mount.h>" "  /* Definition of struct mnt_id_req constants */"
> +.B #include <unistd.h>
> +.P
> +.BI "int syscall(SYS_listmount, struct mnt_id_req * " req ,
> +.BI "            u64 * " mnt_ids ", size_t " nr_mnt_ids ,
> +.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 parent mnt_id being searched */"
> +.BR "    __u64 param;" "   /* The next mnt_id we want to find */"
> +.B };
> +.fi
> +.P
> +.IR Note :
> +glibc provides no wrapper for
> +.BR listmount (),
> +necessitating the use of
> +.BR syscall (2).
> +.SH DESCRIPTION
> +To access the mounts in your namespace,
> +you must have CAP_SYS_ADMIN in the user namespace.
> +.P
> +This function returns a list of mount IDs under the
> +.BR req.mnt_id .
> +This is meant to be used in conjuction with
> +.BR statmount (2)
> +in order to provide a way to iterate and discover mounted file systems.
> +.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).
> +.P
> +.I req.mnt_id
> +is the parent mnt_id that we will list from,
> +which can either be
> +.B LSMT_ROOT
> +which means the root mount of the current mount namespace,
> +or a mount ID obtained from either
> +.BR statx (2)
> +using
> +.B STATX_MNT_ID_UNIQUE
> +or from
> +.BR listmount (2) .
> +.P
> +.I req.param
> +is used to tell the kernel what mount ID to start the list from.
> +This is useful if multiple calls to
> +.BR listmount (2)
> +are required.
> +This can be set to the last mount ID returned + 1 in order to
> +resume from a previous spot in the list.
> +.SH RETURN VALUE
> +On success, the number of entries filled into
> +.I mnt_ids
> +is returned, 0 if there are no more mounts left.
> +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 mnt_ids
> +is NULL or points to a location outside the process's

Remove the mention of NULL for simplicity.

> +accessible address space.
> +.TP
> +.B EINVAL
> +Invalid flag specified in
> +.IR flags .
> +.TP
> +.B EINVAL
> +.I req
> +is of insufficient size to be utilized.

.TP

> +.B E2BIG
> +.I req
> +is too large,
> +the limit is the architectures page size.
> +.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 statmount (2),
> +.BR statx (2)
> -- 
> 2.43.0
> 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Josef Bacik]

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 627 bytes --]

On Tue, Jul 09, 2024 at 02:37:24PM GMT, Josef Bacik wrote:
> > 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,

Hmmmm, interesting.  Maybe I can come up with some rules for common
mistakes.

Cheers,
Alex

> 
> Josef
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]