[03/27] btrfs-progs: Convert man page for filesystem subcommand.
diff mbox

Message ID 1396427378-10487-4-git-send-email-quwenruo@cn.fujitsu.com
State Accepted
Delegated to: David Sterba
Headers show

Commit Message

Qu Wenruo April 2, 2014, 8:29 a.m. UTC
Convert man page for filesystem subcommand.

Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
 Documentation/Makefile             |   2 +-
 Documentation/btrfs-filesystem.txt | 163 +++++++++++++++++++++++++++++++++++++
 2 files changed, 164 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/btrfs-filesystem.txt

diff mbox

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 15c1679..1fa2b35 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -17,7 +17,7 @@  MAN8_TXT += btrfs.txt
 # Sub commands for btrfs
 MAN8_TXT += btrfs-subvolume.txt
-#MAN8_TXT += btrfs-filesystem.txt
+MAN8_TXT += btrfs-filesystem.txt
 #MAN8_TXT += btrfs-balance.txt
 #MAN8_TXT += btrfs-device.txt
 #MAN8_TXT += btrfs-scrub.txt
diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
new file mode 100644
index 0000000..de9b3f3
--- /dev/null
+++ b/Documentation/btrfs-filesystem.txt
@@ -0,0 +1,163 @@ 
+btrfs-filesystem - control btrfs filesystem
+'btrfs filesystem' <subcommand> <args>
+'btrfs filesystem' is used to do the filesystem level control jobs, including
+all the regular filesystem operations like setting/getting label,
+resizing, defragment.
+'df' [-b] path [<path>...]::
+Show space usage information for a mount point.
+If '-b' is given, then byte is used as unit. Default unit will be
+human-readable unit such as KiB/MiB/GiB.
+The command 'btrfs filesystem df' is used to query how many space on the 
+disk(s) are used and an estimation of the free
+space of the filesystem.
+The output of the command 'btrfs filesystem df' shows:
+`Disk size`::::
+the total size of the disks which compose the filesystem.
+`Disk allocated`::::
+the size of the area of the disks used by the chunks.
+`Disk unallocated`::::
+the size of the area of the disks which is free (i.e.
+the differences of the values above).
+the portion of the logical space used by the file and metadata.
+`Free (estimated)`::::
+the estimated free space available: i.e. how many space can be used
+by the user. The evaluation cannot be rigorous because it depends by the
+allocation policy (DUP, Single, RAID1...) of the metadata and data chunks. +
+If every chunk is stored as "Single" the sum of the free (estimated) space
+and the used space  is equal to the disk size.
+Otherwise if all the chunk are mirrored (raid1 or raid10) or duplicated
+the sum of the free (estimated) space and the used space is
+half of the disk size. Normally the free (estimated) is between
+these two limits.
+`Data to disk ratio`::::
+the ratio betwen the logical size (i.e. the space available by
+the chunks) and the disk allocated (by the chunks). Normally it is 
+lower than 100% because the metadata is duplicated for security reasons.
+If all the data and metadata are duplicated (or have a profile like RAID1)
+the Data to disk ratio could be 50%.
+'show' [--mounted|--all-devices|<path>|<uuid>|<device>|<lable>]::
+Show the btrfs filesystem with some additional info.
+If no option nor <path>|<uuid>|<device>|<lable> is passed, btrfs shows
+information of all the btrfs filesystem both mounted and unmounted.
+If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
+If '--all-devices' is passed, all the devices under /dev are scanned;
+otherwise the devices list is extracted from the /proc/partitions file.
+'sync' <path>::
+Force a sync for the filesystem identified by <path>.
+'defragment' [options] <file>|<dir> [<file>|<dir>...]::
+Defragment file data and/or directory metadata *online*.
+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, and use 1 to
+say every single extent must be rewritten.
+You can also turn on compression in defragment operations.
+be verbose
+compress file contents while defragmenting
+defragment files recursively
+flush filesystem after defragmenting
+-s <start>::::
+defragment only from byte <start> onward
+-l <len>::::
+defragment only up to <len> bytes
+-t <size>::::
+defragment only files at least <size> bytes big
+For <start>, <len>, <size> it is possible to append a suffix
+like 'k' for 1 KBytes, 'm' for 1 MBytes...
+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`.
+// Some wording are extracted by the resize2fs man page
+'resize' [devid:][+/-]<size>[gkm]|[devid:]max <path>::
+Resize a filesystem identified by <path> for the underlying device
+devid *online*. +
+The devid can be found with '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, the unit of the <size> parameter defaults to
+bytes. Optionally, the size parameter may be suffixed by one of the following
+units designators: \'K\', \'M', or \'G', kilobytes, megabytes, or gigabytes,
+If \'max' is passed, the filesystem will occupy all available space on the
+device devid.
+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 disk cylinder as before.
+'label' [<dev>|<mount_point>] [newlabel]::
+Show or update the label of a filesystem.
+[<device>|<mountpoint>] is used to identify the filesystem. 
+If a newlabel optional argument is passed, the label is changed.
+NOTE: the maximum allowable length shall be less than 256 chars
+'disk-usage' [-tb] path [path...]::
+Show in which disk the chunks are allocated. +
+If '-b' is given,  set byte as unit;
+If '-t' is given, show data in tabular format.
+'btrfs filesystem' returns a zero exist status if it succeeds. Non zero is
+returned in case of failure.
+'btrfs' is part of btrfs-progs. Btrfs filesystem is currently under heavy
+and not suitable for any uses other than benchmarking and review.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.