Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_scrubv_metadata.2

raw
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)