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>
This commit is contained in:
Christoph Anton Mitterer 2024-04-08 03:46:05 +02:00 committed by David Sterba
parent 8af90d4902
commit 5a956bb3b1

View File

@ -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
filesystems mount point (where its given for each *devid* after the string
`size` or via the :command:`btrfs inspect-internal dump-super` command on the
specific device (where its 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.