From patchwork Wed Apr 2 08:29:14 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Qu Wenruo X-Patchwork-Id: 3927561 X-Patchwork-Delegate: dave@jikos.cz Return-Path: X-Original-To: patchwork-linux-btrfs@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 494EABF540 for ; Wed, 2 Apr 2014 08:33:00 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 3447320240 for ; Wed, 2 Apr 2014 08:32:59 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 1031120211 for ; Wed, 2 Apr 2014 08:32:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758249AbaDBIcy (ORCPT ); Wed, 2 Apr 2014 04:32:54 -0400 Received: from cn.fujitsu.com ([59.151.112.132]:16608 "EHLO heian.cn.fujitsu.com" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1758024AbaDBI2u (ORCPT ); Wed, 2 Apr 2014 04:28:50 -0400 X-IronPort-AV: E=Sophos;i="4.97,778,1389715200"; d="scan'208";a="28775297" Received: from unknown (HELO edo.cn.fujitsu.com) ([10.167.33.5]) by heian.cn.fujitsu.com with ESMTP; 02 Apr 2014 16:26:12 +0800 Received: from G08CNEXCHPEKD03.g08.fujitsu.local (localhost.localdomain [127.0.0.1]) by edo.cn.fujitsu.com (8.14.3/8.13.1) with ESMTP id s328SZCI014914 for ; Wed, 2 Apr 2014 16:28:35 +0800 Received: from adam-work.lan (10.167.226.24) by G08CNEXCHPEKD03.g08.fujitsu.local (10.167.33.89) with Microsoft SMTP Server (TLS) id 14.3.146.2; Wed, 2 Apr 2014 16:28:42 +0800 From: Qu Wenruo To: Subject: [PATCH 03/27] btrfs-progs: Convert man page for filesystem subcommand. Date: Wed, 2 Apr 2014 16:29:14 +0800 Message-ID: <1396427378-10487-4-git-send-email-quwenruo@cn.fujitsu.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1396427378-10487-1-git-send-email-quwenruo@cn.fujitsu.com> References: <1396427378-10487-1-git-send-email-quwenruo@cn.fujitsu.com> MIME-Version: 1.0 X-Originating-IP: [10.167.226.24] Sender: linux-btrfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-btrfs@vger.kernel.org X-Spam-Status: No, score=-7.5 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Convert man page for filesystem subcommand. Signed-off-by: Qu Wenruo --- Documentation/Makefile | 2 +- Documentation/btrfs-filesystem.txt | 163 +++++++++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 Documentation/btrfs-filesystem.txt 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(8) +=================== + +NAME +---- +btrfs-filesystem - control btrfs filesystem + +SYNOPSIS +-------- +'btrfs filesystem' + +DESCRIPTION +----------- +'btrfs filesystem' is used to do the filesystem level control jobs, including +all the regular filesystem operations like setting/getting label, +resizing, defragment. + +SUBCOMMAND +---------- +'df' [-b] 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). + +`Used`:::: +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||||]:: +Show the btrfs filesystem with some additional info. ++ +If no option nor ||| 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 +filesystem(s); +If '--all-devices' is passed, all the devices under /dev are scanned; +otherwise the devices list is extracted from the /proc/partitions file. + +'sync' :: +Force a sync for the filesystem identified by . + +'defragment' [options] | [|...]:: +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. ++ +`Options` ++ +-v:::: +be verbose +-c:::: +compress file contents while defragmenting +-r:::: +defragment files recursively +-f:::: +flush filesystem after defragmenting +-s :::: +defragment only from byte onward +-l :::: +defragment only up to bytes +-t :::: +defragment only files at least bytes big ++ +For , , 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:][+/-][gkm]|[devid:]max :: +Resize a filesystem identified by for the underlying device +devid *online*. + +The devid can be found with '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', or \'G', kilobytes, megabytes, or gigabytes, +respectively. ++ +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' [|] [newlabel]:: +Show or update the label of a filesystem. ++ +[|] 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. + +EXIT STATUS +----------- +'btrfs filesystem' returns a zero exist status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +'btrfs' is part of btrfs-progs. Btrfs filesystem is currently under heavy +development, +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. + +SEE ALSO +-------- +`mkfs.btrfs`(8),