Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 316 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man8/btrfs-qgroup.8 b/upstream/opensuse-tumbleweed/man8/btrfs-qgroup.8
new file mode 100644
index 00000000..71718ce5
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man8/btrfs-qgroup.8
@@ -0,0 +1,316 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BTRFS-QGROUP" "8" "Feb 14, 2024" "6.7.1" "BTRFS"
+.SH NAME
+btrfs-qgroup \- control the quota group of a btrfs filesystem
+.SH SYNOPSIS
+.sp
+\fBbtrfs qgroup\fP <subcommand> <args>
+.SH DESCRIPTION
+.sp
+\fBbtrfs qgroup\fP is used to control quota group (qgroup) of a btrfs filesystem.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+To use qgroup you need to enable quota first using \fBbtrfs quota enable\fP
+command.
+.UNINDENT
+.UNINDENT
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+Qgroup is not stable yet and will impact performance in current mainline
+kernel (v4.14).
+.UNINDENT
+.UNINDENT
+.SH QGROUP
+.sp
+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.
+.sp
+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.
+.sp
+The qgroup identifiers conform to \fIlevel/id\fP where level 0 is reserved to the
+qgroups associated with subvolumes. Such qgroups are created automatically.
+.sp
+The qgroup hierarchy is built by commands \fBcreate\fP and \fBassign\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+If the qgroup of a subvolume is destroyed, quota about the subvolume will
+not be functional until qgroup \fI0/<subvolume id>\fP is created again.
+.UNINDENT
+.UNINDENT
+.SH SUBCOMMAND
+.INDENT 0.0
+.TP
+.B assign [options] <src> <dst> <path>
+Assign qgroup \fIsrc\fP as the child qgroup of \fIdst\fP in the btrfs filesystem
+identified by \fIpath\fP\&.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B  \-\-rescan
+(default since: 4.19) Automatically schedule quota rescan if the new qgroup
+assignment would lead to quota inconsistency. See \fIQUOTA RESCAN\fP for more
+information.
+.TP
+.B  \-\-no\-rescan
+Explicitly ask not to do a rescan, even if the assignment will make the quotas
+inconsistent. This may be useful for repeated calls where the rescan would add
+unnecessary overhead.
+.UNINDENT
+.TP
+.B create <qgroupid> <path>
+Create a subvolume quota group.
+.sp
+For the \fI0/<subvolume id>\fP qgroup, a qgroup can be created even before the
+subvolume is created.
+.TP
+.B destroy <qgroupid> <path>
+Destroy a qgroup.
+.sp
+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.
+.TP
+.B clear\-stale <path>
+Clear all stale qgroups whose subvolume does not exist anymore, this is the
+level 0 qgroup like 0/subvolid. Higher level qgroups are not deleted even
+if they don\(aqt have any child qgroups.
+.TP
+.B limit [options] <size>|none [<qgroupid>] <path>
+Limit the size of a qgroup to \fIsize\fP or no limit in the btrfs filesystem
+identified by \fIpath\fP\&.
+.sp
+If \fIqgroupid\fP is not given, qgroup of the subvolume identified by \fIpath\fP
+is used if possible.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B  \-c
+limit amount of data after compression. This is the default, it is currently not
+possible to turn off this option.
+.TP
+.B  \-e
+limit space exclusively assigned to this qgroup.
+.UNINDENT
+.TP
+.B remove <src> <dst> <path>
+Remove the relationship between child qgroup \fIsrc\fP and parent qgroup \fIdst\fP in
+the btrfs filesystem identified by \fIpath\fP\&.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B  \-\-rescan
+(default since: 4.19) Automatically schedule quota rescan if the removed qgroup
+relation would lead to quota inconsistency. See \fIQUOTA RESCAN\fP for more
+information.
+.TP
+.B  \-\-no\-rescan
+Explicitly ask not to do a rescan, even if the removal will make the quotas
+inconsistent. This may be useful for repeated calls where the rescan would add
+unnecessary overhead.
+.UNINDENT
+.TP
+.B show [options] <path>
+Show all qgroups in the btrfs filesystem identified by <path>.
+.sp
+\fBOptions\fP
+.INDENT 7.0
+.TP
+.B  \-p
+print parent qgroup id.
+.TP
+.B  \-c
+print child qgroup id.
+.TP
+.B  \-r
+print limit of referenced size of qgroup.
+.TP
+.B  \-e
+print limit of exclusive size of qgroup.
+.TP
+.B  \-F
+list all qgroups which impact the given path(include ancestral qgroups)
+.TP
+.B  \-f
+list all qgroups which impact the given path(exclude ancestral qgroups)
+.TP
+.B  \-\-raw
+raw numbers in bytes, without the \fIB\fP suffix.
+.TP
+.B  \-\-human\-readable
+print human friendly numbers, base 1024, this is the default
+.TP
+.B  \-\-iec
+select the 1024 base for the following options, according to the IEC standard.
+.TP
+.B  \-\-si
+select the 1000 base for the following options, according to the SI standard.
+.TP
+.B  \-\-kbytes
+show sizes in KiB, or kB with \-\-si.
+.TP
+.B  \-\-mbytes
+show sizes in MiB, or MB with \-\-si.
+.TP
+.B  \-\-gbytes
+show sizes in GiB, or GB with \-\-si.
+.TP
+.B  \-\-tbytes
+show sizes in TiB, or TB with \-\-si.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B \-\-sort=[+/\-]<attr>[,[+/\-]<attr>]...
+list qgroups in order of <attr>.
+.sp
+<attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl.
+.sp
+Prefix \fI+\fP means ascending order and \fI\-\fP means descending order of \fIattr\fP\&.
+If no prefix is given, use ascending order by default.
+.sp
+If multiple \fIattr\fP values are given, use comma to separate.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B  \-\-sync
+To retrieve information after updating the state of qgroups,
+force sync of the filesystem identified by \fIpath\fP before getting information.
+.UNINDENT
+.UNINDENT
+.SH QUOTA RESCAN
+.sp
+The rescan reads all extent sharing metadata and updates the respective qgroups
+accordingly.
+.sp
+The information consists of bytes owned exclusively (\fIexcl\fP) or shared/referred
+to (\fIrfer\fP). There\(aqs 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.
+.sp
+However there are cases where we can avoid a full rescan, if a subvolume whose
+\fIrfer\fP number equals its \fIexcl\fP number, which means all bytes are exclusively
+owned, then assigning/removing this subvolume only needs to add/subtract \fIrfer\fP
+number from its parent qgroup. This can speed up the rescan.
+.SH EXAMPLES
+.SS Make a parent group that has two quota group children
+.sp
+Given the following filesystem mounted at \fB/mnt/my\-vault\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Label: none  uuid: 60d2ab3b\-941a\-4f22\-8d1a\-315f329797b2
+       Total devices 1 FS bytes used 128.00KiB
+       devid    1 size 5.00GiB used 536.00MiB path /dev/vdb
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Enable quota and create subvolumes.  Check subvolume ids.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ cd /mnt/my\-vault
+$ btrfs quota enable .
+$ btrfs subvolume create a
+$ btrfs subvolume create b
+$ btrfs subvolume list .
+
+ID 261 gen 61 top level 5 path a
+ID 262 gen 62 top level 5 path b
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create qgroup and set limit to 10MiB.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ btrfs qgroup create 1/100 .
+$ btrfs qgroup limit 10M 1/100 .
+$ btrfs qgroup assign 0/261 1/100 .
+$ btrfs qgroup assign 0/262 1/100 .
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+And check qgroups.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ btrfs qgroup show .
+
+qgroupid         rfer         excl
+\-\-\-\-\-\-\-\-         \-\-\-\-         \-\-\-\-
+0/5          16.00KiB     16.00KiB
+0/261        16.00KiB     16.00KiB
+0/262        16.00KiB     16.00KiB
+1/100        32.00KiB     32.00KiB
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH EXIT STATUS
+.sp
+\fBbtrfs qgroup\fP returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+.SH AVAILABILITY
+.sp
+\fBbtrfs\fP is part of btrfs\-progs.  Please refer to the documentation at
+\fI\%https://btrfs.readthedocs.io\fP\&.
+.SH SEE ALSO
+.sp
+\fI\%btrfs\-quota(8)\fP,
+\fI\%btrfs\-subvolume(8)\fP,
+\fI\%mkfs.btrfs(8)\fP
+.\" Generated by docutils manpage writer.
+.