summaryrefslogtreecommitdiffstats
path: root/misc-utils/lsblk.8
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 19:33:32 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 19:33:32 +0000
commit8bb05ac73a5b448b339ce0bc8d396c82c459b47f (patch)
tree1fdda006866bca20d41cb206767ea5241e36852f /misc-utils/lsblk.8
parentAdding debian version 2.39.3-11. (diff)
downloadutil-linux-8bb05ac73a5b448b339ce0bc8d396c82c459b47f.tar.xz
util-linux-8bb05ac73a5b448b339ce0bc8d396c82c459b47f.zip
Merging upstream version 2.40.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--misc-utils/lsblk.8102
-rw-r--r--misc-utils/lsblk.8.adoc58
2 files changed, 149 insertions, 11 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
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[]