path: root/upstream/opensuse-leap-15-6/man2/ioctl_xfs_scrub_metadata.2

.\" Copyright (c) 2017, Oracle.  All rights reserved.
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" SPDX-License-Identifier: GPL-2.0+
.\" %%%LICENSE_END
.TH IOCTL-XFS-SCRUB-METADATA 2 2017-12-01 "XFS"
.SH NAME
ioctl_xfs_scrub_metadata \- check XFS filesystem metadata
.SH SYNOPSIS
.br
.B #include <xfs/xfs_fs.h>
.PP
.BI "int ioctl(int " dest_fd ", XFS_IOC_SCRUB_METADATA, struct xfs_scrub_metadata *" arg );
.SH DESCRIPTION
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:
.PP
.in +4n
.nf
struct xfs_scrub_metadata {
	__u32 sm_type;
	__u32 sm_flags;
	__u64 sm_ino;
	__u32 sm_gen;
	__u32 sm_agno;
	__u64 sm_reserved[5];
};
.fi
.in
.PP
The field
.I sm_reserved
must be zero.
.PP
The field
.I sm_type
indicates the type of metadata to check:
.RS 0.4i
.TP
.B XFS_SCRUB_TYPE_PROBE
Probe the kernel to see if it is willing to try to check or repair this
filesystem.
.BR sm_agno ", " sm_ino ", and " sm_gen
must be zero.

.PD 0
.PP
.nf
.B XFS_SCRUB_TYPE_SB
.B XFS_SCRUB_TYPE_AGF
.B XFS_SCRUB_TYPE_AGFL
.fi
.TP
.B 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
.BR sm_agno "."
.BR sm_ino " and " sm_gen
must be zero.

.PP
.nf
.B XFS_SCRUB_TYPE_BNOBT
.B XFS_SCRUB_TYPE_CNTBT
.B XFS_SCRUB_TYPE_INOBT
.B XFS_SCRUB_TYPE_FINOBT
.B XFS_SCRUB_TYPE_RMAPBT
.fi
.TP
.B 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
.BR sm_agno "."
.BR sm_ino " and " sm_gen
must be zero.

.TP
.B 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
.B sm_ino
and
.BR sm_gen "; "
if not specified, then the file described by
.B dest_fd
will be examined.
.B sm_agno
must be zero.

.PP
.nf
.B XFS_SCRUB_TYPE_BMBTD
.B XFS_SCRUB_TYPE_BMBTA
.B XFS_SCRUB_TYPE_BMBTC
.fi
.TP
.B 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
.BR XFS_SCRUB_TYPE_INODE "."

.TP
.B 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
.BR XFS_SCRUB_TYPE_INODE "."

.TP
.B 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
.BR XFS_SCRUB_TYPE_INODE "."

.TP
.B 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
.BR XFS_SCRUB_TYPE_INODE "."

.PP
.nf
.B XFS_SCRUB_TYPE_RTBITMAP
.fi
.TP
.B XFS_SCRUB_TYPE_RTSUM
Examine the realtime block bitmap and realtime summary inodes for
corruption.

.PP
.nf
.B XFS_SCRUB_TYPE_UQUOTA
.B XFS_SCRUB_TYPE_GQUOTA
.fi
.TP
.B XFS_SCRUB_TYPE_PQUOTA
Examine all user, group, or project quota records for corruption.

.TP
.B XFS_SCRUB_TYPE_FSCOUNTERS
Examine all filesystem summary counters (free blocks, inode count, free inode
count) for errors.
.RE

.PD 1
.PP
The field
.I sm_flags
control the behavior of the scrub operation and provide more information
about the outcome of the operation.
If none of the
.B XFS_SCRUB_OFLAG_*
flags are set upon return, the metadata is clean.
.RS 0.4i
.TP
.B 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.
.TP
.B XFS_SCRUB_OFLAG_CORRUPT
The metadata was corrupt when the call returned.
If
.B XFS_SCRUB_IFLAG_REPAIR
was specified, then an attempted repair failed to fix the problem.
Unmount the filesystem and run
.B xfs_repair
to fix the filesystem.
.TP
.B XFS_SCRUB_OFLAG_PREEN
The metadata is ok, but some aspect of the metadata could be optimized
to increase performance.
Call again with
.B XFS_SCRUB_IFLAG_REPAIR
to optimize the metadata.
.TP
.B XFS_SCRUB_OFLAG_XFAIL
Filesystem errors were encountered when accessing other metadata to
cross-reference the records attached to this metadata object.
.TP
.B 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.
.TP
.B XFS_SCRUB_OFLAG_INCOMPLETE
The checker was unable to complete its check of all records.
.TP
.B XFS_SCRUB_OFLAG_WARNING
The checker encountered a metadata object with potentially problematic
records.
However, the records were not obviously corrupt.
.RE
.PP
For metadata checkers that operate on inodes or inode metadata, the fields
.IR 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
.I dest_fd
is used instead.
If the generation number of the inode does not match
.IR sm_gen ", "
the call will return an error code for the invalid argument.
The
.I sm_agno
field must be zero.
.PP
For metadata checkers that operate on allocation group metadata, the field
.I sm_agno
indicates the allocation group in which to find the metadata.
The
.IR sm_ino " and " sm_gen
fields must be zero.
.PP
For metadata checkers that operate on filesystem-wide metadata, no
further arguments are required.
.IR sm_agno ", " sm_ino ", and " sm_gen
must all be zero.
.SH RETURN VALUE
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.PP
.SH ERRORS
Error codes can be one of, but are not limited to, the following:
.TP
.B EBUSY
The filesystem object is busy; the operation will have to be tried again.
.TP
.B EFSCORRUPTED
Severe filesystem corruption was detected and could not be repaired.
Unmount the filesystem and run
.B xfs_repair
to fix the filesystem.
.TP
.B EINVAL
One or more of the arguments specified is invalid.
.TP
.B ENOENT
The specified metadata object does not exist.
For example, this error code is returned for a
.B XFS_SCRUB_TYPE_REFCNTBT
request on a filesystem that does not support reflink.
.TP
.B 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.
.TP
.B ENOSPC
There is not enough free disk space to attempt a repair.
.TP
.B ENOTRECOVERABLE
Filesystem was mounted in
.B norecovery
mode and therefore has an unclean log.
Neither scrub nor repair operations can be attempted with an unclean
log.
.TP
.B ENOTTY
Online scrubbing or repair were not enabled.
.TP
.B EOPNOTSUPP
Repairs of the requested metadata object are not supported.
.TP
.B EROFS
Filesystem is read-only and a repair was requested.
.TP
.B ESHUTDOWN
Filesystem is shut down due to previous errors.
.SH CONFORMING TO
This API is specific to XFS filesystem on the Linux kernel.
.SH NOTES
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.
.SH SEE ALSO
.BR ioctl (2)
.BR xfs_scrub (8)
.BR xfs_repair (8)