diff options
Diffstat (limited to 'upstream/archlinux/man2/ioctl_xfs_scrub_metadata.2')
| -rw-r--r-- | upstream/archlinux/man2/ioctl_xfs_scrub_metadata.2 | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/upstream/archlinux/man2/ioctl_xfs_scrub_metadata.2 b/upstream/archlinux/man2/ioctl_xfs_scrub_metadata.2 new file mode 100644 index 00000000..046e3e36 --- /dev/null +++ b/upstream/archlinux/man2/ioctl_xfs_scrub_metadata.2 @@ -0,0 +1,306 @@ +.\" 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) |