|
HTML rendering created 2023-06-24 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT COLUMNS | FILTER EXPRESSION | FILTER EXAMPLES | COUNTER EXAMPLES | HISTORY | AUTHORS | SEE ALSO | REPORTING BUGS | AVAILABILITY |
|
|
|
LSFD(1) User Commands LSFD(1)
lsfd - list file descriptors
lsfd [option]
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.
The default output is subject to change. So whenever possible,
you should avoid using default outputs in your scripts. Always
explicitly define expected columns by using --output columns-list
in environments where a stable output is required.
lsfd uses Libsmartcols for output formatting and filtering. See
the description of --output option for customizing the output
format, and --filter option for filtering. Use lsfd --help to get
a list of all available columns.
-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.
-i[4|6], --inet[=4|6]
List only IPv4 sockets and/or IPv6 sockets.
-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.
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.
AINODECLASS <string>
Class of anonymous inode.
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).
ENDPOINT <string>
IPC endpoints information communicated with the fd.
lsfd collects endpoints within the processes that lsfd scans;
lsfd may miss some endpoints if you limits the processes with
-p option.
The format of the column depends on the object associated
with the fd:
FIFO type, mqueue type
PID,COMMAND,ASSOC[-r][-w]
The last characters ([-r][-w]) represents the read and/or
write mode of the endpoint.
eventfd type
PID,COMMAND,ASSOC
EVENTFD.ID <number>
Eventfd ID.
EVENTPOLL.TFDS <string>
File descriptors targeted by the eventpoll file.
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.
INET.LADDR <string>
Local IP address.
INET.RADDR <string>
Remote IP address.
INET6.LADDR <string>
Local IP6 address.
INET6.RADDR <string>
Remote IP6 address.
INODE <number>
Inode number.
INOTIFY.INODES <string>
Cooked version of INOTIFY.INODES.RAW. The format of the
element is inode-number,source-of-inode.
INOTIFY.INODES.RAW <string>
List of monitoring inodes. The format of the element is
inode-number,device-major:_device-minor_.
KNAME <string>
Raw file name extracted from from /proc/pid/fd/fd or
/proc/pid/map_files/region.
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>
Cooked version of KNAME. It is mostly same as KNAME.
Some files have special formats and information sources:
eventpoll
tfds=EVENTPOLL.TFDS
eventfd
id=EVENTFD.ID
inotify
inodes=INOTIFY.INODES
NETLINK
protocol=NETLINK.PROTOCOL[ lport=NETLINK.LPORT[
group=NETLINK.GROUPS]]
PACKET
type=SOCK.TYPE[ protocol=PACKET.PROTOCOL][
iface=PACKET.IFACE]
pidfd
pid=TARGET-PID comm=TARGET-COMMAND nspid=TARGET-NSPIDS
lsfd extracts TARGET-PID and TARGET-NSPIDS from
/proc/pid/fdinfo/fd.
PING
state=SOCK.STATE[ id=PING.ID][ laddr=INET.LADDR [
raddr=INET.RADDR]]
PINGv6
state=SOCK.STATE[ id=PING.ID][ laddr=INET6.LADDR [
raddr=INET6.RADDR]]
RAW
state=SOCK.STATE[ protocol=RAW.PROTOCOL [
laddr=INET.LADDR [ raddr=INET.RADDR]]]
RAWv6
state=SOCK.STATE[ protocol=RAW.PROTOCOL [
laddr=INET6.LADDR [ raddr=INET6.RADDR]]]
signalfd
mask=SIGNALFD.MASK
TCP, TCPv6
state=SOCK.STATE[ laddr=TCP.LADDR [ raddr=TCP.RADDR]]
timerfd
clockid=TIMERFD.CLOCKID[ remaining=TIMERFD.REMAINING [
interval=TIMERFD.INTERVAL]]
UDP, UDPv6
state=SOCK.STATE[ laddr=UDP.LADDR [ raddr=UDP.RADDR]]
lsfd hides raddr= if UDP.RADDR is 0.0.0.0 and UDP.RPORT
is 0.
UDP-LITE, UDPLITEv6
state=SOCK.STATE[ laddr=UDPLITE.LADDR [
raddr=UDPLITE.RADDR]]
UNIX-STREAM
state=SOCK.STATE[ path=UNIX.PATH]
UNIX
state=SOCK.STATE[ path=UNIX.PATH] type=SOCK.TYPE
NETLINK.GROUPS <number>
Netlink multicast groups.
NETLINK.LPORT <number>
Netlink local port id.
NETLINK.PROTOCOL <string>
Netlink protocol.
NLINK <number>
Link count.
NS.NAME <string>
Name (NS.TYPE:[INODE]) of the namespace specified with the
file.
NS.TYPE <string>
Type of the namespace specified with the file. The type is
mnt, cgroup, uts, ipc, user, pid, net, time, or unknown.
OWNER <string>
Owner of the file.
PACKET.IFACE <string>
Interface name associated with the packet socket.
PACKET.PROTOCOL <string>
L3 protocol associated with the packet socket.
PARTITION <string>
Block device name resolved by /proc/partition.
PID <number>
PID of the process opening the file.
PIDFD.COMM <string>
Command of the process targeted by the pidfd.
PIDFD.NSPID <string>
Value of NSpid field in /proc/pid/fdinfo/fd of the pidfd.
Quoted from kernel/fork.c of Linux source tree:
If pid namespaces are supported then this function
will also print the pid of a given pidfd refers to
for all descendant pid namespaces starting from the
current pid namespace of the instance, i.e. the Pid
field and the first entry in the NSpid field will be
identical.
Note that this differs from the Pid and NSpid fields
in /proc/<pid>/status where Pid and NSpid are always
shown relative to the pid namespace of the procfs
instance.
PIDFD.PID <number>
PID of the process targeted by the pidfd.
PING.ID <`number`>
ICMP echo request id used on the PING socket.
POS <number>
File position.
RAW.PROTOCOL <number>
Protocol number of the raw socket.
RDEV <string>
Device ID (if special file).
SIGNALFD.MASK <string>
Masked signals.
SIZE <number>
File size.
SOCK.LISTENING <boolean>
Listening socket.
SOCK.NETS <number>
Inode identifying network namespace where the socket belongs
to.
SOCK.PROTONAME <string>
Protocol name.
SOCK.STATE <string>
State of socket.
SOCK.TYPE <string>
Type of socket. Here type means the second parameter of
socket system call:
• stream
• dgram
• raw
• rdm
• seqpacket
• dccp
• packet
SOURCE <string>
File system, partition, or device containing the file.
STTYPE <string>
Raw file types returned from stat(2): BLK, CHR, DIR, FIFO,
LINK, REG, SOCK, or UNKN.
TCP.LADDR <string>
Local L3 (INET.LADDR or INET6.LADDR) address and local TCP
port.
TCP.LPORT <number>
Local TCP port.
TCP.RADDR <string>
Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP
port.
TCP.RPORT <number>
Remote TCP port.
TID <number>
Thread ID of the process opening the file.
TIMERFD.CLOCKID <string>
Clockid.
TIMERFD.INTERVAL <number>
Interval.
TIMERFD.REMAINING <number>
Remaining time.
TYPE <string>
Cooked version of STTYPE. It is same as STTYPE with
exceptions. For SOCK, print the value for SOCK.PROTONAME. For
UNKN, print the value for AINODECLASS if SOURCE is
anon_inodefs.
UDP.LADDR <string>
Local IP address and local UDP port.
UDP.LPORT <number>
Local UDP port.
UDP.RADDR <string>
Remote IP address and remote UDP port.
UDP.RPORT <number>
Remote UDP port.
UDPLITE.LADDR <string>
Local IP address and local UDPLite port.
UDPLITE.LPORT <number>
Local UDP port.
UDPLITE.RADDR <string>
Remote IP address and remote UDPLite port.
UDPLITE.RPORT <number>
Remote UDP port.
UID <number>
User ID number.
UNIX.PATH <string>
Filesystem pathname for UNIX domain socket.
USER <string>
User of the process.
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 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 boolean 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, and non-negative floating point numbers.
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
INTLIT | FNUMLIT
INTLIT
[1-9][0-9]* | 0
FNUMLIT
INTLIT . [0-9][0-9]*
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
=~ | !~
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'
List timerfd files expired within 0.5 seconds:
# lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
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"
}
]
}
The lsfd command is part of the util-linux package since v2.38.
Masatake YAMATO <yamato@redhat.com>, Karel Zak <kzak@redhat.com>
lsof(8) pidof(1) proc(5) socket(2) stat(2)
For bug reports, use the issue tracker at
https://github.com/util-linux/util-linux/issues.
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/>. 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
2023-06-23. (At that time, the date of the most recent commit
that was found in the repository was 2023-06-22.) 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.39.268-ae62d 2023-06-22 LSFD(1)
|
HTML rendering created 2023-06-24 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|