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 `Options`
  59 +
  60 -v::::
  61 be verbose
  62 -c[<algo>]::::
  63 compress file contents while defragmenting. Optional argument selects the compression
  64 algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no
  65 compression.
  66 -r::::
  67 defragment files recursively in given directories
  68 -f::::
  69 flush data for each file before going to the next file. This will limit the amount
  70 of dirty data to current file, otherwise the amount cumulates from several files
  71 and may increase system load.
  72 -s <start>[kKmMgGtTpPeE]::::
  73 defragment only from byte <start> onward
  74 -l <len>[kKmMgGtTpPeE]::::
  75 defragment only up to <len> bytes
  76 -t <size>[kKmMgGtTpPeE]::::
  77 target extent size, do not touch extents bigger than <size>
  78 +
  79 For <start>, <len>, <size> it is possible to append
  80 units designator: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
  81 KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
  82 +
  83 WARNING: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data,
  84 don't use it if you use snapshots, have de-duplicated your data or made
  85 copies with `cp --reflink`.
  86
  87 *label* [<dev>|<mountpoint>] [<newlabel>]::
  88 Show or update the label of a filesystem.
  89 +
  90 [<device>|<mountpoint>] is used to identify the filesystem.
  91 If a newlabel optional argument is passed, the label is changed.
  92 +
  93 NOTE: the maximum allowable length shall be less than 256 chars
  94
  95 // Some wording are extracted by the resize2fs man page
  96 *resize* [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max|[<devid>:]get_min_size <path>::
  97 Resize a mounted filesystem identified by directory <path>. A particular device
  98 can be resized by specifying a <devid>.
  99 +
 100 If <path> is a file containing a btrfs image then resize does not work as
 101 expected and does not resize the image. This would resize the underlying
 102 filesystem instead.
 103 +
 104 The devid can be found with *btrfs filesystem show* and
 105 defaults to 1 if not specified.
 106 The <size> parameter specifies the new size of the filesystem.
 107 If the prefix + or - is present the size is increased or decreased
 108 by the quantity <size>.
 109 If no units are specified, the unit of the <size> parameter defaults to
 110 bytes. Optionally, the size parameter may be suffixed by one of the following
 111 units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
 112 KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
 113 +
 114 If \'max' is passed, the filesystem will occupy all available space on the
 115 device devid.
 116 If \'get_min_size' is passed, return the minimum size the device can be
 117 shrunk to, without performing any resize operation.
 118 +
 119 The resize command does not manipulate the size of underlying
 120 partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
 121 can expand the partition before enlarging the filesystem and shrink the
 122 partition after reducing the size of the filesystem.  This can done using
 123 `fdisk`(8) or `parted`(8) to delete the existing partition and recreate
 124 it with the new desired size.  When recreating the partition make sure to use
 125 the same starting disk cylinder as before.
 126
 127 *show* [options] [<path>|<uuid>|<device>|<label>]::
 128 Show the btrfs filesystem with some additional info.
 129 +
 130 If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
 131 information of all the btrfs filesystem both mounted and unmounted.
 132 +
 133 `Options`
 134 +
 135 -m|--mounted::::
 136 probe btrfs kernel to list mounted btrfs filesystems(s)
 137 -d|--all-devices::::
 138 scan all devices under /dev, otherwise the devices list is extracted from the
 139 /proc/partitions file.
 140 --raw::::
 141 raw numbers in bytes, without the 'B' suffix
 142 --human-readable::::
 143 print human friendly numbers, base 1024, this is the default
 144 --iec::::
 145 select the 1024 base for the following options, according to the IEC standard
 146 --si::::
 147 select the 1000 base for the following options, according to the SI standard
 148 --kbytes::::
 149 show sizes in KiB, or kB with --si
 150 --mbytes::::
 151 show sizes in MiB, or MB with --si
 152 --gbytes::::
 153 show sizes in GiB, or GB with --si
 154 --tbytes::::
 155 show sizes in TiB, or TB with --si
 156
 157 *sync* <path>::
 158 Force a sync for the filesystem identified by <path>.
 159
 160 *usage* [options] <path> [<path>...]::
 161 Show detailed information about internal filesystem usage.
 162 +
 163 `Options`
 164 +
 165 -b|--raw::::
 166 raw numbers in bytes, without the 'B' suffix
 167 -h|--human-readable::::
 168 print human friendly numbers, base 1024, this is the default
 169 -H::::
 170 print human friendly numbers, base 1000
 171 --iec::::
 172 select the 1024 base for the following options, according to the IEC standard
 173 --si::::
 174 select the 1000 base for the following options, according to the SI standard
 175 -k|--kbytes::::
 176 show sizes in KiB, or kB with --si
 177 -m|--mbytes::::
 178 show sizes in MiB, or MB with --si
 179 -g|--gbytes::::
 180 show sizes in GiB, or GB with --si
 181 -t|--tbytes::::
 182 show sizes in TiB, or TB with --si
 183 -T::::
 184 show data in tabular format
 185 +
 186 If conflicting options are passed, the last one takes precedence.
 187
 188 EXIT STATUS
 189 -----------
 190 *btrfs filesystem* returns a zero exit status if it succeeds. Non zero is
 191 returned in case of failure.
 192
 193 AVAILABILITY
 194 ------------
 195 *btrfs* is part of btrfs-progs.
 196 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 197 further details.
 198
 199 SEE ALSO
 200 --------
 201 `mkfs.btrfs`(8),