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. 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. 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. -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. -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. 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. 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.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: bpf-map id=BPF-MAP.ID type=BPF-MAP.TYPE[ name=BPF.NAME] bpf-prog id=BPF-PROG.ID type=BPF-PROG.TYPE[ 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: o stream o dgram o raw o rdm o seqpacket o dccp o packet SOURCE File system, partition, or device containing the file. 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. 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. 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). 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)' List timerfd files expired within 0.5 seconds: # lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)' 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 , Karel Zak SEE ALSO bpftool(8) bps(8) lslocks(8) lsof(8) pidof(1) proc(5) scols-filter(5) socket(2) ss(8) stat(2) REPORTING BUGS For bug reports, use the issue tracker at . AVAILABILITY The lsfd command is part of the util-linux package which can be downloaded from Linux Kernel Archive . util-linux 2.40.2 2024-07-04 LSFD(1)