Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_bulkstat.2

raw
1 .\" Copyright (c) 2019, Oracle. All rights reserved.
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" SPDX-License-Identifier: GPL-2.0+
5 .\" %%%LICENSE_END
6 .TH IOCTL-XFS-BULKSTAT 2 2019-05-23 "XFS"
7 .SH NAME
8 ioctl_xfs_bulkstat \- query information for a batch of XFS inodes
9 .SH SYNOPSIS
10 .br
11 .B #include <xfs/xfs_fs.h>
12 .PP
13 .BI "int ioctl(int " fd ", XFS_IOC_BULKSTAT, struct xfs_bulkstat_req *" arg );
14 .SH DESCRIPTION
15 Query stat information for a group of XFS inodes.
16 This ioctl uses
17 .B struct xfs_bulkstat_req
18 to set up a bulk transfer from the kernel:
19 .PP
20 .in +4n
21 .nf
22 struct xfs_bulkstat_req {
23 struct xfs_bulk_ireq hdr;
24 struct xfs_bulkstat bulkstat[];
25 };
26 .fi
27 .in
28 .PP
29 See below for the
30 .B xfs_bulkstat
31 structure definition.
32 .PP
33 .in +4n
34 .nf
35 struct xfs_bulk_ireq {
36 uint64_t ino;
37 uint32_t flags;
38 uint32_t icount;
39 uint32_t ocount;
40 uint32_t agno;
41 uint64_t reserved[5];
42 };
43 .fi
44 .in
45 .PP
46 .I hdr.ino
47 should be set to the number of the first inode for which the caller wants
48 information; or zero to start with the first inode in the filesystem;
49 or a special value if
50 .B XFS_BULK_IREQ_SPECIAL
51 is set in the flags field.
52 Note that this is a different semantic than the
53 .B lastip
54 in the old
55 .B FSBULKSTAT
56 ioctl.
57 After the call, this value will be set to the number of the next inode for
58 which information could supplied.
59 This sets up the next call for an iteration loop.
60 .PP
61 If the
62 .B XFS_BULK_IREQ_SPECIAL
63 flag is set in the flags field, the
64 .I ino
65 field is interpreted according to the following special values:
66 .RS 0.4i
67 .TP
68 .B XFS_BULK_IREQ_SPECIAL_ROOT
69 Return stat information for the root directory inode.
70 .RE
71 .PP
72 .PP
73 .I hdr.flags
74 is a bit set of operational flags:
75 .RS 0.4i
76 .TP
77 .B XFS_BULK_IREQ_AGNO
78 If this is set, the call will only return results for the allocation group (AG)
79 set in
80 .BR hdr.agno .
81 If
82 .B hdr.ino
83 is set to zero, results will be returned starting with the first inode in the
84 AG.
85 This flag may not be set at the same time as the
86 .B XFS_BULK_IREQ_SPECIAL
87 flag.
88 .TP
89 .B XFS_BULK_IREQ_SPECIAL
90 If this is set, results will be returned for only the special inode
91 specified in the
92 .B hdr.ino
93 field.
94 This flag may not be set at the same time as the
95 .B XFS_BULK_IREQ_AGNO
96 flag.
97 .TP
98 .B XFS_BULK_IREQ_NREXT64
99 If this is set, data fork extent count is returned via bs_extents64 field and
100 0 is assigned to bs_extents. Otherwise, data fork extent count is returned
101 via bs_extents field and bs_extents64 is assigned a value of 0. In the second
102 case, bs_extents is set to (2^31 - 1) if data fork extent count is larger than
103 2^31. This flag may be set independently of whether other flags have been set.
104 .TP
105 .B XFS_BULK_IREQ_METADIR
106 Return metadata directory tree inodes in the stat output as well.
107 The only fields that will be populated are
108 .IR bs_ino ", " bs_gen ", " bs_mode ", " bs_sick ", and " bs_checked.
109 All other fields, notably
110 .IR bs_blksize ,
111 will be zero.
112 .RE
113 .PP
114 .I hdr.icount
115 is the maximum number of records to return.
116 This should be the size of the array that comes after the header.
117 .PP
118 .I hdr.ocount
119 will be set to the number of records actually returned.
120 .PP
121 .I hdr.agno
122 is the number of the allocation group (AG) for which we want results.
123 If the
124 .B XFS_BULK_IREQ_AGNO
125 flag is not set, this field is ignored.
126 .PP
127 .I hdr.reserved
128 must be set to zero.
129
130 .PP
131 .I bulkstat
132 is an array of
133 .B struct xfs_bulkstat
134 which is described below.
135 The array must have at least
136 .I icount
137 elements.
138 .PP
139 .in +4n
140 .nf
141 struct xfs_bulkstat {
142 uint64_t bs_ino;
143 uint64_t bs_size;
144
145 uint64_t bs_blocks;
146 uint64_t bs_xflags;
147
148 uint64_t bs_atime;
149 uint64_t bs_mtime;
150
151 uint64_t bs_ctime;
152 uint64_t bs_btime;
153
154 uint32_t bs_gen;
155 uint32_t bs_uid;
156 uint32_t bs_gid;
157 uint32_t bs_projectid;
158
159 uint32_t bs_atime_nsec;
160 uint32_t bs_mtime_nsec;
161 uint32_t bs_ctime_nsec;
162 uint32_t bs_btime_nsec;
163
164 uint32_t bs_blksize;
165 uint32_t bs_rdev;
166 uint32_t bs_cowextsize_blks;
167 uint32_t bs_extsize_blks;
168
169 uint32_t bs_nlink;
170 uint32_t bs_extents;
171 uint32_t bs_aextents;
172 uint16_t bs_version;
173 uint16_t bs_forkoff;
174
175 uint16_t bs_sick;
176 uint16_t bs_checked;
177 uint16_t bs_mode;
178 uint16_t bs_pad2;
179 uint64_t bs_extents64;
180
181 uint64_t bs_pad[6];
182 };
183 .fi
184 .in
185 .PP
186 .I bs_ino
187 is the inode number of this record.
188 .PP
189 .I bs_size
190 is the size of the file, in bytes.
191 .PP
192 .I bs_blocks
193 is the number of filesystem blocks allocated to this file, including metadata.
194 .PP
195 .I bs_xflags
196 tell us what extended flags are set this inode.
197 These flags are the same values as those defined in the
198 .B XFS INODE FLAGS
199 section of the
200 .BR ioctl_xfs_fsgetxattr (2)
201 manpage.
202 .PP
203 .I bs_atime
204 is the last time this file was accessed, in seconds.
205 .PP
206 .I bs_mtime
207 is the last time the contents of this file were modified, in seconds.
208 .PP
209 .I bs_ctime
210 is the last time this inode record was modified, in seconds.
211 .PP
212 .I bs_btime
213 is the time this inode record was created, in seconds.
214 .PP
215 .I bs_gen
216 is the generation number of the inode record.
217 .PP
218 .I bs_uid
219 is the user id.
220 .PP
221 .I bs_gid
222 is the group id.
223 .PP
224 .I bs_projectid
225 is the the project id.
226 .PP
227 .I bs_atime_nsec
228 is the nanoseconds component of the last time this file was accessed.
229 .PP
230 .I bs_mtime_nsec
231 is the nanoseconds component of the last time the contents of this file were
232 modified.
233 .PP
234 .I bs_ctime_nsec
235 is the nanoseconds component of the last time this inode record was modified.
236 .PP
237 .I bs_btime_nsec
238 is the nanoseconds component of the time this inode record was created.
239 .PP
240 .I bs_blksize
241 is the size of a data block for this file, in units of bytes.
242 .PP
243 .I bs_rdev
244 is the encoded device id if this is a special file.
245 .PP
246 .I bs_cowextsize_blks
247 is the Copy on Write extent size hint for this file, in units of data blocks.
248 .PP
249 .I bs_extsize_blks
250 is the extent size hint for this file, in units of data blocks.
251 .PP
252 .I bs_nlink
253 is the number of hard links to this inode.
254 .PP
255 .I bs_extents
256 is the number of storage mappings associated with this file's data.
257 .PP
258 .I bs_aextents
259 is the number of storage mappings associated with this file's extended
260 attributes.
261 .PP
262 .I bs_version
263 is the version of this data structure.
264 This will be set to
265 .I XFS_BULKSTAT_VERSION_V5
266 by the kernel.
267 .PP
268 .I bs_forkoff
269 is the offset of the attribute fork in the inode record, in bytes.
270 .PP
271 The fields
272 .IR bs_sick " and " bs_checked
273 indicate the relative health of various allocation group metadata.
274 Please see the section
275 .B XFS INODE METADATA HEALTH REPORTING
276 for more information.
277 .PP
278 .I bs_mode
279 is the file type and mode.
280 .PP
281 .I bs_pad[7]
282 is zeroed.
283 .SH RETURN VALUE
284 On error, \-1 is returned, and
285 .I errno
286 is set to indicate the error.
287 .PP
288 .SH XFS INODE METADATA HEALTH REPORTING
289 .PP
290 The online filesystem checking utility scans inode metadata and records what it
291 finds in the kernel incore state.
292 The following scheme is used for userspace to read the incore health status of
293 an inode:
294 .IP \[bu] 2
295 If a given sick flag is set in
296 .IR bs_sick ,
297 then that piece of metadata has been observed to be damaged.
298 The same bit should be set in
299 .IR bs_checked .
300 .IP \[bu]
301 If a given sick flag is set in
302 .I bs_checked
303 but is not set in
304 .IR bs_sick ,
305 then that piece of metadata has been checked and is not faulty.
306 .IP \[bu]
307 If a given sick flag is not set in
308 .IR bs_checked ,
309 then no conclusion can be made.
310 .PP
311 The following flags apply to these fields:
312 .RS 0.4i
313 .TP
314 .B XFS_BS_SICK_INODE
315 The inode's record itself.
316 .TP
317 .B XFS_BS_SICK_BMBTD
318 File data extent mappings.
319 .TP
320 .B XFS_BS_SICK_BMBTA
321 Extended attribute extent mappings.
322 .TP
323 .B XFS_BS_SICK_BMBTC
324 Copy on Write staging extent mappings.
325 .TP
326 .B XFS_BS_SICK_DIR
327 Directory information.
328 .TP
329 .B XFS_BS_SICK_XATTR
330 Extended attribute data.
331 .TP
332 .B XFS_BS_SICK_SYMLINK
333 Symbolic link target.
334 .TP
335 .B XFS_BS_SICK_PARENT
336 Parent pointers.
337 .TP
338 .B XFS_BS_SICK_DIRTREE
339 Directory is the source of corruption in the directory tree.
340 .RE
341 .SH ERRORS
342 Error codes can be one of, but are not limited to, the following:
343 .TP
344 .B EFAULT
345 The kernel was not able to copy into the userspace buffer.
346 .TP
347 .B EFSBADCRC
348 Metadata checksum validation failed while performing the query.
349 .TP
350 .B EFSCORRUPTED
351 Metadata corruption was encountered while performing the query.
352 .TP
353 .B EINVAL
354 One of the arguments was not valid.
355 .TP
356 .B EIO
357 An I/O error was encountered while performing the query.
358 .TP
359 .B ENOMEM
360 There was insufficient memory to perform the query.
361 .SH CONFORMING TO
362 This API is specific to XFS filesystem on the Linux kernel.
363 .SH SEE ALSO
364 .BR ioctl (2),
365 .BR ioctl_xfs_fsgetxattr (2)