Merging upstream version 2.40.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 54 insertions, 4 deletions

diff --git a/misc-utils/lsblk.8.adoc b/misc-utils/lsblk.8.adoc
index d4b13f2..577ff71 100644
--- a/misc-utils/lsblk.8.adoc
+++ b/misc-utils/lsblk.8.adoc
@@ -20,9 +20,11 @@ lsblk - list block devices
 
 By default, the command prints all block devices (except RAM disks) in a tree-like format. The same device can be repeated in the tree if it relates to other devices. The *--merge* option is recommended for more complicated setups to gather groups of devices and describe complex N:M relationships.
 
+The tree-like output (or *children[]* array in the JSON output) is enabled only if NAME column it present in the output or when *--tree* command line option is used. See also *--nodeps* and *--list* to control the tree formatting.
+
 The default output, as well as the default output from options like *--fs* and *--topology*, is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using *--output* _columns-list_ and *--list* in environments where a stable output is required.
 
-Use *lsblk --help* to get a list of all available columns.
+Use *lsblk --list-columns* to get a list of all available columns.
 
 Note that *lsblk* might be executed in time when *udev* does not have all information about recently added or modified devices yet. In this case it is recommended to use *udevadm settle* before *lsblk* to synchronize with udev.
 
@@ -39,6 +41,9 @@ Disable all built-in filters and list all empty devices and RAM disk devices too
 *-b*, *--bytes*::
 include::man-common/in-bytes.adoc[]
 
+*-H*, *--list-columns*::
+List the available columns, use with *--json* or *--raw* to get output in machine-readable format.
+
 *-D*, *--discard*::
 Print information about the discarding capabilities (TRIM, UNMAP) for each device.
 
@@ -63,7 +68,7 @@ Include devices specified by the comma-separated _list_ of major device numbers.
 Use ASCII characters for tree formatting.
 
 *-J*, *--json*::
-Use JSON output format. It's strongly recommended to use *--output* and also *--tree* if necessary.
+Use JSON output format. It's strongly recommended to use *--output* and also *--tree* if necessary. Note that *children[]* is used only if NAME column or *--tree* is used.
 
 *-l*, *--list*::
 Produce output in the form of a list. The output does not provide information about relationships between devices and since version 2.34 every device is printed only once if *--pairs* or *--raw* not specified (the parsable outputs are maintained in backwardly compatible way).
@@ -84,7 +89,7 @@ Output info about virtio devices only.
 Do not print a header line.
 
 *-o*, *--output* _list_::
-Specify which output columns to print. Use *--help* to get a list of all supported columns. The columns may affect tree-like output. The default is to use tree for the column 'NAME' (see also *--tree*).
+Specify which output columns to print. Use *--list-columns* to get a list of all supported columns. The columns may affect tree-like output. The default is to use tree for the column 'NAME' (see also *--tree*).
 +
 The default list of columns may be extended if _list_ is specified in the format _+list_ (e.g., *lsblk -o +UUID*).
 
@@ -97,6 +102,50 @@ Produce output in the form of key="value" pairs. The output lines are still orde
 *-p*, *--paths*::
 Print full device paths.
 
+*-Q*, *--filter* _expr_::
+Print only the devices that meet the conditions specified by the expr. The
+filter is assessed prior to lsblk collecting data for all output columns. Only
+the necessary data for the lazy evaluation of the expression is retrieved from
+the system. This approach can enhance performance when compared to
+post-filtering, as commonly done by tools such as grep(1).
++
+This feature is EXPERIMENTAL. See also *scols-filter*(5). For example
+exclude sda  and sdb, but print everything else ('!~' is a negative regular
+expression matching operator):
+____
+ lsblk --filter 'NAME !~ "sd[ab]"'
+____
+
+*--highlight* _expr_::
+Colorize lines matching the expression.
+This feature is EXPERIMENTAL. See also *scols-filter*(5).
+
+*--ct* _name_ [: _param_ [: _function_ ]]::
+Define a custom counter. The counters are printed after the standard output.
+The _name_ is the custom name of the counter, the optional _param_ is the name of the column
+to be used for the counter, and the optional _function_ specifies
+the aggregation function, supported functions are: count, min, max, or sum. The
+default is count.
++
+If the _param_ is not specified, then the counter counts the number of lines. This
+feature is EXPERIMENTAL. See also *--ct-filter*.
++
+For example, *--ct MyCounter:SIZE:sum* will count the summary for SIZE from all lines;
+and to count the number of SATA disks, it is possible to use:
+____
+
+ lsblk --ct-filter 'TYPE=="disk" && TRAN=="sata"' --ct "Number of SATA devices"
+____
+
+
+*--ct-filter* _expr_::
+Define a restriction for the next counter. This feature is EXPERIMENTAL. See also *--ct*
+and *scols-filter*(5). For example, aggregate sizes by device type:
+____
+ lsblk --ct-filter 'TYPE=="part"' --ct Partitions:SIZE:sum \
+       --ct-filter 'TYPE=="disk"' --ct WholeDisks:SIZE:sum
+____
+
 *-r*, *--raw*::
 Produce output in raw format. The output lines are still ordered by dependencies. All potentially unsafe characters are hex-escaped (\x<code>) in the NAME, KNAME, LABEL, PARTLABEL and MOUNTPOINT columns.
 
@@ -175,9 +224,10 @@ mailto:kzak@redhat.com[Karel Zak]
 
 == SEE ALSO
 
-*ls*(1),
 *blkid*(8),
 *findmnt*(8)
+*ls*(1),
+*scols-filter*(5)
 
 include::man-common/bugreports.adoc[]