From 325256a23282e6c359561c3d7aa2cb58c33750d8 Mon Sep 17 00:00:00 2001 From: Qu Wenruo Date: Mon, 6 Aug 2018 14:00:08 +0800 Subject: [PATCH] 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 [ update ] Signed-off-by: David Sterba --- Documentation/btrfs-qgroup.asciidoc | 26 ++++++++++++++++++++++++-- 1 file 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 . + --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* :: Create a subvolume quota group. @@ -83,6 +86,10 @@ limit space exclusively assigned to this qgroup. *remove* :: Remove the relationship between child qgroup and parent qgroup in the btrfs filesystem identified by . ++ +`Options` ++ +The same as *assign* subcommand. *show* [options] :: Show all qgroups in the btrfs filesystem identified by . @@ -131,6 +138,21 @@ If multiple s is given, use comma to separate. To retrieve information after updating the state of qgroups, force sync of the filesystem identified by 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