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

[Jeff Layton <jlayton@kernel.org>]

On Tue, 2024-07-09 at 14:31 -0400, Josef Bacik wrote:
> Add some documentation for the new listmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>
> ---
>  man/man2/listmount.2 | 112 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 112 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..212929fb6
> --- /dev/null
> +++ b/man/man2/listmount.2
> @@ -0,0 +1,112 @@
> +.\" 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.

The above does not seem to be correct. I can access the mounts in my
own namespace just fine. What I can't do is access mounts in other
namespaces without CAP_SYS_ADMIN, right?

Maybe this?

"To access mounts outside your own 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) .

The above is a little vague. It's not clear whether the list is just
immediate child mounts or if you get all mounts below that point. The
implementation in the kernel is the latter. You get a list of any
descendent mount of the given mnt_id.

Should we make that more clear?

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

-- 
Jeff Layton <jlayton@kernel.org>