Skip to content

Commit 2ce4219

Browse files
committed
btrfs-progs: list-chunks: update help and documentation
Sync help text with current implementation (sorting, no usage nor empty options). Issue: #559 Signed-off-by: David Sterba <[email protected]>
1 parent 3d2b713 commit 2ce4219

File tree

2 files changed

+95
-12
lines changed

2 files changed

+95
-12
lines changed

Documentation/btrfs-inspect-internal.rst

+85
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,91 @@ logical-resolve [-Pvo] [-s <bufsize>] <logical> <path>
169169
-v
170170
(deprecated) alias for global *-v* option
171171

172+
list-chunks [options] <path>
173+
(needs root privileges)
174+
175+
Enumerate chunks on all devices. The chunks represent the physical
176+
range on devices (not to be confused with block groups that represent
177+
the logical ranges, but the terms are often used interchangeably).
178+
179+
Example output:
180+
181+
.. code-block:: none
182+
183+
Devid PNumber Type/profile PStart Length PEnd LNumber LStart Usage%
184+
----- ------- ----------------- --------- --------- --------- ------- --------- ------
185+
1 1 Data/single 1.00MiB 84.00MiB 85.00MiB 68 191.60GiB 62.77
186+
1 2 System/DUP 85.00MiB 32.00MiB 117.00MiB 39 140.17GiB 0.05
187+
1 3 System/DUP 117.00MiB 32.00MiB 149.00MiB 40 140.17GiB 0.05
188+
1 4 Metadata/DUP 149.00MiB 192.00MiB 341.00MiB 59 188.41GiB 45.00
189+
1 5 Metadata/DUP 341.00MiB 192.00MiB 533.00MiB 60 188.41GiB 45.00
190+
1 6 Data/single 533.00MiB 1.00GiB 1.52GiB 49 169.91GiB 72.23
191+
1 7 Data/single 1.52GiB 16.00MiB 1.54GiB 69 191.68GiB 79.83
192+
1 8 Data/single 1.54GiB 1.00GiB 2.54GiB 17 100.90GiB 46.39
193+
1 9 Data/single 2.54GiB 1.00GiB 3.54GiB 16 99.90GiB 40.68
194+
1 10 Data/single 3.54GiB 1.00GiB 4.54GiB 1 71.40GiB 62.97
195+
1 11 Data/single 4.54GiB 1.00GiB 5.54GiB 33 125.04GiB 26.00
196+
1 12 Data/single 5.54GiB 1.00GiB 6.54GiB 50 170.91GiB 60.44
197+
1 13 Data/single 6.54GiB 512.00MiB 7.04GiB 63 189.16GiB 67.34
198+
1 14 Data/single 7.04GiB 1.00GiB 8.04GiB 51 171.91GiB 70.94
199+
200+
* *Devid* -- the device id
201+
* *PNumber* -- the number of the chunk on the device (in order)
202+
* *Type/profile* -- the chunk type and profile
203+
* *PStart* -- the chunk start on the device
204+
* *Length* -- the chunk length (same for physical and logical address space)
205+
* *PEnd* -- the chunk end, effectively *PStart + Length*
206+
* *LNumber* -- the number of the chunk, in the logical address space of the whole filesystem
207+
* *LStart* -- the chunk start in the logical address space of the whole
208+
filesystem, as it's a single space it's also called *offset*
209+
* *Usage* -- chunk usage, percentage of used data/metadata of the chunk length
210+
211+
The chunks in the output can be sorted by one or more sorting criteria, evaluated
212+
as specified, in the ascending order. By default the chunks are sorted
213+
by *devid* and *pstart*, this is most convenient for single device filesystems.
214+
215+
On multi-device filesystems it's up to the user what is preferred as the layout
216+
of chunks on e.g. striped profiles (RAID0 etc) cannot be easily represented.
217+
A logical view with corresponding underlying structure would be better, but
218+
sorting by *lstart,devid* at least groups devices of the given logical
219+
range. Can be also combined with *usage*.
220+
221+
This output can provide information for balance filters.
222+
223+
``Options``
224+
225+
--sort MODE
226+
sort by a column (ascending):
227+
228+
MODE is a coma separated list of:
229+
230+
*devid* - by device id (default, with pstart)
231+
232+
*pstart* - physical start (relative to the beginning of the device)
233+
234+
*lstart* - logical offset (in the logical address space)
235+
236+
*usage* - by chunk usage (percentage)
237+
238+
*length* - by chunk length
239+
240+
--raw
241+
raw numbers in bytes, without the *B* suffix
242+
--human-readable
243+
print human friendly numbers, base 1024, this is the default
244+
--iec
245+
select the 1024 base for the following options, according to the IEC standard
246+
--si
247+
select the 1000 base for the following options, according to the SI standard
248+
--kbytes
249+
show sizes in KiB, or kB with --si
250+
--mbytes
251+
show sizes in MiB, or MB with --si
252+
--gbytes
253+
show sizes in GiB, or GB with --si
254+
--tbytes
255+
show sizes in TiB, or TB with --si
256+
172257
.. _man-inspect-map-swapfile:
173258

174259
map-swapfile [options] <file>

cmds/inspect.c

+10-12
Original file line numberDiff line numberDiff line change
@@ -691,22 +691,20 @@ static DEFINE_SIMPLE_COMMAND(inspect_min_dev_size, "min-dev-size");
691691

692692
static const char * const cmd_inspect_list_chunks_usage[] = {
693693
"btrfs inspect-internal list-chunks [options] <path>",
694-
"Show chunks (block groups) layout",
695-
"Show chunks (block groups) layout for all devices",
694+
"Enumerate chunks on all devices",
695+
"Enumerate chunks on all devices. Chunks are the physical storage tied to a device,",
696+
"striped profiles they appear multiple times for a ginve logical offset, on other",
697+
"profiles the correspondence is 1:1 or 1:N.",
696698
"",
697699
HELPINFO_UNITS_LONG,
698-
OPTLINE("--sort MODE", "sort by a column ascending (default: pstart),\n"
699-
"MODE can be one of:\n"
700-
"pstart - physical offset, grouped by device\n"
700+
OPTLINE("--sort MODE", "sort by a column (ascending):\n"
701+
"MODE is a coma separated list of:\n"
702+
"devid - by device id (default, with pstart)\n"
703+
"pstart - physical start\n"
701704
"lstart - logical offset\n"
702-
"usage - by chunk usage (implies --usage)\n"
703-
"length_p - by chunk length, secondary by physical offset\n"
704-
"length_l - by chunk length, secondary by logical offset"
705+
"usage - by chunk usage\n"
706+
"length - by chunk length"
705707
),
706-
OPTLINE("--usage", "show usage per block group (note: this can be slow)"),
707-
OPTLINE("--no-usage", "don't show usage per block group"),
708-
OPTLINE("--empty", "show empty space between block groups"),
709-
OPTLINE("--no-empty", "do not show empty space between block groups"),
710708
NULL
711709
};
712710

0 commit comments

Comments
 (0)