SCOLS-FILTER(5) File formats and conventions SCOLS-FILTER(5)
NAME
scols-filter - syntax for libsmartcols filter expressions
SYNTAX
expr: param
| ( expr )
| expr && expr | expr AND expr
| expr || expr | expr OR expr
| !expr | NOT expr
| expr == expr | expr EQ expr
| expr != expr | expr NE expr
| expr >= expr | expr GE expr
| expr <= expr | expr LE expr
| expr > expr | expr GT expr
| expr < expr | expr LT expr
| expr =~ string
| expr !~ string
param: integer
| float
| string
| boolean
| holder
integer: [0-9]*
| [0-9]*[KMGTPEZY]
| [0-9]*[KMGTPEZY]iB
float: integer.integer
boolean: "true" | "false" | "TRUE" | "FALSE"
string: "[^\n\"]*" | '[^\n\']*'
holder: [a-zA-Z][a-zA-Z_.%:/\-0-9]*
DESCRIPTION
The filter expression can be used by application linked with
libsmartcols to filter output data. The application can use the filter
before it gathers all data for the output to reduce resources and
improve performance. This makes scols filter more effective than grep(1)
on the complete output. For example
lsblk --output NAME,LABEL,FSTYPE --filter 'NAME=="sda1"'
helps lsblk(1) to not read LABELs for all block device from udevd or
libblkid, but read it only for device sda1.
The filter can be also used for columns which are not used in the
output.
SYNTAX NOTES
An expression consists of holders, params, and operators.
The currently supported holder type is column name only. The name has to
be used without quotes. Before evaluation, application map column names
in the given expression to the output table columns and assign column
data type to the holder. The default type is "string".
The param is for representing a value directly. The currently supported
data types are integer, float, string and boolean.
An operator works with one or two operand(s). An operator has an
expectation about the data type(s) of its operands. Giving an unexpected
data type to an operator causes a syntax error. The library can cast
between data types, the prefferred is always the type as specified by
param and in case of expression with number and float the preferred is
the float.
Operators taking two operands are and, or, eq, ne, le, lt, ge, gt, =~,
!~. Alphabetically named operators have C-language flavored aliases: &&,
||, ==, !=, <, ⇐, >=, and >.
! is the only operator that takes one operand. If no operator is
specified then expression is true if param or holder are not empty. For
example --filter NAME will return lines where column NAME is not empty.
=~ and !~ is for regular expression matching; if a string at the right
side matches (or not matches for !~ a regular expression at the left
side, the result is true. The right side operand must be a string
literal.
The precedences within operators is or, and, and eq, ne, le, gt, ge, =~,
!~, not.
LIMITATIONS
About float and integer typed values, the filter engine supports only
non-negative numbers. The integer is unsigned 64-bit number, and float
is long double. The integer may be followed by the multiplicative
suffixes KiB, GiB, TiB, PiB, EiB, ZiB, and YiB (the "iB" is optional,
e.g., "K" has the same meaning as "KiB").
AUTHORS
Karel Zak <kzak@redhat.com>
Based on original implementation from Masatake YAMATO
<yamato@redhat.com>.
REPORTING BUGS
For bug reports, use the issue tracker
<https://github.com/util-linux/util-linux/issues>.
AVAILABILITY
The libsmartcols library is part of the util-linux package since version
2.25. It can be downloaded from Linux Kernel Archive
<https://www.kernel.org/pub/linux/utils/util-linux/>.
util-linux 2.41 2025-02-26 SCOLS-FILTER(5)
Generated by dwww version 1.16 on Tue Dec 16 04:13:00 CET 2025.