Documentation/btrfs-filesystem.asciidoc

   1 btrfs-filesystem(8)
   2 ===================
   3
   4 NAME
   5 ----
   6 btrfs-filesystem - control btrfs filesystem
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs filesystem* <subcommand> <args>
  11
  12 DESCRIPTION
  13 -----------
  14 *btrfs filesystem* is used to do the filesystem level control jobs, including
  15 all the regular filesystem operations like setting/getting label,
  16 resizing, defragment.
  17
  18 SUBCOMMAND
  19 ----------
  20 *df* [options] <path>::
  21 Show space usage information for a mount point.
  22 +
  23 `Options`
  24 +
  25 -b|--raw::::
  26 raw numbers in bytes, without the 'B' suffix
  27 -h|--human-readable::::
  28 print human friendly numbers, base 1024, this is the default
  29 -H::::
  30 print human friendly numbers, base 1000
  31 --iec::::
  32 select the 1024 base for the following options, according to the IEC standard
  33 --si::::
  34 select the 1000 base for the following options, according to the SI standard
  35 -k|--kbytes::::
  36 show sizes in KiB, or kB with --si
  37 -m|--mbytes::::
  38 show sizes in MiB, or MB with --si
  39 -g|--gbytes::::
  40 show sizes in GiB, or GB with --si
  41 -t|--tbytes::::
  42 show sizes in TiB, or TB with --si
  43 +
  44 If conflicting options are passed, the last one takes precedence.
  45
  46 *defragment* [options] <file>|<dir> [<file>|<dir>...]::
  47 Defragment file data and/or directory metadata *online*.
  48 +
  49 If '-r' is passed, files in dir will be defragmented recursively.
  50 The start position and the number of bytes to defragment can be specified by
  51 start and len using '-s' and '-l' options below.
  52 Extents bigger than value given by '-t' will be skipped, otherwise this value
  53 is used as a target extent size, but is only advisory and may not be reached
  54 if the free space is too fragmented.
  55 Use 0 to take the kernel default, which is 256kB but may change in the future.
  56 You can also turn on compression in defragment operations.
  57 +
  58 WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as
  59 with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up
  60 the ref-links of CoW data (for example files copied with `cp --reflink`,
  61 snapshots or de-duplicated data).
  62 This may cause considerable increase of space usage depending on the broken up
  63 ref-links.
  64 +
  65 `Options`
  66 +
  67 -v::::
  68 be verbose
  69 -c[<algo>]::::
  70 compress file contents while defragmenting. Optional argument selects the compression
  71 algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no
  72 compression.
  73 -r::::
  74 defragment files recursively in given directories
  75 -f::::
  76 flush data for each file before going to the next file. This will limit the amount
  77 of dirty data to current file, otherwise the amount cumulates from several files
  78 and may increase system load.
  79 -s <start>[kKmMgGtTpPeE]::::
  80 defragment only from byte <start> onward
  81 -l <len>[kKmMgGtTpPeE]::::
  82 defragment only up to <len> bytes
  83 -t <size>[kKmMgGtTpPeE]::::
  84 target extent size, do not touch extents bigger than <size>
  85 +
  86 For <start>, <len>, <size> it is possible to append
  87 units designator: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
  88 KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
  89
  90 *label* [<dev>|<mountpoint>] [<newlabel>]::
  91 Show or update the label of a filesystem.
  92 +
  93 [<device>|<mountpoint>] is used to identify the filesystem.
  94 If a newlabel optional argument is passed, the label is changed.
  95 +
  96 NOTE: the maximum allowable length shall be less than 256 chars
  97
  98 // Some wording are extracted by the resize2fs man page
  99 *resize* [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>::
 100 Resize a mounted filesystem identified by directory <path>. A particular device
 101 can be resized by specifying a <devid>.
 102 +
 103 If <path> is a file containing a btrfs image then resize does not work as
 104 expected and does not resize the image. This would resize the underlying
 105 filesystem instead.
 106 +
 107 The devid can be found with *btrfs filesystem show* and
 108 defaults to 1 if not specified.
 109 The <size> parameter specifies the new size of the filesystem.
 110 If the prefix + or - is present the size is increased or decreased
 111 by the quantity <size>.
 112 If no units are specified, the unit of the <size> parameter defaults to
 113 bytes. Optionally, the size parameter may be suffixed by one of the following
 114 units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
 115 KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
 116 +
 117 If \'max' is passed, the filesystem will occupy all available space on the
 118 device devid.
 119 +
 120 The resize command does not manipulate the size of underlying
 121 partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
 122 can expand the partition before enlarging the filesystem and shrink the
 123 partition after reducing the size of the filesystem.  This can done using
 124 `fdisk`(8) or `parted`(8) to delete the existing partition and recreate
 125 it with the new desired size.  When recreating the partition make sure to use
 126 the same starting disk cylinder as before.
 127
 128 *show* [options] [<path>|<uuid>|<device>|<label>]::
 129 Show the btrfs filesystem with some additional info.
 130 +
 131 If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
 132 information of all the btrfs filesystem both mounted and unmounted.
 133 +
 134 `Options`
 135 +
 136 -m|--mounted::::
 137 probe btrfs kernel to list mounted btrfs filesystems(s)
 138 -d|--all-devices::::
 139 scan all devices under /dev, otherwise the devices list is extracted from the
 140 /proc/partitions file.
 141 --raw::::
 142 raw numbers in bytes, without the 'B' suffix
 143 --human-readable::::
 144 print human friendly numbers, base 1024, this is the default
 145 --iec::::
 146 select the 1024 base for the following options, according to the IEC standard
 147 --si::::
 148 select the 1000 base for the following options, according to the SI standard
 149 --kbytes::::
 150 show sizes in KiB, or kB with --si
 151 --mbytes::::
 152 show sizes in MiB, or MB with --si
 153 --gbytes::::
 154 show sizes in GiB, or GB with --si
 155 --tbytes::::
 156 show sizes in TiB, or TB with --si
 157
 158 *sync* <path>::
 159 Force a sync for the filesystem identified by <path>.
 160
 161 *usage* [options] <path> [<path>...]::
 162 Show detailed information about internal filesystem usage.
 163 +
 164 `Options`
 165 +
 166 -b|--raw::::
 167 raw numbers in bytes, without the 'B' suffix
 168 -h|--human-readable::::
 169 print human friendly numbers, base 1024, this is the default
 170 -H::::
 171 print human friendly numbers, base 1000
 172 --iec::::
 173 select the 1024 base for the following options, according to the IEC standard
 174 --si::::
 175 select the 1000 base for the following options, according to the SI standard
 176 -k|--kbytes::::
 177 show sizes in KiB, or kB with --si
 178 -m|--mbytes::::
 179 show sizes in MiB, or MB with --si
 180 -g|--gbytes::::
 181 show sizes in GiB, or GB with --si
 182 -t|--tbytes::::
 183 show sizes in TiB, or TB with --si
 184 -T::::
 185 show data in tabular format
 186 +
 187 If conflicting options are passed, the last one takes precedence.
 188
 189 EXIT STATUS
 190 -----------
 191 *btrfs filesystem* returns a zero exit status if it succeeds. Non zero is
 192 returned in case of failure.
 193
 194 AVAILABILITY
 195 ------------
 196 *btrfs* is part of btrfs-progs.
 197 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 198 further details.
 199
 200 SEE ALSO
 201 --------
 202 `mkfs.btrfs`(8),