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 filesystem identified by <path> for the underlying device
  93 devid *online*. +
  94 The devid can be found with *btrfs filesystem show* and
  95 defaults to 1 if not specified.
  96 The <size> parameter specifies the new size of the filesystem.
  97 If the prefix + or - is present the size is increased or decreased
  98 by the quantity <size>.
  99 If no units are specified, the unit of the <size> parameter defaults to
 100 bytes. Optionally, the size parameter may be suffixed by one of the following
 101 units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
 102 KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
 103 +
 104 If \'max' is passed, the filesystem will occupy all available space on the
 105 device devid.
 106 +
 107 The resize command does not manipulate the size of underlying
 108 partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
 109 can expand the partition before enlarging the filesystem and shrink the
 110 partition after reducing the size of the filesystem.  This can done using
 111 `fdisk`(8) or `parted`(8) to delete the existing partition and recreate
 112 it with the new desired size.  When recreating the partition make sure to use
 113 the same starting disk cylinder as before.
 114
 115 *show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
 116 Show the btrfs filesystem with some additional info.
 117 +
 118 If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
 119 information of all the btrfs filesystem both mounted and unmounted.
 120 If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
 121 filesystem(s);
 122 If '--all-devices' is passed, all the devices under /dev are scanned;
 123 otherwise the devices list is extracted from the /proc/partitions file.
 124
 125 *sync* <path>::
 126 Force a sync for the filesystem identified by <path>.
 127
 128 *usage* [options] <path> [<path>...]::
 129 Show detailed information about internal filesystem usage.
 130 +
 131 `Options`
 132 +
 133 -b|--raw::::
 134 raw numbers in bytes, without the 'B' suffix
 135 -h|--human-readable::::
 136 print human friendly numbers, base 1024, this is the default
 137 -H::::
 138 print human friendly numbers, base 1000
 139 --iec::::
 140 select the 1024 base for the following options, according to the IEC standard
 141 --si::::
 142 select the 1000 base for the following options, according to the SI standard
 143 -k|--kbytes::::
 144 show sizes in KiB, or kB with --si
 145 -m|--mbytes::::
 146 show sizes in MiB, or MB with --si
 147 -g|--gbytes::::
 148 show sizes in GiB, or GB with --si
 149 -t|--tbytes::::
 150 show sizes in TiB, or TB with --si
 151 -T::::
 152 show data in tabular format
 153 +
 154 If conflicting options are passed, the last one takes precedence.
 155
 156 EXIT STATUS
 157 -----------
 158 *btrfs filesystem* returns a zero exit status if it succeeds. Non zero is
 159 returned in case of failure.
 160
 161 AVAILABILITY
 162 ------------
 163 *btrfs* is part of btrfs-progs.
 164 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 165 further details.
 166
 167 SEE ALSO
 168 --------
 169 `mkfs.btrfs`(8),