]> git.ipfire.org Git - thirdparty/util-linux.git/blob - misc-utils/lsfd.1.adoc
Merge branch 'patch-23' of https://github.com/mariobl/util-linux
[thirdparty/util-linux.git] / misc-utils / lsfd.1.adoc
1 //po4a: entry man manual
2 ////
3 Copyright 2021 Red Hat, Inc.
4
5 This file may be copied under the terms of the GNU Public License.
6 ////
7 = lsfd(1)
8 :doctype: manpage
9 :man manual: User Commands
10 :man source: util-linux {release-version}
11 :page-layout: base
12 :command: lsfd
13 :colon: :
14
15 == NAME
16
17 lsfd - list file descriptors
18
19 == SYNOPSIS
20
21 *lsfd* [option]
22
23 == DESCRIPTION
24
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.
30
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.
34
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.
38
39 == OPTIONS
40
41 *-l*, *--threads*::
42 List in threads level.
43
44 *-J*, *--json*::
45 Use JSON output format.
46
47 *-n*, *--noheadings*::
48 Don't print headings.
49
50 *-o*, *--output* _list_::
51 Specify which output columns to print. See the *OUTPUT COLUMNS*
52 section for details of available columns.
53 +
54 The default list of columns may be extended if _list_ is specified in
55 the format +_list_ (e.g., *lsfd -o +DELETED*).
56
57 *-r*, *--raw*::
58 Use raw output format.
59
60 *--notruncate*::
61 Don't truncate text in columns.
62
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*.
67 +
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.
72
73 *-i*[4|6], *--inet*[=4|=6]::
74 List only IPv4 sockets and/or IPv6 sockets.
75
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*.
79
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.
86 +
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.
90 +
91 See also *COUNTER EXAMPLES*.
92
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*.
97 +
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.
102 +
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.
105
106 *--debug-filter*::
107 Dump the internal data structure for the filter and exit. This is useful
108 only for *lsfd* developers.
109
110 *--dump-counters*::
111 Dump the definition of counters used in *--summary* output.
112
113 *-H*, *--list-columns*::
114 List available columns that you can specify at *--output* option.
115
116 include::man-common/help-version.adoc[]
117
118 == OUTPUT COLUMNS
119
120 Each column has a type. Types are surround by < and >.
121
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.
125
126 AINODECLASS <``string``>::
127 Class of anonymous inode.
128
129 ASSOC <``string``>::
130 Association between file and process.
131
132 BLKDRV <``string``>::
133 Block device driver name resolved by `/proc/devices`.
134
135 BPF-MAP.ID <``number``>::
136 Bpf map ID.
137
138 BPF-MAP.TYPE <``string``>::
139 Decoded name of bpf map type.
140
141 BPF-MAP.TYPE.RAW <``number``>::
142 Bpf map type (raw).
143
144 BPF.NAME <``string``>::
145 Bpf object name.
146
147 BPF-PROG.ID <``number``>::
148 Bpf program ID.
149
150 BPF-PROG.TYPE <``string``>::
151 Decoded name of bpf program type.
152
153 BPF-PROG.TYPE.RAW <``number``>::
154 Bpf program type (raw).
155
156 CHRDRV <``string``>::
157 Character device driver name resolved by `/proc/devices`.
158
159 COMMAND <``string``>::
160 Command of the process opening the file.
161
162 DELETED <``boolean``>::
163 Reachability from the file system.
164
165 DEV <``string``>::
166 ID of the device containing the file.
167
168 DEVTYPE <``string``>::
169 Device type (`blk`, `char`, or `nodev`).
170
171 ENDPOINT <``string``>::
172 IPC endpoints information communicated with the fd.
173 +
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.
177 +
178 The format of the column depends on the object associated
179 with the fd:
180
181 FIFO type:::
182 mqueue type:::
183 ptmx and pts sources:::
184 _PID_,_COMMAND_,_ASSOC_[-r][-w]
185 +
186 The last characters ([-r][-w]) represents the read and/or
187 write mode of the endpoint.
188
189 eventfd type:::
190 _PID_,_COMMAND_,_ASSOC_
191
192 UNIX-STREAM:::
193 _PID_,_COMMAND_,_ASSOC_[-r?][-w?]
194 +
195 About the last characters ([-r?][-w?]), see the description
196 of _SOCK.SHUTDOWN_.
197
198 EVENTFD.ID <``number``>::
199 Eventfd ID.
200
201 EVENTPOLL.TFDS <``string``>::
202 File descriptors targeted by the eventpoll file.
203
204 FD <``number``>::
205 File descriptor for the file.
206
207 FLAGS <``string``>::
208 Flags specified when opening the file.
209
210 FUID <``number``>::
211 User ID number of the file's owner.
212
213 INET.LADDR <``string``>::
214 Local IP address.
215
216 INET.RADDR <``string``>::
217 Remote IP address.
218
219 INET6.LADDR <``string``>::
220 Local IP6 address.
221
222 INET6.RADDR <``string``>::
223 Remote IP6 address.
224
225 INODE <``number``>::
226 Inode number.
227
228 INOTIFY.INODES <``string``>::
229 Cooked version of INOTIFY.INODES.RAW.
230 The format of the element is
231 _inode-number_,_source-of-inode_.
232
233 INOTIFY.INODES.RAW <``string``>::
234 List of monitoring inodes. The format of the element
235 is _inode-number_,_device-major_:_device-minor_.
236
237 KNAME <``string``>::
238 //
239 // It seems that the manpage backend of asciidoctor has limitations
240 // about emitting text with nested face specifications like:
241 //
242 // `_u_` p
243 //
244 // Not only u but also p is decorated with underline.
245 //
246 Raw file name extracted from
247 from ``/proc/``_pid_``/fd/``_fd_ or ``/proc/``_pid_``/map_files/``_region_.
248
249 KTHREAD <``boolean``>::
250 Whether the process is a kernel thread or not.
251
252 MAJ:MIN <``string``>::
253 Device ID for special, or ID of device containing file.
254
255 MAPLEN <``number``>::
256 Length of file mapping (in page).
257
258 MISCDEV <``string``>::
259 Misc character device name resolved by `/proc/misc`.
260
261 MNTID <``number``>::
262 Mount ID.
263
264 MODE <``string``>::
265 Access mode (rwx).
266
267 NAME <``string``>::
268 Cooked version of KNAME. It is mostly same as KNAME.
269 +
270 Some files have special formats and information sources:
271 +
272 bpf-map:::
273 id=_BPF-MAP.ID_ type=_BPF-MAP.TYPE_[ name=_BPF.NAME_]
274 +
275 bpf-prog:::
276 id=_BPF-PROG.ID_ type=_BPF-PROG.TYPE_[ name=_BPF.NAME_]
277 +
278 eventpoll:::
279 tfds=_EVENTPOLL.TFDS_
280 +
281 eventfd:::
282 id=_EVENTFD.ID_
283 +
284 inotify:::
285 inodes=_INOTIFY.INODES_
286 +
287 misc:tun:::
288 iface=_TUN.IFACE_
289 +
290 NETLINK:::
291 protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]]
292 +
293 PACKET:::
294 type=_SOCK.TYPE_[ protocol=_PACKET.PROTOCOL_][ iface=_PACKET.IFACE_]
295 +
296 pidfd:::
297 pid=_TARGET-PID_ comm=_TARGET-COMMAND_ nspid=_TARGET-NSPIDS_
298 +
299 *lsfd* extracts _TARGET-PID_ and _TARGET-NSPIDS_ from
300 ``/proc/``_pid_``/fdinfo/``_fd_.
301 +
302 PING:::
303 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]
304 +
305 PINGv6:::
306 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]
307 +
308 ptmx:::
309 tty-index=_PTMX.TTY-INDEX_
310 +
311 *lsfd* extracts _PTMX.TTY-INDEX_ from
312 ``/proc/``_pid_``/fdinfo/``_fd_.
313 +
314 RAW:::
315 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]]
316 +
317 RAWv6:::
318 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]]
319 +
320 signalfd:::
321 mask=_SIGNALFD.MASK_
322 +
323 TCP:::
324 TCPv6:::
325 state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]]
326 +
327 timerfd:::
328 clockid=_TIMERFD.CLOCKID_[ remaining=_TIMERFD.REMAINING_ [ interval=_TIMERFD.INTERVAL_]]
329 +
330 UDP:::
331 UDPv6:::
332 state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]]
333 +
334 *lsfd* hides ``raddr=`` if _UDP.RADDR_ is ``0.0.0.0`` and _UDP.RPORT_ is 0.
335 +
336 UDP-LITE:::
337 UDPLITEv6:::
338 state=_SOCK.STATE_[ laddr=_UDPLITE.LADDR_ [ raddr=_UDPLITE.RADDR_]]
339 +
340 UNIX-STREAM:::
341 state=_SOCK.STATE_[ path=_UNIX.PATH_]
342 +
343 UNIX:::
344 state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_
345
346 ____
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.
350 ____
351
352 NETLINK.GROUPS <``number``>::
353 Netlink multicast groups.
354
355 NETLINK.LPORT <``number``>::
356 Netlink local port id.
357
358 NETLINK.PROTOCOL <``string``>::
359 Netlink protocol.
360
361 NLINK <``number``>::
362 Link count.
363
364 NS.NAME <``string``>::
365 Name (_NS.TYPE_:[_INODE_]) of the namespace specified with the file.
366
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`.
371
372 OWNER <``string``>::
373 Owner of the file.
374
375 PACKET.IFACE <``string``>::
376 Interface name associated with the packet socket.
377
378 PACKET.PROTOCOL <``string``>::
379 L3 protocol associated with the packet socket.
380
381 PARTITION <``string``>::
382 Block device name resolved by `/proc/partition`.
383
384 PID <``number``>::
385 PID of the process opening the file.
386
387 PIDFD.COMM <``string``>::
388 Command of the process targeted by the pidfd.
389
390 PIDFD.NSPID <``string``>::
391 Value of NSpid field in ``/proc/``_pid_``/fdinfo/``_fd_ of the pidfd.
392 +
393 Quoted from kernel/fork.c of Linux source tree:
394 +
395 ____
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.
400
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.
404 ____
405
406 PIDFD.PID <``number``>::
407 PID of the process targeted by the pidfd.
408
409 PING.ID <`number`>::
410 ICMP echo request id used on the PING socket.
411
412 POS <``number``>::
413 File position.
414
415 RAW.PROTOCOL <``number``>::
416 Protocol number of the raw socket.
417
418 RDEV <``string``>::
419 Device ID (if special file).
420
421 SIGNALFD.MASK <``string``>::
422 Masked signals.
423
424 SIZE <``number``>::
425 File size.
426
427 SOCK.LISTENING <``boolean``>::
428 Listening socket.
429
430 SOCK.NETS <``number``>::
431 Inode identifying network namespace where the socket belongs to.
432
433 SOCK.PROTONAME <``string``>::
434 Protocol name.
435
436 SOCK.SHUTDOWN <``string``>::
437 Shutdown state of socket.
438 +
439 [-r?]:::
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.
443 +
444 [-w?]:::
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.
448
449 SOCK.STATE <``string``>::
450 State of socket.
451
452 SOCK.TYPE <``string``>::
453 Type of socket. Here type means the second parameter of
454 socket system call:
455 +
456 * stream
457 * dgram
458 * raw
459 * rdm
460 * seqpacket
461 * dccp
462 * packet
463
464 SOURCE <``string``>::
465 File system, partition, or device containing the file.
466
467 STTYPE <``string``>::
468 Raw file types returned from *stat*(2): BLK, CHR, DIR, FIFO, LINK, REG, SOCK, or UNKN.
469
470 TCP.LADDR <``string``>::
471 Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.
472
473 TCP.LPORT <``number``>::
474 Local TCP port.
475
476 TCP.RADDR <``string``>::
477 Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.
478
479 TCP.RPORT <``number``>::
480 Remote TCP port.
481
482 TID <``number``>::
483 Thread ID of the process opening the file.
484
485 TIMERFD.CLOCKID <``string``>::
486 Clockid.
487
488 TIMERFD.INTERVAL <``number``>::
489 Interval.
490
491 TIMERFD.REMAINING <``number``>::
492 Remaining time.
493
494 PTMX.TTY-INDEX <``number``>::
495 TTY index of the counterpart.
496
497 TUN.IFACE <``string``>::
498 Network interface behind the tun device.
499
500 TYPE <``string``>::
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.
504
505 UDP.LADDR <``string``>::
506 Local IP address and local UDP port.
507
508 UDP.LPORT <``number``>::
509 Local UDP port.
510
511 UDP.RADDR <``string``>::
512 Remote IP address and remote UDP port.
513
514 UDP.RPORT <``number``>::
515 Remote UDP port.
516
517 UDPLITE.LADDR <``string``>::
518 Local IP address and local UDPLite port.
519
520 UDPLITE.LPORT <``number``>::
521 Local UDP port.
522
523 UDPLITE.RADDR <``string``>::
524 Remote IP address and remote UDPLite port.
525
526 UDPLITE.RPORT <``number``>::
527 Remote UDP port.
528
529 UID <``number``>::
530 User ID number.
531
532 UNIX.PATH <``string``>::
533 Filesystem pathname for UNIX domain socket.
534
535 USER <``string``>::
536 User of the process.
537
538 XMODE <``string``>::
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.
542 +
543 [-r]:::
544 opened of mapped for reading. This is also in _MODE_.
545 +
546 [-w]:::
547 opened of mapped for writing. This is also in _MODE_.
548 +
549 [-x]:::
550 mapped for executing the code. This is also in _MODE_.
551 +
552 [-D]:::
553 deleted from the file system. See also _DELETED_.
554 +
555 [-Ll]:::
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.
560 +
561 [-m]:::
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).
568
569 == FILTER EXAMPLES
570
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.
574
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: ::
577 ....
578 # lsfd -Q '(PID == 1) or (PID == 2)'
579 ....
580
581 Do the same in an alternative way: ::
582 ....
583 # lsfd -Q '(PID == 1) || (PID == 2)'
584 ....
585
586 Do the same in a more efficient way: ::
587 ....
588 # lsfd --pid 1,2
589 ....
590
591 Whitescapes can be used instead of a comma: ::
592 ....
593 # lsfd --pid '1 2'
594 ....
595
596 Utilize *pidof*(1) for list the files associated with "firefox": ::
597 ....
598 # lsfd --pid "$(pidof firefox)"
599 ....
600
601 List the 1st file descriptor opened by PID 1 process: ::
602 ....
603 # lsfd -Q '(PID == 1) and (FD == 1)'
604 ....
605
606 Do the same in an alternative way: ::
607 ....
608 # lsfd -Q '(PID == 1) && (FD == 1)'
609 ....
610
611 List all running executables: ::
612 ....
613 # lsfd -Q 'ASSOC == "exe"'
614 ....
615
616 Do the same in an alternative way: ::
617 ....
618 # lsfd -Q 'ASSOC eq "exe"'
619 ....
620
621 Do the same but print only file names: ::
622 ....
623 # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
624 ....
625
626 List deleted files associated to processes: ::
627 ....
628 # lsfd -Q 'DELETED'
629 ....
630
631 List non-regular files: ::
632 ....
633 # lsfd -Q 'TYPE != "REG"'
634 ....
635
636 List block devices: ::
637 ....
638 # lsfd -Q 'DEVTYPE == "blk"'
639 ....
640
641 Do the same with TYPE column: ::
642 ....
643 # lsfd -Q 'TYPE == "BLK"'
644 ....
645
646 List files including "dconf" directory in their names: ::
647 ....
648 # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
649 ....
650
651 List files opened in a QEMU virtual machine: ::
652 ....
653 # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
654 ....
655
656 Hide files associated to kernel threads: ::
657 ....
658 # lsfd -Q '!KTHREAD'
659 ....
660
661 List timerfd files expired within 0.5 seconds: ::
662 ....
663 # lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
664 ....
665
666 == COUNTER EXAMPLES
667
668 Report the numbers of netlink socket descriptors and unix socket descriptors: ::
669 ....
670 # lsfd --summary=only \
671 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
672 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
673 VALUE COUNTER
674 57 netlink sockets
675 1552 unix sockets
676 ....
677
678 Do the same but print in JSON format: ::
679 ....
680 # lsfd --summary=only --json \
681 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
682 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
683 {
684 "lsfd-summary": [
685 {
686 "value": 15,
687 "counter": "netlink sockets"
688 },{
689 "value": 798,
690 "counter": "unix sockets"
691 }
692 ]
693 }
694 ....
695
696
697 == HISTORY
698
699 The *lsfd* command is part of the util-linux package since v2.38.
700
701 == AUTHORS
702
703 mailto:yamato@redhat.com[Masatake YAMATO],
704 mailto:kzak@redhat.com[Karel Zak]
705
706 == SEE ALSO
707 *bpftool*(8)
708 *bps*(8)
709 *lslocks*(8)
710 *lsof*(8)
711 *pidof*(1)
712 *proc*(5)
713 *scols-filter*(5)
714 *socket*(2)
715 *ss*(8)
716 *stat*(2)
717
718 include::man-common/bugreports.adoc[]
719
720 include::man-common/footer.adoc[]
721
722 ifdef::translation[]
723 include::man-common/translation.adoc[]
724 endif::[]