]> git.ipfire.org Git - thirdparty/util-linux.git/blob - misc-utils/lsfd.1.adoc
Merge branch 'setuid' of https://github.com/eworm-de/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 --help*
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 *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 *FILTER EXPRESSION* 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 include::man-common/help-version.adoc[]
114
115 == OUTPUT COLUMNS
116
117 Each column has a type. Types are surround by < and >.
118
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.
122
123 AINODECLASS <``string``>::
124 Class of anonymous inode.
125
126 ASSOC <``string``>::
127 Association between file and process.
128
129 BLKDRV <``string``>::
130 Block device driver name resolved by `/proc/devices`.
131
132 CHRDRV <``string``>::
133 Character device driver name resolved by `/proc/devices`.
134
135 COMMAND <``string``>::
136 Command of the process opening the file.
137
138 DELETED <``boolean``>::
139 Reachability from the file system.
140
141 DEV <``string``>::
142 ID of the device containing the file.
143
144 DEVTYPE <``string``>::
145 Device type (`blk`, `char`, or `nodev`).
146
147 ENDPOINT <``string``>::
148 IPC endpoints information communicated with the fd.
149 +
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.
153 +
154 The format of the column depends on the object associated
155 with the fd:
156
157 FIFO type:::
158 mqueue type:::
159 _PID_,_COMMAND_,_ASSOC_[-r][-w]
160 +
161 The last characters ([-r][-w]) represents the read and/or
162 write mode of the endpoint.
163
164 eventfd type:::
165 _PID_,_COMMAND_,_ASSOC_
166
167 EVENTFD.ID <``number``>::
168 Eventfd ID.
169
170 EVENTPOLL.TFDS <``string``>::
171 File descriptors targeted by the eventpoll file.
172
173 FD <``number``>::
174 File descriptor for the file.
175
176 FLAGS <``string``>::
177 Flags specified when opening the file.
178
179 FUID <``number``>::
180 User ID number of the file's owner.
181
182 INET.LADDR <``string``>::
183 Local IP address.
184
185 INET.RADDR <``string``>::
186 Remote IP address.
187
188 INET6.LADDR <``string``>::
189 Local IP6 address.
190
191 INET6.RADDR <``string``>::
192 Remote IP6 address.
193
194 INODE <``number``>::
195 Inode number.
196
197 KNAME <``string``>::
198 //
199 // It seems that the manpage backend of asciidoctor has limitations
200 // about emitting text with nested face specifications like:
201 //
202 // `_u_` p
203 //
204 // Not only u but also p is decorated with underline.
205 //
206 Raw file name extracted from
207 from ``/proc/``_pid_``/fd/``_fd_ or ``/proc/``_pid_``/map_files/``_region_.
208
209 KTHREAD <``boolean``>::
210 Whether the process is a kernel thread or not.
211
212 MAJ:MIN <``string``>::
213 Device ID for special, or ID of device containing file.
214
215 MAPLEN <``number``>::
216 Length of file mapping (in page).
217
218 MISCDEV <``string``>::
219 Misc character device name resolved by `/proc/misc`.
220
221 MNTID <``number``>::
222 Mount ID.
223
224 MODE <``string``>::
225 Access mode (rwx).
226
227 NAME <``string``>::
228 Cooked version of KNAME. It is mostly same as KNAME.
229 +
230 Some files have special formats and information sources:
231 +
232 eventpoll:::
233 tfds=_EVENTPOLL.TFDS_
234 +
235 eventfd:::
236 id=_EVENTFD.ID_
237 +
238 NETLINK:::
239 protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]]
240 +
241 PACKET:::
242 type=_SOCK.TYPE_[ protocol=_PACKET.PROTOCOL_][ iface=_PACKET.IFACE_]
243 +
244 pidfd:::
245 pid=_TARGET-PID_ comm=_TARGET-COMMAND_ nspid=_TARGET-NSPIDS_
246 +
247 *lsfd* extracts _TARGET-PID_ and _TARGET-NSPIDS_ from
248 ``/proc/``_pid_``/fdinfo/``_fd_.
249 +
250 PING:::
251 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]
252 +
253 PINGv6:::
254 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]
255 +
256 RAW:::
257 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]]
258 +
259 RAWv6:::
260 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]]
261 +
262 signalfd:::
263 mask=_SIGNALFD.MASK_
264 +
265 TCP:::
266 TCPv6:::
267 state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]]
268 +
269 timerfd:::
270 clockid=_TIMERFD.CLOCKID_[ remaining=_TIMERFD.REMAINING_ [ interval=_TIMERFD.INTERVAL_]]
271 +
272 UDP:::
273 UDPv6:::
274 state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]]
275 +
276 *lsfd* hides ``raddr=`` if _UDP.RADDR_ is ``0.0.0.0`` and _UDP.RPORT_ is 0.
277 +
278 UDP-LITE:::
279 UDPLITEv6:::
280 state=_SOCK.STATE_[ laddr=_UDPLITE.LADDR_ [ raddr=_UDPLITE.RADDR_]]
281 +
282 UNIX-STREAM:::
283 state=_SOCK.STATE_[ path=_UNIX.PATH_]
284 +
285 UNIX:::
286 state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_
287
288 NETLINK.GROUPS <``number``>::
289 Netlink multicast groups.
290
291 NETLINK.LPORT <``number``>::
292 Netlink local port id.
293
294 NETLINK.PROTOCOL <``string``>::
295 Netlink protocol.
296
297 NLINK <``number``>::
298 Link count.
299
300 NS.NAME <``string``>::
301 Name (_NS.TYPE_:[_INODE_]) of the namespace specified with the file.
302
303 NS.TYPE <``string``>::
304 Type of the namespace specified with the file.
305 The type is `mnt`, `cgroup`, `uts`, `ipc`, `user`, `pid`, `net`,
306 `time`, or `unknown`.
307
308 OWNER <``string``>::
309 Owner of the file.
310
311 PACKET.IFACE <``string``>::
312 Interface name associated with the packet socket.
313
314 PACKET.PROTOCOL <``string``>::
315 L3 protocol associated with the packet socket.
316
317 PARTITION <``string``>::
318 Block device name resolved by `/proc/partition`.
319
320 PID <``number``>::
321 PID of the process opening the file.
322
323 PIDFD.COMM <``string``>::
324 Command of the process targeted by the pidfd.
325
326 PIDFD.NSPID <``string``>::
327 Value of NSpid field in ``/proc/``_pid_``/fdinfo/``_fd_ of the pidfd.
328 +
329 Quoted from kernel/fork.c of Linux source tree:
330 +
331 ____
332 If pid namespaces are supported then this function will also print
333 the pid of a given pidfd refers to for all descendant pid namespaces
334 starting from the current pid namespace of the instance, i.e. the
335 Pid field and the first entry in the NSpid field will be identical.
336
337 Note that this differs from the Pid and NSpid fields in
338 /proc/<pid>/status where Pid and NSpid are always shown relative to
339 the pid namespace of the procfs instance.
340 ____
341
342 PIDFD.PID <``number``>::
343 PID of the process targeted by the pidfd.
344
345 PING.ID <`number`>::
346 ICMP echo request id used on the PING socket.
347
348 POS <``number``>::
349 File position.
350
351 RAW.PROTOCOL <``number``>::
352 Protocol number of the raw socket.
353
354 RDEV <``string``>::
355 Device ID (if special file).
356
357 SIGNALFD.MASK <``string``>::
358 Masked signals.
359
360 SIZE <``number``>::
361 File size.
362
363 SOCK.LISTENING <``boolean``>::
364 Listening socket.
365
366 SOCK.NETS <``number``>::
367 Inode identifying network namespace where the socket belongs to.
368
369 SOCK.PROTONAME <``string``>::
370 Protocol name.
371
372 SOCK.STATE <``string``>::
373 State of socket.
374
375 SOCK.TYPE <``string``>::
376 Type of socket. Here type means the second parameter of
377 socket system call:
378 +
379 * stream
380 * dgram
381 * raw
382 * rdm
383 * seqpacket
384 * dccp
385 * packet
386
387 SOURCE <``string``>::
388 File system, partition, or device containing the file.
389
390 STTYPE <``string``>::
391 Raw file types returned from *stat*(2): BLK, CHR, DIR, FIFO, LINK, REG, SOCK, or UNKN.
392
393 TCP.LADDR <``string``>::
394 Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.
395
396 TCP.LPORT <``number``>::
397 Local TCP port.
398
399 TCP.RADDR <``string``>::
400 Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.
401
402 TCP.RPORT <``number``>::
403 Remote TCP port.
404
405 TID <``number``>::
406 Thread ID of the process opening the file.
407
408 TIMERFD.CLOCKID <``string``>::
409 Clockid.
410
411 TIMERFD.INTERVAL <``number``>::
412 Interval.
413
414 TIMERFD.REMAINING <``number``>::
415 Remaining time.
416
417 TYPE <``string``>::
418 Cooked version of STTYPE. It is same as STTYPE with exceptions.
419 For SOCK, print the value for SOCK.PROTONAME.
420 For UNKN, print the value for AINODECLASS if SOURCE is anon_inodefs.
421
422 UDP.LADDR <``string``>::
423 Local IP address and local UDP port.
424
425 UDP.LPORT <``number``>::
426 Local UDP port.
427
428 UDP.RADDR <``string``>::
429 Remote IP address and remote UDP port.
430
431 UDP.RPORT <``number``>::
432 Remote UDP port.
433
434 UDPLITE.LADDR <``string``>::
435 Local IP address and local UDPLite port.
436
437 UDPLITE.LPORT <``number``>::
438 Local UDP port.
439
440 UDPLITE.RADDR <``string``>::
441 Remote IP address and remote UDPLite port.
442
443 UDPLITE.RPORT <``number``>::
444 Remote UDP port.
445
446 UID <``number``>::
447 User ID number.
448
449 UNIX.PATH <``string``>::
450 Filesystem pathname for UNIX domain socket.
451
452 USER <``string``>::
453 User of the process.
454
455 == FILTER EXPRESSION
456
457 *lsfd* evaluates the expression passed to *--filter* option every time
458 before printing a file line. *lsfd* prints the line only if the result
459 of evaluation is `true`.
460
461 An expression consists of column names, literals and, operators like:
462 `DELETED`, `(PID == 1)`, `(NAME == "/etc/passwd")`, `(PID == 1) && DELETED`.
463 `DELETED`, `PID`, and `NAME` are column names in the example.
464 `1` and "/etc/passwd" are literals.
465 `==` and `&&` are operators.
466
467 Before evaluation, *lsfd* substitutes column names in the given
468 expression with actual column values in the line. There are three
469 different data types: `boolean`, `string`, and `number`. For columns
470 with a `boolean` type, the value can be stand-alone. For `string` and
471 `number` values, the value must be an operand of an operator, for
472 example, `(PID == 1)`. See *OUTPUT COLUMNS* about the types of
473 columns.
474
475 Literal is for representing a value directly. See BOOLLIT, STRLIT, and
476 NUMLIT. Different data types have different literal syntax.
477
478 An operator works with one or two operand(s). An operator has an
479 expectation about the data type(s) of its operands. Giving an
480 unexpected data type to an operator causes a syntax error.
481
482 Operators taking two operands are `and`, `or`, `eq`, `ne`, `le`, `lt`, `ge`, `gt`, `=~`, `!~`.
483 Alphabetically named operators have C-language
484 flavored aliases: `&&`, `||`, `==`, `!=`, `<`, `<=`, `>=`, and `>`.
485
486 `!` is the only operator that takes one operand.
487
488 `eq`, `ne`, and their aliases expect operands have the same data type.
489 Applying these operators return a `boolean`.
490
491 `and`, `or`, `not` and their aliases expect operands have `boolean` data
492 type. Applying these operators return a `boolean`.
493
494 `lt`, `le`, `gt`, `ge`, and their aliases expect operands have
495 `number` data types. Applying these operators return a `boolean`.
496
497 `=~` is for regular expression matching; if a string at the right side
498 matches a regular expression at the left side, the result is true.
499 The right side operand must be a string literal. See STRLIT about the
500 syntax.
501
502 `!~` is a short-hand version of `not (STR =~ PAT)`; it inverts the
503 result of `=~`.
504
505 === Limitations
506
507 The current implementation does not define precedences within
508 operators. Use `(` and `)` explicitly for grouping the
509 sub-expressions if your expression uses more than two operators.
510
511 About `number` typed values, the filter engine supports only
512 non-negative integers, and non-negative floating point numbers.
513
514 === Semi-formal syntax
515
516 //TRANSLATORS: In the following messages, translate only the <``variables``>.
517 EXPR :: BOOLEXP
518
519 BOOLEXP0 :: COLUMN <``boolean``> | BOOLLIT | _(_ BOOLEXP _)_
520
521 BOOLEXP :: BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG
522
523 COLUMN :: [\_A-Za-z][-_:A-Za-z0-9]*
524
525 BOOLOP1 :: _!_ BOOLEXP0 | _not_ BOOLEXP0
526
527 STREXP :: COLUMN <``string``> | STRLIT
528
529 NUMEXP :: COLUMN <``number``> | NUMLIT
530
531 BOOLLIT :: _true_ | _false_
532
533 CHARS :: ( [^\] | _\\_ | _\'_ | _\"_ )*
534
535 STRLIT :: _'_ CHARS _'_ | _"_ CHARS _"_
536
537 NUMLIT :: INTLIT | FNUMLIT
538
539 INTLIT :: [1-9][0-9]* | _0_
540
541 FNUMLIT :: INTLIT _._ [0-9][0-9]*
542
543 BOOLOP2 :: STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0
544
545 OP2 :: _==_ | _eq_ | _!=_ | _ne_
546
547 BOOLOP2BL :: BOOLEXP0 OP2BL BOOLEXP0
548
549 OP2BL :: _&&_ | _and_ | _||_ | _or_
550
551 BOOLOP2CMP :: NUMEXP OP2CMP NUMEXP
552
553 OP2CMP :: _<_ | _lt_ | _\<=_ | _le_ | _>_ | _gt_ | _>=_ | _ge_
554
555 BOOLOP2REG :: STREXP OP2REG STRLIT
556
557 OP2REG :: _=~_ | _!~_
558
559 == FILTER EXAMPLES
560
561 *lsfd* has few options for filtering. In most of cases, what you should
562 know is *-Q* (or *--filter*) option. Combined with *-o* (or
563 *--output*) option, you can customize the output as you want.
564
565 //TRANSLATORS: In the following messages, don't forget to add whitespace at the end!
566 List files associated with PID 1 and PID 2 processes: ::
567 ....
568 # lsfd -Q '(PID == 1) or (PID == 2)'
569 ....
570
571 Do the same in an alternative way: ::
572 ....
573 # lsfd -Q '(PID == 1) || (PID == 2)'
574 ....
575
576 Do the same in a more efficient way: ::
577 ....
578 # lsfd --pid 1,2
579 ....
580
581 Whitescapes can be used instead of a comma: ::
582 ....
583 # lsfd --pid '1 2'
584 ....
585
586 Utilize *pidof*(1) for list the files associated with "firefox": ::
587 ....
588 # lsfd --pid "$(pidof firefox)"
589 ....
590
591 List the 1st file descriptor opened by PID 1 process: ::
592 ....
593 # lsfd -Q '(PID == 1) and (FD == 1)'
594 ....
595
596 Do the same in an alternative way: ::
597 ....
598 # lsfd -Q '(PID == 1) && (FD == 1)'
599 ....
600
601 List all running executables: ::
602 ....
603 # lsfd -Q 'ASSOC == "exe"'
604 ....
605
606 Do the same in an alternative way: ::
607 ....
608 # lsfd -Q 'ASSOC eq "exe"'
609 ....
610
611 Do the same but print only file names: ::
612 ....
613 # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
614 ....
615
616 List deleted files associated to processes: ::
617 ....
618 # lsfd -Q 'DELETED'
619 ....
620
621 List non-regular files: ::
622 ....
623 # lsfd -Q 'TYPE != "REG"'
624 ....
625
626 List block devices: ::
627 ....
628 # lsfd -Q 'DEVTYPE == "blk"'
629 ....
630
631 Do the same with TYPE column: ::
632 ....
633 # lsfd -Q 'TYPE == "BLK"'
634 ....
635
636 List files including "dconf" directory in their names: ::
637 ....
638 # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
639 ....
640
641 List files opened in a QEMU virtual machine: ::
642 ....
643 # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
644 ....
645
646 Hide files associated to kernel threads: ::
647 ....
648 # lsfd -Q '!KTHREAD'
649 ....
650
651 List timerfd files expired within 0.5 seconds: ::
652 ....
653 # lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
654 ....
655
656 == COUNTER EXAMPLES
657
658 Report the numbers of netlink socket descriptors and unix socket descriptors: ::
659 ....
660 # lsfd --summary=only \
661 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
662 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
663 VALUE COUNTER
664 57 netlink sockets
665 1552 unix sockets
666 ....
667
668 Do the same but print in JSON format: ::
669 ....
670 # lsfd --summary=only --json \
671 -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
672 -C 'unix sockets':'(NAME =~ "UNIX:.*")'
673 {
674 "lsfd-summary": [
675 {
676 "value": 15,
677 "counter": "netlink sockets"
678 },{
679 "value": 798,
680 "counter": "unix sockets"
681 }
682 ]
683 }
684 ....
685
686
687 == HISTORY
688
689 The *lsfd* command is part of the util-linux package since v2.38.
690
691 == AUTHORS
692
693 mailto:yamato@redhat.com[Masatake YAMATO],
694 mailto:kzak@redhat.com[Karel Zak]
695
696 == SEE ALSO
697
698 *lsof*(8)
699 *pidof*(1)
700 *proc*(5)
701 *socket*(2)
702 *stat*(2)
703
704 include::man-common/bugreports.adoc[]
705
706 include::man-common/footer.adoc[]
707
708 ifdef::translation[]
709 include::man-common/translation.adoc[]
710 endif::[]