1LSFD(1) User Commands LSFD(1)
2
6 lsfd - list file descriptors
7
9 lsfd [option]
10
12 lsfd is intended to be a modern replacement for lsof(8) on Linux
13 systems. Unlike lsof, lsfd is specialized to Linux kernel; it supports
14 Linux specific features like namespaces with simpler code. lsfd is not
15 a drop-in replacement for lsof; they are different in the command line
16 interface and output formats.
17 The default output is subject to change. So whenever possible, you
19 should avoid using default outputs in your scripts. Always explicitly
20 define expected columns by using --output columns-list in environments
21 where a stable output is required.
22 lsfd uses Libsmartcols for output formatting and filtering. See the
24 description of --output option for customizing the output format, and
25 --filter option for filtering. Use lsfd --help to get a list of all
26 available columns.
27
29 -l, --threads
30 List in threads level.
31 -J, --json
33 Use JSON output format.
34 -n, --noheadings
36 Don’t print headings.
37 -o, --output list
39 Specify which output columns to print. See the OUTPUT COLUMNS
40 section for details of available columns.
41 The default list of columns may be extended if list is specified in
43 the format +list (e.g., lsfd -o +DELETED).
44 -r, --raw
46 Use raw output format.
47 --notruncate
49 Don’t truncate text in columns.
50 -p, --pid pids
52 Collect information only for specified processes. pids is a list of
53 pids. A comma or whitespaces can be used as separators. You can use
54 this option with pidof(1). See FILTER EXAMPLES.
55 Both -Q option with an expression including PID, e.g. -Q (PID ==
57 1), and -p option, e.g. -p 1, may print the same output but using
58 -p option is much more efficient because -p option works at a much
59 earlier stage of processing than the -Q option.
60 -i[4|6], --inet[=4|6]
62 List only IPv4 sockets and/or IPv6 sockets.
63 -Q, --filter expr
65 Print only the files matching the condition represented by the
66 expr. See also FILTER EXAMPLES.
67 -C, --counter label:filter_expr
69 Define a custom counter used in --summary output. lsfd makes a
70 counter named label. During collect information, lsfd counts files
71 matching filter_expr, and stores the counted number to the counter
72 named label. lsfd applies filters defined with --filter options
73 before counting; files excluded by the filters are not counted.
74 See FILTER EXPRESSION about filter_expr. label should not include {
76 nor :. You can define multiple counters by specifying this option
77 multiple times.
78 See also COUNTER EXAMPLES.
80 --summary[=when]
82 This option controls summary lines output. The optional argument
83 when can be only, append or never. If the when argument is omitted,
84 it defaults to only.
85 The summary reports counters. A counter consists of a label and an
87 integer value. --counter is the option for defining a counter. If a
88 user defines no counter, lsfd uses the definitions of pre-defined
89 built-in counters (default counters) to make the summary output.
90 CAUTION: Using --summary and --json may make the output broken.
92 Only combining --summary=only and --json is valid.
93 --debug-filter
95 Dump the internal data structure for the filter and exit. This is
96 useful only for lsfd developers.
97 --dump-counters
99 Dump the definition of counters used in --summary output.
100 -h, --help
102 Display help text and exit.
103 -V, --version
105 Print version and exit.
106
108 Each column has a type. Types are surround by < and >.
109 CAUTION: The names and types of columns are not stable yet. They may be
111 changed in the future releases.
112 AINODECLASS <string>
114 Class of anonymous inode.
115 ASSOC <string>
117 Association between file and process.
118 BLKDRV <string>
120 Block device driver name resolved by /proc/devices.
121 CHRDRV <string>
123 Character device driver name resolved by /proc/devices.
124 COMMAND <string>
126 Command of the process opening the file.
127 DELETED <boolean>
129 Reachability from the file system.
130 DEV <string>
132 ID of the device containing the file.
133 DEVTYPE <string>
135 Device type (blk, char, or nodev).
136 ENDPOINT <string>
138 IPC endpoints information communicated with the fd. The format of
139 the column depends on the object associated with the fd:
140 FIFO type
142 PID,COMMAND,ASSOC[-r][-w]
143 The last characters ([-r][-w]) represents the read and/or write
145 mode of the endpoint.
146 lsfd collects endpoints within the processes that lsfd scans; lsfd
148 may miss some endpoints if you limits the processes with -p option.
149 FD <number>
151 File descriptor for the file.
152 FLAGS <string>
154 Flags specified when opening the file.
155 FUID <number>
157 User ID number of the file’s owner.
158 INET.LADDR <string>
160 Local IP address.
161 INET.RADDR <string>
163 Remote IP address.
164 INET6.LADDR <string>
166 Local IP6 address.
167 INET6.RADDR <string>
169 Remote IP6 address.
170 INODE <number>
172 Inode number.
173 KNAME <string>
175 Raw file name extracted from from /proc/pid/fd/fd or
176 /proc/pid/map_files/region.
177 KTHREAD <boolean>
179 Whether the process is a kernel thread or not.
180 MAJ:MIN <string>
182 Device ID for special, or ID of device containing file.
183 MAPLEN <number>
185 Length of file mapping (in page).
186 MISCDEV <string>
188 Misc character device name resolved by /proc/misc.
189 MNTID <number>
191 Mount ID.
192 MODE <string>
194 Access mode (rwx).
195 NAME <string>
197 Cooked version of KNAME. It is mostly same as KNAME.
198 Some files have special formats and information sources:
200 NETLINK
202 protocol=NETLINK.PROTOCOL[ lport=NETLINK.LPORT[
203 group=NETLINK.GROUPS]]
204 PACKET
206 type=SOCK.TYPE[ protocol=PACKET.PROTOCOL][ iface=PACKET.IFACE]
207 pidfd
209 pid=TARGET-PID comm=TARGET-COMMAND nspid=TARGET-NSPIDS
210 lsfd extracts TARGET-PID and TARGET-NSPIDS from
212 /proc/pid/fdinfo/fd.
213 PING
215 state=SOCK.STATE[ id=PING.ID][ laddr=INET.LADDR [
216 raddr=INET.RADDR]]
217 PINGv6
219 state=SOCK.STATE[ id=PING.ID][ laddr=INET6.LADDR [
220 raddr=INET6.RADDR]]
221 RAW
223 state=SOCK.STATE[ protocol=RAW.PROTOCOL [ laddr=INET.LADDR [
224 raddr=INET.RADDR]]]
225 RAWv6
227 state=SOCK.STATE[ protocol=RAW.PROTOCOL [ laddr=INET6.LADDR [
228 raddr=INET6.RADDR]]]
229 TCP, TCPv6
231 state=SOCK.STATE[ laddr=TCP.LADDR [ raddr=TCP.RADDR]]
232 UDP, UDPv6
234 state=SOCK.STATE[ laddr=UDP.LADDR [ raddr=UDP.RADDR]]
235 lsfd hides raddr= if UDP.RADDR is 0.0.0.0 and UDP.RPORT is 0.
237 UDP-LITE, UDPLITEv6
239 state=SOCK.STATE[ laddr=UDPLITE.LADDR [ raddr=UDPLITE.RADDR]]
240 UNIX-STREAM
242 state=SOCK.STATE[ path=UNIX.PATH]
243 UNIX
245 state=SOCK.STATE[ path=UNIX.PATH] type=SOCK.TYPE
246 NETLINK.GROUPS <number>>
248 Netlink multicast groups.
249 NETLINK.LPORT <number>>
251 Netlink local port id.
252 NETLINK.PROTOCOL <string>>
254 Netlink protocol.
255 NLINK <number>
257 Link count.
258 NS.NAME <string>
260 Name (NS.TYPE:[INODE]) of the namespace specified with the file.
261 NS.TYPE <string>
263 Type of the namespace specified with the file. The type is mnt,
264 cgroup, uts, ipc, user, pid, net, time, or unknown.
265 OWNER <string>
267 Owner of the file.
268 PACKET.IFACE <string>
270 Interface name associated with the packet socket.
271 PACKET.PROTOCOL <string>
273 L3 protocol associated with the packet socket.
274 PARTITION <string>
276 Block device name resolved by /proc/partition.
277 PID <number>
279 PID of the process opening the file.
280 PIDFD.COMM <string>
282 Command of the process targeted by the pidfd.
283 PIDFD.NSPID <string>
285 Value of NSpid field in /proc/pid/fdinfo/fd of the pidfd.
286 Quoted from kernel/fork.c of Linux source tree:
288 If pid namespaces are supported then this function will
290 also print the pid of a given pidfd refers to for all
291 descendant pid namespaces starting from the current pid
292 namespace of the instance, i.e. the Pid field and the
293 first entry in the NSpid field will be identical.
294 Note that this differs from the Pid and NSpid fields in
296 /proc/<pid>/status where Pid and NSpid are always shown
297 relative to the pid namespace of the procfs instance.
298 PIDFD.PID <number>
300 PID of the process targeted by the pidfd.
301 PING.ID <`number`>
303 ICMP echo request id used on the PING socket.
304 POS <number>
306 File position.
307 RAW.PROTOCOL <number>
309 Protocol number of the raw socket.
310 RDEV <string>
312 Device ID (if special file).
313 SIZE <number>
315 File size.
316 SOCK.LISTENING <boolean>
318 Listening socket.
319 SOCK.NETS <number>
321 Inode identifying network namespace where the socket belongs to.
322 SOCK.PROTONAME <string>
324 Protocol name.
325 SOCK.STATE <string>
327 State of socket.
328 SOCK.TYPE <string>
330 Type of socket. Here type means the second parameter of socket
331 system call:
332 • stream
334 • dgram
336 • raw
338 • rdm
340 • seqpacket
342 • dccp
344 • packet
346 SOURCE <string>
348 File system, partition, or device containing the file.
349 STTYPE <string>
351 Raw file types returned from stat(2): BLK, CHR, DIR, FIFO, LINK,
352 REG, SOCK, or UNKN.
353 TCP.LADDR <string>
355 Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.
356 TCP.LPORT <integer>
358 Local TCP port.
359 TCP.RADDR <string>
361 Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.
362 TCP.RPORT <integer>
364 Remote TCP port.
365 TID <number>
367 Thread ID of the process opening the file.
368 TYPE <string>
370 Cooked version of STTYPE. It is same as STTYPE with exceptions. For
371 SOCK, print the value for SOCK.PROTONAME. For UNKN, print the value
372 for AINODECLASS if SOURCE is anon_inodefs.
373 UDP.LADDR <string>
375 Local IP address and local UDP port.
376 UDP.LPORT <integer>
378 Local UDP port.
379 UDP.RADDR <string>
381 Remote IP address and remote UDP port.
382 UDP.RPORT <integer>
384 Remote UDP port.
385 UDPLITE.LADDR <string>
387 Local IP address and local UDPLite port.
388 UDPLITE.LPORT <integer>
390 Local UDP port.
391 UDPLITE.RADDR <string>
393 Remote IP address and remote UDPLite port.
394 UDPLITE.RPORT <integer>
396 Remote UDP port.
397 UID <number>
399 User ID number.
400 UNIX.PATH <string>
402 Filesystem pathname for UNIX domain socket.
403 USER <string>
405 User of the process.
406
408 lsfd evaluates the expression passed to --filter option every time
409 before printing a file line. lsfd prints the line only if the result of
410 evaluation is true.
411 An expression consists of column names, literals and, operators like:
413 DELETED, (PID == 1), (NAME == "/etc/passwd"), (PID == 1) && DELETED.
414 DELETED, PID, and NAME are column names in the example. 1 and
415 "/etc/passwd" are literals. == and && are operators.
416 Before evaluation, lsfd substitutes column names in the given
418 expression with actual column values in the line. There are three
419 different data types: boolean, string, and number. For columns with a
420 boolean type, the value can be stand-alone. For string and number
421 values, the value must be an operand of an operator, for example, (PID
422 == 1). See OUTPUT COLUMNS about the types of columns.
423 Literal is for representing a value directly. See BOOLLIT, STRLIT, and
425 NUMLIT. Different data types have different literal syntax.
426 An operator works with one or two operand(s). An operator has an
428 expectation about the data type(s) of its operands. Giving an
429 unexpected data type to an operator causes a syntax error.
430 Operators taking two operands are and, or, eq, ne, le, lt, ge, gt, =~,
432 !~. Alphabetically named operators have C-language flavored aliases:
433 &&, ||, ==, !=, <, ⇐, >=, and >.
434 ! is the only operator that takes one operand.
436 eq, ne, and their aliases expect operands have the same data type.
438 Applying these operators return a boolean.
439 and, or, not and their aliases expect operands have boolean data type.
441 Applying these operators return a boolean.
442 lt, le, gt, ge, and their aliases expect operands have number data
444 types. Applying these operators return a boolean.
445 =~ is for regular expression matching; if a string at the right side
447 matches a regular expression at the left side, the result is true. The
448 right side operand must be a string literal. See STRLIT about the
449 syntax.
450 !~ is a short-hand version of not (STR =~ PAT); it inverts the result
452 of =~.
453 Limitations
455 The current implementation does not define precedences within
456 operators. Use ( and ) explicitly for grouping the sub-expressions if
457 your expression uses more than two operators.
458 About number typed values, the filter engine supports only non-negative
460 integers.
461 Semi-formal syntax
463 EXPR
464 BOOLEXP
465 BOOLEXP0
467 COLUMN <boolean> | BOOLLIT | ( BOOLEXP )
468 BOOLEXP
470 BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG
471 COLUMN
473 [_A-Za-z][-_:A-Za-z0-9]*
474 BOOLOP1
476 ! BOOLEXP0 | not BOOLEXP0
477 STREXP
479 COLUMN <string> | STRLIT
480 NUMEXP
482 COLUMN <number> | NUMLIT
483 BOOLLIT
485 true | false
486 CHARS
488 ( [^\] | \\ | \' | \" )*
489 STRLIT
491 ' CHARS ' | " CHARS "
492 NUMLIT
494 [1-9][0-9]* | 0
495 BOOLOP2
497 STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0
498 OP2
500 == | eq | != | ne
501 BOOLOP2BL
503 BOOLEXP0 OP2BL BOOLEXP0
504 OP2BL
506 && | and | || | or
507 BOOLOP2CMP
509 NUMEXP OP2CMP NUMEXP
510 OP2CMP
512 < | lt | <= | le | > | gt | >= | ge
513 BOOLOP2REG
515 STREXP OP2REG STRLIT
516 OP2REG
518 =~ | !~
519
521 lsfd has few options for filtering. In most of cases, what you should
522 know is -Q (or --filter) option. Combined with -o (or --output) option,
523 you can customize the output as you want.
524 List files associated with PID 1 and PID 2 processes:
526 # lsfd -Q '(PID == 1) or (PID == 2)'
528 Do the same in an alternative way:
530 # lsfd -Q '(PID == 1) || (PID == 2)'
532 Do the same in a more efficient way:
534 # lsfd --pid 1,2
536 Whitescapes can be used instead of a comma:
538 # lsfd --pid '1 2'
540 Utilize pidof(1) for list the files associated with "firefox":
542 # lsfd --pid "$(pidof firefox)"
544 List the 1st file descriptor opened by PID 1 process:
546 # lsfd -Q '(PID == 1) and (FD == 1)'
548 Do the same in an alternative way:
550 # lsfd -Q '(PID == 1) && (FD == 1)'
552 List all running executables:
554 # lsfd -Q 'ASSOC == "exe"'
556 Do the same in an alternative way:
558 # lsfd -Q 'ASSOC eq "exe"'
560 Do the same but print only file names:
562 # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
564 List deleted files associated to processes:
566 # lsfd -Q 'DELETED'
568 List non-regular files:
570 # lsfd -Q 'TYPE != "REG"'
572 List block devices:
574 # lsfd -Q 'DEVTYPE == "blk"'
576 Do the same with TYPE column:
578 # lsfd -Q 'TYPE == "BLK"'
580 List files including "dconf" directory in their names:
582 # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
584 List files opened in a QEMU virtual machine:
586 # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
588 Hide files associated to kernel threads:
590 # lsfd -Q '!KTHREAD'
592
594 Report the numbers of netlink socket descriptors and unix socket
595 descriptors:
596 # lsfd --summary=only \
598 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
599 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
600 VALUE COUNTER
601 57 netlink sockets
602 1552 unix sockets
603 Do the same but print in JSON format:
605 # lsfd --summary=only --json \
607 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
608 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
609 {
610 "lsfd-summary": [
611 {
612 "value": 15,
613 "counter": "netlink sockets"
614 },{
615 "value": 798,
616 "counter": "unix sockets"
617 }
618 ]
619 }
620
622 The lsfd command is part of the util-linux package since v2.38.
623
625 Masatake YAMATO <yamato@redhat.com>, Karel Zak <kzak@redhat.com>
626
628 lsof(8) pidof(1) proc(5) socket(2) stat(2)
629
631 For bug reports, use the issue tracker at
632 https://github.com/util-linux/util-linux/issues.
633
635 The lsfd command is part of the util-linux package which can be
636 downloaded from Linux Kernel Archive
637 <https://www.kernel.org/pub/linux/utils/util-linux/>.
638util-linux 2.39.2 2023-08-17 LSFD(1)