Debian Codegraph @

upstream/fedora-44/man2/listmount.2

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