Debian Codegraph @

upstream/fedora-44/man2/statmount.2

raw
1 '\" t
2 .\" Copyright (c) 2024 Josef Bacik <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH statmount 2 2024-07-23 "Linux man-pages 6.13"
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 .P
72 (Note that reserved space and padding is omitted.)
73 .SS The mnt_id_req structure
74 .I req.size
75 is used by the kernel to determine which
76 .I struct\~mnt_id_req
77 is being passed in;
78 it should always be set to
79 .IR sizeof(struct\~mnt_id_req) .
80 .P
81 .I req.mnt_id
82 can be obtained from either
83 .BR statx (2)
84 using
85 .B STATX_MNT_ID_UNIQUE
86 or from
87 .BR listmount (2)
88 and is used as the identifier to query the status of the desired mount point.
89 .P
90 .I req.param
91 is used to tell the kernel which fields the caller is interested in.
92 It is an ORed combination of the following constants
93 .P
94 .in +4n
95 .TS
96 lB l.
97 STATMOUNT_SB_BASIC /* Want/got sb_* */
98 STATMOUNT_MNT_BASIC /* Want/got mnt_* */
99 STATMOUNT_PROPAGATE_FROM /* Want/got propagate_from */
100 STATMOUNT_MNT_ROOT /* Want/got mnt_root */
101 STATMOUNT_MNT_POINT /* Want/got mnt_point */
102 STATMOUNT_FS_TYPE /* Want/got fs_type */
103 .TE
104 .in
105 .P
106 In general,
107 the kernel does
108 .I not
109 reject values in
110 .I req.param
111 other than the above.
112 (For an exception,
113 see
114 .B EINVAL
115 in errors.)
116 Instead,
117 it simply informs the caller which values are supported
118 by this kernel and filesystem via the
119 .I statmount.mask
120 field.
121 Therefore,
122 .I do not
123 simply set
124 .I req.param
125 to
126 .B UINT_MAX
127 (all bits set),
128 as one or more bits may,
129 in the future,
130 be used to specify an extension to the buffer.
131 .SS The returned information
132 The status information for the target mount is returned in the
133 .I statmount
134 structure pointed to by
135 .IR smbuf .
136 .P
137 The fields in the
138 .I statmount
139 structure are:
140 .TP
141 .I smbuf.size
142 The size of the returned
143 .I smbuf
144 structure,
145 including any of the strings fields that were filled.
146 .TP
147 .I smbuf.mask
148 The ORed combination of
149 .BI STATMOUNT_ *
150 flags indicating which fields were filled in and thus valid.
151 The kernel may return fields that weren't requested,
152 and may fail to return fields that were requested,
153 depending on what the backing file system and kernel supports.
154 In either case,
155 .I req.param
156 will not be equal to
157 .IR mask .
158 .TP
159 .I smbuf.sb_dev_major
160 .TQ
161 .I smbuf.sb_dev_minor
162 The device that is mounted at this mount point.
163 .TP
164 .I smbuf.sb_magic
165 The file system specific super block magic.
166 .TP
167 .I smbuf.sb_flags
168 The flags that are set on the super block,
169 an ORed combination of
170 .BR SB_RDONLY ,
171 .BR SB_SYNCHRONOUS ,
172 .BR SB_DIRSYNC ,
173 .BR SB_LAZYTIME .
174 .TP
175 .I smbuf.fs_type
176 The offset to the location in the
177 .I smbuf.str
178 buffer that contains the string representation of the mounted file system.
179 It is a null-terminated string.
180 .TP
181 .I smbuf.mnt_id
182 The unique mount ID of the mount.
183 .TP
184 .I smbuf.mnt_parent_id
185 The unique mount ID of the parent mount point of this mount.
186 If this is the root mount point then
187 .IR smbuf.mnt_id\~==\~smbuf.parent_mount_id .
188 .TP
189 .I smbuf.mnt_id_old
190 This corresponds to the mount ID that is exported by
191 .IR /proc/ pid /mountinfo .
192 .TP
193 .I smbuf.mnt_parent_id_old
194 This corresponds to the parent mount ID that is exported by
195 .IR /proc/ pid /mountinfo .
196 .TP
197 .I smbuf.mnt_attr
198 The
199 .BI MOUNT_ATTR_ *
200 flags set on this mount point.
201 .TP
202 .I smbuf.mnt_propagation
203 The mount propagation flags,
204 which can be one of
205 .BR MS_SHARED ,
206 .BR MS_SLAVE ,
207 .BR MS_PRIVATE ,
208 .BR MS_UNBINDABLE .
209 .TP
210 .I smbuf.mnt_peer_group
211 The ID of the shared peer group.
212 .TP
213 .I smbuf.mnt_master
214 The mount point receives its propagation from this mount ID.
215 .TP
216 .I smbuf.propagate_from
217 The ID from the namespace we propagated from.
218 .TP
219 .I smbuf.mnt_root
220 The offset to the location in the
221 .I smbuf.str
222 buffer that contains the string representation of the mount
223 relative to the root of the file system.
224 It is a null-terminated string.
225 .TP
226 .I smbuf.mnt_point
227 The offset to the location in the
228 .I smbuf.str
229 buffer that contains the string representation of the mount
230 relative to the current root (ie if you are in a
231 .BR chroot ).
232 It is a null-terminated string.
233 .SH RETURN VALUE
234 On success, zero is returned.
235 On error, \-1 is returned, and
236 .I errno
237 is set to indicate the error.
238 .SH ERRORS
239 .TP
240 .B EPERM
241 Permission is denied for accessing this mount.
242 .TP
243 .B EFAULT
244 .I req
245 or
246 .I smbuf
247 points to a location outside the process's accessible
248 address space.
249 .TP
250 .B EINVAL
251 Invalid flag specified in
252 .IR flags .
253 .TP
254 .B EINVAL
255 .I req
256 is of insufficient size to be utilized.
257 .TP
258 .B E2BIG
259 .I req
260 is too large.
261 .TP
262 .B EOVERFLOW
263 The size of
264 .I smbuf
265 is too small to contain either the
266 .IR smbuf.fs_type ,
267 .IR smbuf.mnt_root ,
268 or
269 .IR smbuf.mnt_point .
270 Allocate a larger buffer and retry the call.
271 .TP
272 .B ENOENT
273 The specified
274 .I req.mnt_id
275 doesn't exist.
276 .TP
277 .B ENOMEM
278 Out of memory (i.e., kernel memory).
279 .SH STANDARDS
280 Linux.
281 .SH SEE ALSO
282 .BR listmount (2),
283 .BR statx (2)