Debian Codegraph @

upstream/mageia-cauldron/man2/statmount.2

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH statmount 2 2025-12-23 "Linux man-pages 6.17"
7 .SH NAME
8 statmount \- get a mount status
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/mount.h>" " /* Definition of STATMOUNT_* constants */"
15 .B #include <unistd.h>
16 .P
17 .BI "int syscall(SYS_statmount, struct mnt_id_req *" req ,
18 .BI " struct statmount *" smbuf ", size_t " bufsize ,
19 .BI " unsigned long " flags );
20 .P
21 .B #include <linux/mount.h>
22 .fi
23 .P
24 .EX
25 .B struct mnt_id_req {
26 .BR " __u32 size;" " /* sizeof(struct mnt_id_req) */"
27 .BR " __u64 mnt_id;" " /* The mnt_id being queried */"
28 .BR " __u64 param;" " /* An ORed combination of the STATMOUNT_ constants */"
29 .B };
30 .P
31 .B struct statmount {
32 .B " __u32 size;"
33 .B " __u64 mask;"
34 .B " __u32 sb_dev_major;"
35 .B " __u32 sb_dev_minor;"
36 .B " __u64 sb_magic;"
37 .B " __u32 sb_flags;"
38 .B " __u32 fs_type;"
39 .B " __u64 mnt_id;"
40 .B " __u64 mnt_parent_id;"
41 .B " __u32 mnt_id_old;"
42 .B " __u32 mnt_parent_id_old;"
43 .B " __u64 mnt_attr;"
44 .B " __u64 mnt_propagation;"
45 .B " __u64 mnt_peer_group;"
46 .B " __u64 mnt_master;"
47 .B " __u64 propagate_from;"
48 .B " __u32 mnt_root;"
49 .B " __u32 mnt_point;"
50 .B " char str[];"
51 .B };
52 .EE
53 .P
54 .IR Note :
55 glibc provides no wrapper for
56 .BR statmount (),
57 necessitating the use of
58 .BR syscall (2).
59 .SH DESCRIPTION
60 To access a mount's status,
61 the caller must have CAP_SYS_ADMIN in the user namespace.
62 .P
63 This function returns information about a mount,
64 storing it in the buffer pointed to by
65 .IR smbuf .
66 The returned buffer is a
67 .I struct statmount
68 which is of size
69 .I bufsize
70 with the fields filled in as described below.
71 .I flags
72 must be 0.
73 .P
74 (Note that reserved space and padding is omitted.)
75 .SS The mnt_id_req structure
76 .I req.size
77 is used by the kernel to determine which
78 .I struct\~mnt_id_req
79 is being passed in;
80 it should always be set to
81 .IR sizeof(struct\~mnt_id_req) .
82 .P
83 .I req.mnt_id
84 can be obtained from either
85 .BR statx (2)
86 using
87 .B STATX_MNT_ID_UNIQUE
88 or from
89 .BR listmount (2)
90 and is used as the identifier to query the status of the desired mount point.
91 .P
92 .I req.param
93 is used to tell the kernel which fields the caller is interested in.
94 It is an ORed combination of the following constants
95 .P
96 .in +4n
97 .TS
98 lB l.
99 STATMOUNT_SB_BASIC /* Want/got sb_* */
100 STATMOUNT_MNT_BASIC /* Want/got mnt_* */
101 STATMOUNT_PROPAGATE_FROM /* Want/got propagate_from */
102 STATMOUNT_MNT_ROOT /* Want/got mnt_root */
103 STATMOUNT_MNT_POINT /* Want/got mnt_point */
104 STATMOUNT_FS_TYPE /* Want/got fs_type */
105 .TE
106 .in
107 .P
108 In general,
109 the kernel does
110 .I not
111 reject values in
112 .I req.param
113 other than the above.
114 (For an exception,
115 see
116 .B EINVAL
117 in errors.)
118 Instead,
119 it simply informs the caller which values are supported
120 by this kernel and filesystem via the
121 .I statmount.mask
122 field.
123 Therefore,
124 .I do not
125 simply set
126 .I req.param
127 to
128 .B UINT_MAX
129 (all bits set),
130 as one or more bits may,
131 in the future,
132 be used to specify an extension to the buffer.
133 .SS The returned information
134 The status information for the target mount is returned in the
135 .I statmount
136 structure pointed to by
137 .IR smbuf .
138 .P
139 The fields in the
140 .I statmount
141 structure are:
142 .TP
143 .I smbuf.size
144 The size of the returned
145 .I smbuf
146 structure,
147 including any of the strings fields that were filled.
148 .TP
149 .I smbuf.mask
150 The ORed combination of
151 .BI STATMOUNT_ *
152 flags indicating which fields were filled in and thus valid.
153 The kernel may return fields that weren't requested,
154 and may fail to return fields that were requested,
155 depending on what the backing file system and kernel supports.
156 In either case,
157 .I req.param
158 will not be equal to
159 .IR mask .
160 .TP
161 .I smbuf.sb_dev_major
162 .TQ
163 .I smbuf.sb_dev_minor
164 The device that is mounted at this mount point.
165 .TP
166 .I smbuf.sb_magic
167 The file system specific super block magic.
168 .TP
169 .I smbuf.sb_flags
170 The flags that are set on the super block,
171 an ORed combination of
172 .BR SB_RDONLY ,
173 .BR SB_SYNCHRONOUS ,
174 .BR SB_DIRSYNC ,
175 .BR SB_LAZYTIME .
176 .TP
177 .I smbuf.fs_type
178 The offset to the location in the
179 .I smbuf.str
180 buffer that contains the string representation of the mounted file system.
181 It is a null-terminated string.
182 .TP
183 .I smbuf.mnt_id
184 The unique mount ID of the mount.
185 .TP
186 .I smbuf.mnt_parent_id
187 The unique mount ID of the parent mount point of this mount.
188 If this is the root mount point then
189 .IR smbuf.mnt_id\~==\~smbuf.parent_mount_id .
190 .TP
191 .I smbuf.mnt_id_old
192 This corresponds to the mount ID that is exported by
193 .IR /proc/ pid /mountinfo .
194 .TP
195 .I smbuf.mnt_parent_id_old
196 This corresponds to the parent mount ID that is exported by
197 .IR /proc/ pid /mountinfo .
198 .TP
199 .I smbuf.mnt_attr
200 The
201 .BI MOUNT_ATTR_ *
202 flags set on this mount point.
203 .TP
204 .I smbuf.mnt_propagation
205 The mount propagation flags,
206 which can be one of
207 .BR MS_SHARED ,
208 .BR MS_SLAVE ,
209 .BR MS_PRIVATE ,
210 .BR MS_UNBINDABLE .
211 .TP
212 .I smbuf.mnt_peer_group
213 The ID of the shared peer group.
214 .TP
215 .I smbuf.mnt_master
216 The mount point receives its propagation from this mount ID.
217 .TP
218 .I smbuf.propagate_from
219 The ID from the namespace we propagated from.
220 .TP
221 .I smbuf.mnt_root
222 The offset to the location in the
223 .I smbuf.str
224 buffer that contains the string representation of the mount
225 relative to the root of the file system.
226 It is a null-terminated string.
227 .TP
228 .I smbuf.mnt_point
229 The offset to the location in the
230 .I smbuf.str
231 buffer that contains the string representation of the mount
232 relative to the current root (ie if you are in a
233 .BR chroot ).
234 It is a null-terminated string.
235 .SH RETURN VALUE
236 On success, zero is returned.
237 On error, \-1 is returned, and
238 .I errno
239 is set to indicate the error.
240 .SH ERRORS
241 .TP
242 .B EPERM
243 Permission is denied for accessing this mount.
244 .TP
245 .B EFAULT
246 .I req
247 or
248 .I smbuf
249 points to a location outside the process's accessible
250 address space.
251 .TP
252 .B EINVAL
253 Invalid flag specified in
254 .IR flags .
255 .TP
256 .B EINVAL
257 .I req
258 is of insufficient size to be utilized.
259 .TP
260 .B E2BIG
261 .I req
262 is too large.
263 .TP
264 .B EOVERFLOW
265 The size of
266 .I smbuf
267 is too small to contain either the
268 .IR smbuf.fs_type ,
269 .IR smbuf.mnt_root ,
270 or
271 .IR smbuf.mnt_point .
272 Allocate a larger buffer and retry the call.
273 .TP
274 .B ENOENT
275 The specified
276 .I req.mnt_id
277 doesn't exist.
278 .TP
279 .B ENOMEM
280 Out of memory (i.e., kernel memory).
281 .SH STANDARDS
282 Linux.
283 .SH SEE ALSO
284 .BR listmount (2),
285 .BR statx (2)