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 --help*
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 *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 *FILTER EXPRESSION* 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 include::man-common/help-version.adoc[]
117 Each column has a type. Types are surround by < and >.
119 //TRANSLATORS: Keep {colon} untranslated.
120 CAUTION{colon} The names and types of columns are not stable yet.
121 They may be changed in the future releases.
123 AINODECLASS <``string``>::
124 Class of anonymous inode.
127 Association between file and process.
129 BLKDRV <``string``>::
130 Block device driver name resolved by `/proc/devices`.
132 CHRDRV <``string``>::
133 Character device driver name resolved by `/proc/devices`.
135 COMMAND <``string``>::
136 Command of the process opening the file.
138 DELETED <``boolean``>::
139 Reachability from the file system.
142 ID of the device containing the file.
144 DEVTYPE <``string``>::
145 Device type (`blk`, `char`, or `nodev`).
147 ENDPOINT <``string``>::
148 IPC endpoints information communicated with the fd.
150 *lsfd* collects endpoints within the processes that
151 *lsfd* scans; *lsfd* may miss some endpoints
152 if you limits the processes with *-p* option.
154 The format of the column depends on the object associated
159 _PID_,_COMMAND_,_ASSOC_[-r][-w]
161 The last characters ([-r][-w]) represents the read and/or
162 write mode of the endpoint.
165 _PID_,_COMMAND_,_ASSOC_
167 EVENTFD.ID <``number``>::
170 EVENTPOLL.TFDS <``string``>::
171 File descriptors targeted by the eventpoll file.
174 File descriptor for the file.
177 Flags specified when opening the file.
180 User ID number of the file's owner.
182 INET.LADDR <``string``>::
185 INET.RADDR <``string``>::
188 INET6.LADDR <``string``>::
191 INET6.RADDR <``string``>::
197 INOTIFY.INODES <``string``>::
198 Cooked version of INOTIFY.INODES.RAW.
199 The format of the element is
200 _inode-number_,_source-of-inode_.
202 INOTIFY.INODES.RAW <``string``>::
203 List of monitoring inodes. The format of the element
204 is _inode-number_,_device-major_:_device-minor_.
208 // It seems that the manpage backend of asciidoctor has limitations
209 // about emitting text with nested face specifications like:
213 // Not only u but also p is decorated with underline.
215 Raw file name extracted from
216 from ``/proc/``_pid_``/fd/``_fd_ or ``/proc/``_pid_``/map_files/``_region_.
218 KTHREAD <``boolean``>::
219 Whether the process is a kernel thread or not.
221 MAJ:MIN <``string``>::
222 Device ID for special, or ID of device containing file.
224 MAPLEN <``number``>::
225 Length of file mapping (in page).
227 MISCDEV <``string``>::
228 Misc character device name resolved by `/proc/misc`.
237 Cooked version of KNAME. It is mostly same as KNAME.
239 Some files have special formats and information sources:
242 tfds=_EVENTPOLL.TFDS_
248 inodes=_INOTIFY.INODES_
254 protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]]
257 type=_SOCK.TYPE_[ protocol=_PACKET.PROTOCOL_][ iface=_PACKET.IFACE_]
260 pid=_TARGET-PID_ comm=_TARGET-COMMAND_ nspid=_TARGET-NSPIDS_
262 *lsfd* extracts _TARGET-PID_ and _TARGET-NSPIDS_ from
263 ``/proc/``_pid_``/fdinfo/``_fd_.
266 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]
269 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]
272 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]]
275 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]]
282 state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]]
285 clockid=_TIMERFD.CLOCKID_[ remaining=_TIMERFD.REMAINING_ [ interval=_TIMERFD.INTERVAL_]]
289 state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]]
291 *lsfd* hides ``raddr=`` if _UDP.RADDR_ is ``0.0.0.0`` and _UDP.RPORT_ is 0.
295 state=_SOCK.STATE_[ laddr=_UDPLITE.LADDR_ [ raddr=_UDPLITE.RADDR_]]
298 state=_SOCK.STATE_[ path=_UNIX.PATH_]
301 state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_
303 NETLINK.GROUPS <``number``>::
304 Netlink multicast groups.
306 NETLINK.LPORT <``number``>::
307 Netlink local port id.
309 NETLINK.PROTOCOL <``string``>::
315 NS.NAME <``string``>::
316 Name (_NS.TYPE_:[_INODE_]) of the namespace specified with the file.
318 NS.TYPE <``string``>::
319 Type of the namespace specified with the file.
320 The type is `mnt`, `cgroup`, `uts`, `ipc`, `user`, `pid`, `net`,
321 `time`, or `unknown`.
326 PACKET.IFACE <``string``>::
327 Interface name associated with the packet socket.
329 PACKET.PROTOCOL <``string``>::
330 L3 protocol associated with the packet socket.
332 PARTITION <``string``>::
333 Block device name resolved by `/proc/partition`.
336 PID of the process opening the file.
338 PIDFD.COMM <``string``>::
339 Command of the process targeted by the pidfd.
341 PIDFD.NSPID <``string``>::
342 Value of NSpid field in ``/proc/``_pid_``/fdinfo/``_fd_ of the pidfd.
344 Quoted from kernel/fork.c of Linux source tree:
347 If pid namespaces are supported then this function will also print
348 the pid of a given pidfd refers to for all descendant pid namespaces
349 starting from the current pid namespace of the instance, i.e. the
350 Pid field and the first entry in the NSpid field will be identical.
352 Note that this differs from the Pid and NSpid fields in
353 /proc/<pid>/status where Pid and NSpid are always shown relative to
354 the pid namespace of the procfs instance.
357 PIDFD.PID <``number``>::
358 PID of the process targeted by the pidfd.
361 ICMP echo request id used on the PING socket.
366 RAW.PROTOCOL <``number``>::
367 Protocol number of the raw socket.
370 Device ID (if special file).
372 SIGNALFD.MASK <``string``>::
378 SOCK.LISTENING <``boolean``>::
381 SOCK.NETS <``number``>::
382 Inode identifying network namespace where the socket belongs to.
384 SOCK.PROTONAME <``string``>::
387 SOCK.STATE <``string``>::
390 SOCK.TYPE <``string``>::
391 Type of socket. Here type means the second parameter of
402 SOURCE <``string``>::
403 File system, partition, or device containing the file.
405 STTYPE <``string``>::
406 Raw file types returned from *stat*(2): BLK, CHR, DIR, FIFO, LINK, REG, SOCK, or UNKN.
408 TCP.LADDR <``string``>::
409 Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.
411 TCP.LPORT <``number``>::
414 TCP.RADDR <``string``>::
415 Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.
417 TCP.RPORT <``number``>::
421 Thread ID of the process opening the file.
423 TIMERFD.CLOCKID <``string``>::
426 TIMERFD.INTERVAL <``number``>::
429 TIMERFD.REMAINING <``number``>::
432 TUN.IFACE <``string``>::
433 Network intrface behind the tun device.
436 Cooked version of STTYPE. It is same as STTYPE with exceptions.
437 For SOCK, print the value for SOCK.PROTONAME.
438 For UNKN, print the value for AINODECLASS if SOURCE is anon_inodefs.
440 UDP.LADDR <``string``>::
441 Local IP address and local UDP port.
443 UDP.LPORT <``number``>::
446 UDP.RADDR <``string``>::
447 Remote IP address and remote UDP port.
449 UDP.RPORT <``number``>::
452 UDPLITE.LADDR <``string``>::
453 Local IP address and local UDPLite port.
455 UDPLITE.LPORT <``number``>::
458 UDPLITE.RADDR <``string``>::
459 Remote IP address and remote UDPLite port.
461 UDPLITE.RPORT <``number``>::
467 UNIX.PATH <``string``>::
468 Filesystem pathname for UNIX domain socket.
475 *lsfd* evaluates the expression passed to *--filter* option every time
476 before printing a file line. *lsfd* prints the line only if the result
477 of evaluation is `true`.
479 An expression consists of column names, literals and, operators like:
480 `DELETED`, `(PID == 1)`, `(NAME == "/etc/passwd")`, `(PID == 1) && DELETED`.
481 `DELETED`, `PID`, and `NAME` are column names in the example.
482 `1` and "/etc/passwd" are literals.
483 `==` and `&&` are operators.
485 Before evaluation, *lsfd* substitutes column names in the given
486 expression with actual column values in the line. There are three
487 different data types: `boolean`, `string`, and `number`. For columns
488 with a `boolean` type, the value can be stand-alone. For `string` and
489 `number` values, the value must be an operand of an operator, for
490 example, `(PID == 1)`. See *OUTPUT COLUMNS* about the types of
493 Literal is for representing a value directly. See BOOLLIT, STRLIT, and
494 NUMLIT. Different data types have different literal syntax.
496 An operator works with one or two operand(s). An operator has an
497 expectation about the data type(s) of its operands. Giving an
498 unexpected data type to an operator causes a syntax error.
500 Operators taking two operands are `and`, `or`, `eq`, `ne`, `le`, `lt`, `ge`, `gt`, `=~`, `!~`.
501 Alphabetically named operators have C-language
502 flavored aliases: `&&`, `||`, `==`, `!=`, `<`, `<=`, `>=`, and `>`.
504 `!` is the only operator that takes one operand.
506 `eq`, `ne`, and their aliases expect operands have the same data type.
507 Applying these operators return a `boolean`.
509 `and`, `or`, `not` and their aliases expect operands have `boolean` data
510 type. Applying these operators return a `boolean`.
512 `lt`, `le`, `gt`, `ge`, and their aliases expect operands have
513 `number` data types. Applying these operators return a `boolean`.
515 `=~` is for regular expression matching; if a string at the right side
516 matches a regular expression at the left side, the result is true.
517 The right side operand must be a string literal. See STRLIT about the
520 `!~` is a short-hand version of `not (STR =~ PAT)`; it inverts the
525 The current implementation does not define precedences within
526 operators. Use `(` and `)` explicitly for grouping the
527 sub-expressions if your expression uses more than two operators.
529 About `number` typed values, the filter engine supports only
530 non-negative integers, and non-negative floating point numbers.
532 === Semi-formal syntax
534 //TRANSLATORS: In the following messages, translate only the <``variables``>.
537 BOOLEXP0 :: COLUMN <``boolean``> | BOOLLIT | _(_ BOOLEXP _)_
539 BOOLEXP :: BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG
541 COLUMN :: [\_A-Za-z][-_:A-Za-z0-9]*
543 BOOLOP1 :: _!_ BOOLEXP0 | _not_ BOOLEXP0
545 STREXP :: COLUMN <``string``> | STRLIT
547 NUMEXP :: COLUMN <``number``> | NUMLIT
549 BOOLLIT :: _true_ | _false_
551 CHARS :: ( [^\] | _\\_ | _\'_ | _\"_ )*
553 STRLIT :: _'_ CHARS _'_ | _"_ CHARS _"_
555 NUMLIT :: INTLIT | FNUMLIT
557 INTLIT :: [1-9][0-9]* | _0_
559 FNUMLIT :: INTLIT _._ [0-9][0-9]*
561 BOOLOP2 :: STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0
563 OP2 :: _==_ | _eq_ | _!=_ | _ne_
565 BOOLOP2BL :: BOOLEXP0 OP2BL BOOLEXP0
567 OP2BL :: _&&_ | _and_ | _||_ | _or_
569 BOOLOP2CMP :: NUMEXP OP2CMP NUMEXP
571 OP2CMP :: _<_ | _lt_ | _\<=_ | _le_ | _>_ | _gt_ | _>=_ | _ge_
573 BOOLOP2REG :: STREXP OP2REG STRLIT
575 OP2REG :: _=~_ | _!~_
579 *lsfd* has few options for filtering. In most of cases, what you should
580 know is *-Q* (or *--filter*) option. Combined with *-o* (or
581 *--output*) option, you can customize the output as you want.
583 //TRANSLATORS: In the following messages, don't forget to add whitespace at the end!
584 List files associated with PID 1 and PID 2 processes: ::
586 # lsfd -Q '(PID == 1) or (PID == 2)'
589 Do the same in an alternative way: ::
591 # lsfd -Q '(PID == 1) || (PID == 2)'
594 Do the same in a more efficient way: ::
599 Whitescapes can be used instead of a comma: ::
604 Utilize *pidof*(1) for list the files associated with "firefox": ::
606 # lsfd --pid "$(pidof firefox)"
609 List the 1st file descriptor opened by PID 1 process: ::
611 # lsfd -Q '(PID == 1) and (FD == 1)'
614 Do the same in an alternative way: ::
616 # lsfd -Q '(PID == 1) && (FD == 1)'
619 List all running executables: ::
621 # lsfd -Q 'ASSOC == "exe"'
624 Do the same in an alternative way: ::
626 # lsfd -Q 'ASSOC eq "exe"'
629 Do the same but print only file names: ::
631 # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
634 List deleted files associated to processes: ::
639 List non-regular files: ::
641 # lsfd -Q 'TYPE != "REG"'
644 List block devices: ::
646 # lsfd -Q 'DEVTYPE == "blk"'
649 Do the same with TYPE column: ::
651 # lsfd -Q 'TYPE == "BLK"'
654 List files including "dconf" directory in their names: ::
656 # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
659 List files opened in a QEMU virtual machine: ::
661 # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
664 Hide files associated to kernel threads: ::
669 List timerfd files expired within 0.5 seconds: ::
671 # lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
676 Report the numbers of netlink socket descriptors and unix socket descriptors: ::
678 # lsfd --summary=only \
679 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
680 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
686 Do the same but print in JSON format: ::
688 # lsfd --summary=only --json \
689 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
690 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
695 "counter": "netlink sockets"
698 "counter": "unix sockets"
707 The *lsfd* command is part of the util-linux package since v2.38.
711 mailto:yamato@redhat.com[Masatake YAMATO],
712 mailto:kzak@redhat.com[Karel Zak]
722 include::man-common/bugreports.adoc[]
724 include::man-common/footer.adoc[]
727 include::man-common/translation.adoc[]