Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_fsbulkstat.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-FSBULKSTAT 2 2019-06-17 "XFS"
7 .SH NAME
8 ioctl_xfs_fsbulkstat \- 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_FSBULKSTAT, struct xfs_fsop_bulkreq *" arg );
14 .br
15 .BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *" arg );
16 .SH DESCRIPTION
17 Query stat information for a group of XFS inodes.
18 .PP
19 NOTE: This ioctl has been superseded.
20 Please see the
21 .BR ioctl_xfs_bulkstat (2)
22 manpage for information about its replacement.
23 .PP
24 These ioctls use
25 .B struct xfs_fsop_bulkreq
26 to set up a bulk transfer with the kernel:
27 .PP
28 .in +4n
29 .nf
30 struct xfs_fsop_bulkreq {
31 __u64 *lastip;
32 __s32 count;
33 void *ubuffer;
34 __s32 *ocount;
35 };
36 .fi
37 .in
38 .PP
39 .I lastip
40 points to a value that will receive the number of the "last inode."
41 This cannot be NULL.
42 For
43 .BR FSBULKSTAT ,
44 this should be set to one less than the number of the first inode for which the
45 caller wants information, or zero to start with the first inode in the
46 filesystem.
47 For
48 .BR FSBULKSTAT_SINGLE ,
49 this should be set to the number of the inode for which the caller wants
50 information.
51 After the call, this value will be set to the number of the last inode for
52 which information was supplied.
53 This field will not be updated if
54 .I ocount
55 is NULL.
56 .PP
57 .I count
58 is the number of elements in the
59 .B ubuffer
60 array and therefore the number of inodes for which to return stat information.
61 This value must be set to 1 for
62 .BR FSBULKSTAT_SINGLE .
63 .PP
64 .I ocount
65 points to a value that will receive the number of records returned.
66 If this value is NULL, then neither
67 .I ocount
68 nor
69 .I lastip
70 will be updated.
71 .PP
72 .I ubuffer
73 points to a memory buffer into which inode stat information will be copied.
74 This buffer must be an array of
75 .B struct xfs_bstat
76 which is described below.
77 The array must have at least
78 .I count
79 elements.
80 .PP
81 .in +4n
82 .nf
83 struct xfs_bstat {
84 __u64 bs_ino;
85 __u16 bs_mode;
86 __u16 bs_nlink;
87 __u32 bs_uid;
88 __u32 bs_gid;
89 __u32 bs_rdev;
90 __s32 bs_blksize;
91 __s64 bs_size;
92 struct xfs_bstime bs_atime;
93 struct xfs_bstime bs_mtime;
94 struct xfs_bstime bs_ctime;
95 int64_t bs_blocks;
96 __u32 bs_xflags;
97 __s32 bs_extsize;
98 __s32 bs_extents;
99 __u32 bs_gen;
100 __u16 bs_projid_lo;
101 __u16 bs_forkoff;
102 __u16 bs_projid_hi;
103 uint16_t bs_sick;
104 uint16_t bs_checked;
105 unsigned char bs_pad[2];
106 __u32 bs_cowextsize;
107 __u32 bs_dmevmask;
108 __u16 bs_dmstate;
109 __u16 bs_aextents;
110 };
111 .fi
112 .in
113 .PP
114 The structure members are as follows:
115 .PP
116 .I bs_ino
117 is the inode number for this record.
118 .PP
119 .I bs_mode
120 is the file type and mode.
121 .PP
122 .I bs_nlink
123 is the number of hard links to this inode.
124 .PP
125 .I bs_uid
126 is the user id.
127 .PP
128 .I bs_gid
129 is the group id.
130 .PP
131 .I bs_rdev
132 is the encoded device id if this is a special file.
133 .PP
134 .I bs_blksize
135 is the size of a data block for this file, in units of bytes.
136 .PP
137 .I bs_size
138 is the size of the file, in bytes.
139 .PP
140 .I bs_atime
141 is the last time this file was accessed.
142 .PP
143 .I bs_mtime
144 is the last time the contents of this file were modified.
145 .PP
146 .I bs_ctime
147 is the last time this inode record was modified.
148 .PP
149 .I bs_blocks
150 is the number of filesystem blocks allocated to this file, including metadata.
151 .PP
152 .I bs_xflags
153 contains the extended flags that are set on this inode.
154 These flags are the same values as those defined in the
155 .B XFS INODE FLAGS
156 section of the
157 .BR ioctl_xfs_fsgetxattr (2)
158 manpage.
159
160 .PD 1
161 .PP
162 .I bs_extsize
163 is the extent size hint for this file, in bytes.
164 .PP
165 .I bs_extents
166 is the number of storage mappings associated with this file's data.
167 .PP
168 .I bs_gen
169 is the generation number of the inode record.
170 .PP
171 .I bs_projid_lo
172 is the lower 16-bits of the project id.
173 .PP
174 .I bs_forkoff
175 is the offset of the attribute fork in the inode record, in bytes.
176 .PP
177 .I bs_projid_hi
178 is the upper 16-bits of the project id.
179 .PP
180 .I bs_pad[6]
181 is zeroed.
182 .PP
183 .I bs_cowextsize
184 is the Copy on Write extent size hint for this file, in bytes.
185 .PP
186 .I bs_dmevmask
187 is unused on Linux.
188 .PP
189 .I bs_dmstate
190 is unused on Linux.
191 .PP
192 .I bs_aextents
193 is the number of storage mappings associated with this file's extended
194 attributes.
195 .PP
196 The fields
197 .IR bs_sick " and " bs_checked
198 indicate the relative health of various inode metadata:
199 .IP \[bu] 2
200 If a given sick flag is set in
201 .IR bs_sick ,
202 then that piece of metadata has been observed to be damaged.
203 The same bit should be set in
204 .IR bs_checked .
205 .IP \[bu]
206 If a given sick flag is set in
207 .I bs_checked
208 but is not set in
209 .IR bs_sick ,
210 then that piece of metadata has been checked and is not faulty.
211 .IP \[bu]
212 If a given sick flag is not set in
213 .IR bs_checked ,
214 then no conclusion can be made.
215 .PP
216 The following flags apply to these fields:
217 .RS 0.4i
218 .TP
219 .B XFS_BS_SICK_INODE
220 The inode's record itself.
221 .TP
222 .B XFS_BS_SICK_BMBTD
223 File data extent mappings.
224 .TP
225 .B XFS_BS_SICK_BMBTA
226 Extended attribute extent mappings.
227 .TP
228 .B XFS_BS_SICK_BMBTC
229 Copy on Write staging extent mappings.
230 .TP
231 .B XFS_BS_SICK_DIR
232 Directory information.
233 .TP
234 .B XFS_BS_SICK_XATTR
235 Extended attribute data.
236 .TP
237 .B XFS_BS_SICK_SYMLINK
238 Symbolic link target.
239 .TP
240 .B XFS_BS_SICK_PARENT
241 Parent pointers.
242 .TP
243 .B XFS_BS_SICK_DIRTREE
244 Directory is the source of corruption in the directory tree.
245 .RE
246 .SH RETURN VALUE
247 On error, \-1 is returned, and
248 .I errno
249 is set to indicate the error.
250 .PP
251 .SH ERRORS
252 Error codes can be one of, but are not limited to, the following:
253 .TP
254 .B EFAULT
255 The kernel was not able to copy into the userspace buffer.
256 .TP
257 .B EFSBADCRC
258 Metadata checksum validation failed while performing the query.
259 .TP
260 .B EFSCORRUPTED
261 Metadata corruption was encountered while performing the query.
262 .TP
263 .B EINVAL
264 One of the arguments was not valid.
265 .TP
266 .B EIO
267 An I/O error was encountered while performing the query.
268 .TP
269 .B ENOMEM
270 There was insufficient memory to perform the query.
271 .SH CONFORMING TO
272 This API is specific to XFS filesystem on the Linux kernel.
273 .SH SEE ALSO
274 .BR ioctl (2),
275 .BR ioctl_xfs_fsgetxattr (2)