libbtrfsutil: copy in Btrfs UAPI headers

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

diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc
index cd7192c..3108457 100644 (file)
--- a/Documentation/btrfs-qgroup.asciidoc
+++ b/Documentation/btrfs-qgroup.asciidoc
@@ -11,25 +11,29 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-*btrfs qgroup* is used to control quota group(qgroup) of a btrfs filesystem.
+*btrfs qgroup* is used to control quota group (qgroup) of a btrfs filesystem.
 
-NOTE: To use qgroup, it needs to enable quota first using *btrfs quota*
+NOTE: To use qgroup you need to enable quota first using *btrfs quota enable*
 command.
 
 WARNING: Qgroup is not stable yet and will impact performance in current mainline
-kernel(v3.14 so far).
+kernel (v4.14).
 
 QGROUP
 ------
-Quota group or qgroup in btrfs has its hierarchy like subvolume.
-One subvolume/snapshot can reach its quota limits if it consumes all the quota
-assigned to it or any of the parent qgroup(s).
+Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are
+attached to subvolumes. The size limits are set per qgroup and apply when any
+limit is reached in tree that contains a given subvolume.
 
-Also for snapshot, it consumes no quota initially since all its data
-shares with its parent, so only modification in snapshot consumes quota.
+The limits are separated between shared and exclusive and reflect the extent
+ownership. For example a fresh snapshot shares almost all the blocks with the
+original subvolume, new writes to either subvolume will raise towards the
+exclusive limit.
 
-Every subvolume/snapshot will have its own qgroup with id '0/<subvolume id>'
-upon creating, but can be later destroyed by *btrfs qgroup destroy* command.
+The qgroup identifiers conform to 'level/id' where level 0 is reserved to the
+qgroups associated with subvolumes. Such qgroups are created automatically.
+
+The qgroup hierarchy is built by commands *create* and *assign*.
 
 NOTE: If the qgroup of a subvolume is destroyed, quota about the subvolume
 will not be functional until qgroup '0/<subvolume id>' is created again.
@@ -52,13 +56,13 @@ Explicitly ask not to do a rescan.
 Create a subvolume quota group.
 +
 For the '0/<subvolume id>' qgroup, a qgroup can be created even before the
-subvolume created.
+subvolume is created.
 
 *destroy* <qgroupid> <path>::
 Destroy a qgroup.
 +
-If a qgroup is no isolated,which means it is a parent or child qgroup, it
-can't be destroyed.
+If a qgroup is not isolated, meaning it is a parent or child qgroup, then it
+can only be destroyed after the relationship is removed.
 
 *limit* [options] <size>|none [<qgroupid>] <path>::
 Limit the size of a qgroup to <size> or no limit in the btrfs filesystem
@@ -122,6 +126,10 @@ Prefix \'+' means ascending order and \'-' means descending order of <attr>.
 If no prefix is given, use ascending order by default.
 +
 If multiple <attr>s is given, use comma to separate.
++
+--sync::::
+To retrieve information after updating the state of qgroups,
+force sync of the filesystem identified by <path> before getting information.
 
 EXIT STATUS
 -----------