btrfs-progs: Fix typos in docs and user-facing strings

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

diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
index c456898..536243b 100644 (file)
--- a/Documentation/btrfs-balance.asciidoc
+++ b/Documentation/btrfs-balance.asciidoc
@@ -21,8 +21,8 @@ filesystem.
 The balance operation is cancellable by the user. The on-disk state of the
 filesystem is always consistent so an unexpected interruption (eg. system crash,
 reboot) does not corrupt the filesystem. The progress of the balance operation
 The balance operation is cancellable by the user. The on-disk state of the
 filesystem is always consistent so an unexpected interruption (eg. system crash,
 reboot) does not corrupt the filesystem. The progress of the balance operation

-is temporarily stored and will be resumed upon mount, unless the mount option
-'skip_balance' is specified.
+is temporarily stored as an internal state and will be resumed upon mount,
+unless the mount option 'skip_balance' is specified.

 
 WARNING: running balance without filters will take a lot of time as it basically
 rewrites the entire filesystem and needs to update all block pointers.
 
 WARNING: running balance without filters will take a lot of time as it basically
 rewrites the entire filesystem and needs to update all block pointers.


@@ -45,29 +45,27 @@ COMPATIBILITY
 
 NOTE: The balance subcommand also exists under the *btrfs filesystem*
 namespace. This still works for backward compatibility but is deprecated and
 
 NOTE: The balance subcommand also exists under the *btrfs filesystem*
 namespace. This still works for backward compatibility but is deprecated and

-should not be used anymore.
+should not be used any more.

 
 NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility
 
 NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility

-but is deprecated and should not be used anymore. Use *btrfs balance start*
+but is deprecated and should not be used any more. Use *btrfs balance start*

 command instead.
 
 PERFORMANCE IMPLICATIONS
 ------------------------
 
 command instead.
 
 PERFORMANCE IMPLICATIONS
 ------------------------
 

-Balance operation is intense namely in the IO respect, but can be also CPU
-intense. It affects other actions on the filesystem. There are typically lots
-of data being copied from one location to another, and lots of metadata get
-updated.
+Balancing operations are very IO intensive and can also be quite CPU intensive,
+impacting other ongoing filesystem operations. Typically large amounts of data
+are copied from one location to another, with corresponding metadata updates.

 
 

-Depending on the actual block group layout, it can be also seek-heavy. The
-performance on rotational devices is noticeably worse than on SSDs or fast
-arrays.
+Depending upon the block group layout, it can also be seek heavy. Performance
+on rotational devices is noticeably worse compared to SSDs or fast arrays.

 
 SUBCOMMAND
 ----------
 *cancel* <path>::
 
 SUBCOMMAND
 ----------
 *cancel* <path>::

-cancel running or paused balance, the command will block and wait until the
-actually processed blockgroup is finished
+cancels a running or paused balance, the command will block and wait until the
+current blockgroup being processed completes

 
 *pause* <path>::
 pause running balance operation, this will store the state of the balance
 
 *pause* <path>::
 pause running balance operation, this will store the state of the balance


@@ -89,7 +87,7 @@ warned and has a few seconds to cancel the operation before it starts. The
 warning and delay can be skipped with '--full-balance' option.
 +
 Please note that the filters must be written together with the '-d', '-m' and
 warning and delay can be skipped with '--full-balance' option.
 +
 Please note that the filters must be written together with the '-d', '-m' and

-'-s' options, because they're optional and bare '-d' etc alwo work and mean no
+'-s' options, because they're optional and bare '-d' etc also work and mean no

 filters.
 +
 `Options`
 filters.
 +
 `Options`


@@ -143,7 +141,7 @@ The minimum range boundary is inclusive, maximum is exclusive.
 
 *devid=<id>*::
 Balances only block groups which have at least one chunk on the given
 
 *devid=<id>*::
 Balances only block groups which have at least one chunk on the given

-device. To list devices with ids use *btrfs fi show*.
+device. To list devices with ids use *btrfs filesystem show*.

 
 *drange=<range>*::
 Balance only block groups which overlap with the given byte range on any
 
 *drange=<range>*::
 Balance only block groups which overlap with the given byte range on any


@@ -203,10 +201,11 @@ ENOSPC
 ------
 
 The way balance operates, it usually needs to temporarily create a new block
 ------
 
 The way balance operates, it usually needs to temporarily create a new block

-group and move the old data there. For that it needs work space, otherwise
-it fails for ENOSPC reasons.
+group and move the old data there, before the old block group can be removed.
+For that it needs the work space, otherwise it fails for ENOSPC reasons.

 This is not the same ENOSPC as if the free space is exhausted. This refers to
 This is not the same ENOSPC as if the free space is exhausted. This refers to

-the space on the level of block groups.
+the space on the level of block groups, which are bigger parts of the filesystem
+that contain many file extents.

 
 The free work space can be calculated from the output of the *btrfs filesystem show*
 command:
 
 The free work space can be calculated from the output of the *btrfs filesystem show*
 command:


@@ -229,7 +228,7 @@ space. After that it might be possible to run other filters.
 
 Conversion to profiles based on striping (RAID0, RAID5/6) require the work
 space on each device. An interrupted balance may leave partially filled block
 
 Conversion to profiles based on striping (RAID0, RAID5/6) require the work
 space on each device. An interrupted balance may leave partially filled block

-groups that might consume the work space.
+groups that consume the work space.

 
 EXAMPLES
 --------
 
 EXAMPLES
 --------


@@ -240,14 +239,14 @@ can be found in section 'TYPICAL USECASES' of `btrfs-device`(8).
 MAKING BLOCK GROUP LAYOUT MORE COMPACT
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MAKING BLOCK GROUP LAYOUT MORE COMPACT
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-The layout of block groups is not normally visible, most tools report only
+The layout of block groups is not normally visible; most tools report only

 summarized numbers of free or used space, but there are still some hints
 provided.
 
 Let's use the following real life example and start with the output:
 
 --------------------
 summarized numbers of free or used space, but there are still some hints
 provided.
 
 Let's use the following real life example and start with the output:
 
 --------------------

-$ btrfs fi df /path
+$ btrfs filesystem df /path

 Data, single: total=75.81GiB, used=64.44GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.84GiB
 Data, single: total=75.81GiB, used=64.44GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.84GiB


@@ -273,7 +272,7 @@ data and thus will be faster. A typical filter command would look like:
 # btrfs balance start -dusage=50 /path
 Done, had to relocate 2 out of 97 chunks
 
 # btrfs balance start -dusage=50 /path
 Done, had to relocate 2 out of 97 chunks
 

-$ btrfs fi df /path
+$ btrfs filesystem df /path

 Data, single: total=74.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.84GiB
 Data, single: total=74.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.84GiB


@@ -288,7 +287,7 @@ usage filter.
 # btrfs balance start -dusage=85 /path
 Done, had to relocate 13 out of 95 chunks
 
 # btrfs balance start -dusage=85 /path
 Done, had to relocate 13 out of 95 chunks
 

-$ btrfs fi df /path
+$ btrfs filesystem df /path

 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.85GiB
 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.85GiB


@@ -300,7 +299,7 @@ data to the remaining blockgroups, ie. the 6GiB are now free of filesystem
 structures, and can be reused for new data or metadata block groups.
 
 We can do a similar exercise with the metadata block groups, but this should
 structures, and can be reused for new data or metadata block groups.
 
 We can do a similar exercise with the metadata block groups, but this should

-not be typically necessary, unless the used/total ration is really off. Here
+not typically be necessary, unless the used/total ratio is really off. Here

 the ratio is roughly 50% but the difference as an absolute number is "a few
 gigabytes", which can be considered normal for a workload with snapshots or
 reflinks updated frequently.
 the ratio is roughly 50% but the difference as an absolute number is "a few
 gigabytes", which can be considered normal for a workload with snapshots or
 reflinks updated frequently.


@@ -309,7 +308,7 @@ reflinks updated frequently.
 # btrfs balance start -musage=50 /path
 Done, had to relocate 4 out of 89 chunks
 
 # btrfs balance start -musage=50 /path
 Done, had to relocate 4 out of 89 chunks
 

-$ btrfs fi df /path
+$ btrfs filesystem df /path

 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=14.87GiB, used=8.85GiB
 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=14.87GiB, used=8.85GiB


@@ -327,7 +326,7 @@ further compaction:
 # btrfs balance start -musage=70 /path
 Done, had to relocate 13 out of 88 chunks
 
 # btrfs balance start -musage=70 /path
 Done, had to relocate 13 out of 88 chunks
 

-$ btrfs fi df .
+$ btrfs filesystem df .

 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=11.97GiB, used=8.83GiB
 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=11.97GiB, used=8.83GiB


@@ -351,7 +350,7 @@ can be used to reclaim unused block groups to make it available.
 # btrfs balance start -dusage=0 /path
 --------------------
 
 # btrfs balance start -dusage=0 /path
 --------------------
 

-This should lead to decrease in the 'total' numbers in the *btrfs fi df* output.
+This should lead to decrease in the 'total' numbers in the *btrfs filesystem df* output.

 
 EXIT STATUS
 -----------
 
 EXIT STATUS
 -----------