scols-filter(5) — Linux manual page

NAME \| SYNTAX \| DESCRIPTION \| SYNTAX NOTES \| LIMITATIONS \| AUTHORS \| REPORTING BUGS \| AVAILABILITY

SCOLS-FILTER(5)        File formats and conventions       SCOLS-FILTER(5)

NAME top

       scols-filter - syntax for libsmartcols filter expressions

SYNTAX top

           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 top

       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 top

       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 top

       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 top

       Karel Zak <kzak@redhat.com>

       Based on original implementation from Masatake YAMATO
       <yamato@redhat.com>.

REPORTING BUGS top

       For bug reports, use the issue tracker
       <https://github.com/util-linux/util-linux/issues>.

AVAILABILITY top

       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/>. This page is
       part of the util-linux (a random collection of Linux utilities)
       project. Information about the project can be found at 
       ⟨https://www.kernel.org/pub/linux/utils/util-linux/⟩. If you have a
       bug report for this manual page, send it to
       util-linux@vger.kernel.org. This page was obtained from the
       project's upstream Git repository
       ⟨git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git⟩ on
       2025-08-11. (At that time, the date of the most recent commit that
       was found in the repository was 2025-08-05.) If you discover any
       rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page,
       or you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a
       mail to man-pages@man7.org

util-linux 2.42-start-521-ec46  2025-08-09                SCOLS-FILTER(5)

Pages that refer to this page: lsfd(1), findmnt(8), lsblk(8), lsns(8)