diff options
author | Qu Wenruo <wqu@suse.com> | 2018-08-06 14:00:08 +0800 |
---|---|---|
committer | David Sterba <dsterba@suse.com> | 2018-10-31 18:24:14 +0100 |
commit | 325256a23282e6c359561c3d7aa2cb58c33750d8 (patch) | |
tree | b6a914dae6b01be55921ba1979a38088f017bf5a | |
parent | dda84b8a162a0bfb85a9b81376579c7b48ef73d0 (diff) |
btrfs-progs: doc: Update btrfs-qgroup regarding the rescan conditions
Add a new section, QUOTA RESCAN, to explain why and when we need a full
quota rescan when assigning/removing qgroup relationship.
Also, since 'remove' shares the same options of 'assign', add reference
to 'assign' options for 'remove' subcommand.
Signed-off-by: Qu Wenruo <wqu@suse.com>
[ update ]
Signed-off-by: David Sterba <dsterba@suse.com>
-rw-r--r-- | Documentation/btrfs-qgroup.asciidoc | 26 |
1 files changed, 24 insertions, 2 deletions
diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc index ad10f04d..dff08674 100644 --- a/Documentation/btrfs-qgroup.asciidoc +++ b/Documentation/btrfs-qgroup.asciidoc @@ -48,9 +48,12 @@ identified by <path>. + --rescan:::: (default since: 4.19) Automatically schedule quota rescan if the new qgroup -assignment would lead to quota inconsistency. +assignment would lead to quota inconsistency. See 'QUOTA RESCAN' for more +information. --no-rescan:::: -Explicitly ask not to do a rescan. +Explicitly ask not to do a rescan, even if the assignment will make the quotas +inconsitent. This may be useful for repeated calls where the rescan would add +unnecessary overhead. *create* <qgroupid> <path>:: Create a subvolume quota group. @@ -83,6 +86,10 @@ limit space exclusively assigned to this qgroup. *remove* <src> <dst> <path>:: Remove the relationship between child qgroup <src> and parent qgroup <dst> in the btrfs filesystem identified by <path>. ++ +`Options` ++ +The same as *assign* subcommand. *show* [options] <path>:: Show all qgroups in the btrfs filesystem identified by <path>. @@ -131,6 +138,21 @@ If multiple <attr>s is given, use comma to separate. To retrieve information after updating the state of qgroups, force sync of the filesystem identified by <path> before getting information. +QUOTA RESCAN +------------ +The rescan reads all extent sharing metadata and updates the respective qgoups +accordingly. + +The information consists of bytes owned exclusively ('excl') or shared/referred +to ('rfer'). There's no explicit information about which extents are shared or +owned exclusively. This means when qgroup relationship changes, extent owners +change and qgroup numbers are no longer consistent unless we do a full rescan. + +However there are cases where we can avoid a full rescan, if a subvolume whose +'rfer' number equals its 'excl' number, which means all bytes are exclusively +owned, then assigning/removing this subvolume only needs to add/subtract 'rfer' +number from its parent qgroup. This can speed up the rescan. + EXIT STATUS ----------- *btrfs qgroup* returns a zero exit status if it succeeds. Non zero is |