Debian Codegraph @

upstream/debian-unstable/man8/btrfs-check.8

raw
1 .\" Man page generated from reStructuredText
2 .\" by the Docutils 0.22.4 manpage writer.
3 .
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .TH "BTRFS-CHECK" "8" "May 10, 2026" "7.0" "BTRFS"
32 .SH NAME
33 btrfs-check \- check or repair a btrfs filesystem
34 .SH SYNOPSIS
35 .sp
36 \fBbtrfs check\fP [options] <device>
37 .SH DESCRIPTION
38 .sp
39 The filesystem checker is used to verify structural integrity of a filesystem
40 and attempt to repair it if requested. It is recommended to unmount the
41 filesystem prior to running the check, but it is possible to start checking a
42 mounted filesystem (see \-\-force).
43 .sp
44 By default, \fBbtrfs check\fP will not modify the device but you can reaffirm that
45 by the option \fI\-\-readonly\fP\&.
46 .sp
47 \fBbtrfsck\fP is an alias of \fBbtrfs check\fP command and is now deprecated.
48 .sp
49 \fBNote:\fP
50 .INDENT 0.0
51 .INDENT 3.5
52 Even though the filesystem checker requires a device argument, it scans for all
53 devices belonging to the same filesystem, thus it should not cause a difference
54 using different devices of the same filesystem.
55 Furthermore btrfs\-check(8) \%<> will automatically choose the good mirror, thus as long
56 as there is a good copy for metadata, it will not report such case as an error.
57 .UNINDENT
58 .UNINDENT
59 .sp
60 \fBWarning:\fP
61 .INDENT 0.0
62 .INDENT 3.5
63 Do not use \fI\-\-repair\fP unless you are advised to do so by a developer
64 or an experienced user, and then only after having accepted that no \fIfsck\fP
65 successfully repair all types of filesystem corruption. E.g. some other software
66 or hardware bugs can fatally damage a volume.
67 .UNINDENT
68 .UNINDENT
69 .sp
70 The structural integrity check verifies if internal filesystem objects or
71 data structures satisfy the constraints, point to the right objects or are
72 correctly connected together.
73 .sp
74 There are several cross checks that can detect wrong reference counts of shared
75 extents, backreferences, missing extents of inodes, directory and inode
76 connectivity etc.
77 .sp
78 The amount of memory required can be high, depending on the size of the
79 filesystem, similarly the run time. Check the modes that can also affect that.
80 .SH SAFE OR ADVISORY OPTIONS
81 .INDENT 0.0
82 .TP
83 .B \-b|\-\-backup
84 use the first valid set of backup roots stored in the superblock
85 .sp
86 This can be combined with \fI\-\-super\fP if some of the superblocks are damaged.
87 .UNINDENT
88 .INDENT 0.0
89 .TP
90 .B \-\-check\-data\-csum
91 verify checksums of data blocks
92 .sp
93 This expects that the filesystem is otherwise OK, and is basically an offline
94 \fIscrub\fP that does not repair data from spare copies.
95 .TP
96 .BI \-\-chunk\-root \ <bytenr>
97 use the given offset \fIbytenr\fP for the chunk tree root
98 .UNINDENT
99 .INDENT 0.0
100 .TP
101 .B \-E|\-\-subvol\-extents <subvolid>
102 show extent state for the given subvolume
103 .UNINDENT
104 .INDENT 0.0
105 .TP
106 .BI \-\-mode \ <MODE>
107 select mode of operation regarding memory and IO
108 .sp
109 The \fIMODE\fP can be one of:
110 .INDENT 7.0
111 .TP
112 .B original
113 The metadata are read into memory and verified, thus the requirements are high
114 on large filesystems and can even lead to out\-of\-memory conditions. The
115 possible workaround is to export the block device over network to a machine
116 with enough memory.
117 .TP
118 .B lowmem
119 This mode is supposed to address the high memory consumption at the cost of
120 increased IO when it needs to re\-read blocks. This may increase run time.
121 .UNINDENT
122 .UNINDENT
123 .INDENT 0.0
124 .TP
125 .B \-p|\-\-progress
126 indicate progress at various checking phases
127 .TP
128 .B \-Q|\-\-qgroup\-report
129 verify qgroup accounting and compare against filesystem accounting
130 .TP
131 .B \-r|\-\-tree\-root <bytenr>
132 use the given offset \(aqbytenr\(aq for the tree root
133 .UNINDENT
134 .INDENT 0.0
135 .TP
136 .B \-\-readonly
137 (default)
138 run in read\-only mode, this option exists to calm potential panic when users
139 are going to run the checker
140 .UNINDENT
141 .INDENT 0.0
142 .TP
143 .B \-s|\-\-super <N>
144 use Nth superblock copy, valid values are 0, 1 or 2 if the
145 respective superblock offset is within the device size
146 .sp
147 This can be used to use a different starting point if some of the primary
148 superblock is damaged.
149 .UNINDENT
150 .SH DANGEROUS OPTIONS
151 .INDENT 0.0
152 .TP
153 .B \-\-repair
154 enable the repair mode and attempt to fix problems where possible
155 .sp
156 \fBNote:\fP
157 .INDENT 7.0
158 .INDENT 3.5
159 There\(aqs a warning and 10 second delay when this option is run without
160 \fI\-\-force\fP to give users a chance to think twice before running repair, the
161 warnings in documentation have shown to be insufficient.
162 .UNINDENT
163 .UNINDENT
164 .sp
165 \fBNote:\fP
166 .INDENT 7.0
167 .INDENT 3.5
168 Please finish/cancel the running replace/balance before using this command.
169 .UNINDENT
170 .UNINDENT
171 .TP
172 .B \-\-init\-csum\-tree
173 create a new checksum tree and recalculate checksums in all files
174 .sp
175 \fBWarning:\fP
176 .INDENT 7.0
177 .INDENT 3.5
178 Do not blindly use this option to fix checksum mismatch problems.
179 .UNINDENT
180 .UNINDENT
181 .TP
182 .B \-\-init\-extent\-tree
183 build the extent tree from scratch
184 .sp
185 \fBWarning:\fP
186 .INDENT 7.0
187 .INDENT 3.5
188 Do not use unless you know what you\(aqre doing.
189 .UNINDENT
190 .UNINDENT
191 .UNINDENT
192 .INDENT 0.0
193 .TP
194 .B \-\-force
195 allow work on a mounted filesystem and skip mount checks. Note that
196 this should work fine on a quiescent or read\-only mounted filesystem
197 but may crash if the device is changed externally, e.g. by the kernel
198 module.
199 .sp
200 \fBNote:\fP
201 .INDENT 7.0
202 .INDENT 3.5
203 It is possible to run with \-\-repair but on a mounted filesystem
204 that will most likely lead to a corruption unless the filesystem
205 is in a quiescent state which may not be possible to guarantee.
206 .UNINDENT
207 .UNINDENT
208 .sp
209 This option also skips the delay and warning in the repair mode (see
210 \fI\-\-repair\fP).
211 .UNINDENT
212 .SH DEPRECATED OR REMOVED OPTIONS
213 .INDENT 0.0
214 .TP
215 .B \-\-clear\-space\-cache v1|v2
216 completely remove the free space cache of the given version
217 .sp
218 See also the \fIclear_cache\fP mount option.
219 .sp
220 \fBWarning:\fP
221 .INDENT 7.0
222 .INDENT 3.5
223 This option is deprecated, please use \fIbtrfs rescue clear\-space\-cache\fP
224 instead, this option would be removed in the future eventually.
225 .UNINDENT
226 .UNINDENT
227 .UNINDENT
228 .SH EXIT STATUS
229 .sp
230 \fBbtrfs check\fP returns a zero exit status if it succeeds. Non zero is
231 returned in case of failure.
232 .SH AVAILABILITY
233 .sp
234 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
235 \%<https://\:btrfs\:.readthedocs\:.io>\&.
236 .SH SEE ALSO
237 .sp
238 mkfs.btrfs(8) \%<>,
239 btrfs\-scrub(8) \%<>,
240 btrfs\-rescue(8) \%<>
241 .\" End of generated man page.