From: Karel Zak Date: Thu, 11 Jan 2024 16:00:25 +0000 (+0100) Subject: lsblk: add docs for filters and counters X-Git-Tag: v2.40-rc1~54 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c1b1b22e87c03bd99f7a1ff79c3cc6968f95658a;p=thirdparty%2Futil-linux.git lsblk: add docs for filters and counters Fixes: https://github.com/util-linux/util-linux/issues/2697 Signed-off-by: Karel Zak --- diff --git a/bash-completion/lsblk b/bash-completion/lsblk index fe9ae829a0..4f1c39dfba 100644 --- a/bash-completion/lsblk +++ b/bash-completion/lsblk @@ -62,6 +62,10 @@ _lsblk_module() --discard --exclude --fs + --filter + --highlight + --ct + --ct-filter --help --include --json diff --git a/misc-utils/lsblk.8.adoc b/misc-utils/lsblk.8.adoc index a66e0580af..577ff71cd5 100644 --- a/misc-utils/lsblk.8.adoc +++ b/misc-utils/lsblk.8.adoc @@ -24,7 +24,7 @@ The tree-like output (or *children[]* array in the JSON output) is enabled only 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. @@ -102,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) in the NAME, KNAME, LABEL, PARTLABEL and MOUNTPOINT columns. @@ -180,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[] diff --git a/misc-utils/lsblk.c b/misc-utils/lsblk.c index e9d732f920..30bd2edfdf 100644 --- a/misc-utils/lsblk.c +++ b/misc-utils/lsblk.c @@ -2313,10 +2313,10 @@ static void __attribute__((__noreturn__)) usage(void) fputs(_(" -M, --merge group parents of sub-trees (usable for RAIDs, Multi-path)\n"), out); fputs(_(" -O, --output-all output all columns\n"), out); fputs(_(" -P, --pairs use key=\"value\" output format\n"), out); - fputs(_(" -Q, --filter restrict output\n"), out); - fputs(_(" --highlight colorize lines maching the query\n"), out); - fputs(_(" --ct-filter restrict the next counters\n"), out); - fputs(_(" --ct [:[:]] define custom counter\n"), out); + fputs(_(" -Q, --filter print only lines maching the expression\n"), out); + fputs(_(" --highlight colorize lines maching the expression\n"), out); + fputs(_(" --ct-filter restrict the next counter\n"), out); + fputs(_(" --ct [:[:]] define a custom counter\n"), out); fputs(_(" -S, --scsi output info about SCSI devices\n"), out); fputs(_(" -N, --nvme output info about NVMe devices\n"), out); fputs(_(" -v, --virtio output info about virtio devices\n"), out);