From patchwork Fri Sep 22 03:27:31 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 9965091 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 54176602D8 for ; Fri, 22 Sep 2017 03:27:40 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4038D28E3F for ; Fri, 22 Sep 2017 03:27:40 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 30D4429792; Fri, 22 Sep 2017 03:27:40 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0DA4628E3F for ; Fri, 22 Sep 2017 03:27:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751791AbdIVD1i (ORCPT ); Thu, 21 Sep 2017 23:27:38 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:46454 "EHLO aserp1040.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751788AbdIVD1h (ORCPT ); Thu, 21 Sep 2017 23:27:37 -0400 Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v8M3RXmi016364 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 22 Sep 2017 03:27:33 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v8M3RWN2013691 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 22 Sep 2017 03:27:33 GMT Received: from abhmp0007.oracle.com (abhmp0007.oracle.com [141.146.116.13]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id v8M3RWQ5006184; Fri, 22 Sep 2017 03:27:32 GMT Received: from localhost (/73.25.142.12) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 21 Sep 2017 20:27:32 -0700 Date: Thu, 21 Sep 2017 20:27:31 -0700 From: "Darrick J. Wong" To: linux-xfs@vger.kernel.org, Brian Foster , Dave Chinner Subject: [PATCH] man: describe the metadata scrubbing ioctl Message-ID: <20170922032731.GC5728@magnolia> References: <150595305131.18473.16572195821331601191.stgit@magnolia> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <150595305131.18473.16572195821331601191.stgit@magnolia> User-Agent: Mutt/1.5.24 (2015-08-30) X-Source-IP: userv0022.oracle.com [156.151.31.74] Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Document the XFS-specific metadata scrub/repair ioctl's behavior, arguments, and side effects. Dump this in xfsprogs for lack of a better destination. Signed-off-by: Darrick J. Wong --- man/Makefile | 2 man/man2/ioctl_xfs_scrub_metadata.2 | 298 +++++++++++++++++++++++++++++++++++ 2 files changed, 299 insertions(+), 1 deletion(-) create mode 100644 man/man2/ioctl_xfs_scrub_metadata.2 -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html 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/ioctl_xfs_scrub_metadata.2 b/man/man2/ioctl_xfs_scrub_metadata.2 new file mode 100644 index 0000000..fa1c56d --- /dev/null +++ b/man/man2/ioctl_xfs_scrub_metadata.2 @@ -0,0 +1,298 @@ +.\" 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 +.\" . +.\" %%%LICENSE_END +.TH IOCTL-XFS-SCRUB-METADATA 2 2017-09-21 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_xfs_scrub_metadata \- check XFS filesystem metadata +.SH SYNOPSIS +.br +.B #include +.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 metadata for +errors or suboptimal metadata. +Examination includes running the 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 +tie up the filesystem for a long period of time. +The type and location of the metadata is conveyed in a structure of the +following form: +.PP +.in +4n +.EX +struct xfs_scrub_metadata { + __u32 sm_type; + __u32 sm_flags; + __u64 sm_ino; + __u32 sm_gen; + __u32 sm_agno; + __u64 sm_reserved[5]; +}; +.EE +.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. +If any +.B sm_flags +output flags are set in +.BR sm_gen ", " +they will be copied to +.B sm_flags +before the call returns. + +.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 "." + +.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 free space btrees, inode btress, reverse +mapping btrees, or reference count btrees, respectively. +against the allocation group's metadata btrees, if possible. +Space extent records are checked for obviously incorrect values and +cross-referenced with the other space extent metadata to ensure that +there are no conflicts. +The allocation group number must be given in +.BR sm_agno "." + +.TP +.B XFS_SCRUB_TYPE_INODE +Examine a given inode's 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 makes +sense. +The inode to examine can 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. + +.PP +.nf +.B XFS_SCRUB_TYPE_BMBTD +.B XFS_SCRUB_TYPE_BMBTA +.fi +.TP +.B XFS_SCRUB_TYPE_BMBTC +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 checker will examine the metadata and +try to fix any problems or suboptimal metadata that it finds. +If no errors occur during the repair operation, the check is performed a +second time to determine if the repair succeeded. +If errors do 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. +.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. +.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. +.PP +For metadata checkers that operate on filesystem-wide metadata, no +further arguments are required. +.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 repair 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 a lot 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. +.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 on Linux. +.SH NOTES +These operations may tie up the filesystem for a long time. +A calling process can be stop the operation by being sent a fatal +signal, but non-fatal signals are blocked. +.SH SEE ALSO +.BR ioctl (2)