Debian Codegraph @

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

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