[PATCH v2 5/5] man: describe the metadata scrubbing ioctl

["Darrick J. Wong" <darrick.wong@oracle.com>]

From: Darrick J. Wong <darrick.wong@oracle.com>

Document the XFS-specific metadata scrub/repair ioctl's behavior,
arguments, and side effects.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 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)