X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=Documentation%2Fbtrfs-filesystem.asciidoc;h=f0a9ba4dae39f915e72c220f1585d730de5e4b60;hb=d0aafc51e4d1fcfd37e80712ba7b404ddde2a7d6;hp=cefdc8ea93ddda9c9b1d9a606ebff80efaa8c74a;hpb=7ffccaf0c3b4d4979d7d74bab3d79d9541a6e665;p=platform%2Fupstream%2Fbtrfs-progs.git diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc index cefdc8e..f0a9ba4 100644 --- a/Documentation/btrfs-filesystem.asciidoc +++ b/Documentation/btrfs-filesystem.asciidoc @@ -3,7 +3,7 @@ btrfs-filesystem(8) NAME ---- -btrfs-filesystem - control btrfs filesystem +btrfs-filesystem - command group that primarily does work on the whole filesystems SYNOPSIS -------- @@ -11,14 +11,51 @@ SYNOPSIS DESCRIPTION ----------- -*btrfs filesystem* is used to do the filesystem level control jobs, including -all the regular filesystem operations like setting/getting label, -resizing, defragment. +*btrfs filesystem* is used to perform several whole filesystem level tasks, +including all the regular filesystem operations like resizing, space stats, +label setting/getting, and defragmentation. There are other whole filesystem +tasks like scrub or balance that are grouped in separate commands. SUBCOMMAND ---------- *df* [options] :: -Show space usage information for a mount point. +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 GlobalReserve is a portion of Metadata. In case the filesystem metadata is +exhausted, 'GlobalReserve/total + Metadata/used = Metadata/total'. Otherwise +there appears to be some unused space of Metadata. + `Options` + @@ -44,65 +81,127 @@ show sizes in TiB, or TB with --si If conflicting options are passed, the last one takes precedence. *defragment* [options] | [|...]:: -Defragment file data and/or directory metadata *online*. +Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer. + 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 len using '-s' and '-l' options below. -Any extent bigger than threshold given by '-t' option, will be considered -already defragged. -Use 0 to take the kernel default. +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 reflinks 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 +reflinks. ++ +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 --c:::: -compress file contents while defragmenting +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), 'lzo' or 'zstd'. Currently it's not possible to select no +compression. See also section 'EXAMPLES'. -r:::: -defragment files recursively +defragment files recursively in given directories -f:::: -flush filesystem after defragmenting +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 +accumulates from several files and will increase system load. This can also lead +to ENOSPC if there's too much dirty data to write and it's not possible to make +the reservations for the new data (ie. how the COW design works). ++ -s [kKmMgGtTpPeE]:::: -defragment only from byte onward +defragmentation will start from the given offset, default is beginning of a file -l [kKmMgGtTpPeE]:::: -defragment only up to bytes +defragment only up to 'len' bytes, default is the file size -t [kKmMgGtTpPeE]:::: -defragment only files at least bytes big +target extent size, do not touch extents bigger than 'size', default: 32M + -For , , 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. +The value is only advisory and the final size of the extents may differ, +depending on the state of the free space and fragmentation or other internal +logic. Reasonable values are from tens to hundreds of megabytes. + +*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 filesystem 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. + -WARNING: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data, -don't use it if you use snapshots, have de-duplicated your data or made -copies with `cp --reflink`. +`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. +*label* [|] []:: +Show or update the label of a filesystem. This works on a mounted filesystem or +a filesystem image. + -[|] is used to identify the filesystem. -If a newlabel optional argument is passed, the label is changed. +The 'newlabel' argument is optional. Current label is printed if the argument +is omitted. + -NOTE: the maximum allowable length shall be less than 256 chars +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 filesystem identified by for the underlying device -devid *online*. + -The devid can be found with *btrfs filesystem show* and +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 parameter specifies the new size of the filesystem. -If the prefix + or - is present the size is increased or decreased -by the quantity . -If no units are specified, the unit of the parameter defaults to -bytes. 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. +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 +unit 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 devid. +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 @@ -110,23 +209,89 @@ 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 disk cylinder as before. +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* [--mounted|--all-devices||||