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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Josef,

On Tue, Jul 09, 2024 at 02:31:23PM GMT, Josef Bacik wrote:
> Add some documentation for the new listmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@xxxxxxxxxxxxxx>

Thanks!  I've applied the patch with some minor tweaks:

	diff --git i/man/man2/listmount.2 w/man/man2/listmount.2
	index 212929fb6..8f7c7afaa 100644
	--- i/man/man2/listmount.2
	+++ w/man/man2/listmount.2
	@@ -4,7 +4,9 @@
	 .\"
	 .TH listmount 2 (date) "Linux man-pages (unreleased)"
	 .SH NAME
	-listmount \- get a list of mount ID's
	+listmount
	+\-
	+get a list of mount ID's
	 .SH LIBRARY
	 Standard C library
	 .RI ( libc ", " \-lc )
	@@ -14,15 +16,15 @@ .SH SYNOPSIS
	 .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 "            uint64_t * " 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 */"
	+.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
	@@ -45,7 +47,8 @@ .SS The mnt_id_req structure
	 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).
	+it should always be set to
	+.IR \%sizeof(struct\~mnt_id_req) .
	 .P
	 .I req.mnt_id
	 is the parent mnt_id that we will list from,
	@@ -69,7 +72,8 @@ .SS The mnt_id_req structure
	 .SH RETURN VALUE
	 On success, the number of entries filled into
	 .I mnt_ids
	-is returned, 0 if there are no more mounts left.
	+is returned;
	+0 if there are no more mounts left.
	 On error, \-1 is returned, and
	 .I errno
	 is set to indicate the error.

Would you mind adding an example program in a new patch?

Have a lovely night!
Alex

> ---
>  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@xxxxxxxxxxxxxx>
> +.\"
> +.\" 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
> +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)
> -- 
> 2.43.0
> 
> 

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

Attachment: signature.asc
Description: PGP signature


[Index of Archives]     [Linux Ext4 Filesystem]     [Union Filesystem]     [Filesystem Testing]     [Ceph Users]     [Ecryptfs]     [NTFS 3]     [AutoFS]     [Kernel Newbies]     [Share Photos]     [Security]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux Cachefs]     [Reiser Filesystem]     [Linux RAID]     [NTFS 3]     [Samba]     [Device Mapper]     [CEPH Development]

  Powered by Linux