1 //po4a: entry man manual
3 Copyright 2021 Red Hat, Inc.
5 This file may be copied under the terms of the GNU Public License.
9 :man manual: User Commands
10 :man source: util-linux {release-version}
17 lsfd - list file descriptors
25 *lsfd* is intended to be a modern replacement for *lsof*(8) on Linux systems.
26 Unlike *lsof*, *lsfd* is specialized to Linux kernel; it supports Linux
27 specific features like namespaces with simpler code. *lsfd* is not a
28 drop-in replacement for *lsof*; they are different in the command line
29 interface and output formats.
31 The default output is subject to change. So whenever possible, you should avoid using
32 default outputs in your scripts. Always explicitly define expected columns by using
33 *--output* _columns-list_ in environments where a stable output is required.
35 *lsfd* uses Libsmartcols for output formatting and filtering. See the description of *--output*
36 option for customizing the output format, and *--filter* option for filtering. Use *lsfd --list-columns*
37 to get a list of all available columns.
42 List in threads level.
45 Use JSON output format.
47 *-n*, *--noheadings*::
50 *-o*, *--output* _list_::
51 Specify which output columns to print. See the *OUTPUT COLUMNS*
52 section for details of available columns.
54 The default list of columns may be extended if _list_ is specified in
55 the format +_list_ (e.g., *lsfd -o +DELETED*).
58 Use raw output format.
61 Don't truncate text in columns.
63 *-p*, *--pid* _pids_::
64 Collect information only for specified processes.
65 _pids_ is a list of pids. A comma or whitespaces can be used as separators.
66 You can use this option with *pidof*(1). See *FILTER EXAMPLES*.
68 Both *-Q* option with an expression including PID, e.g. -Q (PID == 1),
69 and *-p* option, e.g. -p 1, may print the same output but using *-p*
70 option is much more efficient because *-p* option works at a much earlier
71 stage of processing than the *-Q* option.
73 *-i*[4|6], *--inet*[=4|=6]::
74 List only IPv4 sockets and/or IPv6 sockets.
76 *-Q*, *--filter* _expr_::
77 Print only the files matching the condition represented by the _expr_.
78 See also *scols-filter*(5) and *FILTER EXAMPLES*.
80 *-C*, *--counter* __label__:__filter_expr__::
81 Define a custom counter used in *--summary* output. *lsfd* makes a
82 counter named _label_. During collect information, *lsfd* counts files
83 matching _filter_expr_, and stores the counted number to the
84 counter named _label_. *lsfd* applies filters defined with *--filter*
85 options before counting; files excluded by the filters are not counted.
87 See *scols-filter*(5) about _filter_expr_.
88 _label_ should not include `{` nor `:`. You can define multiple
89 counters by specifying this option multiple times.
91 See also *COUNTER EXAMPLES*.
93 *--summary*[=_when_]::
94 This option controls summary lines output. The optional argument _when_
95 can be *only*, *append* or *never*. If the _when_ argument is omitted,
96 it defaults to *only*.
98 The summary reports counters. A counter consists of a label and an
99 integer value. *--counter* is the option for defining a counter. If
100 a user defines no counter, *lsfd* uses the definitions of pre-defined
101 built-in counters (default counters) to make the summary output.
103 CAUTION{colon} Using *--summary* and *--json* may make the output broken. Only combining *--summary*=*only* and *--json* is valid.
104 //TRANSLATORS: Keep {colon} untranslated.
107 Dump the internal data structure for the filter and exit. This is useful
108 only for *lsfd* developers.
111 Dump the definition of counters used in *--summary* output.
113 *-H*, *--list-columns*::
114 List available columns that you can specify at *--output* option.
116 include::man-common/help-version.adoc[]
120 Each column has a type. Types are surround by < and >.
122 //TRANSLATORS: Keep {colon} untranslated.
123 CAUTION{colon} The names and types of columns are not stable yet.
124 They may be changed in the future releases.
126 AINODECLASS <``string``>::
127 Class of anonymous inode.
130 Association between file and process.
132 BLKDRV <``string``>::
133 Block device driver name resolved by `/proc/devices`.
135 BPF-MAP.ID <``number``>::
138 BPF-MAP.TYPE <``string``>::
139 Decoded name of bpf map type.
141 BPF-MAP.TYPE.RAW <``number``>::
144 BPF.NAME <``string``>::
147 BPF-PROG.ID <``number``>::
150 BPF-PROG.TYPE <``string``>::
151 Decoded name of bpf program type.
153 BPF-PROG.TYPE.RAW <``number``>::
154 Bpf program type (raw).
156 CHRDRV <``string``>::
157 Character device driver name resolved by `/proc/devices`.
159 COMMAND <``string``>::
160 Command of the process opening the file.
162 DELETED <``boolean``>::
163 Reachability from the file system.
166 ID of the device containing the file.
168 DEVTYPE <``string``>::
169 Device type (`blk`, `char`, or `nodev`).
171 ENDPOINT <``string``>::
172 IPC endpoints information communicated with the fd.
174 *lsfd* collects endpoints within the processes that
175 *lsfd* scans; *lsfd* may miss some endpoints
176 if you limits the processes with *-p* option.
178 The format of the column depends on the object associated
183 ptmx and pts sources:::
184 _PID_,_COMMAND_,_ASSOC_[-r][-w]
186 The last characters ([-r][-w]) represents the read and/or
187 write mode of the endpoint.
190 _PID_,_COMMAND_,_ASSOC_
193 _PID_,_COMMAND_,_ASSOC_[-r?][-w?]
195 About the last characters ([-r?][-w?]), see the description
198 EVENTFD.ID <``number``>::
201 EVENTPOLL.TFDS <``string``>::
202 File descriptors targeted by the eventpoll file.
205 File descriptor for the file.
208 Flags specified when opening the file.
211 User ID number of the file's owner.
213 INET.LADDR <``string``>::
216 INET.RADDR <``string``>::
219 INET6.LADDR <``string``>::
222 INET6.RADDR <``string``>::
228 INOTIFY.INODES <``string``>::
229 Cooked version of INOTIFY.INODES.RAW.
230 The format of the element is
231 _inode-number_,_source-of-inode_.
233 INOTIFY.INODES.RAW <``string``>::
234 List of monitoring inodes. The format of the element
235 is _inode-number_,_device-major_:_device-minor_.
239 // It seems that the manpage backend of asciidoctor has limitations
240 // about emitting text with nested face specifications like:
244 // Not only u but also p is decorated with underline.
246 Raw file name extracted from
247 from ``/proc/``_pid_``/fd/``_fd_ or ``/proc/``_pid_``/map_files/``_region_.
249 KTHREAD <``boolean``>::
250 Whether the process is a kernel thread or not.
252 MAJ:MIN <``string``>::
253 Device ID for special, or ID of device containing file.
255 MAPLEN <``number``>::
256 Length of file mapping (in page).
258 MISCDEV <``string``>::
259 Misc character device name resolved by `/proc/misc`.
268 Cooked version of KNAME. It is mostly same as KNAME.
270 Some files have special formats and information sources:
273 id=_BPF-MAP.ID_ type=_BPF-MAP.TYPE_[ name=_BPF.NAME_]
276 id=_BPF-PROG.ID_ type=_BPF-PROG.TYPE_[ name=_BPF.NAME_]
279 tfds=_EVENTPOLL.TFDS_
285 inodes=_INOTIFY.INODES_
291 protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]]
294 type=_SOCK.TYPE_[ protocol=_PACKET.PROTOCOL_][ iface=_PACKET.IFACE_]
297 pid=_TARGET-PID_ comm=_TARGET-COMMAND_ nspid=_TARGET-NSPIDS_
299 *lsfd* extracts _TARGET-PID_ and _TARGET-NSPIDS_ from
300 ``/proc/``_pid_``/fdinfo/``_fd_.
303 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]
306 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]
309 tty-index=_PTMX.TTY-INDEX_
311 *lsfd* extracts _PTMX.TTY-INDEX_ from
312 ``/proc/``_pid_``/fdinfo/``_fd_.
315 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]]
318 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]]
325 state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]]
328 clockid=_TIMERFD.CLOCKID_[ remaining=_TIMERFD.REMAINING_ [ interval=_TIMERFD.INTERVAL_]]
332 state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]]
334 *lsfd* hides ``raddr=`` if _UDP.RADDR_ is ``0.0.0.0`` and _UDP.RPORT_ is 0.
338 state=_SOCK.STATE_[ laddr=_UDPLITE.LADDR_ [ raddr=_UDPLITE.RADDR_]]
341 state=_SOCK.STATE_[ path=_UNIX.PATH_]
344 state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_
347 Note that `(deleted)` markers are removed from this column.
348 Refer to _KNAME_, _DELETED_, or _XMODE_ to know the
349 readability of the file from the file system.
352 NETLINK.GROUPS <``number``>::
353 Netlink multicast groups.
355 NETLINK.LPORT <``number``>::
356 Netlink local port id.
358 NETLINK.PROTOCOL <``string``>::
364 NS.NAME <``string``>::
365 Name (_NS.TYPE_:[_INODE_]) of the namespace specified with the file.
367 NS.TYPE <``string``>::
368 Type of the namespace specified with the file.
369 The type is `mnt`, `cgroup`, `uts`, `ipc`, `user`, `pid`, `net`,
370 `time`, or `unknown`.
375 PACKET.IFACE <``string``>::
376 Interface name associated with the packet socket.
378 PACKET.PROTOCOL <``string``>::
379 L3 protocol associated with the packet socket.
381 PARTITION <``string``>::
382 Block device name resolved by `/proc/partition`.
385 PID of the process opening the file.
387 PIDFD.COMM <``string``>::
388 Command of the process targeted by the pidfd.
390 PIDFD.NSPID <``string``>::
391 Value of NSpid field in ``/proc/``_pid_``/fdinfo/``_fd_ of the pidfd.
393 Quoted from kernel/fork.c of Linux source tree:
396 If pid namespaces are supported then this function will also print
397 the pid of a given pidfd refers to for all descendant pid namespaces
398 starting from the current pid namespace of the instance, i.e. the
399 Pid field and the first entry in the NSpid field will be identical.
401 Note that this differs from the Pid and NSpid fields in
402 /proc/<pid>/status where Pid and NSpid are always shown relative to
403 the pid namespace of the procfs instance.
406 PIDFD.PID <``number``>::
407 PID of the process targeted by the pidfd.
410 ICMP echo request id used on the PING socket.
415 RAW.PROTOCOL <``number``>::
416 Protocol number of the raw socket.
419 Device ID (if special file).
421 SIGNALFD.MASK <``string``>::
427 SOCK.LISTENING <``boolean``>::
430 SOCK.NETS <``number``>::
431 Inode identifying network namespace where the socket belongs to.
433 SOCK.PROTONAME <``string``>::
436 SOCK.SHUTDOWN <``string``>::
437 Shutdown state of socket.
440 If the first character is _r_, the receptions are allowed.
441 If it is _-_, the receptions are disallowed.
442 If it is _?_, the state is unknown.
445 If the second character is _w_, the transmissions are allowed.
446 If it is _-_, the transmissions are disallowed.
447 If it is _?_, the state is unknown.
449 SOCK.STATE <``string``>::
452 SOCK.TYPE <``string``>::
453 Type of socket. Here type means the second parameter of
464 SOURCE <``string``>::
465 File system, partition, or device containing the file.
467 STTYPE <``string``>::
468 Raw file types returned from *stat*(2): BLK, CHR, DIR, FIFO, LINK, REG, SOCK, or UNKN.
470 TCP.LADDR <``string``>::
471 Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.
473 TCP.LPORT <``number``>::
476 TCP.RADDR <``string``>::
477 Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.
479 TCP.RPORT <``number``>::
483 Thread ID of the process opening the file.
485 TIMERFD.CLOCKID <``string``>::
488 TIMERFD.INTERVAL <``number``>::
491 TIMERFD.REMAINING <``number``>::
494 PTMX.TTY-INDEX <``number``>::
495 TTY index of the counterpart.
497 TUN.IFACE <``string``>::
498 Network interface behind the tun device.
501 Cooked version of STTYPE. It is same as STTYPE with exceptions.
502 For SOCK, print the value for SOCK.PROTONAME.
503 For UNKN, print the value for AINODECLASS if SOURCE is anon_inodefs.
505 UDP.LADDR <``string``>::
506 Local IP address and local UDP port.
508 UDP.LPORT <``number``>::
511 UDP.RADDR <``string``>::
512 Remote IP address and remote UDP port.
514 UDP.RPORT <``number``>::
517 UDPLITE.LADDR <``string``>::
518 Local IP address and local UDPLite port.
520 UDPLITE.LPORT <``number``>::
523 UDPLITE.RADDR <``string``>::
524 Remote IP address and remote UDPLite port.
526 UDPLITE.RPORT <``number``>::
532 UNIX.PATH <``string``>::
533 Filesystem pathname for UNIX domain socket.
539 Extended version of _MODE_. This column may grow; new letters may be
540 appended to _XMODE_ when *lsfd* supports a new state of file descriptors
541 and/or memory mappings.
544 opened of mapped for reading. This is also in _MODE_.
547 opened of mapped for writing. This is also in _MODE_.
550 mapped for executing the code. This is also in _MODE_.
553 deleted from the file system. See also _DELETED_.
556 locked or leased. _l_ represents a read, a shared lock or a read lease.
557 _L_ represents a write or an exclusive lock or a write lease. If both
558 read/shared and write/exclusive locks or leases are taken by a file
559 descriptor, _L_ is used as the flag.
562 Multiplexed. If the file descriptor is targeted by a eventpoll file
563 or classical system calls for multiplexing (select, pselect, poll, and
564 ppoll), this bit flag is set. Note that if an invocation of the
565 classical system calls is interrupted, *lsfd* may fail to mark _m_
566 on the file descriptors monitored by the invocation.
567 See *restart_syscall*(2).
571 *lsfd* has few options for filtering. In most of cases, what you should
572 know is *-Q* (or *--filter*) option. Combined with *-o* (or
573 *--output*) option, you can customize the output as you want.
575 //TRANSLATORS: In the following messages, don't forget to add whitespace at the end!
576 List files associated with PID 1 and PID 2 processes: ::
578 # lsfd -Q '(PID == 1) or (PID == 2)'
581 Do the same in an alternative way: ::
583 # lsfd -Q '(PID == 1) || (PID == 2)'
586 Do the same in a more efficient way: ::
591 Whitescapes can be used instead of a comma: ::
596 Utilize *pidof*(1) for list the files associated with "firefox": ::
598 # lsfd --pid "$(pidof firefox)"
601 List the 1st file descriptor opened by PID 1 process: ::
603 # lsfd -Q '(PID == 1) and (FD == 1)'
606 Do the same in an alternative way: ::
608 # lsfd -Q '(PID == 1) && (FD == 1)'
611 List all running executables: ::
613 # lsfd -Q 'ASSOC == "exe"'
616 Do the same in an alternative way: ::
618 # lsfd -Q 'ASSOC eq "exe"'
621 Do the same but print only file names: ::
623 # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
626 List deleted files associated to processes: ::
631 List non-regular files: ::
633 # lsfd -Q 'TYPE != "REG"'
636 List block devices: ::
638 # lsfd -Q 'DEVTYPE == "blk"'
641 Do the same with TYPE column: ::
643 # lsfd -Q 'TYPE == "BLK"'
646 List files including "dconf" directory in their names: ::
648 # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
651 List files opened in a QEMU virtual machine: ::
653 # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
656 Hide files associated to kernel threads: ::
661 List timerfd files expired within 0.5 seconds: ::
663 # lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
668 Report the numbers of netlink socket descriptors and unix socket descriptors: ::
670 # lsfd --summary=only \
671 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
672 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
678 Do the same but print in JSON format: ::
680 # lsfd --summary=only --json \
681 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
682 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
687 "counter": "netlink sockets"
690 "counter": "unix sockets"
699 The *lsfd* command is part of the util-linux package since v2.38.
703 mailto:yamato@redhat.com[Masatake YAMATO],
704 mailto:kzak@redhat.com[Karel Zak]
718 include::man-common/bugreports.adoc[]
720 include::man-common/footer.adoc[]
723 include::man-common/translation.adoc[]