HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |CONFORMING TO |NOTES |SEE ALSO |COLOPHON | |
IOCTL-XFS-...B-METADATA(2) System Calls ManualIOCTL-XFS-...B-METADATA(2)ioctl_xfs_scrub_metadata - check XFS filesystem metadata
#include <xfs/xfs_fs.h>int ioctl(intdest_fd, XFS_IOC_SCRUB_METADATA, structxfs_scrub_metadata *arg);
This XFS ioctl asks the kernel driver to examine a piece of filesystem metadata for errors or suboptimal metadata. Examination includes running metadata verifiers, checking records for obviously incorrect or impossible values, and cross- referencing each record with any other available metadata in the filesystem. This ioctl can also try to repair or optimize metadata, though this may block normal filesystem operations for a long period of time. The type and location of the metadata to scrub is conveyed in a structure of the following form: struct xfs_scrub_metadata { __u32 sm_type; __u32 sm_flags; __u64 sm_ino; __u32 sm_gen; __u32 sm_agno; __u64 sm_reserved[5]; }; The fieldsm_reserved must be zero. The fieldsm_type indicates the type of metadata to check:XFS_SCRUB_TYPE_PROBE Probe the kernel to see if it is willing to try to check or repair this filesystem.sm_agno,sm_ino, andsm_genmust be zero.XFS_SCRUB_TYPE_SBXFS_SCRUB_TYPE_AGFXFS_SCRUB_TYPE_AGFLXFS_SCRUB_TYPE_AGI Examine a given allocation group's superblock, free space header, free block list, or inode header, respectively. Headers are checked for obviously incorrect values and cross-referenced against the allocation group's metadata btrees, if possible. The allocation group number must be given insm_agno.sm_inoandsm_genmust be zero.XFS_SCRUB_TYPE_BNOBTXFS_SCRUB_TYPE_CNTBTXFS_SCRUB_TYPE_INOBTXFS_SCRUB_TYPE_FINOBTXFS_SCRUB_TYPE_RMAPBTXFS_SCRUB_TYPE_REFCNTBT Examine a given allocation group's two free space btrees, two inode btrees, reverse mapping btrees, or reference count btrees, respectively. Records are checked for obviously incorrect values and cross- referenced with other allocation group metadata records to ensure that there are no conflicts. The allocation group number must be given insm_agno.sm_inoandsm_genmust be zero.XFS_SCRUB_TYPE_RGSUPER Examine a given realtime allocation group's superblock. The realtime allocation group number must be given insm_agno.sm_ino andsm_gen must be zero.XFS_SCRUB_TYPE_INODE Examine a given inode record for obviously incorrect values and discrepancies with the rest of filesystem metadata. Parent pointers are checked for impossible inode values and are then followed up to the parent directory to ensure that the linkage is correct. The inode to examine may be specified either throughsm_ino andsm_gen; if not specified, then the file described bydest_fdwill be examined.sm_agnomust be zero.XFS_SCRUB_TYPE_BMBTDXFS_SCRUB_TYPE_BMBTAXFS_SCRUB_TYPE_BMBTC Examine a given inode's data block map, extended attribute block map, or copy on write block map. Inode records are examined for obviously incorrect values and discrepancies with the three block map types. The block maps are checked for obviously wrong values and cross-referenced with the allocation group space extent metadata for discrepancies. The inode to examine can be specified in the same manner asXFS_SCRUB_TYPE_INODE.XFS_SCRUB_TYPE_XATTR Examine the extended attribute records and indices of a given inode for incorrect pointers and other signs of damage. The inode to examine can be specified in the same manner asXFS_SCRUB_TYPE_INODE.XFS_SCRUB_TYPE_DIR Examine the entries in a given directory for invalid data or dangling pointers. If the filesystem supports directory parent pointers, each entry will be checked to confirm that the child file has a matching parent pointer. The directory to examine can be specified in the same manner asXFS_SCRUB_TYPE_INODE.XFS_SCRUB_TYPE_PARENT For filesystems that support directory parent pointers, this scrubber examines all the parent pointers attached to a file and confirms that the parent directory has an entry matching the parent pointer. For filesystems that do not support directory parent pointers, this scrubber checks that a subdirectory's dotdot entry points to a directory with an entry that points back to the subdirectory. The inode to examine can be specified in the same manner asXFS_SCRUB_TYPE_INODE.XFS_SCRUB_TYPE_DIRTREE This scrubber looks for problems in the directory tree structure such as loops and directories accessible through more than one path. Problems are detected by walking parent pointers upwards towards the root. Loops are detected by comparing the parent directory at each step against the directories already examined. Directories with multiple paths are detected by counting the parent pointers attached to a directory. Non-directories do not have links pointing away from the directory tree root and can be skipped. The directory to examine can be specified in the same manner asXFS_SCRUB_TYPE_INODE.XFS_SCRUB_TYPE_SYMLINK Examine the target of a symbolic link for obvious pathname problems. The link to examine can be specified in the same manner asXFS_SCRUB_TYPE_INODE.XFS_SCRUB_TYPE_RTBITMAPXFS_SCRUB_TYPE_RTSUMXFS_SCRUB_TYPE_RTRMAPBTXFS_SCRUB_TYPE_RTREFCBT Examine a given realtime allocation group's free space bitmap, summary file, reverse mapping btree, or reference count btree, respectively.XFS_SCRUB_TYPE_UQUOTAXFS_SCRUB_TYPE_GQUOTAXFS_SCRUB_TYPE_PQUOTA Examine all user, group, or project quota records for corruption.XFS_SCRUB_TYPE_FSCOUNTERS Examine all filesystem summary counters (free blocks, inode count, free inode count) for errors.XFS_SCRUB_TYPE_NLINKS Scan all inodes in the filesystem to verify each file's link count.XFS_SCRUB_TYPE_HEALTHY Mark everything healthy after a clean scrub run. This clears out all the indirect health problem markers that might remain in the system.XFS_SCRUB_TYPE_METAPATH Check that a metadata directory path actually points to the active metadata inode. Metadata inodes are usually cached for the duration of the mount, so this scrubber ensures that the same inode will still be reachable after an unmount and mount cycle. Discrepancies can happen if the directory or parent pointer scrubbers rebuild a metadata directory but lose a link in the process. Thesm_inofield should be passed one of the following special values to communicate which path to check:XFS_SCRUB_METAPATH_RTDIR Realtime metadata file subdirectory.XFS_SCRUB_METAPATH_RTBITMAP Realtime bitmap file.XFS_SCRUB_METAPATH_RTSUMMARY Realtime summary file.XFS_SCRUB_METAPATH_QUOTADIR Quota metadata file subdirectory.XFS_SCRUB_METAPATH_USRQUOTA User quota file.XFS_SCRUB_METAPATH_GRPQUOTA Group quota file.XFS_SCRUB_METAPATH_PRJQUOTA Project quota file.XFS_SCRUB_METAPATH_RTRMAPBT Realtime rmap btree file.XFS_SCRUB_METAPATH_RTREFCOUNTBT Realtime reference count btree file. The values ofsm_agno andsm_gen must be zero. The fieldsm_flags control the behavior of the scrub operation and provide more information about the outcome of the operation. If none of theXFS_SCRUB_OFLAG_*flags are set upon return, the metadata is clean.XFS_SCRUB_IFLAG_REPAIR If the caller sets this flag, the kernel driver will examine the metadata and try to fix all problems and to optimize metadata when possible. If no errors occur during the repair operation, the check is performed a second time to determine whether the repair succeeded. If errors occur, the call returns an error status immediately.XFS_SCRUB_OFLAG_CORRUPT The metadata was corrupt when the call returned. IfXFS_SCRUB_IFLAG_REPAIRwas specified, then an attempted repair failed to fix the problem. Unmount the filesystem and runxfs_repairto fix the filesystem.XFS_SCRUB_OFLAG_PREEN The metadata is ok, but some aspect of the metadata could be optimized to increase performance. Call again withXFS_SCRUB_IFLAG_REPAIRto optimize the metadata.XFS_SCRUB_OFLAG_XFAIL Filesystem errors were encountered when accessing other metadata to cross-reference the records attached to this metadata object.XFS_SCRUB_OFLAG_XCORRUPT Discrepancies were found when cross-referencing the records attached to this metadata object against all other available metadata in the system.XFS_SCRUB_OFLAG_INCOMPLETE The checker was unable to complete its check of all records.XFS_SCRUB_OFLAG_WARNING The checker encountered a metadata object with potentially problematic records. However, the records were not obviously corrupt. For metadata checkers that operate on inodes or inode metadata, the fieldssm_ino andsm_gen are the inode number and generation number of the inode to check. If the inode number is zero, the inode represented bydest_fd is used instead. If the generation number of the inode does not matchsm_gen, the call will return an error code for the invalid argument. Thesm_agno field must be zero. For metadata checkers that operate on allocation group metadata, the fieldsm_agno indicates the allocation group in which to find the metadata. Thesm_ino andsm_gen fields must be zero. For metadata checkers that operate on filesystem-wide metadata, no further arguments are required.sm_agno,sm_ino, andsm_gen must all be zero.On error, -1 is returned, anderrno is set to indicate the error.
Error codes can be one of, but are not limited to, the following:EBUSYThe filesystem object is busy; the operation will have to be tried again.EFSCORRUPTED Severe filesystem corruption was detected and could not be repaired. Unmount the filesystem and runxfs_repairto fix the filesystem.EINVALOne or more of the arguments specified is invalid.ENOENTThe specified metadata object does not exist. For example, this error code is returned for aXFS_SCRUB_TYPE_REFCNTBT request on a filesystem that does not support reflink.ENOMEMThere was not sufficient memory to perform the scrub or repair operation. Some operations (most notably reference count checking) require large amounts of memory.ENOSPCThere is not enough free disk space to attempt a repair.ENOTRECOVERABLE Filesystem was mounted innorecoverymode and therefore has an unclean log. Neither scrub nor repair operations can be attempted with an unclean log.ENOTTYOnline scrubbing or repair were not enabled.EOPNOTSUPP Repairs of the requested metadata object are not supported.EROFSFilesystem is read-only and a repair was requested.ESHUTDOWN Filesystem is shut down due to previous errors.
This API is specific to XFS filesystem on the Linux kernel.
These operations may block other filesystem operations for a long time. A calling process can stop the operation by being sent a fatal signal, but non-fatal signals are blocked.
ioctl(2)xfs_scrub(8)xfs_repair(8)
This page is part of thexfsprogs (utilities for XFS filesystems) project. Information about the project can be found at ⟨http://xfs.org/⟩. If you have a bug report for this manual page, send it to linux-xfs@vger.kernel.org. This page was obtained from the project's upstream Git repository ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-06-23.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgXFS 2017-12-01IOCTL-XFS-...B-METADATA(2)Pages that refer to this page:ioctl_xfs_scrubv_metadata(2), xfsctl(3)
Copyright and license for this manual page
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |