btrfs-progs: docs: how to get the length of the portion used by btrfs on a device

A user who wants to shrink a btrfs filesystem within some other logical
device (like a partition) will likely want to adapt the size of the
underlying device, too.

This commit adds documentation that describes how the length of the
portion that btrfs uses of some device can be found out.

Thanks go out to Roman Mamedov <rm@romanrm.net> for hinting `btrfs
filesystem show` as alternative command.

Note: the granularity is one sectorsize and the input values are
silently rounded down to avoid bugs from converted filesystems that
would not adhere to the native btrfs constraints.

[ci skip]

Pull-request: #775
Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
Signed-off-by: David Sterba <dsterba@suse.com>

1 files changed, 10 insertions, 1 deletions

diff --git a/Documentation/btrfs-filesystem.rst b/Documentation/btrfs-filesystem.rst
index 5b4fdbfa..207f7b02 100644
--- a/Documentation/btrfs-filesystem.rst
+++ b/Documentation/btrfs-filesystem.rst
@@ -251,11 +251,20 @@ resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>
         The resize command does not manipulate the size of underlying
         partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
         expand the partition before enlarging the filesystem and shrink the
-        partition after reducing the size of the filesystem.  This can done using
+        partition after reducing the size of the filesystem.  This can be done using
         :manref:`fdisk(8)` or :manref:`parted(8)` to delete the existing partition and recreate
         it with the new desired size.  When recreating the partition make sure to use
         the same starting partition offset as before.
 
+        The size of the portion that the filesystem uses of an underlying device can be
+        determined via the :command:`btrfs filesystem show --raw` command on the
+        filesystem’s mount point (where it’s given for each *devid* after the string
+        `size` or via the :command:`btrfs inspect-internal dump-super` command on the
+        specific device (where it’s given as the value of `dev_item.total_bytes`, which
+        is not to be confused with `total_bytes`).
+        The value is also the address of the first byte not used by the
+        filesystem.
+
         Growing is usually instant as it only updates the size. However, shrinking could
         take a long time if there are data in the device area that's beyond the new
         end. Relocation of the data takes time.