Debian Codegraph @

upstream/debian-unstable/man2/listmount.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH listmount 2 2025-09-06 "Linux man-pages 6.18"
6 .SH NAME
7 listmount
8 \-
9 get a list of mount ID's
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/mount.h>" " /* Definition of struct mnt_id_req constants */"
16 .B #include <unistd.h>
17 .P
18 .BR "int syscall(" "size_t n;"
19 .BI " SYS_listmount, struct mnt_id_req *" req ,
20 .BI " uint64_t " mnt_ids [ n "], size_t " n ,
21 .BI " unsigned long " flags );
22 .P
23 .B #include <linux/mount.h>
24 .P
25 .B struct mnt_id_req {
26 .BR " __u32 size;" " /* sizeof(struct mnt_id_req) */"
27 .BR " __u64 mnt_id;" " /* The parent mnt_id being searched */"
28 .BR " __u64 param;" " /* The next mnt_id we want to find */"
29 .B };
30 .fi
31 .P
32 .IR Note :
33 glibc provides no wrapper for
34 .BR listmount (),
35 necessitating the use of
36 .BR syscall (2).
37 .SH DESCRIPTION
38 To access the mounts in your namespace,
39 you must have CAP_SYS_ADMIN in the user namespace.
40 .P
41 This function returns a list of mount IDs under the
42 .BR req.mnt_id .
43 This is meant to be used in conjuction with
44 .BR statmount (2)
45 in order to provide a way to iterate and discover mounted file systems.
46 .SS The mnt_id_req structure
47 .I req.size
48 is used by the kernel to determine which struct
49 .I mnt_id_req
50 is being passed in,
51 it should always be set to
52 .IR \%sizeof(struct\~mnt_id_req) .
53 .P
54 .I req.mnt_id
55 is the parent mnt_id that we will list from,
56 which can either be
57 .B LSMT_ROOT
58 which means the root mount of the current mount namespace,
59 or a mount ID obtained from either
60 .BR statx (2)
61 using
62 .B STATX_MNT_ID_UNIQUE
63 or from
64 .BR listmount (2) .
65 .P
66 .I req.param
67 is used to tell the kernel what mount ID to start the list from.
68 This is useful if multiple calls to
69 .BR listmount (2)
70 are required.
71 This can be set to the last mount ID returned in order to
72 resume from a previous spot in the list.
73 .SH RETURN VALUE
74 On success, the number of entries filled into
75 .I mnt_ids
76 is returned;
77 0 if there are no more mounts left.
78 On error, \-1 is returned, and
79 .I errno
80 is set to indicate the error.
81 .SH ERRORS
82 .TP
83 .B EPERM
84 The caller does not have
85 .B CAP_SYS_ADMIN
86 in the user namespace.
87 .TP
88 .B EFAULT
89 .I req
90 or
91 .I mnt_ids
92 points to a location outside the process's accessible
93 address space.
94 .TP
95 .B EINVAL
96 Invalid flag specified in
97 .IR flags .
98 .TP
99 .B EINVAL
100 .I req
101 is of insufficient size to be utilized.
102 .TP
103 .B E2BIG
104 .I req
105 is too large,
106 the limit is the architectures page size.
107 .TP
108 .B ENOENT
109 The specified
110 .I req.mnt_id
111 doesn't exist.
112 .TP
113 .B ENOMEM
114 Out of memory (i.e., kernel memory).
115 .SH STANDARDS
116 Linux.
117 .SH SEE ALSO
118 .BR statmount (2),
119 .BR statx (2)