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 <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 +
 117 The resize command does not manipulate the size of underlying
 118 partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
 119 can expand the partition before enlarging the filesystem and shrink the
 120 partition after reducing the size of the filesystem.  This can done using
 121 `fdisk`(8) or `parted`(8) to delete the existing partition and recreate
 122 it with the new desired size.  When recreating the partition make sure to use
 123 the same starting disk cylinder as before.
 124
 125 *show* [options] [<path>|<uuid>|<device>|<label>]::
 126 Show the btrfs filesystem with some additional info.
 127 +
 128 If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
 129 information of all the btrfs filesystem both mounted and unmounted.
 130 +
 131 `Options`
 132 +
 133 -m|--mounted::::
 134 probe btrfs kernel to list mounted btrfs filesystems(s)
 135 -d|--all-devices::::
 136 scan all devices under /dev, otherwise the devices list is extracted from the
 137 /proc/partitions file.
 138 --raw::::
 139 raw numbers in bytes, without the 'B' suffix
 140 --human-readable::::
 141 print human friendly numbers, base 1024, this is the default
 142 --iec::::
 143 select the 1024 base for the following options, according to the IEC standard
 144 --si::::
 145 select the 1000 base for the following options, according to the SI standard
 146 --kbytes::::
 147 show sizes in KiB, or kB with --si
 148 --mbytes::::
 149 show sizes in MiB, or MB with --si
 150 --gbytes::::
 151 show sizes in GiB, or GB with --si
 152 --tbytes::::
 153 show sizes in TiB, or TB with --si
 154
 155 *sync* <path>::
 156 Force a sync for the filesystem identified by <path>.
 157
 158 *usage* [options] <path> [<path>...]::
 159 Show detailed information about internal filesystem usage.
 160 +
 161 `Options`
 162 +
 163 -b|--raw::::
 164 raw numbers in bytes, without the 'B' suffix
 165 -h|--human-readable::::
 166 print human friendly numbers, base 1024, this is the default
 167 -H::::
 168 print human friendly numbers, base 1000
 169 --iec::::
 170 select the 1024 base for the following options, according to the IEC standard
 171 --si::::
 172 select the 1000 base for the following options, according to the SI standard
 173 -k|--kbytes::::
 174 show sizes in KiB, or kB with --si
 175 -m|--mbytes::::
 176 show sizes in MiB, or MB with --si
 177 -g|--gbytes::::
 178 show sizes in GiB, or GB with --si
 179 -t|--tbytes::::
 180 show sizes in TiB, or TB with --si
 181 -T::::
 182 show data in tabular format
 183 +
 184 If conflicting options are passed, the last one takes precedence.
 185
 186 EXIT STATUS
 187 -----------
 188 *btrfs filesystem* returns a zero exit status if it succeeds. Non zero is
 189 returned in case of failure.
 190
 191 AVAILABILITY
 192 ------------
 193 *btrfs* is part of btrfs-progs.
 194 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 195 further details.
 196
 197 SEE ALSO
 198 --------
 199 `mkfs.btrfs`(8),