LSFD(1) User Commands LSFD(1)
NAME
lsfd - list file descriptors
SYNOPSIS
lsfd [option]
DESCRIPTION
lsfd is intended to be a modern replacement for lsof(8) on Linux
systems. Unlike lsof, lsfd is specialized to Linux kernel; it supports
Linux specific features like namespaces with simpler code. lsfd is not
a drop-in replacement for lsof; they are different in the command line
interface and output formats.
lsfd uses Libsmartcols for output formatting and filtering. See the
description of --output option for customizing the output format, and
--filter option for filtering.
OPTIONS
-l, --threads
List in threads level.
-J, --json
Use JSON output format.
-n, --noheadings
Don’t print headings.
-o, --output list
Specify which output columns to print. See the OUTPUT COLUMNS
section for details of available columns.
The default list of columns may be extended if list is specified in
the format +list (e.g., lsfd -o +DELETED).
-r, --raw
Use raw output format.
--notruncate
Don’t truncate text in columns.
-p, --pid pids
Collect information only for specified processes. pids is a list of
pids. A comma or whitespaces can be used as separators. You can use
this option with pidof(1). See FILTER EXAMPLES.
Both -Q option with an expression including PID, e.g. -Q (PID ==
1), and -p option, e.g. -p 1, may print the same output but using
-p option is much more efficient because -p option works at a much
earlier stage of processing than the -Q option.
-Q, --filter expr
Print only the files matching the condition represented by the
expr. See also FILTER EXAMPLES.
-C, --counter label:filter_expr
Define a custom counter used in --summary output. lsfd makes a
counter named label. During collect information, lsfd counts files
matching filter_expr, and stores the counted number to the counter
named label. lsfd applies filters defined with --filter options
before counting; files excluded by the filters are not counted.
See FILTER EXPRESSION about filter_expr. label should not include {
nor :. You can define multiple counters by specifying this option
multiple times.
See also COUNTER EXAMPLES.
--summary[=when]
This option controls summary lines output. The optional argument
when can be only, append or never. If the when argument is omitted,
it defaults to only.
The summary reports counters. A counter consists of a label and an
integer value. --counter is the option for defining a counter. If a
user defines no counter, lsfd uses the definitions of pre-defined
built-in counters (default counters) to make the summary output.
CAUTION: Using --summary and --json may make the output broken.
Only combining --summary=only and --json is valid.
--debug-filter
Dump the internal data structure for the filter and exit. This is
useful only for lsfd developers.
--dump-counters
Dump the definition of counters used in --summary output.
-h, --help
Display help text and exit.
-V, --version
Print version and exit.
OUTPUT COLUMNS
Each column has a type. Types are surround by < and >.
CAUTION: The names and types of columns are not stable yet. They may be
changed in the future releases.
ASSOC <string>
Association between file and process.
BLKDRV <string>
Block device driver name resolved by /proc/devices.
CHRDRV <string>
Character device driver name resolved by /proc/devices.
COMMAND <string>
Command of the process opening the file.
DELETED <boolean>
Reachability from the file system.
DEV <string>
ID of the device containing the file.
DEVTYPE <string>
Device type (blk, char, or nodev).
FD <number>
File descriptor for the file.
FLAGS <string>
Flags specified when opening the file.
FUID <number>
User ID number of the file’s owner.
INODE <number>
Inode number.
KTHREAD <boolean>
Whether the process is a kernel thread or not.
MAJ:MIN <string>
Device ID for special, or ID of device containing file.
MAPLEN <number>
Length of file mapping (in page).
MISCDEV <string>
Misc character device name resolved by /proc/misc.
MNTID <number>
Mount ID.
MODE <string>
Access mode (rwx).
NAME <string>
Name of the file.
NLINK <number>
Link count.
OWNER <string>
Owner of the file.
PARTITION <string>
Block device name resolved by /proc/partition.
PID <number>
PID of the process opening the file.
POS <number>
File position.
PROTONAME <string>
Protocol name.
RDEV <string>
Device ID (if special file).
SIZE <number>
File size.
SOURCE <string>
File system, partition, or device containing the file.
TID <number>
Thread ID of the process opening the file.
TYPE <string>
File type.
UID <number>
User ID number.
USER <string>
User of the process.
FILTER EXPRESSION
lsfd evaluates the expression passed to --filter option every time
before printing a file line. lsfd prints the line only if the result of
evaluation is true.
An expression consists of column names, literals and, operators like:
DELETED, (PID == 1), (NAME == "/etc/passwd"), (PID == 1) && DELETED.
DELETED, PID, and NAME are column names in the example. 1 and
"/etc/passwd" are literals. == and && are operators.
Before evaluation, lsfd substitutes column names in the given
expression with actual column values in the line. There are three
different data types: boolean, string, and number. For columns with a
boolean type, the value can be stand-alone. For string and number
values, the value must be an operand of an operator, for example, (PID
== 1). See the "OUTPUT COLUMNS" about the types of columns.
Literal is for representing a value directly. See BOOLLIT, STRLIT, and
NUMLIT. Different data types have different literal syntax.
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.
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.
eq, ne, and their aliases expect operands have the same data type.
Applying these operators return a boolean.
and, or, not and their aliases expect operands have bool data type.
Applying these operators return a boolean.
lt, le, gt, ge, and their aliases expect operands have number data
types. Applying these operators return a boolean.
=~ is for regular expression matching; if a string at the right side
matches a regular expression at the left side, the result is true. The
right side operand must be a string literal. See STRLIT about the
syntax.
!~ is a short-hand version of not (STR =~ PAT); it inverts the result
of =~.
Limitations
The current implementation does not define precedences within
operators. Use ( and ) explicitly for grouping the sub-expressions if
your expression uses more than two operators.
About number typed values, the filter engine supports only non-negative
integers.
Semi-formal syntax
EXPR
BOOLEXP
BOOLEXP0
COLUMN <boolean> | BOOLLIT | ( BOOLEXP )
BOOLEXP
BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG
COLUMN
[_A-Za-z][-_:A-Za-z0-9]*
BOOLOP1
! BOOLEXP0 | not BOOLEXP0
STREXP
COLUMN <string> | STRLIT
NUMEXP
COLUMN <number> | NUMLIT
BOOLLIT
true | false
CHARS
( [^\] | \\ | \' | \" )*
STRLIT
' CHARS ' | " CHARS "
NUMLIT
[1-9][0-9]* | 0
BOOLOP2
STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0
OP2
== | eq | != | ne
BOOLOP2BL
BOOLEXP0 OP2BL BOOLEXP0
OP2BL
&& | and | || | or
BOOLOP2CMP
NUMEXP OP2CMP NUMEXP
OP2CMP
< | lt | <= | le | > | gt | >= | ge
BOOLOP2REG
STREXP OP2REG STRLIT
OP2REG
=~ | !~
FILTER EXAMPLES
lsfd has few options for filtering. In most of cases, what you should
know is -Q (or --filter) option. Combined with -o (or --output) option,
you can customize the output as you want.
List files associated with PID 1 and PID 2 processes:
# lsfd -Q '(PID == 1) or (PID == 2)'
Do the same in an alternative way:
# lsfd -Q '(PID == 1) || (PID == 2)'
Do the same in a more efficient way:
# lsfd --pid 1,2
Whitescapes can be used instead of a comma:
# lsfd --pid '1 2'
Utilize pidof(1) for list the files associated with "firefox":
# lsfd --pid "$(pidof firefox)"
List the 1st file descriptor opened by PID 1 process:
# lsfd -Q '(PID == 1) and (FD == 1)'
Do the same in an alternative way:
# lsfd -Q '(PID == 1) && (FD == 1)'
List all running executables:
# lsfd -Q 'ASSOC == "exe"'
Do the same in an alternative way:
# lsfd -Q 'ASSOC eq "exe"'
Do the same but print only file names:
# lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
List deleted files associated to processes:
# lsfd -Q 'DELETED'
List non-regular files:
# lsfd -Q 'TYPE != "REG"'
List block devices:
# lsfd -Q 'DEVTYPE == "blk"'
Do the same with TYPE column:
# lsfd -Q 'TYPE == "BLK"'
List files including "dconf" directory in their names:
# lsfd -Q 'NAME =~ ".\*/dconf/.*"'
List files opened in a QEMU virtual machine:
# lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
Hide files associated to kernel threads:
# lsfd -Q '!KTHREAD'
COUNTER EXAMPLES
Report the numbers of netlink socket descriptors and unix socket
descriptors:
# lsfd --summary=only \
-C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
-C 'unix sockets':'(NAME =~ "UNIX:.*")'
VALUE COUNTER
57 netlink sockets
1552 unix sockets
Do the same but print in JSON format:
# lsfd --summary=only --json \
-C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
-C 'unix sockets':'(NAME =~ "UNIX:.*")'
{
"lsfd-summary": [
{
"value": 15,
"counter": "netlink sockets"
},{
"value": 798,
"counter": "unix sockets"
}
]
}
HISTORY
The lsfd command is part of the util-linux package since v2.38.
AUTHORS
Masatake YAMATO <yamato@redhat.com>, Karel Zak <kzak@redhat.com>
SEE ALSO
lsof(8) pidof(1) proc(5)
REPORTING BUGS
For bug reports, use the issue tracker at
https://github.com/util-linux/util-linux/issues.
AVAILABILITY
The lsfd command is part of the util-linux package which can be
downloaded from Linux Kernel Archive
<https://www.kernel.org/pub/linux/utils/util-linux/>.
util-linux 2.38.1 2022-08-04 LSFD(1)
Generated by dwww version 1.15 on Thu Jun 27 07:09:14 CEST 2024.