btrfs-progs: Update README and other docs

[platform/upstream/btrfs-progs.git] / Documentation / btrfs-filesystem.asciidoc

diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc
index 86652ff..9782af9 100644 (file)
--- a/Documentation/btrfs-filesystem.asciidoc
+++ b/Documentation/btrfs-filesystem.asciidoc
@@ -11,9 +11,10 @@ SYNOPSIS
 
 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.
+*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
+taks like scrub or balance that are grouped in separate commands.
 
 SUBCOMMAND
 ----------
@@ -97,6 +98,14 @@ 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::::
@@ -108,23 +117,58 @@ 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.
+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 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 <start>[kKmMgGtTpPeE]::::
 defragmentation will start from the given offset, default is beginning of a file
 -l <len>[kKmMgGtTpPeE]::::
 defragment only up to 'len' bytes, default is the file size
 -t <size>[kKmMgGtTpPeE]::::
-target extent size, do not touch extents bigger than 'size'
+target extent size, do not touch extents bigger than 'size', default: 32M
 +
-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).
+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] <path> [<path>..]::
+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.
 +
-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.
+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* [<dev>|<mountpoint>] [<newlabel>]::
 Show or update the label of a filesystem. This works on a mounted filesystem or