|
HTML rendering created 2025-02-02 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 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 --list-columns
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 scols-filter(5) and 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 scols-filter(5) 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.
--hyperlink[=mode]
Print paths as terminal hyperlinks. The mode can be set to
"always", "never", or "auto". The optional argument when can
be set to "auto", "never", or "always". If the when argument
is omitted, it will default to "auto". The "auto" setting
means that hyperlinks will only be used if the output is on a
terminal.
-H, --list-columns
List available columns that you can specify at --output
option.
-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
Class of anonymous inode.
ASSOC
Association between file and process.
BLKDRV
Block device driver name resolved by /proc/devices.
BPF-MAP.ID
Bpf map ID.
BPF-MAP.TYPE
Decoded name of bpf map type.
BPF-MAP.TYPE.RAW
Bpf map type (raw).
BPF.NAME
Bpf object name.
BPF-PROG.ID
Bpf program ID.
BPF-PROG.TAG
Bpf program TAG.
BPF-PROG.TYPE
Decoded name of bpf program type.
BPF-PROG.TYPE.RAW
Bpf program type (raw).
CHRDRV
Character device driver name resolved by /proc/devices.
COMMAND
Command of the process opening the file.
DELETED
Reachability from the file system.
DEV
ID of the device containing the file.
DEVTYPE
Device type (blk, char, or nodev).
ENDPOINT
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, ptmx and pts sources
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
UNIX-STREAM
PID,COMMAND,ASSOC[-r?][-w?]
About the last characters ([-r?][-w?]), see the
description of SOCK.SHUTDOWN.
EVENTFD.ID
Eventfd ID.
EVENTPOLL.TFDS
File descriptors targeted by the eventpoll file.
FD
File descriptor for the file.
FLAGS
Flags specified when opening the file.
FUID
User ID number of the file’s owner.
INET.LADDR
Local IP address.
INET.RADDR
Remote IP address.
INET6.LADDR
Local IP6 address.
INET6.RADDR
Remote IP6 address.
INODE
Inode number.
INOTIFY.INODES
Cooked version of INOTIFY.INODES.RAW. The format of the
element is inode-number,source-of-inode.
INOTIFY.INODES.RAW
List of monitoring inodes. The format of the element is
inode-number,device-major:device-minor.
KNAME
Raw file name extracted from from /proc/pid/fd/fd or
/proc/pid/map_files/region.
KTHREAD
Whether the process is a kernel thread or not.
MAJ:MIN
Device ID for special, or ID of device containing file.
MAPLEN
Length of file mapping (in page).
MISCDEV
Misc character device name resolved by /proc/misc.
MNTID
Mount ID.
MODE
Access mode (rwx).
NAME
Cooked version of KNAME. It is mostly same as KNAME.
Some files have special formats and information sources:
AF_VSOCK
state=SOCK.STATE type=SOCK.TYPE laddr=VSOCK.LADDR[
raddr=VSOCK.RADDR]
raddr is not shown for listening sockets.
bpf-map
id=BPF-MAP.ID type=BPF-MAP.TYPE[ name=BPF.NAME]
bpf-prog
id=BPF-PROG.ID type=BPF-PROG.TYPE tag= BPF-PROG.TAG [
name=BPF.NAME]
eventpoll
tfds=EVENTPOLL.TFDS
eventfd
id=EVENTFD.ID
inotify
inodes=INOTIFY.INODES
misc:tun
iface=TUN.IFACE
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]]
ptmx
tty-index=PTMX.TTY-INDEX
lsfd extracts PTMX.TTY-INDEX from /proc/pid/fdinfo/fd.
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
Note that (deleted) markers are removed from this column.
Refer to KNAME, DELETED, or XMODE to know the readability
of the file from the file system.
NETLINK.GROUPS
Netlink multicast groups.
NETLINK.LPORT
Netlink local port id.
NETLINK.PROTOCOL
Netlink protocol.
NLINK
Link count.
NS.NAME
Name (NS.TYPE:[INODE]) of the namespace specified with the
file.
NS.TYPE
Type of the namespace specified with the file. The type is
mnt, cgroup, uts, ipc, user, pid, net, time, or unknown.
OWNER
Owner of the file.
PACKET.IFACE
Interface name associated with the packet socket.
PACKET.PROTOCOL
L3 protocol associated with the packet socket.
PARTITION
Block device name resolved by /proc/partition.
PID
PID of the process opening the file.
PIDFD.COMM
Command of the process targeted by the pidfd.
PIDFD.NSPID
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//status where Pid and NSpid are always
shown relative to the pid namespace of the procfs
instance.
PIDFD.PID
PID of the process targeted by the pidfd.
PING.ID <`number`>
ICMP echo request id used on the PING socket.
POS
File position.
RAW.PROTOCOL
Protocol number of the raw socket.
RDEV
Device ID (if special file).
SIGNALFD.MASK
Masked signals.
SIZE
File size.
SOCK.LISTENING
Listening socket.
SOCK.NETS
Inode identifying network namespace where the socket belongs
to.
SOCK.PROTONAME
Protocol name.
SOCK.SHUTDOWN
Shutdown state of socket.
[-r?]
If the first character is r, the receptions are allowed.
If it is -, the receptions are disallowed. If it is ?, the
state is unknown.
[-w?]
If the second character is w, the transmissions are
allowed. If it is -, the transmissions are disallowed. If
it is ?, the state is unknown.
SOCK.STATE
State of socket.
SOCK.TYPE
Type of socket. Here type means the second parameter of socket
system call:
• stream
• dgram
• raw
• rdm
• seqpacket
• dccp
• packet
SOURCE
File system, partition, or device containing the file. For the
association having ERROR as the value for TYPE column, lsfd
fills this column with syscall:_errno_.
STTYPE
Raw file types returned from stat(2): BLK, CHR, DIR, FIFO,
LINK, REG, SOCK, or UNKN.
TCP.LADDR
Local L3 (INET.LADDR or INET6.LADDR) address and local TCP
port.
TCP.LPORT
Local TCP port.
TCP.RADDR
Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP
port.
TCP.RPORT
Remote TCP port.
TID
Thread ID of the process opening the file.
TIMERFD.CLOCKID
Clockid.
TIMERFD.INTERVAL
Interval.
TIMERFD.REMAINING
Remaining time.
PTMX.TTY-INDEX
TTY index of the counterpart.
TUN.IFACE
Network interface behind the tun device.
TYPE
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.
If lsfd gets an error when calling a syscall to know about a
target file descriptor, lsfd fills this column for it with
ERROR.
UDP.LADDR
Local IP address and local UDP port.
UDP.LPORT
Local UDP port.
UDP.RADDR
Remote IP address and remote UDP port.
UDP.RPORT
Remote UDP port.
UDPLITE.LADDR
Local IP address and local UDPLite port.
UDPLITE.LPORT
Local UDP port.
UDPLITE.RADDR
Remote IP address and remote UDPLite port.
UDPLITE.RPORT
Remote UDP port.
UID
User ID number.
UNIX.PATH
Filesystem pathname for UNIX domain socket.
USER
User of the process.
VSOCK.LADDR , VSOCK.RADDR
Local VSOCK address. The format of the element is
VSOCK.LCID:VSOCK.LPORT.
Well-known CIDs will be decoded: “*”, “hypervisor”, “local”,
or “host”. Well-known ports will be decoded: “*”.
VSOCK.LCID , VSOCK.RCID
Local and remote VSOCK context identifiers.
VSOCK.LPORT , VSOCK.RPORT
Local and remote VSOCK ports.
XMODE
Extended version of MODE. This column may grow; new letters
may be appended to XMODE when lsfd supports a new state of
file descriptors and/or memory mappings.
[-r]
opened of mapped for reading. This is also in MODE.
[-w]
opened of mapped for writing. This is also in MODE.
[-x]
mapped for executing the code. This is also in MODE.
[-D]
deleted from the file system. See also DELETED.
[-Ll]
locked or leased. l represents a read, a shared lock or a
read lease. L represents a write or an exclusive lock or a
write lease. If both read/shared and write/exclusive locks
or leases are taken by a file descriptor, L is used as the
flag.
[-m]
Multiplexed. If the file descriptor is targeted by a
eventpoll file or classical system calls for multiplexing
(select, pselect, poll, and ppoll), this bit flag is set.
Note that if an invocation of the classical system calls
is interrupted, lsfd may fail to mark m on the file
descriptors monitored by the invocation. See
restart_syscall(2).
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
Whitespaces 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)'
List timerfd files expired within 0.5 seconds:
# lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
List processes communicating via unix stream sockets:
# lsfd -Q 'TYPE == "UNIX-STREAM" && UNIX.PATH =~ ".+"' -oUNIX.PATH,PID,COMMAND,FD,SOCK.STATE,ENDPOINTS
List processes communicating via a specified unix stream socket:
# lsfd -Q 'TYPE == "UNIX-STREAM" && UNIX.PATH == "@/tmp/.X11-unix/X0"' -oUNIX.PATH,PID,COMMAND,FD,SOCK.STATE,ENDPOINTS
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 , Karel Zak
bpftool(8), bps(8), lslocks(8), lsof(8), pidof(1), proc(5),
scols-filter(5), socket(2), ss(8), stat(2), vsock(7)
For bug reports, use the issue tracker
<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
[email protected]. 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-02-02. (At that time, the date of the most recent commit that
was found in the repository was 2025-01-30.) 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 [email protected]
util-linux 2.41.devel-938-0a... 2025-01-15 LSFD(1)
|
HTML rendering created 2025-02-02 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. |
|