From: Darrick J. Wong <darrick.wong@xxxxxxxxxx> Document the XFS-specific metadata scrub/repair ioctl's behavior, arguments, and side effects. Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx> --- man/Makefile | 2 man/man2/Makefile | 22 ++ man/man2/ioctl_xfs_scrub_metadata.2 | 318 +++++++++++++++++++++++++++++++++++ 3 files changed, 341 insertions(+), 1 deletion(-) create mode 100644 man/man2/Makefile create mode 100644 man/man2/ioctl_xfs_scrub_metadata.2 diff --git a/man/Makefile b/man/Makefile index 863284c..cae891f 100644 --- a/man/Makefile +++ b/man/Makefile @@ -5,7 +5,7 @@ TOPDIR = .. include $(TOPDIR)/include/builddefs -SUBDIRS = man3 man5 man8 +SUBDIRS = man2 man3 man5 man8 default : $(SUBDIRS) diff --git a/man/man2/Makefile b/man/man2/Makefile new file mode 100644 index 0000000..8aecde3 --- /dev/null +++ b/man/man2/Makefile @@ -0,0 +1,22 @@ +# +# Copyright (c) 2000-2001 Silicon Graphics, Inc. All Rights Reserved. +# + +TOPDIR = ../.. +include $(TOPDIR)/include/builddefs + +MAN_SECTION = 2 + +MAN_PAGES = $(shell echo *.$(MAN_SECTION)) +MAN_DEST = $(PKG_MAN_DIR)/man$(MAN_SECTION) +LSRCFILES = $(MAN_PAGES) + +default : $(MAN_PAGES) + +include $(BUILDRULES) + +install : + +install-dev : default + $(INSTALL) -m 755 -d $(MAN_DEST) + $(INSTALL_MAN) diff --git a/man/man2/ioctl_xfs_scrub_metadata.2 b/man/man2/ioctl_xfs_scrub_metadata.2 new file mode 100644 index 0000000..a0403e6 --- /dev/null +++ b/man/man2/ioctl_xfs_scrub_metadata.2 @@ -0,0 +1,318 @@ +.\" Copyright (c) 2017, Oracle. All rights reserved. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" <http://www.gnu.org/licenses/>. +.\" %%%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. +.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) -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
