1IOCTL-XFS-SCRUB-METADATA(2)   System Calls Manual  IOCTL-XFS-SCRUB-METADATA(2)
2
3
4

NAME

6       ioctl_xfs_scrub_metadata - check XFS filesystem metadata
7

SYNOPSIS

9       #include <xfs/xfs_fs.h>
10
11       int  ioctl(int  dest_fd, XFS_IOC_SCRUB_METADATA, struct xfs_scrub_meta‐
12       data *arg);
13

DESCRIPTION

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
24           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
33       The field sm_reserved must be zero.
34
35       The field sm_type indicates the type of metadata to check:
36
37           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
42           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
53           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
67           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
77           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
90           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
96           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
101           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
106           XFS_SCRUB_TYPE_RTBITMAP
107           XFS_SCRUB_TYPE_RTSUM
108                  Examine  the  realtime  block  bitmap  and  realtime summary
109                  inodes for corruption.
110
111           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
117           XFS_SCRUB_TYPE_FSCOUNTERS
118                  Examine  all filesystem summary counters (free blocks, inode
119                  count, free inode count) for errors.
120
121
122       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
126           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
134           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
140           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
145           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
150           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
155           XFS_SCRUB_OFLAG_INCOMPLETE
156                  The checker was unable to complete its check of all records.
157
158           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
163       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
170       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
174       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

RETURN VALUE

179       On error, -1 is returned, and errno is set to indicate the error.
180

ERRORS

182       Error codes can be one of, but are not limited to, the following:
183
184       EBUSY  The  filesystem  object  is  busy; the operation will have to be
185              tried again.
186
187       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
192       EINVAL One or more of the arguments specified is invalid.
193
194       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
198       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
202       ENOSPC There is not enough free disk space to attempt a repair.
203
204       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
209       ENOTTY Online scrubbing or repair were not enabled.
210
211       EOPNOTSUPP
212              Repairs of the requested metadata object are not supported.
213
214       EROFS  Filesystem is read-only and a repair was requested.
215
216       ESHUTDOWN
217              Filesystem is shut down due to previous errors.
218

CONFORMING TO

220       This API is specific to XFS filesystem on the Linux kernel.
221

NOTES

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

SEE ALSO

228       ioctl(2) xfs_scrub(8) xfs_repair(8)
229
230
231
232XFS                               2017-12-01       IOCTL-XFS-SCRUB-METADATA(2)
Impressum