1IOCTL-XFS-SCRUB-METADATA(2) System Calls Manual IOCTL-XFS-SCRUB-METADATA(2)
2
6 ioctl_xfs_scrub_metadata - check XFS filesystem metadata
7
9 #include <xfs/xfs_fs.h>
10 int ioctl(int dest_fd, XFS_IOC_SCRUB_METADATA, struct xfs_scrub_meta‐
12 data *arg);
13
15 This XFS ioctl asks the kernel driver to examine a piece of filesystem
16 metadata for errors or suboptimal metadata. Examination includes run‐
17 ning metadata verifiers, checking records for obviously incorrect or
18 impossible values, and cross-referencing each record with any other
19 available metadata in the filesystem. This ioctl can also try to
20 repair or optimize metadata, though this may block normal filesystem
21 operations for a long period of time. The type and location of the
22 metadata to scrub is conveyed in a structure of the following form:
23 struct xfs_scrub_metadata {
25 __u32 sm_type;
26 __u32 sm_flags;
27 __u64 sm_ino;
28 __u32 sm_gen;
29 __u32 sm_agno;
30 __u64 sm_reserved[5];
31 };
32 The field sm_reserved must be zero.
34 The field sm_type indicates the type of metadata to check:
36 XFS_SCRUB_TYPE_PROBE
38 Probe the kernel to see if it is willing to try to check or
39 repair this filesystem. sm_agno, sm_ino, and sm_gen must be
40 zero.
41 XFS_SCRUB_TYPE_SB
43 XFS_SCRUB_TYPE_AGF
44 XFS_SCRUB_TYPE_AGFL
45 XFS_SCRUB_TYPE_AGI
46 Examine a given allocation group's superblock, free space
47 header, free block list, or inode header, respectively.
48 Headers are checked for obviously incorrect values and
49 cross-referenced against the allocation group's metadata
50 btrees, if possible. The allocation group number must be
51 given in sm_agno. sm_ino and sm_gen must be zero.
52 XFS_SCRUB_TYPE_BNOBT
54 XFS_SCRUB_TYPE_CNTBT
55 XFS_SCRUB_TYPE_INOBT
56 XFS_SCRUB_TYPE_FINOBT
57 XFS_SCRUB_TYPE_RMAPBT
58 XFS_SCRUB_TYPE_REFCNTBT
59 Examine a given allocation group's two free space btrees,
60 two inode btrees, reverse mapping btrees, or reference count
61 btrees, respectively. Records are checked for obviously
62 incorrect values and cross-referenced with other allocation
63 group metadata records to ensure that there are no con‐
64 flicts. The allocation group number must be given in
65 sm_agno. sm_ino and sm_gen must be zero.
66 XFS_SCRUB_TYPE_INODE
68 Examine a given inode record for obviously incorrect values
69 and discrepancies with the rest of filesystem metadata.
70 Parent pointers are checked for impossible inode values and
71 are then followed up to the parent directory to ensure that
72 the linkage is correct. The inode to examine may be speci‐
73 fied either through sm_ino and sm_gen; if not specified,
74 then the file described by dest_fd will be examined.
75 sm_agno must be zero.
76 XFS_SCRUB_TYPE_BMBTD
78 XFS_SCRUB_TYPE_BMBTA
79 XFS_SCRUB_TYPE_BMBTC
80 XFS_SCRUB_TYPE_PARENT
81 Examine a given inode's data block map, extended attribute
82 block map, copy on write block map, or parent inode pointer.
83 Inode records are examined for obviously incorrect values
84 and discrepancies with the three block map types. The block
85 maps are checked for obviously wrong values and cross-refer‐
86 enced with the allocation group space extent metadata for
87 discrepancies. The inode to examine can be specified in the
88 same manner as XFS_SCRUB_TYPE_INODE.
89 XFS_SCRUB_TYPE_XATTR
91 Examine the extended attribute records and indices of a
92 given inode for incorrect pointers and other signs of dam‐
93 age. The inode to examine can be specified in the same man‐
94 ner as XFS_SCRUB_TYPE_INODE.
95 XFS_SCRUB_TYPE_DIR
97 Examine the entries in a given directory for invalid data or
98 dangling pointers. The directory to examine can be speci‐
99 fied in the same manner as XFS_SCRUB_TYPE_INODE.
100 XFS_SCRUB_TYPE_SYMLINK
102 Examine the target of a symbolic link for obvious pathname
103 problems. The link to examine can be specified in the same
104 manner as XFS_SCRUB_TYPE_INODE.
105 XFS_SCRUB_TYPE_RTBITMAP
107 XFS_SCRUB_TYPE_RTSUM
108 Examine the realtime block bitmap and realtime summary
109 inodes for corruption.
110 XFS_SCRUB_TYPE_UQUOTA
112 XFS_SCRUB_TYPE_GQUOTA
113 XFS_SCRUB_TYPE_PQUOTA
114 Examine all user, group, or project quota records for cor‐
115 ruption.
116 XFS_SCRUB_TYPE_FSCOUNTERS
118 Examine all filesystem summary counters (free blocks, inode
119 count, free inode count) for errors.
120 The field sm_flags control the behavior of the scrub operation and pro‐
123 vide more information about the outcome of the operation. If none of
124 the XFS_SCRUB_OFLAG_* flags are set upon return, the metadata is clean.
125 XFS_SCRUB_IFLAG_REPAIR
127 If the caller sets this flag, the kernel driver will examine
128 the metadata and try to fix all problems and to optimize
129 metadata when possible. If no errors occur during the
130 repair operation, the check is performed a second time to
131 determine whether the repair succeeded. If errors occur,
132 the call returns an error status immediately.
133 XFS_SCRUB_OFLAG_CORRUPT
135 The metadata was corrupt when the call returned. If
136 XFS_SCRUB_IFLAG_REPAIR was specified, then an attempted
137 repair failed to fix the problem. Unmount the filesystem
138 and run xfs_repair to fix the filesystem.
139 XFS_SCRUB_OFLAG_PREEN
141 The metadata is ok, but some aspect of the metadata could be
142 optimized to increase performance. Call again with
143 XFS_SCRUB_IFLAG_REPAIR to optimize the metadata.
144 XFS_SCRUB_OFLAG_XFAIL
146 Filesystem errors were encountered when accessing other
147 metadata to cross-reference the records attached to this
148 metadata object.
149 XFS_SCRUB_OFLAG_XCORRUPT
151 Discrepancies were found when cross-referencing the records
152 attached to this metadata object against all other available
153 metadata in the system.
154 XFS_SCRUB_OFLAG_INCOMPLETE
156 The checker was unable to complete its check of all records.
157 XFS_SCRUB_OFLAG_WARNING
159 The checker encountered a metadata object with potentially
160 problematic records. However, the records were not obvi‐
161 ously corrupt.
162 For metadata checkers that operate on inodes or inode metadata, the
164 fields sm_ino and sm_gen are the inode number and generation number of
165 the inode to check. If the inode number is zero, the inode represented
166 by dest_fd is used instead. If the generation number of the inode does
167 not match sm_gen, the call will return an error code for the invalid
168 argument. The sm_agno field must be zero.
169 For metadata checkers that operate on allocation group metadata, the
171 field sm_agno indicates the allocation group in which to find the meta‐
172 data. The sm_ino and sm_gen fields must be zero.
173 For metadata checkers that operate on filesystem-wide metadata, no fur‐
175 ther arguments are required. sm_agno, sm_ino, and sm_gen must all be
176 zero.
177
179 On error, -1 is returned, and errno is set to indicate the error.
180
182 Error codes can be one of, but are not limited to, the following:
183 EBUSY The filesystem object is busy; the operation will have to be
185 tried again.
186 EFSCORRUPTED
188 Severe filesystem corruption was detected and could not be
189 repaired. Unmount the filesystem and run xfs_repair to fix the
190 filesystem.
191 EINVAL One or more of the arguments specified is invalid.
193 ENOENT The specified metadata object does not exist. For example, this
195 error code is returned for a XFS_SCRUB_TYPE_REFCNTBT request on
196 a filesystem that does not support reflink.
197 ENOMEM There was not sufficient memory to perform the scrub or repair
199 operation. Some operations (most notably reference count check‐
200 ing) require large amounts of memory.
201 ENOSPC There is not enough free disk space to attempt a repair.
203 ENOTRECOVERABLE
205 Filesystem was mounted in norecovery mode and therefore has an
206 unclean log. Neither scrub nor repair operations can be
207 attempted with an unclean log.
208 ENOTTY Online scrubbing or repair were not enabled.
210 EOPNOTSUPP
212 Repairs of the requested metadata object are not supported.
213 EROFS Filesystem is read-only and a repair was requested.
215 ESHUTDOWN
217 Filesystem is shut down due to previous errors.
218
220 This API is specific to XFS filesystem on the Linux kernel.
221
223 These operations may block other filesystem operations for a long time.
224 A calling process can stop the operation by being sent a fatal signal,
225 but non-fatal signals are blocked.
226
228 ioctl(2) xfs_scrub(8) xfs_repair(8)
229XFS 2017-12-01 IOCTL-XFS-SCRUB-METADATA(2)