| 1 |
.\" Copyright (c) 2023-2024 Oracle. All rights reserved. |
| 2 |
.\" |
| 3 |
.\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| 4 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 5 |
.\" %%%LICENSE_END |
| 6 |
.TH IOCTL-XFS-SCRUBV-METADATA 2 2024-05-21 "XFS" |
| 7 |
.SH NAME |
| 8 |
ioctl_xfs_scrubv_metadata \- check a lot of XFS filesystem metadata |
| 9 |
.SH SYNOPSIS |
| 10 |
.br |
| 11 |
.B #include <xfs/xfs_fs.h> |
| 12 |
.PP |
| 13 |
.BI "int ioctl(int " dest_fd ", XFS_IOC_SCRUBV_METADATA, struct xfs_scrub_vec_head *" arg ); |
| 14 |
.SH DESCRIPTION |
| 15 |
This XFS ioctl asks the kernel driver to examine several pieces of filesystem |
| 16 |
metadata for errors or suboptimal metadata. |
| 17 |
Multiple scrub types can be invoked to target a single filesystem object. |
| 18 |
See |
| 19 |
.BR ioctl_xfs_scrub_metadata (2) |
| 20 |
for a discussion of metadata validation, and documentation of the various |
| 21 |
.B XFS_SCRUB_TYPE |
| 22 |
and |
| 23 |
.B XFS_SCRUB_FLAGS |
| 24 |
values referenced below. |
| 25 |
|
| 26 |
The types and location of the metadata to scrub are conveyed as a vector with |
| 27 |
a header of the following form: |
| 28 |
.PP |
| 29 |
.in +4n |
| 30 |
.nf |
| 31 |
|
| 32 |
struct xfs_scrub_vec_head { |
| 33 |
__u64 svh_ino; |
| 34 |
__u32 svh_gen; |
| 35 |
__u32 svh_agno; |
| 36 |
__u32 svh_flags; |
| 37 |
__u16 svh_rest_us; |
| 38 |
__u16 svh_nr; |
| 39 |
__u64 svh_reserved; |
| 40 |
__u64 svh_vectors; |
| 41 |
}; |
| 42 |
.fi |
| 43 |
.in |
| 44 |
.PP |
| 45 |
The field |
| 46 |
.IR svh_ino , |
| 47 |
.IR svh_gen , |
| 48 |
and |
| 49 |
.IR svh_agno |
| 50 |
correspond to the |
| 51 |
.IR sm_ino , |
| 52 |
.IR sm_gen , |
| 53 |
and |
| 54 |
.IR sm_agno |
| 55 |
fields of the regular scrub ioctl. |
| 56 |
Exactly one filesystem object can be specified in a single call. |
| 57 |
The kernel will proceed with each vector in |
| 58 |
.I svh_vectors |
| 59 |
until progress is no longer possible. |
| 60 |
|
| 61 |
The field |
| 62 |
.I svh_rest_us |
| 63 |
specifies an amount of time to pause between each scrub invocation to give |
| 64 |
the system a chance to process other requests. |
| 65 |
|
| 66 |
The field |
| 67 |
.I svh_nr |
| 68 |
specifies the number of vectors in the |
| 69 |
.I svh_vectors |
| 70 |
array. |
| 71 |
|
| 72 |
The field |
| 73 |
.I svh_vectors |
| 74 |
is a pointer to an array of |
| 75 |
.B struct xfs_scrub_vec |
| 76 |
structures. |
| 77 |
|
| 78 |
.PP |
| 79 |
The field |
| 80 |
.I svh_reserved |
| 81 |
must be zero. |
| 82 |
|
| 83 |
Each vector has the following form: |
| 84 |
.PP |
| 85 |
.in +4n |
| 86 |
.nf |
| 87 |
|
| 88 |
struct xfs_scrub_vec { |
| 89 |
__u32 sv_type; |
| 90 |
__u32 sv_flags; |
| 91 |
__s32 sv_ret; |
| 92 |
__u32 sv_reserved; |
| 93 |
}; |
| 94 |
.fi |
| 95 |
.in |
| 96 |
|
| 97 |
.PP |
| 98 |
The fields |
| 99 |
.I sv_type |
| 100 |
and |
| 101 |
.I sv_flags |
| 102 |
indicate the type of metadata to check and the behavioral changes that |
| 103 |
userspace will permit of the kernel. |
| 104 |
The |
| 105 |
.I sv_flags |
| 106 |
field will be updated upon completion of the scrub call. |
| 107 |
See the documentation of |
| 108 |
.B XFS_SCRUB_TYPE_* |
| 109 |
and |
| 110 |
.B XFS_SCRUB_[IO]FLAG_* |
| 111 |
values in |
| 112 |
.BR ioctl_xfs_scrub_metadata (2) |
| 113 |
for a detailed description of their purpose. |
| 114 |
|
| 115 |
.PP |
| 116 |
If a vector's |
| 117 |
.I sv_type |
| 118 |
field is set to the value |
| 119 |
.BR XFS_SCRUB_TYPE_BARRIER , |
| 120 |
the kernel will stop processing vectors and return to userspace if a scrubber |
| 121 |
flags corruption by setting one of the |
| 122 |
.B XFS_SCRUB_OFLAG_* |
| 123 |
values in |
| 124 |
.I sv_flags |
| 125 |
or |
| 126 |
returns an operation error in |
| 127 |
.IR sv_ret . |
| 128 |
Otherwise, the kernel returns only after processing all vectors. |
| 129 |
|
| 130 |
The |
| 131 |
.I sv_ret |
| 132 |
field is set to the return value of the scrub function. |
| 133 |
See the RETURN VALUE |
| 134 |
section of the |
| 135 |
.BR ioctl_xfs_scrub_metadata (2) |
| 136 |
manual page for more information. |
| 137 |
|
| 138 |
The |
| 139 |
.B sv_reserved |
| 140 |
field must be zero. |
| 141 |
|
| 142 |
.SH RETURN VALUE |
| 143 |
On error, \-1 is returned, and |
| 144 |
.I errno |
| 145 |
is set to indicate the error. |
| 146 |
.PP |
| 147 |
.SH ERRORS |
| 148 |
Error codes can be one of, but are not limited to, the following: |
| 149 |
.TP |
| 150 |
.B EINVAL |
| 151 |
One or more of the arguments specified is invalid. |
| 152 |
.TP |
| 153 |
.B EINTR |
| 154 |
The operation was interrupted. |
| 155 |
.TP |
| 156 |
.B ENOMEM |
| 157 |
There was not sufficient memory to perform the scrub or repair operation. |
| 158 |
.TP |
| 159 |
.B EFAULT |
| 160 |
A memory fault was encountered while reading or writing the vector. |
| 161 |
.SH CONFORMING TO |
| 162 |
This API is specific to XFS filesystem on the Linux kernel. |
| 163 |
.SH NOTES |
| 164 |
These operations may block other filesystem operations for a long time. |
| 165 |
A calling process can stop the operation by being sent a fatal |
| 166 |
signal, but non-fatal signals are blocked. |
| 167 |
.SH SEE ALSO |
| 168 |
.BR ioctl (2) |
| 169 |
.BR ioctl_xfs_scrub_metadata (2) |
| 170 |
.BR xfs_scrub (8) |
| 171 |
.BR xfs_repair (8) |