'\" t
.\"     Title: btrfs-filesystem
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 11/22/2014
.\"    Manual: Btrfs Manual
.\"    Source: Btrfs v3.17
.\"  Language: English
.\"
.TH "BTRFS\-FILESYSTEM" "8" "11/22/2014" "Btrfs v3\&.17" "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-filesystem \- control btrfs filesystem
.SH "SYNOPSIS"
.sp
\fBbtrfs filesystem\fR \fI<subcommand>\fR \fI<args>\fR
.SH "DESCRIPTION"
.sp
\fBbtrfs filesystem\fR is used to do the filesystem level control jobs, including all the regular filesystem operations like setting/getting label, resizing, defragment\&.
.SH "SUBCOMMAND"
.PP
\fBdf\fR [options] \fI<path>\fR
.RS 4
Show space usage information for a mount point\&.
.sp
\fBOptions\fR
.PP
\-b|\-\-raw
.RS 4
raw numbers in bytes, without the
\fIB\fR
suffix
.RE
.PP
\-h
.RS 4
print human friendly numbers, base 1024, this is the default
.RE
.PP
\-H
.RS 4
print human friendly numbers, base 1000
.RE
.PP
\-\-iec
.RS 4
select the 1024 base for the following options, according to the IEC standard
.RE
.PP
\-\-si
.RS 4
select the 1000 base for the following options, according to the SI standard
.RE
.PP
\-k|\-\-kbytes
.RS 4
show sizes in KiB, or kB with \-\-si
.RE
.PP
\-m|\-\-mbytes
.RS 4
show sizes in MiB, or mB with \-\-si
.RE
.PP
\-g|\-\-gbytes
.RS 4
show sizes in GiB, or gB with \-\-si
.RE
.PP
\-t|\-\-tbytes
.RS 4
show sizes in TiB, or tB with \-\-si
.RE
.RE
.sp
If conflicting options are passed, the last one takes precedence\&.
.PP
\fBshow\fR [\-\-mounted|\-\-all\-devices|\fI<path>\fR|\fI<uuid>\fR|\fI<device>\fR|\fI<label>\fR]
.RS 4
Show the btrfs filesystem with some additional info\&.
.sp
If no option nor
\fI<path>\fR|\fI<uuid>\fR|\fI<device>\fR|\fI<label>\fR
is passed, btrfs shows information of all the btrfs filesystem both mounted and unmounted\&. If
\fI\-\-mounted\fR
is passed, it would probe btrfs kernel to list mounted btrfs filesystem(s); If
\fI\-\-all\-devices\fR
is passed, all the devices under /dev are scanned; otherwise the devices list is extracted from the /proc/partitions file\&.
.RE
.PP
\fBsync\fR \fI<path>\fR
.RS 4
Force a sync for the filesystem identified by
\fI<path>\fR\&.
.RE
.PP
\fBdefragment\fR [options] \fI<file>\fR|\fI<dir>\fR [\fI<file>\fR|\fI<dir>\fR\&...]
.RS 4
Defragment file data and/or directory metadata
\fBonline\fR\&.
.sp
If
\fI\-r\fR
is passed, files in dir will be defragmented recursively\&. The start position and the number of bytes to defragment can be specified by start and len using
\fI\-s\fR
and
\fI\-l\fR
options below\&. Any extent bigger than threshold given by
\fI\-t\fR
option, will be considered already defragged\&. Use 0 to take the kernel default\&. You can also turn on compression in defragment operations\&.
.sp
\fBOptions\fR
.PP
\-v
.RS 4
be verbose
.RE
.PP
\-c
.RS 4
compress file contents while defragmenting
.RE
.PP
\-r
.RS 4
defragment files recursively
.RE
.PP
\-f
.RS 4
flush filesystem after defragmenting
.RE
.PP
\-s \fI<start>\fR
.RS 4
defragment only from byte
\fI<start>\fR
onward
.RE
.PP
\-l \fI<len>\fR
.RS 4
defragment only up to
\fI<len>\fR
bytes
.RE
.PP
\-t \fI<size>\fR
.RS 4
defragment only files at least
\fI<size>\fR
bytes big
.sp
For
\fI<start>\fR,
\fI<len>\fR,
\fI<size>\fR
it is possible to append a suffix like
\fIk\fR
for 1 KBytes,
\fIm\fR
for 1 MBytes\&...
.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
defragmenting with kernels up to 2\&.6\&.37 will unlink COW\-ed copies of data, don\(cqt use it if you use snapshots, have de\-duplicated your data or made copies with
\fBcp \-\-reflink\fR\&.
.sp .5v
.RE
.RE
.RE
.PP
\fBresize\fR [\fI<devid>\fR:]\fI<size>\fR[gkm]|[\fI<devid>\fR:]max \fI<path>\fR
.RS 4
Resize a filesystem identified by
\fI<path>\fR
for the underlying device devid
\fBonline\fR\&.

The devid can be found with
\fBbtrfs filesystem show\fR
and defaults to 1 if not specified\&. The
\fI<size>\fR
parameter specifies the new size of the filesystem\&. If the prefix + or \- is present the size is increased or decreased by the quantity
\fI<size>\fR\&. If no units are specified, the unit of the
\fI<size>\fR
parameter defaults to bytes\&. Optionally, the size parameter may be suffixed by one of the following units designators: \*(AqK\*(Aq, \*(AqM\*(Aq, or \*(AqG\*(Aq, kilobytes, megabytes, or gigabytes, respectively\&.
.sp
If \*(Aqmax\*(Aq is passed, the filesystem will occupy all available space on the device devid\&.
.sp
The resize command does not manipulate the size of underlying partition\&. If you wish to enlarge/reduce a filesystem, you must make sure you can expand the partition before enlarging the filesystem and shrink the partition after reducing the size of the filesystem\&. This can done using
\fBfdisk\fR(8) or
\fBparted\fR(8) to delete the existing partition and recreate it with the new desired size\&. When recreating the partition make sure to use the same starting disk cylinder as before\&.
.RE
.PP
\fBlabel\fR [\fI<dev>\fR|\fI<mountpoint>\fR] [\fI<newlabel>\fR]
.RS 4
Show or update the label of a filesystem\&.
.sp
[\fI<device>\fR|\fI<mountpoint>\fR] is used to identify the filesystem\&. If a newlabel optional argument is passed, the label is changed\&. NOTE: the maximum allowable length shall be less than 256 chars
.RE
.SH "EXIT STATUS"
.sp
\fBbtrfs filesystem\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),