.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH listmount 2 2024-11-17 "Linux man-pages 6.10"
.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 "            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 */"
.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
.IR \%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 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)