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