From 3d69435ee3292b4b1db2d61c4784789d75883821 Mon Sep 17 00:00:00 2001 From: Dimitri John Ledkov Date: Tue, 26 Jul 2016 13:24:39 +0100 Subject: Imported Upstream version 4.6.1 --- Documentation/btrfs-filesystem.asciidoc | 373 ++++++++++++++++++++++++++++++++ 1 file changed, 373 insertions(+) create mode 100644 Documentation/btrfs-filesystem.asciidoc (limited to 'Documentation/btrfs-filesystem.asciidoc') diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc new file mode 100644 index 00000000..dc032faa --- /dev/null +++ b/Documentation/btrfs-filesystem.asciidoc @@ -0,0 +1,373 @@ +btrfs-filesystem(8) +=================== + +NAME +---- +btrfs-filesystem - command group of btrfs that usually work on the whole filesystem + +SYNOPSIS +-------- +*btrfs filesystem* + +DESCRIPTION +----------- +*btrfs filesystem* is used to do the whole filesystem level tasks, including +all the regular filesystem operations like resizing, space stats, label +setting/getting, and defragmentation. + +SUBCOMMAND +---------- +*df* [options] :: +Show a terse summary information about allocation of block group types of a given +mount point. The original purpose of this command was a debugging helper. The +output needs to be further interpreted and is not suitable for quick overview. ++ +-- +An example with description: + +* device size: '1.9TiB', one device, no RAID +* filesystem size: '1.9TiB' +* created with: 'mkfs.btrfs -d single -m single' +-- ++ +------------------------------ +$ btrfs filesystem df /path +Data, single: total=1.15TiB, used=1.13TiB +System, single: total=32.00MiB, used=144.00KiB +Metadata, single: total=12.00GiB, used=6.45GiB +GlobalReserve, single: total=512.00MiB, used=0.00B +------------------------------ ++ +-- +* 'Data', 'System' and 'Metadata' are separate block group types. +'GlobalReserve' is an artificial and internal emergency space, see below. +* 'single' -- the allocation profile, defined at mkfs time +* 'total' -- sum of space reserved for +all allocation profiles of the given type, ie. all Data/single. Note that it's +not total size of filesystem. +* 'used' -- sum of used space of the above, ie. file extents, metadata blocks +-- ++ +'GlobalReserve' is an artificial and internal emergency space. It is used eg. +when the filesystem is full. Its 'total' size is dynamic based on the +filesystem size, usually not larger than 512MiB, 'used' may fluctuate. ++ +The global block reserve is accounted within Metadata. In case the filesystem +metadata are exhausted, 'GlobalReserve/total + Metadata/used = Metadata/total'. ++ +`Options` ++ +-b|--raw:::: +raw numbers in bytes, without the 'B' suffix +-h|--human-readable:::: +print human friendly numbers, base 1024, this is the default +-H:::: +print human friendly numbers, base 1000 +--iec:::: +select the 1024 base for the following options, according to the IEC standard +--si:::: +select the 1000 base for the following options, according to the SI standard +-k|--kbytes:::: +show sizes in KiB, or kB with --si +-m|--mbytes:::: +show sizes in MiB, or MB with --si +-g|--gbytes:::: +show sizes in GiB, or GB with --si +-t|--tbytes:::: +show sizes in TiB, or TB with --si ++ +If conflicting options are passed, the last one takes precedence. + +*defragment* [options] | [|...]:: +Defragment file data on a mounted filesystem. ++ +If '-r' is passed, files in dir will be defragmented recursively. +The start position and the number of bytes to defragment can be specified by +start and length using '-s' and '-l' options below. +Extents bigger than value given by '-t' will be skipped, otherwise this value +is used as a target extent size, but is only advisory and may not be reached +if the free space is too fragmented. +Use 0 to take the kernel default, which is 256kB but may change in the future. +You can also turn on compression in defragment operations. ++ +WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as +with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up +the ref-links of COW data (for example files copied with `cp --reflink`, +snapshots or de-duplicated data). +This may cause considerable increase of space usage depending on the broken up +ref-links. ++ +NOTE: Directory arguments without '-r' do not defragment files recursively but will +defragment certain internal trees (extent tree and the subvolume tree). This has been +confusing and could be removed in the future. ++ +For 'start', 'len', 'size' it is possible to append +units designator: \'K', \'M', \'G', \'T', \'P', or \'E', which represent +KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). ++ +`Options` ++ +-v:::: +be verbose, print file names as they're submitted for defragmentation +-c[]:::: +compress file contents while defragmenting. Optional argument selects the compression +algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no +compression. See also section 'EXAMPLES'. +-r:::: +defragment files recursively in given directories +-f:::: +flush data for each file before going to the next file. This will limit the amount +of dirty data to current file, otherwise the amount cumulates from several files +and may increase system load. +-s [kKmMgGtTpPeE]:::: +defragmentation will start from the given offset, default is beginning of a file +-l [kKmMgGtTpPeE]:::: +defragment only up to 'len' bytes, default is the file size +-t [kKmMgGtTpPeE]:::: +target extent size, do not touch extents bigger than 'size' + +*du* [options] [..]:: +Calculate disk usage of the target files using FIEMAP. For individual +files, it will report a count of total bytes, and exclusive (not +shared) bytes. We also calculate a 'set shared' value which is +described below. ++ +Each argument to 'btrfs fi du' will have a 'set shared' value +calculated for it. We define each 'set' as those files found by a +recursive search of an argument. The 'set shared' value +then is a sum of all shared space referenced by the set. ++ +'set shared' takes into account overlapping shared extents, hence it +isn't as simple as adding up shared extents. ++ +`Options` ++ +-s|--summarize:::: +display only a total for each argument +--raw:::: +raw numbers in bytes, without the 'B' suffix. +--human-readable:::: +print human friendly numbers, base 1024, this is the default +--iec:::: +select the 1024 base for the following options, according to the IEC standard. +--si:::: +select the 1000 base for the following options, according to the SI standard. +--kbytes:::: +show sizes in KiB, or kB with --si. +--mbytes:::: +show sizes in MiB, or MB with --si. +--gbytes:::: +show sizes in GiB, or GB with --si. +--tbytes:::: +show sizes in TiB, or TB with --si. + +*label* [|] []:: +Show or update the label of a filesystem. This works on a mounted filesystem or +a filesystem image. ++ +The 'newlabel' argument is optional. Current label is printed if the the argument +is omitted. ++ +NOTE: the maximum allowable length shall be less than 256 chars and must not contain +a newline. The trailing newline is stripped automatically. + +// Some wording are extracted by the resize2fs man page +*resize* [:][+/-][kKmMgGtTpPeE]|[:]max :: +Resize a mounted filesystem identified by 'path'. A particular device +can be resized by specifying a 'devid'. ++ +WARNING: If 'path' is a file containing a BTRFS image then resize does not work +as expected and does not resize the image. This would resize the underlying +filesystem instead. ++ +The 'devid' can be found in the output of *btrfs filesystem show* and +defaults to 1 if not specified. +The 'size' parameter specifies the new size of the filesystem. +If the prefix '+' or '-' is present the size is increased or decreased +by the quantity 'size'. +If no units are specified, bytes are assumed for 'size'. +Optionally, the size parameter may be suffixed by one of the following +units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent +KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). ++ +If 'max' is passed, the filesystem will occupy all available space on the +device respecting 'devid' (remember, devid 1 by default). ++ +The resize command does not manipulate the size of underlying +partition. If you wish to enlarge/reduce a filesystem, you must make sure you +can expand the partition before enlarging the filesystem and shrink the +partition after reducing the size of the filesystem. This can done using +`fdisk`(8) or `parted`(8) to delete the existing partition and recreate +it with the new desired size. When recreating the partition make sure to use +the same starting partition offset as before. ++ +Growing is usually instant as it only updates the size. However, shrinking could +take a long time if there are data in the device area that's beyond the new +end. Relocation of the data takes time. ++ +See also section 'EXAMPLES'. + +*show* [options] [|||