lsfd(1) — Linux manual page


LSFD(1)                       User Commands                      LSFD(1)

NAME         top

       lsfd - list file descriptors

SYNOPSIS         top

       lsfd [option]

DESCRIPTION         top

       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         top

       -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.

           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

           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

       -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.

           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.

           Dump the internal data structure for the filter and exit.
           This is useful only for lsfd developers.

           Dump the definition of counters used in --summary output.

       -h, --help
           Display help text and exit.

       -V, --version
           Print version and exit.

OUTPUT COLUMNS         top

       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. The
           format of the column depends on the object associated with
           the fd:

           FIFO type

               The last characters ([-r][-w]) represents the read and/or
               write mode of the endpoint.

           lsfd collects endpoints within the processes that lsfd scans;
           lsfd may miss some endpoints if you limits the processes with
           -p option.

       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.

       INODE <number>
           Inode number.

       KNAME <string>
           Raw file name extracted from from /proc/pid/fd/fd or

       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:

               pid=TARGET-PID comm=TARGET-COMMAND nspid=TARGET-NSPIDS

               lsfd extracts TARGET-PID and TARGET-NSPIDS from

               state=SOCK.STATE[ laddr=TCP.LADDR:_TCP.LPORT_ [

               state=SOCK.STATE[ laddr=UDP.LADDR:_UDP.LPORT_ [

               lsfd hides raddr= if UDP.RADDR is and UDP.RPORT
               is 0.

               state=SOCK.STATE[ path=UNIX.PATH]

               state=SOCK.STATE[ path=UNIX.PATH] type=SOCK.TYPE

       NLINK <number>
           Link count.

       NS.NAME <string>
           Name (NS.TYPE:[INODE]) of the namespace specified with the

       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.

       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.

       POS <number>
           File position.

       RDEV <string>
           Device ID (if special file).

       SIZE <number>
           File size.

       SOCK.LISTENING <boolean>
           Listening socket.

       SOCK.NETS <number>
           Inode identifying network namespace where the socket belogs

       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 IP address and local TCP port.

       TCP.LPORT <integer>
           Local TCP port.

       TCP.RADDR <string>
           Remote IP address and remote TCP port.

       TCP.RPORT <integer>
           Remote TCP port.

       TID <number>
           Thread ID of the process opening the file.

       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

       UDP.LADDR <string>
           Local IP address and local UDP port.

       UDP.LPORT <integer>
           Local UDP port.

       UDP.RADDR <string>
           Remote IP address and remote UDP port.

       UDP.RPORT <integer>
           Remote UDP port.

       UID <number>
           User ID number.

       UNIX.PATH <string>
           Filesystem pathname for UNIX doamin 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

       Literal is for representing a value directly. See BOOLLIT,
       STRLIT, and NUMLIT. Different data types have different literal

       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 =~.

       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

           COLUMN <boolean> | BOOLLIT | ( BOOLEXP )



           ! BOOLEXP0 | not BOOLEXP0

           COLUMN <string> | STRLIT

           COLUMN <number> | NUMLIT

           true | false

           ( [^\] | \\ | \' | \" )*

           ' CHARS ' | " CHARS "

           [1-9][0-9]* | 0


           == | eq | != | ne


           && | and |  || | or


           < | lt | <= | le | > | gt | >= | ge


           =~ | !~


       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'


       Report the numbers of netlink socket descriptors and unix socket

           # 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         top

       The lsfd command is part of the util-linux package since v2.38.

AUTHORS         top

       Masatake YAMATO <>, Karel Zak <>

SEE ALSO         top

       lsof(8) pidof(1) proc(5) socket(2) stat(2)

REPORTING BUGS         top

       For bug reports, use the issue tracker at

AVAILABILITY         top

       The lsfd command is part of the util-linux package which can be
       downloaded from Linux Kernel Archive
       <>. This page
       is part of the util-linux (a random collection of Linux
       utilities) project. Information about the project can be found at
       ⟨⟩. If you have
       a bug report for this manual page, send it to This page was obtained from the
       project's upstream Git repository
       ⟨git://⟩ on
       2022-12-17. (At that time, the date of the most recent commit
       that was found in the repository was 2022-12-13.) 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

util-linux 2.38.643-57df0      2022-12-17                        LSFD(1)