Imported Upstream version 4.6.1

1 files changed, 182 insertions, 0 deletions

diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc
new file mode 100644
index 00000000..fb64aa4a
--- /dev/null
+++ b/Documentation/btrfs-subvolume.asciidoc
@@ -0,0 +1,182 @@
+btrfs-subvolume(8)
+==================
+
+NAME
+----
+btrfs-subvolume - control btrfs subvolume(s)
+
+SYNOPSIS
+--------
+*btrfs subvolume* <subcommand> [<args>]
+
+DESCRIPTION
+-----------
+*btrfs subvolume* is used to control the filesystem to create/delete/list/show
+subvolumes and snapshots.
+
+SUBVOLUME AND SNAPSHOT
+----------------------
+A subvolume in btrfs is not like an LVM logical volume, which is quite
+independent from each other, a btrfs subvolume has its hierarchy and relations
+between other subvolumes.
+
+A subvolume in btrfs can be accessed in two ways.
+
+1. From the parent subvolume +
+When accessing from the parent subvolume, the subvolume can be used just
+like a directory. It can have child subvolumes and its own files/directories.
+
+2. Separate mounted filesystem +
+When `mount`(8) using 'subvol' or 'subvolid' mount option, one can access
+files/directories/subvolumes inside it, but nothing in parent subvolumes.
+
+Also every btrfs filesystem has a default subvolume as its initially top-level
+subvolume, whose subvolume id is 5. (0 is also acceptable as an alias.)
+
+A btrfs snapshot is much like a subvolume, but shares its data(and metadata)
+with other subvolume/snapshot. Due to the capabilities of COW, modifications
+inside a snapshot will only show in a snapshot but not in its source subvolume.
+
+Although in btrfs, subvolumes/snapshots are treated as directories, only
+subvolume/snapshot can be the source of a snapshot, snapshot can not be made
+from normal directories.
+
+SUBCOMMAND
+-----------
+*create* [-i <qgroupid>] [<dest>]<name>::
+Create a subvolume <name> in <dest>.
++
+If <dest> is not given, subvolume <name> will be created in the current
+directory.
++
+`Options`
++
+-i <qgroupid>::::
+Add the newly created subvolume to a qgroup. This option can be given multiple
+times.
+
+*delete* [options] <subvolume> [<subvolume>...]::
+Delete the subvolume(s) from the filesystem.
++
+If <subvolume> is not a subvolume, btrfs returns an error but continues if
+there are more arguments to process.
++
+The corresponding directory is removed instantly but the data blocks are
+removed later.  The deletion does not involve full commit by default due to
+performance reasons (as a consequence, the subvolume may appear again after a
+crash).  Use one of the '--commit' options to wait until the operation is safely
+stored on the media.
++
+`Options`
++
+-c|--commit-after::::
+wait for transaction commit at the end of the operation
++
+-C|--commit-each::::
+wait for transaction commit after deleting each subvolume
+
+*find-new* <subvolume> <last_gen>::
+List the recently modified files in a subvolume, after <last_gen> ID.
+
+*get-default* <path>::
+Get the default subvolume of the filesystem <path>.
++
+The output format is similar to *subvolume list* command.
+
+*list* [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>::
+List the subvolumes present in the filesystem <path>.
++
+For every subvolume the following information is shown by default. +
+ID <ID> top level <ID> path <path> +
+where path is the relative path of the subvolume to the top level subvolume.
+The subvolume's ID may be used by the subvolume set-default command,
+or at mount time via the subvolid= option.
+If `-p` is given, then parent <ID> is added to the output between ID
+and top level. The parent's ID may be used at mount time via the
+`subvolrootid=` option.
++
+`Options`
++
+-p::::
+print parent ID.
+-a::::
+print all the subvolumes in the filesystem and distinguish between
+absolute and relative path with respect to the given <path>.
+-c::::
+print the ogeneration of the subvolume, aliases: ogen or origin generation.
+-g::::
+print the generation of the subvolume.
+-o::::
+print only subvolumes below specified <path>.
+-u::::
+print the UUID of the subvolume.
+-q::::
+print the parent uuid of subvolumes (and snapshots).
+-R::::
+print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
+-t::::
+print the result as a table.
+-s::::
+only snapshot subvolumes in the filesystem will be listed.
+-r::::
+only readonly subvolumes in the filesystem will be listed.
+-G [+|-]<value>::::
+list subvolumes in the filesystem that its generation is
+>=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is
+neither \'+' nor \'-', it means = value.
+-C [+|-]<value>::::
+list subvolumes in the filesystem that its ogeneration is
+>=, \<= or = value. The usage is the same to '-g' option.
+--sort=rootid,gen,ogen,path::::
+list subvolumes in order by specified items.
+you can add \'\+' or \'-' in front of each items, \'+' means ascending,
+\'-' means descending. The default is ascending.
++
+for --sort you can combine some items together by \',', just like
+-sort=+ogen,-gen,path,rootid.
+
+*set-default* <id> <path>::
+Set the subvolume of the filesystem <path> which is mounted as
+default.
++
+The subvolume is identified by <id>, which is returned by the *subvolume list*
+command.
+
+*show* <path>::
+Show information of a given subvolume in the <path>.
+
+*snapshot* [-r] <source> <dest>|[<dest>/]<name>::
+Create a writable/readonly snapshot of the subvolume <source> with the
+name <name> in the <dest> directory.
++
+If only <dest> is given, the subvolume will be named the basename of <source>.
+If <source> is not a subvolume, btrfs returns an error.
+If '-r' is given, the snapshot will be readonly.
+
+*sync* <path> [subvolid...]::
+Wait until given subvolume(s) are completely removed from the filesystem
+after deletion. If no subvolume id is given, wait until all current  deletion
+requests are completed, but do not wait for subvolumes deleted meanwhile.
+The status of subvolume ids is checked periodically.
++
+`Options`
++
+-s <N>::::
+sleep N seconds between checks (default: 1)
+
+EXIT STATUS
+-----------
+*btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-quota`(8),
+`btrfs-qgroup`(8),