Debian Codegraph @

upstream/debian-unstable/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 2026-03-19 "Linux man-pages 6.18"
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 .B " union {"
28 .BR " __u32 mnt_ns_fd;" " /* fd of mnt_ns to query the mnt_id in */"
29 .BR " __u32 mnt_fd;" " /* fd on the mount being queried */"
30 .B " };"
31 .BR " __u64 mnt_id;" " /* The mnt_id being queried */"
32 .BR " __u64 param;" " /* ORed combination of the STATMOUNT_ constants */"
33 .BR " __u32 mnt_ns_id;" " /* The id of mnt_ns to query the mnt_id in */"
34 .B };
35 .P
36 .B struct statmount {
37 .B " __u32 size;"
38 .B " __u32 mnt_opts;"
39 .B " __u64 mask;"
40 .B " __u32 sb_dev_major;"
41 .B " __u32 sb_dev_minor;"
42 .B " __u64 sb_magic;"
43 .B " __u32 sb_flags;"
44 .B " __u32 fs_type;"
45 .B " __u64 mnt_id;"
46 .B " __u64 mnt_parent_id;"
47 .B " __u32 mnt_id_old;"
48 .B " __u32 mnt_parent_id_old;"
49 .B " __u64 mnt_attr;"
50 .B " __u64 mnt_propagation;"
51 .B " __u64 mnt_peer_group;"
52 .B " __u64 mnt_master;"
53 .B " __u64 propagate_from;"
54 .B " __u32 mnt_root;"
55 .B " __u32 mnt_point;"
56 .B " __u64 mnt_ns_id;"
57 .B " __u32 fs_subtype;"
58 .B " __u32 sb_source;"
59 .B " __u32 opt_num;"
60 .B " __u32 opt_array;"
61 .B " __u32 opt_sec_num;"
62 .B " __u32 opt_sec_array;"
63 .B " __u32 mnt_uidmap_num;"
64 .B " __u32 mnt_uidmap;"
65 .B " __u32 mnt_gidmap_num;"
66 .B " __u32 mnt_gidmap;"
67 .B " __u64 supported_mask;"
68 .B " char str[];"
69 .B };
70 .EE
71 .P
72 .IR Note :
73 glibc provides no wrapper for
74 .BR statmount (),
75 necessitating the use of
76 .BR syscall (2).
77 .SH DESCRIPTION
78 To access a mount's status,
79 the caller must have CAP_SYS_ADMIN in the user namespace.
80 In case of accessing a mount in a foreign mount namespace (specified via
81 .I req.mnt_ns_id
82 or
83 .IR req.mnt_ns_fd ),
84 the foreign mount namespace should be child of the current namespace.
85 .P
86 This function returns information about a mount,
87 storing it in the buffer pointed to by
88 .IR smbuf .
89 The returned buffer is a
90 .I struct statmount
91 which is of size
92 .I bufsize
93 with the fields filled in as described below.
94 .I flags
95 must either be 0 or
96 .BR STATMOUNT_BY_FD .
97 .P
98 (Note that reserved space and padding is omitted.)
99 .SS The mnt_id_req structure
100 .I req.size
101 is used by the kernel to determine which
102 .I struct\~mnt_id_req
103 is being passed in;
104 it should always be set to
105 .IR sizeof(struct\~mnt_id_req) .
106 .P
107 .I req.mnt_ns_fd
108 can be obtained from
109 .B PIDFD_GET_MNT_NAMESPACE
110 .BR ioctl (2)
111 operation or by opening a file descriptor to
112 .IR /proc/ pid /ns/mnt
113 and is used to specify a foreign mount namespace in which to query
114 .I req.mnt_id
115 (since Linux 6.18).
116 .P
117 .I req.mnt_fd
118 is a file descriptor on a mount.
119 If
120 .B STATMOUNT_BY_FD
121 flag is specified,
122 .I req.mnt_id
123 and
124 .I req.mnt_ns_id
125 are zeroed,
126 the function will return information about
127 the mount the file descriptor is on
128 (since Linux 7.0).
129 .P
130 The fd can also be on a mount that has been lazily unmounted (see
131 .BR umount2 (2)
132 with
133 .BR MNT_DETACH ).
134 In this case,
135 .B STATMOUNT_MNT_POINT
136 and
137 .B STATMOUNT_MNT_NS_ID
138 will be unset, since an unmounted mount is no longer a part of the filesystem.
139 .P
140 .I req.mnt_id
141 can be obtained from either
142 .BR statx (2)
143 using
144 .B STATX_MNT_ID_UNIQUE
145 or from
146 .BR listmount (2)
147 and is used as the identifier to query the status of the desired mount point.
148 .P
149 .I req.param
150 is used to tell the kernel which fields the caller is interested in.
151 It is an ORed combination of the following constants
152 .P
153 .in +4n
154 .TS
155 lB l.
156 STATMOUNT_SB_BASIC /* Want/got sb_* */
157 STATMOUNT_MNT_BASIC /* Want/got mnt_* */
158 STATMOUNT_PROPAGATE_FROM /* Want/got propagate_from */
159 STATMOUNT_MNT_ROOT /* Want/got mnt_root */
160 STATMOUNT_MNT_POINT /* Want/got mnt_point */
161 STATMOUNT_FS_TYPE /* Want/got fs_type */
162 STATMOUNT_MNT_NS_ID /* Want/got mnt_ns_id */
163 STATMOUNT_MNT_OPTS /* Want/got mnt_opts */
164 STATMOUNT_FS_SUBTYPE /* Want/got fs_subtype */
165 STATMOUNT_SB_SOURCE /* Want/got sb_source */
166 STATMOUNT_OPT_ARRAY /* Want/got opt_{num,array} */
167 STATMOUNT_OPT_SEC_ARRAY /* Want/got opt_sec_{num,array} */
168 STATMOUNT_MNT_UIDMAP /* Want/got uidmap{_num,} */
169 STATMOUNT_MNT_GIDMAP /* Want/got gidmap{_num,} */
170 STATMOUNT_SUPPORTED_MASK /* Want/got supported mask flags */
171 .TE
172 .in
173 .P
174 In general,
175 the kernel does
176 .I not
177 reject values in
178 .I req.param
179 other than the above.
180 (For an exception,
181 see
182 .B EINVAL
183 in errors.)
184 Instead,
185 it simply informs the caller which values are supported
186 by this kernel and filesystem via the
187 .I statmount.mask
188 field.
189 Therefore,
190 .I do not
191 simply set
192 .I req.param
193 to
194 .B UINT_MAX
195 (all bits set),
196 as one or more bits may,
197 in the future,
198 be used to specify an extension to the buffer.
199 .P
200 .I req.mnt_ns_id
201 can be obtained from
202 .B NS_GET_MNTNS_ID
203 .BR ioctl (2)
204 operation and is used to specify a foreign mount namespace in which to query
205 .I req.mnt_id
206 (since Linux 6.11).
207 .SS The returned information
208 The status information for the target mount is returned in the
209 .I statmount
210 structure pointed to by
211 .IR smbuf .
212 .P
213 The fields in the
214 .I statmount
215 structure are:
216 .TP
217 .I smbuf.size
218 The size of the returned
219 .I smbuf
220 structure,
221 including any of the strings fields that were filled.
222 .TP
223 .IR smbuf.mnt_opts " (since Linux 6.11)"
224 The offset to the location in the
225 .I smbuf.str
226 buffer that contains a comma separated list of mount options,
227 similiar to those in
228 .BR proc_pid_mountinfo (5) .
229 It is a null-terminated string.
230 .TP
231 .I smbuf.mask
232 The ORed combination of
233 .BI STATMOUNT_ *
234 flags indicating which fields were filled in and thus valid.
235 The kernel may return fields that weren't requested,
236 and may fail to return fields that were requested,
237 depending on what the backing file system and kernel supports.
238 In either case,
239 .I req.param
240 will not be equal to
241 .IR mask .
242 .TP
243 .I smbuf.sb_dev_major
244 .TQ
245 .I smbuf.sb_dev_minor
246 The device that is mounted at this mount point.
247 .TP
248 .I smbuf.sb_magic
249 The file system specific super block magic.
250 .TP
251 .I smbuf.sb_flags
252 The flags that are set on the super block,
253 an ORed combination of
254 .BR SB_RDONLY ,
255 .BR SB_SYNCHRONOUS ,
256 .BR SB_DIRSYNC ,
257 .BR SB_LAZYTIME .
258 .TP
259 .I smbuf.fs_type
260 The offset to the location in the
261 .I smbuf.str
262 buffer that contains the string representation of the mounted file system.
263 It is a null-terminated string.
264 .TP
265 .I smbuf.mnt_id
266 The unique mount ID of the mount.
267 .TP
268 .I smbuf.mnt_parent_id
269 The unique mount ID of the parent mount point of this mount.
270 If this is the root mount point then
271 .IR smbuf.mnt_id\~==\~smbuf.parent_mount_id .
272 .TP
273 .I smbuf.mnt_id_old
274 This corresponds to the mount ID that is exported by
275 .IR /proc/ pid /mountinfo .
276 .TP
277 .I smbuf.mnt_parent_id_old
278 This corresponds to the parent mount ID that is exported by
279 .IR /proc/ pid /mountinfo .
280 .TP
281 .I smbuf.mnt_attr
282 The
283 .BI MOUNT_ATTR_ *
284 flags set on this mount point.
285 .TP
286 .I smbuf.mnt_propagation
287 The mount propagation flags,
288 which can be one of
289 .BR MS_SHARED ,
290 .BR MS_SLAVE ,
291 .BR MS_PRIVATE ,
292 .BR MS_UNBINDABLE .
293 .TP
294 .I smbuf.mnt_peer_group
295 The ID of the shared peer group.
296 .TP
297 .I smbuf.mnt_master
298 The mount point receives its propagation from this mount ID.
299 .TP
300 .I smbuf.propagate_from
301 The ID from the namespace we propagated from.
302 .TP
303 .I smbuf.mnt_root
304 The offset to the location in the
305 .I smbuf.str
306 buffer that contains the string representation of the mount
307 relative to the root of the file system.
308 It is a null-terminated string.
309 .TP
310 .I smbuf.mnt_point
311 The offset to the location in the
312 .I smbuf.str
313 buffer that contains the string representation of the mount
314 relative to the current root (ie if you are in a
315 .BR chroot ).
316 It is a null-terminated string.
317 .TP
318 .IR smbuf.mnt_ns_id " (since Linux 6.11)"
319 The unique ID of the mount namespace the mount belongs to.
320 .TP
321 .IR smbuf.fs_subtype " (since Linux 6.13)"
322 The offset to the location in the
323 .I smbuf.str
324 buffer that contains the string representation of the file system subtype.
325 This is particularly useful for disambiguating FUSE mounts.
326 It is a null-terminated string.
327 .TP
328 .IR smbuf.sb_source " (since Linux 6.13)"
329 The offset to the location in the
330 .I smbuf.str
331 that contains the source of the mount.
332 It is a null-terminated string.
333 .TP
334 .IR smbuf.opt_num " (since Linux 6.13)"
335 The number of filesystem options set on the mount.
336 .TP
337 .IR smbuf.opt_array " (since Linux 6.13)"
338 The offset to the location in the
339 .I smbuf.str
340 buffer that contains file system options separated by null bytes.
341 They can be iterated over with the help of
342 .IR smbuf.opt_num .
343 .TP
344 .IR smbuf.opt_sec_num " (since Linux 6.13)"
345 The number of security options set on the mount.
346 .TP
347 .IR smbuf.opt_sec_array " (since Linux 6.13)"
348 The offset to the location in the
349 .I smbuf.str
350 buffer that contains security options separated by null bytes.
351 They can be iterated over with the help of
352 .IR smbuf.opt_sec_num .
353 .TP
354 .IR smbuf.mnt_uidmap_num " (since Linux 6.15)"
355 The number of uid mappings applied on the mount.
356 If
357 .I smbuf.mask
358 has STATMOUNT_MNT_UIDMAP set and this field is 0,
359 then uid mappings applied on the mount
360 cannot be resolved in the user namespace of the caller.
361 .TP
362 .IR smbuf.mnt_uidmap " (since Linux 6.15)"
363 The offset to the location in the
364 .I smbuf.str
365 buffer that contains uid mappings as consecutive null-terminated strings.
366 They can be iterated over with the help of
367 .IR smbuf.mnt_uidmap_num .
368 The whole range of uid mappings must be resolvable in the user namespace
369 of the caller.
370 .TP
371 .IR smbuf.mnt_gidmap_num " (since Linux 6.15)"
372 The number of gid mappings applied on the mount.
373 If
374 .I smbuf.mask
375 has STATMOUNT_MNT_GIDMAP set and this field is 0,
376 then gid mappings applied on the mount
377 cannot be resolved in the user namespace of the caller.
378 .TP
379 .IR smbuf.mnt_gidmap " (since Linux 6.15)"
380 The offset to the location in the
381 .I smbuf.str
382 buffer that contains gid mappings as consecutive null-terminated strings.
383 They can be iterated over with the help of
384 .IR smbuf.mnt_gidmap_num .
385 The whole range of gid mappings must be resolvable in the user namespace
386 of the caller.
387 .TP
388 .IR smbuf.supported_mask " (since Linux 6.15)"
389 The ORed combination of
390 .BI STATMOUNT_ *
391 flags supported by the current kernel.
392 .SH RETURN VALUE
393 On success, zero is returned.
394 On error, \-1 is returned, and
395 .I errno
396 is set to indicate the error.
397 .SH ERRORS
398 .TP
399 .B EPERM
400 Permission is denied for accessing this mount.
401 .TP
402 .B EFAULT
403 .I req
404 or
405 .I smbuf
406 points to a location outside the process's accessible
407 address space.
408 .TP
409 .B EINVAL
410 Invalid flag specified in
411 .IR flags .
412 .TP
413 .B EINVAL
414 .I req
415 is of insufficient size to be utilized.
416 .TP
417 .B EINVAL
418 Both
419 .I req.mnt_ns_id
420 and
421 .I req.mnt_ns_fd
422 were set.
423 .TP
424 .B EINVAL
425 .I req.mnt_id
426 or
427 .I req.mnt_ns_id
428 was specified alongside
429 .IR req.mnt_fd .
430 .TP
431 .B EBADF
432 .I req.mnt_fd
433 is an invalid file descriptor.
434 .TP
435 .B E2BIG
436 .I req
437 is too large.
438 .TP
439 .B EOVERFLOW
440 The size of
441 .I smbuf
442 is too small to contain either the
443 .IR smbuf.fs_type ,
444 .IR smbuf.mnt_root ,
445 or
446 .IR smbuf.mnt_point .
447 Allocate a larger buffer and retry the call.
448 .TP
449 .B ENOENT
450 The specified
451 .I req.mnt_id
452 doesn't exist.
453 .TP
454 .B ENOMEM
455 Out of memory (i.e., kernel memory).
456 .SH STANDARDS
457 Linux.
458 .SH SEE ALSO
459 .BR listmount (2),
460 .BR statx (2)