SCOLS-FILTER(5)

💖 SCOLS-FILTER(5) 💖

okay bestie, welcome to the file formats and conventions corner of the manual, and today's main character is scols-filter — the syntax for libsmartcols filter expressions. yes, that libsmartcols. the one quietly running the show. ✨

---

🌸 SYNTAX 🌸

here's the whole grammar, untouched, exactly as it is, no notes:

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]*

like. look at it. it's giving clean. 💅

---

🦋 DESCRIPTION 🦋

so any app that's linked against libsmartcols can use a filter expression to filter its output data. the glow-up here is that the app can apply the filter before it gathers all the data it needs for the output — which means fewer resources burned and better performance overall. and that is literally why the scols filter is more effective than running grep(1) over the complete output afterwards. no cap.

for example:

lsblk --output NAME,LABEL,FSTYPE --filter 'NAME=="sda1"'

this helps lsblk(1) not read LABELs for every single block device from udevd or libblkid — it reads them only for device sda1. the way that it just skips the whole rest of the party. iconic. 😌

also, plot twist: the filter can be used for columns that aren't even in the output. yeah. it's like that.

---

✨ SYNTAX NOTES ✨

an expression is made of holders, params, and operators. the holy trinity, fr fr.

the currently supported holder type is column name only, and that name has to be written without quotes. before evaluation, the application maps column names in the given expression to the output table columns and assigns a column data type to the holder. the default type is "string".

a param is how you represent a value directly. the currently supported data types are integer, float, string, and boolean.

an operator works with one or two operand(s), and every operator has an expectation about the data type(s) of its operands. hand an operator an unexpected data type and you get a syntax error — it will not be chill about it. the library can cast between data types, and the preferred type is always the type as specified by param; and in an expression with a number and a float, the preferred one is the float.

the operators that take two operands are and, or, eq, ne, le, lt, ge, gt, =~, !~. the alphabetically named ones have C-language flavored aliases: &&, ||, ==, !=, <, ⇐, >=, and >.

! is the only operator that takes one operand. and if no operator is specified at all, the expression is true when the param or holder is not empty. so like:

--filter NAME

returns the lines where column NAME is not empty. simple as that. 💖

=~ and !~ are for regular expression matching — if a string on the right side matches (or, for !~, does not match a regular expression on the left side), the result is true. heads up though: the right side operand must be a string literal.

the precedences within operators go: or, and, and then eq, ne, le, gt, ge, =~, !~, not.

---

🎀 LIMITATIONS 🎀

about float and integer typed values — the filter engine supports only non-negative numbers. no negatives, bestie, we don't do those here. the integer is an unsigned 64-bit number, and the float is a long double.

the integer may be followed by the multiplicative suffixes KiB, GiB, TiB, PiB, EiB, ZiB, and YiB — and the "iB" part is optional, so e.g. "K" has the same meaning as "KiB". convenient or what. 🍓

---

👑 AUTHORS 👑

• Karel Zak <kzak@redhat.com>
• Based on original implementation from Masatake YAMATO <yamato@redhat.com>.

legends, honestly. we stan. 🫶

---

💀 REPORTING BUGS 💀

found a bug? for bug reports, use the issue tracker: https://github.com/util-linux/util-linux/issues.

please actually report it instead of just tweeting about it, i'm begging 😭

---

🌈 AVAILABILITY 🌈

the libsmartcols library is part of the util-linux package since version 2.25. it can be downloaded from the Linux Kernel Archive: https://www.kernel.org/pub/linux/utils/util-linux/.

---

and that's the whole page, bestie — brought to you by util-linux 2.42.4, dated 2026-09-21, manual section 5, and this sign-off is officially your reminder that you now know scols-filter better than most people. slay. 💅✨🌸