Merging upstream version 2.40.

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

1 files changed, 95 insertions, 7 deletions

diff --git a/misc-utils/lsblk.8 b/misc-utils/lsblk.8
index f67b96c..235f88b 100644
--- a/misc-utils/lsblk.8
+++ b/misc-utils/lsblk.8
@@ -2,12 +2,12 @@
 .\"     Title: lsblk
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 2.0.20
-.\"      Date: 2023-12-01
+.\"      Date: 2024-03-20
 .\"    Manual: System Administration
-.\"    Source: util-linux 2.39.3
+.\"    Source: util-linux 2.40
 .\"  Language: English
 .\"
-.TH "LSBLK" "8" "2023-12-01" "util\-linux 2.39.3" "System Administration"
+.TH "LSBLK" "8" "2024-03-20" "util\-linux 2.40" "System Administration"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -38,9 +38,11 @@ lsblk \- list block devices
 .sp
 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 \fB\-\-merge\fP option is recommended for more complicated setups to gather groups of devices and describe complex N:M relationships.
 .sp
+The tree\-like output (or \fBchildren[]\fP array in the JSON output) is enabled only if NAME column it present in the output or when \fB\-\-tree\fP command line option is used. See also \fB\-\-nodeps\fP and \fB\-\-list\fP to control the tree formatting.
+.sp
 The default output, as well as the default output from options like \fB\-\-fs\fP and \fB\-\-topology\fP, is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using \fB\-\-output\fP \fIcolumns\-list\fP and \fB\-\-list\fP in environments where a stable output is required.
 .sp
-Use \fBlsblk \-\-help\fP to get a list of all available columns.
+Use \fBlsblk \-\-list\-columns\fP to get a list of all available columns.
 .sp
 Note that \fBlsblk\fP might be executed in time when \fBudev\fP does not have all information about recently added or modified devices yet. In this case it is recommended to use \fBudevadm settle\fP before \fBlsblk\fP to synchronize with udev.
 .sp
@@ -68,6 +70,11 @@ examples: "1 KiB" and "1 MiB" are respectively exhibited as "1 K" and "1 M",
 then omitting on purpose the mention "iB", which is part of these abbreviations.
 .RE
 .sp
+\fB\-H\fP, \fB\-\-list\-columns\fP
+.RS 4
+List the available columns, use with \fB\-\-json\fP or \fB\-\-raw\fP to get output in machine\-readable format.
+.RE
+.sp
 \fB\-D\fP, \fB\-\-discard\fP
 .RS 4
 Print information about the discarding capabilities (TRIM, UNMAP) for each device.
@@ -107,7 +114,7 @@ Use ASCII characters for tree formatting.
 .sp
 \fB\-J\fP, \fB\-\-json\fP
 .RS 4
-Use JSON output format. It\(cqs strongly recommended to use \fB\-\-output\fP and also \fB\-\-tree\fP if necessary.
+Use JSON output format. It\(cqs strongly recommended to use \fB\-\-output\fP and also \fB\-\-tree\fP if necessary. Note that \fBchildren[]\fP is used only if NAME column or \fB\-\-tree\fP is used.
 .RE
 .sp
 \fB\-l\fP, \fB\-\-list\fP
@@ -142,7 +149,7 @@ Do not print a header line.
 .sp
 \fB\-o\fP, \fB\-\-output\fP \fIlist\fP
 .RS 4
-Specify which output columns to print. Use \fB\-\-help\fP to get a list of all supported columns. The columns may affect tree\-like output. The default is to use tree for the column \*(AqNAME\*(Aq (see also \fB\-\-tree\fP).
+Specify which output columns to print. Use \fB\-\-list\-columns\fP to get a list of all supported columns. The columns may affect tree\-like output. The default is to use tree for the column \*(AqNAME\*(Aq (see also \fB\-\-tree\fP).
 .sp
 The default list of columns may be extended if \fIlist\fP is specified in the format \fI+list\fP (e.g., \fBlsblk \-o +UUID\fP).
 .RE
@@ -162,6 +169,86 @@ Produce output in the form of key="value" pairs. The output lines are still orde
 Print full device paths.
 .RE
 .sp
+\fB\-Q\fP, \fB\-\-filter\fP \fIexpr\fP
+.RS 4
+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).
+.sp
+This feature is EXPERIMENTAL. See also \fBscols\-filter\fP(5). For example
+exclude sda  and sdb, but print everything else (\*(Aq!~\*(Aq is a negative regular
+expression matching operator):
+.RE
+.RS 3
+.ll -.6i
+.sp
+.if n .RS 4
+.nf
+.fam C
+lsblk \-\-filter \*(AqNAME !~ "sd[ab]"\*(Aq
+.fam
+.fi
+.if n .RE
+.br
+.RE
+.ll
+.sp
+\fB\-\-highlight\fP \fIexpr\fP
+.RS 4
+Colorize lines matching the expression.
+This feature is EXPERIMENTAL. See also \fBscols\-filter\fP(5).
+.RE
+.sp
+\fB\-\-ct\fP \fIname\fP [: \fIparam\fP [: \fIfunction\fP ]]
+.RS 4
+Define a custom counter. The counters are printed after the standard output.
+The \fIname\fP is the custom name of the counter, the optional \fIparam\fP is the name of the column
+to be used for the counter, and the optional \fIfunction\fP specifies
+the aggregation function, supported functions are: count, min, max, or sum. The
+default is count.
+.sp
+If the \fIparam\fP is not specified, then the counter counts the number of lines. This
+feature is EXPERIMENTAL. See also \fB\-\-ct\-filter\fP.
+.sp
+For example, \fB\-\-ct MyCounter:SIZE:sum\fP will count the summary for SIZE from all lines;
+and to count the number of SATA disks, it is possible to use:
+.RE
+.RS 3
+.ll -.6i
+.sp
+.if n .RS 4
+.nf
+.fam C
+lsblk \-\-ct\-filter \*(AqTYPE=="disk" && TRAN=="sata"\*(Aq \-\-ct "Number of SATA devices"
+.fam
+.fi
+.if n .RE
+.br
+.RE
+.ll
+.sp
+\fB\-\-ct\-filter\fP \fIexpr\fP
+.RS 4
+Define a restriction for the next counter. This feature is EXPERIMENTAL. See also \fB\-\-ct\fP
+and \fBscols\-filter\fP(5). For example, aggregate sizes by device type:
+.RE
+.RS 3
+.ll -.6i
+.sp
+.if n .RS 4
+.nf
+.fam C
+lsblk \-\-ct\-filter \*(AqTYPE=="part"\*(Aq \-\-ct Partitions:SIZE:sum \(rs
+      \-\-ct\-filter \*(AqTYPE=="disk"\*(Aq \-\-ct WholeDisks:SIZE:sum
+.fam
+.fi
+.if n .RE
+.br
+.RE
+.ll
+.sp
 \fB\-r\fP, \fB\-\-raw\fP
 .RS 4
 Produce output in raw format. The output lines are still ordered by dependencies. All potentially unsafe characters are hex\-escaped (\(rsx<code>) in the NAME, KNAME, LABEL, PARTLABEL and MOUNTPOINT columns.
@@ -281,9 +368,10 @@ The \fBlsblk\fP command needs to be able to look up each block device by major:m
 .MTO "kzak\(atredhat.com" "Karel Zak" ""
 .SH "SEE ALSO"
 .sp
-\fBls\fP(1),
 \fBblkid\fP(8),
 \fBfindmnt\fP(8)
+\fBls\fP(1),
+\fBscols\-filter\fP(5)
 .SH "REPORTING BUGS"
 .sp
 For bug reports, use the issue tracker at \c