Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_scrub_metadata.2

raw
1 .\" Copyright (c) 2017, 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-SCRUB-METADATA 2 2017-12-01 "XFS"
7 .SH NAME
8 ioctl_xfs_scrub_metadata \- check XFS filesystem metadata
9 .SH SYNOPSIS
10 .br
11 .B #include <xfs/xfs_fs.h>
12 .PP
13 .BI "int ioctl(int " dest_fd ", XFS_IOC_SCRUB_METADATA, struct xfs_scrub_metadata *" arg );
14 .SH DESCRIPTION
15 This XFS ioctl asks the kernel driver to examine a piece of filesystem
16 metadata for errors or suboptimal metadata.
17 Examination includes running metadata verifiers, checking records
18 for obviously incorrect or impossible values, and cross-referencing each
19 record with any other available metadata in the filesystem.
20 This ioctl can also try to repair or optimize metadata, though this may
21 block normal filesystem operations for a long period of time.
22 The type and location of the metadata to scrub is conveyed in a structure
23 of the following form:
24 .PP
25 .in +4n
26 .nf
27 struct xfs_scrub_metadata {
28 __u32 sm_type;
29 __u32 sm_flags;
30 __u64 sm_ino;
31 __u32 sm_gen;
32 __u32 sm_agno;
33 __u64 sm_reserved[5];
34 };
35 .fi
36 .in
37 .PP
38 The field
39 .I sm_reserved
40 must be zero.
41 .PP
42 The field
43 .I sm_type
44 indicates the type of metadata to check:
45 .RS 0.4i
46 .TP
47 .B XFS_SCRUB_TYPE_PROBE
48 Probe the kernel to see if it is willing to try to check or repair this
49 filesystem.
50 .BR sm_agno ", " sm_ino ", and " sm_gen
51 must be zero.
52
53 .PD 0
54 .PP
55 .nf
56 .B XFS_SCRUB_TYPE_SB
57 .B XFS_SCRUB_TYPE_AGF
58 .B XFS_SCRUB_TYPE_AGFL
59 .fi
60 .TP
61 .B XFS_SCRUB_TYPE_AGI
62 Examine a given allocation group's superblock, free space header, free
63 block list, or inode header, respectively.
64 Headers are checked for obviously incorrect values and cross-referenced
65 against the allocation group's metadata btrees, if possible.
66 The allocation group number must be given in
67 .BR sm_agno "."
68 .BR sm_ino " and " sm_gen
69 must be zero.
70
71 .PP
72 .nf
73 .B XFS_SCRUB_TYPE_BNOBT
74 .B XFS_SCRUB_TYPE_CNTBT
75 .B XFS_SCRUB_TYPE_INOBT
76 .B XFS_SCRUB_TYPE_FINOBT
77 .B XFS_SCRUB_TYPE_RMAPBT
78 .fi
79 .TP
80 .B XFS_SCRUB_TYPE_REFCNTBT
81 Examine a given allocation group's two free space btrees, two inode
82 btrees, reverse mapping btrees, or reference count btrees, respectively.
83 Records are checked for obviously incorrect values and cross-referenced
84 with other allocation group metadata records to ensure that there are no
85 conflicts.
86 The allocation group number must be given in
87 .BR sm_agno "."
88 .BR sm_ino " and " sm_gen
89 must be zero.
90
91 .PP
92 .TP
93 .B XFS_SCRUB_TYPE_RGSUPER
94 Examine a given realtime allocation group's superblock.
95 The realtime allocation group number must be given in
96 .IR sm_agno "."
97 .IR sm_ino " and " sm_gen
98 must be zero.
99
100 .TP
101 .B XFS_SCRUB_TYPE_INODE
102 Examine a given inode record for obviously incorrect values and
103 discrepancies with the rest of filesystem metadata.
104 Parent pointers are checked for impossible inode values and are then
105 followed up to the parent directory to ensure that the linkage is
106 correct.
107 The inode to examine may be specified either through
108 .B sm_ino
109 and
110 .BR sm_gen "; "
111 if not specified, then the file described by
112 .B dest_fd
113 will be examined.
114 .B sm_agno
115 must be zero.
116
117 .PP
118 .nf
119 .B XFS_SCRUB_TYPE_BMBTD
120 .B XFS_SCRUB_TYPE_BMBTA
121 .fi
122 .TP
123 .B XFS_SCRUB_TYPE_BMBTC
124 Examine a given inode's data block map, extended attribute block map,
125 or copy on write block map.
126 Inode records are examined for obviously incorrect values and
127 discrepancies with the three block map types.
128 The block maps are checked for obviously wrong values and
129 cross-referenced with the allocation group space extent metadata for
130 discrepancies.
131 The inode to examine can be specified in the same manner as
132 .BR XFS_SCRUB_TYPE_INODE "."
133
134 .TP
135 .B XFS_SCRUB_TYPE_XATTR
136 Examine the extended attribute records and indices of a given inode for
137 incorrect pointers and other signs of damage.
138 The inode to examine can be specified in the same manner as
139 .BR XFS_SCRUB_TYPE_INODE "."
140
141 .TP
142 .B XFS_SCRUB_TYPE_DIR
143 Examine the entries in a given directory for invalid data or dangling pointers.
144 If the filesystem supports directory parent pointers, each entry will be
145 checked to confirm that the child file has a matching parent pointer.
146 The directory to examine can be specified in the same manner as
147 .BR XFS_SCRUB_TYPE_INODE "."
148
149 .TP
150 .B XFS_SCRUB_TYPE_PARENT
151 For filesystems that support directory parent pointers, this scrubber
152 examines all the parent pointers attached to a file and confirms that the
153 parent directory has an entry matching the parent pointer.
154 For filesystems that do not support directory parent pointers, this scrubber
155 checks that a subdirectory's dotdot entry points to a directory with an entry
156 that points back to the subdirectory.
157 The inode to examine can be specified in the same manner as
158 .BR XFS_SCRUB_TYPE_INODE "."
159
160 .TP
161 .B XFS_SCRUB_TYPE_DIRTREE
162 This scrubber looks for problems in the directory tree structure such as loops
163 and directories accessible through more than one path.
164 Problems are detected by walking parent pointers upwards towards the root.
165 Loops are detected by comparing the parent directory at each step against the
166 directories already examined.
167 Directories with multiple paths are detected by counting the parent pointers
168 attached to a directory.
169 Non-directories do not have links pointing away from the directory tree root
170 and can be skipped.
171 The directory to examine can be specified in the same manner as
172 .BR XFS_SCRUB_TYPE_INODE "."
173
174 .TP
175 .B XFS_SCRUB_TYPE_SYMLINK
176 Examine the target of a symbolic link for obvious pathname problems.
177 The link to examine can be specified in the same manner as
178 .BR XFS_SCRUB_TYPE_INODE "."
179
180 .PP
181 .nf
182 .B XFS_SCRUB_TYPE_RTBITMAP
183 .B XFS_SCRUB_TYPE_RTSUM
184 .B XFS_SCRUB_TYPE_RTRMAPBT
185 .fi
186 .TP
187 .B XFS_SCRUB_TYPE_RTREFCBT
188 Examine a given realtime allocation group's free space bitmap, summary file,
189 reverse mapping btree, or reference count btree, respectively.
190
191 .PP
192 .nf
193 .B XFS_SCRUB_TYPE_UQUOTA
194 .B XFS_SCRUB_TYPE_GQUOTA
195 .fi
196 .TP
197 .B XFS_SCRUB_TYPE_PQUOTA
198 Examine all user, group, or project quota records for corruption.
199
200 .TP
201 .B XFS_SCRUB_TYPE_FSCOUNTERS
202 Examine all filesystem summary counters (free blocks, inode count, free inode
203 count) for errors.
204
205 .TP
206 .B XFS_SCRUB_TYPE_NLINKS
207 Scan all inodes in the filesystem to verify each file's link count.
208
209 .TP
210 .B XFS_SCRUB_TYPE_HEALTHY
211 Mark everything healthy after a clean scrub run.
212 This clears out all the indirect health problem markers that might remain
213 in the system.
214
215 .TP
216 .B XFS_SCRUB_TYPE_METAPATH
217 Check that a metadata directory path actually points to the active metadata
218 inode.
219 Metadata inodes are usually cached for the duration of the mount, so this
220 scrubber ensures that the same inode will still be reachable after an unmount
221 and mount cycle.
222 Discrepancies can happen if the directory or parent pointer scrubbers rebuild
223 a metadata directory but lose a link in the process.
224 The
225 .B sm_ino
226 field should be passed one of the following special values to communicate which
227 path to check:
228
229 .RS 7
230 .TP
231 .B XFS_SCRUB_METAPATH_RTDIR
232 Realtime metadata file subdirectory.
233 .TP
234 .B XFS_SCRUB_METAPATH_RTBITMAP
235 Realtime bitmap file.
236 .TP
237 .B XFS_SCRUB_METAPATH_RTSUMMARY
238 Realtime summary file.
239 .TP
240 .B XFS_SCRUB_METAPATH_QUOTADIR
241 Quota metadata file subdirectory.
242 .TP
243 .B XFS_SCRUB_METAPATH_USRQUOTA
244 User quota file.
245 .TP
246 .B XFS_SCRUB_METAPATH_GRPQUOTA
247 Group quota file.
248 .TP
249 .B XFS_SCRUB_METAPATH_PRJQUOTA
250 Project quota file.
251 .TP
252 .B XFS_SCRUB_METAPATH_RTRMAPBT
253 Realtime rmap btree file.
254 .TP
255 .B XFS_SCRUB_METAPATH_RTREFCOUNTBT
256 Realtime reference count btree file.
257 .RE
258
259 The values of
260 .I sm_agno
261 and
262 .I sm_gen
263 must be zero.
264 .RE
265
266 .PD 1
267 .PP
268 The field
269 .I sm_flags
270 control the behavior of the scrub operation and provide more information
271 about the outcome of the operation.
272 If none of the
273 .B XFS_SCRUB_OFLAG_*
274 flags are set upon return, the metadata is clean.
275 .RS 0.4i
276 .TP
277 .B XFS_SCRUB_IFLAG_REPAIR
278 If the caller sets this flag, the kernel driver will examine the
279 metadata and try to fix all problems and to optimize metadata when
280 possible.
281 If no errors occur during the repair operation, the check is performed a
282 second time to determine whether the repair succeeded.
283 If errors occur, the call returns an error status immediately.
284 .TP
285 .B XFS_SCRUB_OFLAG_CORRUPT
286 The metadata was corrupt when the call returned.
287 If
288 .B XFS_SCRUB_IFLAG_REPAIR
289 was specified, then an attempted repair failed to fix the problem.
290 Unmount the filesystem and run
291 .B xfs_repair
292 to fix the filesystem.
293 .TP
294 .B XFS_SCRUB_OFLAG_PREEN
295 The metadata is ok, but some aspect of the metadata could be optimized
296 to increase performance.
297 Call again with
298 .B XFS_SCRUB_IFLAG_REPAIR
299 to optimize the metadata.
300 .TP
301 .B XFS_SCRUB_OFLAG_XFAIL
302 Filesystem errors were encountered when accessing other metadata to
303 cross-reference the records attached to this metadata object.
304 .TP
305 .B XFS_SCRUB_OFLAG_XCORRUPT
306 Discrepancies were found when cross-referencing the records attached to
307 this metadata object against all other available metadata in the system.
308 .TP
309 .B XFS_SCRUB_OFLAG_INCOMPLETE
310 The checker was unable to complete its check of all records.
311 .TP
312 .B XFS_SCRUB_OFLAG_WARNING
313 The checker encountered a metadata object with potentially problematic
314 records.
315 However, the records were not obviously corrupt.
316 .RE
317 .PP
318 For metadata checkers that operate on inodes or inode metadata, the fields
319 .IR sm_ino " and " sm_gen
320 are the inode number and generation number of the inode to check.
321 If the inode number is zero, the inode represented by
322 .I dest_fd
323 is used instead.
324 If the generation number of the inode does not match
325 .IR sm_gen ", "
326 the call will return an error code for the invalid argument.
327 The
328 .I sm_agno
329 field must be zero.
330 .PP
331 For metadata checkers that operate on allocation group metadata, the field
332 .I sm_agno
333 indicates the allocation group in which to find the metadata.
334 The
335 .IR sm_ino " and " sm_gen
336 fields must be zero.
337 .PP
338 For metadata checkers that operate on filesystem-wide metadata, no
339 further arguments are required.
340 .IR sm_agno ", " sm_ino ", and " sm_gen
341 must all be zero.
342 .SH RETURN VALUE
343 On error, \-1 is returned, and
344 .I errno
345 is set to indicate the error.
346 .PP
347 .SH ERRORS
348 Error codes can be one of, but are not limited to, the following:
349 .TP
350 .B EBUSY
351 The filesystem object is busy; the operation will have to be tried again.
352 .TP
353 .B EFSCORRUPTED
354 Severe filesystem corruption was detected and could not be repaired.
355 Unmount the filesystem and run
356 .B xfs_repair
357 to fix the filesystem.
358 .TP
359 .B EINVAL
360 One or more of the arguments specified is invalid.
361 .TP
362 .B ENOENT
363 The specified metadata object does not exist.
364 For example, this error code is returned for a
365 .B XFS_SCRUB_TYPE_REFCNTBT
366 request on a filesystem that does not support reflink.
367 .TP
368 .B ENOMEM
369 There was not sufficient memory to perform the scrub or repair operation.
370 Some operations (most notably reference count checking) require large
371 amounts of memory.
372 .TP
373 .B ENOSPC
374 There is not enough free disk space to attempt a repair.
375 .TP
376 .B ENOTRECOVERABLE
377 Filesystem was mounted in
378 .B norecovery
379 mode and therefore has an unclean log.
380 Neither scrub nor repair operations can be attempted with an unclean
381 log.
382 .TP
383 .B ENOTTY
384 Online scrubbing or repair were not enabled.
385 .TP
386 .B EOPNOTSUPP
387 Repairs of the requested metadata object are not supported.
388 .TP
389 .B EROFS
390 Filesystem is read-only and a repair was requested.
391 .TP
392 .B ESHUTDOWN
393 Filesystem is shut down due to previous errors.
394 .SH CONFORMING TO
395 This API is specific to XFS filesystem on the Linux kernel.
396 .SH NOTES
397 These operations may block other filesystem operations for a long time.
398 A calling process can stop the operation by being sent a fatal
399 signal, but non-fatal signals are blocked.
400 .SH SEE ALSO
401 .BR ioctl (2)
402 .BR xfs_scrub (8)
403 .BR xfs_repair (8)