ioctl_xfs_scrub_metadata(2) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON

IOCTL-XFS-...B-METADATA(2) System Calls ManualIOCTL-XFS-...B-METADATA(2)

NAME         top

       ioctl_xfs_scrub_metadata - check XFS filesystem metadata

SYNOPSIS         top

       #include <xfs/xfs_fs.h>

       int ioctl(int dest_fd, XFS_IOC_SCRUB_METADATA, struct
       xfs_scrub_metadata *arg);

DESCRIPTION         top

       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 field sm_reserved must be zero.

       The field sm_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, and
                  sm_gen must be zero.

           XFS_SCRUB_TYPE_SB
           XFS_SCRUB_TYPE_AGF
           XFS_SCRUB_TYPE_AGFL
           XFS_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 in sm_agno.
                  sm_ino and sm_gen must be zero.

           XFS_SCRUB_TYPE_BNOBT
           XFS_SCRUB_TYPE_CNTBT
           XFS_SCRUB_TYPE_INOBT
           XFS_SCRUB_TYPE_FINOBT
           XFS_SCRUB_TYPE_RMAPBT
           XFS_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 in sm_agno.
                  sm_ino and sm_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 through
                  sm_ino and sm_gen; if not specified, then the file
                  described by dest_fd will be examined.  sm_agno must
                  be zero.

           XFS_SCRUB_TYPE_BMBTD
           XFS_SCRUB_TYPE_BMBTA
           XFS_SCRUB_TYPE_BMBTC
           XFS_SCRUB_TYPE_PARENT
                  Examine a given inode's data block map, extended
                  attribute block map, copy on write block map, or
                  parent inode pointer.  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 as XFS_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 as XFS_SCRUB_TYPE_INODE.

           XFS_SCRUB_TYPE_DIR
                  Examine the entries in a given directory for invalid
                  data or dangling pointers.  The directory to examine
                  can be specified in the same manner as
                  XFS_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 as XFS_SCRUB_TYPE_INODE.

           XFS_SCRUB_TYPE_RTBITMAP
           XFS_SCRUB_TYPE_RTSUM
                  Examine the realtime block bitmap and realtime summary
                  inodes for corruption.

           XFS_SCRUB_TYPE_UQUOTA
           XFS_SCRUB_TYPE_GQUOTA
           XFS_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.

       The field sm_flags control the behavior of the scrub operation
       and provide more information about the outcome of the operation.
       If none of the XFS_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.  If
                  XFS_SCRUB_IFLAG_REPAIR was specified, then an
                  attempted repair failed to fix the problem.  Unmount
                  the filesystem and run xfs_repair to 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 with XFS_SCRUB_IFLAG_REPAIR to 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 fields sm_ino and sm_gen are the inode number and generation
       number of the inode to check.  If the inode number is zero, the
       inode represented by dest_fd is used instead.  If the generation
       number of the inode does not match sm_gen, the call will return
       an error code for the invalid argument.  The sm_agno field must
       be zero.

       For metadata checkers that operate on allocation group metadata,
       the field sm_agno indicates the allocation group in which to find
       the metadata.  The sm_ino and sm_gen fields must be zero.

       For metadata checkers that operate on filesystem-wide metadata,
       no further arguments are required.  sm_agno, sm_ino, and sm_gen
       must all be zero.

RETURN VALUE         top

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

ERRORS         top

       Error codes can be one of, but are not limited to, the following:

       EBUSY  The 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 run xfs_repair to
              fix the filesystem.

       EINVAL One or more of the arguments specified is invalid.

       ENOENT The specified metadata object does not exist.  For
              example, this error code is returned for a
              XFS_SCRUB_TYPE_REFCNTBT request on a filesystem that does
              not support reflink.

       ENOMEM There was not sufficient memory to perform the scrub or
              repair operation.  Some operations (most notably reference
              count checking) require large amounts of memory.

       ENOSPC There is not enough free disk space to attempt a repair.

       ENOTRECOVERABLE
              Filesystem was mounted in norecovery mode and therefore
              has an unclean log.  Neither scrub nor repair operations
              can be attempted with an unclean log.

       ENOTTY Online scrubbing or repair were not enabled.

       EOPNOTSUPP
              Repairs of the requested metadata object are not
              supported.

       EROFS  Filesystem is read-only and a repair was requested.

       ESHUTDOWN
              Filesystem is shut down due to previous errors.

CONFORMING TO         top

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

NOTES         top

       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.

SEE ALSO         top

       ioctl(2) xfs_scrub(8) xfs_repair(8)

COLOPHON         top

       This page is part of the xfsprogs (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 [email protected].  This page was obtained
       from the project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-05-17.)  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 is not part of the original
       manual page), send a mail to [email protected]

XFS                            2017-12-01     IOCTL-XFS-...B-METADATA(2)

Pages that refer to this page: xfsctl(3)