'\" t
.\"     Title: btrfs-check
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/05/2021
.\"    Manual: Btrfs Manual
.\"    Source: Btrfs v5.10.1
.\"  Language: English
.\"
.TH "BTRFS\-CHECK" "8" "02/05/2021" "Btrfs v5\&.10\&.1" "Btrfs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
btrfs-check \- check or repair a btrfs filesystem
.SH "SYNOPSIS"
.sp
\fBbtrfs check\fR [options] \fI<device>\fR
.SH "DESCRIPTION"
.sp
The filesystem checker is used to verify structural integrity of a filesystem and attempt to repair it if requested\&. It is recommended to unmount the filesystem prior to running the check, but it is possible to start checking a mounted filesystem (see \fI\-\-force\fR)\&.
.sp
By default, \fBbtrfs check\fR will not modify the device but you can reaffirm that by the option \fI\-\-readonly\fR\&.
.sp
\fBbtrfsck\fR is an alias of \fBbtrfs check\fR command and is now deprecated\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.sp
Do not use \fI\-\-repair\fR unless you are advised to do so by a developer or an experienced user, and then only after having accepted that no \fIfsck\fR successfully repair all types of filesystem corruption\&. Eg\&. some other software or hardware bugs can fatally damage a volume\&.
.sp .5v
.RE
.sp
The structural integrity check verifies if internal filesystem objects or data structures satisfy the constraints, point to the right objects or are correctly connected together\&.
.sp
There are several cross checks that can detect wrong reference counts of shared extents, backreferences, missing extents of inodes, directory and inode connectivity etc\&.
.sp
The amount of memory required can be high, depending on the size of the filesystem, similarly the run time\&. Check the modes that can also affect that\&.
.SH "SAFE OR ADVISORY OPTIONS"
.PP
\-b|\-\-backup
.RS 4
use the first valid set of backup roots stored in the superblock
.sp
This can be combined with
\fI\-\-super\fR
if some of the superblocks are damaged\&.
.RE
.PP
\-\-check\-data\-csum
.RS 4
verify checksums of data blocks
.sp
This expects that the filesystem is otherwise OK, and is basically an offline
\fIscrub\fR
that does not repair data from spare copies\&.
.RE
.PP
\-\-chunk\-root \fI<bytenr>\fR
.RS 4
use the given offset
\fIbytenr\fR
for the chunk tree root
.RE
.PP
\-E|\-\-subvol\-extents \fI<subvolid>\fR
.RS 4
show extent state for the given subvolume
.RE
.PP
\-p|\-\-progress
.RS 4
indicate progress at various checking phases
.RE
.PP
\-Q|\-\-qgroup\-report
.RS 4
verify qgroup accounting and compare against filesystem accounting
.RE
.PP
\-r|\-\-tree\-root \fI<bytenr>\fR
.RS 4
use the given offset
\fIbytenr\fR
for the tree root
.RE
.PP
\-\-readonly
.RS 4
(default) run in read\-only mode, this option exists to calm potential panic when users are going to run the checker
.RE
.PP
\-s|\-\-super \fI<superblock>\fR
.RS 4
use \*(Aqsuperblock\(cqth superblock copy, valid values are 0, 1 or 2 if the respective superblock offset is within the device size
.sp
This can be used to use a different starting point if some of the primary superblock is damaged\&.
.RE
.PP
\-\-clear\-space\-cache v1|v2
.RS 4
completely wipe all free space cache of given type
.sp
For free space cache
\fIv1\fR, the
\fIclear_cache\fR
kernel mount option only rebuilds the free space cache for block groups that are modified while the filesystem is mounted with that option\&. Thus, using this option with
\fIv1\fR
makes it possible to actually clear the entire free space cache\&.
.sp
For free space cache
\fIv2\fR, the
\fIclear_cache\fR
kernel mount option destroys the entire free space cache\&. This option, with
\fIv2\fR
provides an alternative method of clearing the free space cache that doesn\(cqt require mounting the filesystem\&.
.RE
.PP
\-\-clear\-ino\-cache
.RS 4
remove leftover items pertaining to the deprecated inode map feature
.RE
.SH "DANGEROUS OPTIONS"
.PP
\-\-repair
.RS 4
enable the repair mode and attempt to fix problems where possible
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
there\(cqs a warning and 10 second delay when this option is run without
\fI\-\-force\fR
to give users a chance to think twice before running repair, the warnings in documentation have shown to be insufficient
.sp .5v
.RE
.RE
.PP
\-\-init\-csum\-tree
.RS 4
create a new checksum tree and recalculate checksums in all files
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Do not blindly use this option to fix checksum mismatch problems\&.
.sp .5v
.RE
.RE
.PP
\-\-init\-extent\-tree
.RS 4
build the extent tree from scratch
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Do not use unless you know what you\(cqre doing\&.
.sp .5v
.RE
.RE
.PP
\-\-mode \fI<MODE>\fR
.RS 4
select mode of operation regarding memory and IO
.sp
The
\fIMODE\fR
can be one of:
.PP
\fIoriginal\fR
.RS 4
The metadata are read into memory and verified, thus the requirements are high on large filesystems and can even lead to out\-of\-memory conditions\&. The possible workaround is to export the block device over network to a machine with enough memory\&.
.RE
.PP
\fIlowmem\fR
.RS 4
This mode is supposed to address the high memory consumption at the cost of increased IO when it needs to re\-read blocks\&. This may increase run time\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
\fIlowmem\fR
mode does not work with
\fI\-\-repair\fR
yet, and is still considered experimental\&.
.sp .5v
.RE
.RE
.RE
.PP
\-\-force
.RS 4
allow work on a mounted filesystem\&. Note that this should work fine on a quiescent or read\-only mounted filesystem but may crash if the device is changed externally, eg\&. by the kernel module\&. Repair without mount checks is not supported right now\&.
.sp
This option also skips the delay and warning in the repair mode (see
\fI\-\-repair\fR)\&.
.RE
.SH "EXIT STATUS"
.sp
\fBbtrfs check\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&.
.SH "AVAILABILITY"
.sp
\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
.SH "SEE ALSO"
.sp
\fBmkfs\&.btrfs\fR(8), \fBbtrfs\-scrub\fR(8), \fBbtrfs\-rescue\fR(8)