1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
'\" t
.\" Title: scols-filter
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\" Date: 2025-09-22
.\" Manual: File formats and conventions
.\" Source: util-linux 2.41.2
.\" Language: English
.\"
.TH "SCOLS\-FILTER" "5" "2025-09-22" "util\-linux 2.41.2" "File formats and conventions"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
. mso www.tmac
. am URL
. ad l
. .
. am MTO
. ad l
. .
. LINKSTYLE blue R < >
.\}
.SH "NAME"
scols-filter \- syntax for libsmartcols filter expressions
.SH "SYNTAX"
.sp
.if n .RS 4
.nf
.fam C
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: "[^\(rsn\(rs"]*" | \*(Aq[^\(rsn\(rs\*(Aq]*\*(Aq
holder: [a\-zA\-Z][a\-zA\-Z_.%:/\(rs\-0\-9]*
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
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
.sp
.if n .RS 4
.nf
.fam C
lsblk \-\-output NAME,LABEL,FSTYPE \-\-filter \*(AqNAME=="sda1"\*(Aq
.fam
.fi
.if n .RE
.sp
helps lsblk(1) to not read LABELs for all block device from udevd or libblkid,
but read it only for device sda1.
.sp
The filter can be also used for columns which are not used in the output.
.SH "SYNTAX NOTES"
.sp
An expression consists of holders, params, and operators.
.sp
The currently supported \f(CRholder\fP 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".
.sp
The \f(CRparam\fP is for representing a value directly. The currently supported data
types are integer, float, string and boolean.
.sp
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 \f(CRparam\fP and in case of expression with
number and float the preferred is the float.
.sp
Operators taking two operands are \f(CRand\fP, \f(CRor\fP, \f(CReq\fP, \f(CRne\fP, \f(CRle\fP, \f(CRlt\fP, \f(CRge\fP, \f(CRgt\fP, \f(CR=~\fP, \f(CR!~\fP.
Alphabetically named operators have C\-language
flavored aliases: \f(CR&&\fP, \f(CR||\fP, \f(CR==\fP, \f(CR!=\fP, \f(CR<\fP, \f(CR\(lA\fP, \f(CR>=\fP, and \f(CR>\fP.
.sp
\f(CR!\fP 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 \f(CR\-\-filter NAME\fP will
return lines where column NAME is not empty.
.sp
\f(CR=~\fP and \f(CR!~\fP is for regular expression matching; if a string at the right side
matches (or not matches for \f(CR!~\fP a regular expression at the left side, the result
is true. The right side operand must be a string literal.
.sp
The precedences within operators is \f(CRor\fP, \f(CRand\fP, and \f(CReq\fP, \f(CRne\fP, \f(CRle\fP, \f(CRgt\fP, \f(CRge\fP, \f(CR=~\fP, \f(CR!~\fP, \f(CRnot\fP.
.SH "LIMITATIONS"
.sp
About \f(CRfloat\fP and \f(CRinteger\fP typed values, the filter engine supports only
non\-negative numbers. The \f(CRinteger\fP is unsigned 64\-bit number, and \f(CRfloat\fP is
long double. The \f(CRinteger\fP 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").
.SH "AUTHORS"
.sp
.MTO "kzak\(atredhat.com" "Karel Zak" ""
.sp
Based on original implementation from \c
.MTO "yamato\(atredhat.com" "Masatake YAMATO" "."
.SH "REPORTING BUGS"
.sp
For bug reports, use the \c
.URL "https://github.com/util\-linux/util\-linux/issues" "issue tracker" "."
.SH "AVAILABILITY"
.sp
The \fBlibsmartcols\fP library is part of the util\-linux package since version 2.25. It can be downloaded from \c
.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."
|
