summaryrefslogtreecommitdiffstats
path: root/misc-utils/lsfd.1.adoc
blob: 23eee28913672cf2c1707491b5927f010823ee99 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
//po4a: entry man manual
////
Copyright 2021 Red Hat, Inc.

This file may be copied under the terms of the GNU Public License.
////
= lsfd(1)
:doctype: manpage
:man manual: User Commands
:man source: util-linux {release-version}
:page-layout: base
:command: lsfd
:colon: :

== NAME

lsfd - list file descriptors

== SYNOPSIS

*lsfd* [option]

== DESCRIPTION

*lsfd* is intended to be a modern replacement for *lsof*(8) on Linux systems.
Unlike *lsof*, *lsfd* is specialized to Linux kernel; it supports Linux
specific features like namespaces with simpler code. *lsfd* is not a
drop-in replacement for *lsof*; they are different in the command line
interface and output formats.

The default output is subject to change. So whenever possible, you should avoid using
default outputs in your scripts. Always explicitly define expected columns by using
*--output* _columns-list_ in environments where a stable output is required.

*lsfd* uses Libsmartcols for output formatting and filtering. See the description of *--output*
option for customizing the output format, and *--filter* option for filtering. Use *lsfd --help*
to get a list of all available columns.

== OPTIONS

*-l*, *--threads*::
List in threads level.

*-J*, *--json*::
Use JSON output format.

*-n*, *--noheadings*::
Don't print headings.

*-o*, *--output* _list_::
Specify which output columns to print. See the *OUTPUT COLUMNS*
section for details of available columns.
+
The default list of columns may be extended if _list_ is specified in
the format +_list_ (e.g., *lsfd -o +DELETED*).

*-r*, *--raw*::
Use raw output format.

*--notruncate*::
Don't truncate text in columns.

*-p*, *--pid* _pids_::
Collect information only for specified processes.
_pids_ is a list of pids. A comma or whitespaces can be used as separators.
You can use this option with *pidof*(1). See *FILTER EXAMPLES*.
+
Both *-Q* option with an expression including PID, e.g. -Q (PID == 1),
and *-p* option, e.g. -p 1, may print the same output but using *-p*
option is much more efficient because *-p* option works at a much earlier
stage of processing than the *-Q* option.

*-i*[4|6], *--inet*[=4|=6]::
List only IPv4 sockets and/or IPv6 sockets.

*-Q*, *--filter* _expr_::
Print only the files matching the condition represented by the _expr_.
See also *FILTER EXAMPLES*.

*-C*, *--counter* __label__:__filter_expr__::
Define a custom counter used in *--summary* output. *lsfd* makes a
counter named _label_. During collect information, *lsfd* counts files
matching _filter_expr_, and stores the counted number to the
counter named _label_. *lsfd* applies filters defined with *--filter*
options before counting; files excluded by the filters are not counted.
+
See *FILTER EXPRESSION* about _filter_expr_.
_label_ should not include `{` nor `:`. You can define multiple
counters by specifying this option multiple times.
+
See also *COUNTER EXAMPLES*.

*--summary*[=_when_]::
This option controls summary lines output. The optional argument _when_
can be *only*, *append* or *never*. If the _when_ argument is omitted,
it defaults to *only*.
+
The summary reports counters. A counter consists of a label and an
integer value.  *--counter* is the option for defining a counter.  If
a user defines no counter, *lsfd* uses the definitions of pre-defined
built-in counters (default counters) to make the summary output.
+
CAUTION{colon} Using *--summary* and *--json* may make the output broken. Only combining *--summary*=*only* and *--json* is valid.
//TRANSLATORS: Keep {colon} untranslated.

*--debug-filter*::
Dump the internal data structure for the filter and exit. This is useful
only for *lsfd* developers.

*--dump-counters*::
Dump the definition of counters used in *--summary* output.

include::man-common/help-version.adoc[]

== OUTPUT COLUMNS

Each column has a type. Types are surround by < and >.

//TRANSLATORS: Keep {colon} untranslated.
CAUTION{colon} The names and types of columns are not stable yet.
They may be changed in the future releases.

AINODECLASS <``string``>::
Class of anonymous inode.

ASSOC <``string``>::
Association between file and process.

BLKDRV <``string``>::
Block device driver name resolved by `/proc/devices`.

CHRDRV <``string``>::
Character device driver name resolved by `/proc/devices`.

COMMAND <``string``>::
Command of the process opening the file.

DELETED <``boolean``>::
Reachability from the file system.

DEV <``string``>::
ID of the device containing the file.

DEVTYPE <``string``>::
Device type (`blk`, `char`, or `nodev`).

ENDPOINT <``string``>::
IPC endpoints information communicated with the fd.
The format of the column depends on the object associated
with the fd:
+
FIFO type:::
_PID_,_COMMAND_,_ASSOC_[-r][-w]
+
The last characters ([-r][-w]) represents the read and/or
write mode of the endpoint.

+
*lsfd* collects endpoints within the processes that
*lsfd* scans; *lsfd* may miss some endpoints
if you limits the processes with *-p* option.

FD <``number``>::
File descriptor for the file.

FLAGS <``string``>::
Flags specified when opening the file.

FUID <``number``>::
User ID number of the file's owner.

INET.LADDR <``string``>::
Local IP address.

INET.RADDR <``string``>::
Remote IP address.

INET6.LADDR <``string``>::
Local IP6 address.

INET6.RADDR <``string``>::
Remote IP6 address.

INODE <``number``>::
Inode number.

KNAME <``string``>::
//
// It seems that the manpage backend of asciidoctor has limitations
// about emitting text with nested face specifications like:
//
//   `_u_` p
//
// Not only u but also p is decorated with underline.
//
Raw file name extracted from
from ``/proc/``_pid_``/fd/``_fd_ or ``/proc/``_pid_``/map_files/``_region_.

KTHREAD <``boolean``>::
Whether the process is a kernel thread or not.

MAJ:MIN <``string``>::
Device ID for special, or ID of device containing file.

MAPLEN <``number``>::
Length of file mapping (in page).

MISCDEV <``string``>::
Misc character device name resolved by `/proc/misc`.

MNTID <``number``>::
Mount ID.

MODE <``string``>::
Access mode (rwx).

NAME <``string``>::
Cooked version of KNAME. It is mostly same as KNAME.
+
Some files have special formats and information sources:
+
NETLINK:::
protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]]
+
PACKET:::
type=_SOCK.TYPE_[ protocol=_PACKET.PROTOCOL_][ iface=_PACKET.IFACE_]
+
pidfd:::
pid=_TARGET-PID_ comm=_TARGET-COMMAND_ nspid=_TARGET-NSPIDS_
+
*lsfd* extracts _TARGET-PID_ and _TARGET-NSPIDS_ from
``/proc/``_pid_``/fdinfo/``_fd_.
+
PING:::
state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]
+
PINGv6:::
state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]
+
RAW:::
state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]]
+
RAWv6:::
state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]]
+
TCP:::
TCPv6:::
state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]]
+
UDP:::
UDPv6:::
state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]]
+
*lsfd* hides ``raddr=`` if _UDP.RADDR_ is ``0.0.0.0`` and _UDP.RPORT_ is 0.
+
UDP-LITE:::
UDPLITEv6:::
state=_SOCK.STATE_[ laddr=_UDPLITE.LADDR_ [ raddr=_UDPLITE.RADDR_]]
+
UNIX-STREAM:::
state=_SOCK.STATE_[ path=_UNIX.PATH_]
+
UNIX:::
state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_

NETLINK.GROUPS <``number``>>::
Netlink multicast groups.

NETLINK.LPORT <``number``>>::
Netlink local port id.

NETLINK.PROTOCOL <``string``>>::
Netlink protocol.

NLINK <``number``>::
Link count.

NS.NAME <``string``>::
Name (_NS.TYPE_:[_INODE_]) of the namespace specified with the file.

NS.TYPE <``string``>::
Type of the namespace specified with the file.
The type is `mnt`, `cgroup`, `uts`, `ipc`, `user`, `pid`, `net`,
`time`, or `unknown`.

OWNER <``string``>::
Owner of the file.

PACKET.IFACE <``string``>::
Interface name associated with the packet socket.

PACKET.PROTOCOL <``string``>::
L3 protocol associated with the packet socket.

PARTITION <``string``>::
Block device name resolved by `/proc/partition`.

PID <``number``>::
PID of the process opening the file.

PIDFD.COMM <``string``>::
Command of the process targeted by the pidfd.

PIDFD.NSPID <``string``>::
Value of NSpid field in ``/proc/``_pid_``/fdinfo/``_fd_ of the pidfd.
+
Quoted from kernel/fork.c of Linux source tree:
+
____
If pid namespaces are supported then this function will also print
the pid of a given pidfd refers to for all descendant pid namespaces
starting from the current pid namespace of the instance, i.e. the
Pid field and the first entry in the NSpid field will be identical.

Note that this differs from the Pid and NSpid fields in
/proc/<pid>/status where Pid and NSpid are always shown relative to
the pid namespace of the procfs instance.
____

PIDFD.PID <``number``>::
PID of the process targeted by the pidfd.

PING.ID <`number`>::
ICMP echo request id used on the PING socket.

POS <``number``>::
File position.

RAW.PROTOCOL <``number``>::
Protocol number of the raw socket.

RDEV <``string``>::
Device ID (if special file).

SIZE <``number``>::
File size.

SOCK.LISTENING <``boolean``>::
Listening socket.

SOCK.NETS <``number``>::
Inode identifying network namespace where the socket belongs to.

SOCK.PROTONAME <``string``>::
Protocol name.

SOCK.STATE <``string``>::
State of socket.

SOCK.TYPE <``string``>::
Type of socket. Here type means the second parameter of
socket system call:
+
* stream
* dgram
* raw
* rdm
* seqpacket
* dccp
* packet

SOURCE <``string``>::
File system, partition, or device containing the file.

STTYPE <``string``>::
Raw file types returned from *stat*(2): BLK, CHR, DIR, FIFO, LINK, REG, SOCK, or UNKN.

TCP.LADDR <``string``>::
Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.

TCP.LPORT <``integer``>::
Local TCP port.

TCP.RADDR <``string``>::
Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.

TCP.RPORT <``integer``>::
Remote TCP port.

TID <``number``>::
Thread ID of the process opening the file.

TYPE <``string``>::
Cooked version of STTYPE. It is same as STTYPE with exceptions.
For SOCK, print the value for SOCK.PROTONAME.
For UNKN, print the value for AINODECLASS if SOURCE is anon_inodefs.

UDP.LADDR <``string``>::
Local IP address and local UDP port.

UDP.LPORT <``integer``>::
Local UDP port.

UDP.RADDR <``string``>::
Remote IP address and remote UDP port.

UDP.RPORT <``integer``>::
Remote UDP port.

UDPLITE.LADDR <``string``>::
Local IP address and local UDPLite port.

UDPLITE.LPORT <``integer``>::
Local UDP port.

UDPLITE.RADDR <``string``>::
Remote IP address and remote UDPLite port.

UDPLITE.RPORT <``integer``>::
Remote UDP port.

UID <``number``>::
User ID number.

UNIX.PATH <``string``>::
Filesystem pathname for UNIX domain socket.

USER <``string``>::
User of the process.

== FILTER EXPRESSION

*lsfd* evaluates the expression passed to *--filter* option every time
before printing a file line. *lsfd* prints the line only if the result
of evaluation is `true`.

An expression consists of column names, literals and, operators like:
`DELETED`, `(PID == 1)`, `(NAME == "/etc/passwd")`, `(PID == 1) && DELETED`.
`DELETED`, `PID`, and `NAME` are column names in the example.
`1` and "/etc/passwd" are literals.
`==` and `&&` are operators.

Before evaluation, *lsfd* substitutes column names in the given
expression with actual column values in the line. There are three
different data types: `boolean`, `string`, and `number`.  For columns
with a `boolean` type, the value can be stand-alone.  For `string` and
`number` values, the value must be an operand of an operator, for
example, `(PID == 1)`. See *OUTPUT COLUMNS* about the types of
columns.

Literal is for representing a value directly. See BOOLLIT, STRLIT, and
NUMLIT. Different data types have different literal syntax.

An operator works with one or two operand(s). An operator has an
expectation about the data type(s) of its operands. Giving an
unexpected data type to an operator causes a syntax error.

Operators taking two operands are `and`, `or`, `eq`, `ne`, `le`, `lt`, `ge`, `gt`, `=~`, `!~`.
Alphabetically named operators have C-language
flavored aliases: `&&`, `||`, `==`, `!=`, `<`, `<=`, `>=`, and `>`.

`!` is the only operator that takes one operand.

`eq`, `ne`, and their aliases expect operands have the same data type.
Applying these operators return a `boolean`.

`and`, `or`, `not` and their aliases expect operands have `boolean` data
type. Applying these operators return a `boolean`.

`lt`, `le`, `gt`, `ge`, and their aliases expect operands have
`number` data types. Applying these operators return a `boolean`.

`=~` is for regular expression matching; if a string at the right side
matches a regular expression at the left side, the result is true.
The right side operand must be a string literal. See STRLIT about the
syntax.

`!~` is a short-hand version of `not (STR =~ PAT)`; it inverts the
result of `=~`.

=== Limitations

The current implementation does not define precedences within
operators.  Use `(` and `)` explicitly for grouping the
sub-expressions if your expression uses more than two operators.

About `number` typed values, the filter engine supports only
non-negative integers.

=== Semi-formal syntax

//TRANSLATORS: In the following messages, translate only the <``variables``>.
EXPR :: BOOLEXP

BOOLEXP0 :: COLUMN <``boolean``> | BOOLLIT | _(_ BOOLEXP _)_

BOOLEXP :: BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG

COLUMN :: [\_A-Za-z][-_:A-Za-z0-9]*

BOOLOP1 :: _!_ BOOLEXP0 | _not_ BOOLEXP0

STREXP :: COLUMN <``string``> | STRLIT

NUMEXP :: COLUMN <``number``> | NUMLIT

BOOLLIT :: _true_ | _false_

CHARS  :: ( [^\] | _\\_ | _\'_ | _\"_ )*

STRLIT :: _'_ CHARS _'_ | _"_ CHARS _"_

NUMLIT :: [1-9][0-9]* | _0_

BOOLOP2 :: STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0

OP2   :: _==_ | _eq_ | _!=_ | _ne_

BOOLOP2BL :: BOOLEXP0 OP2BL BOOLEXP0

OP2BL ::  _&&_ | _and_ |  _||_ | _or_

BOOLOP2CMP :: NUMEXP OP2CMP NUMEXP

OP2CMP :: _<_ | _lt_ | _\<=_ | _le_ | _>_ | _gt_ | _>=_ | _ge_

BOOLOP2REG :: STREXP OP2REG STRLIT

OP2REG :: _=~_ | _!~_

== FILTER EXAMPLES

*lsfd* has few options for filtering. In most of cases, what you should
know is *-Q* (or *--filter*) option.  Combined with *-o* (or
*--output*) option, you can customize the output as you want.

//TRANSLATORS: In the following messages, don't forget to add whitespace at the end!
List files associated with PID 1 and PID 2 processes: ::
....
# lsfd -Q '(PID == 1) or (PID == 2)'
....

Do the same in an alternative way: ::
....
# lsfd -Q '(PID == 1) || (PID == 2)'
....

Do the same in a more efficient way: ::
....
# lsfd --pid 1,2
....

Whitescapes can be used instead of a comma: ::
....
# lsfd --pid '1 2'
....

Utilize *pidof*(1) for list the files associated with "firefox": ::
....
# lsfd --pid "$(pidof firefox)"
....

List the 1st file descriptor opened by PID 1 process: ::
....
# lsfd -Q '(PID == 1) and (FD == 1)'
....

Do the same in an alternative way: ::
....
# lsfd -Q '(PID == 1) && (FD == 1)'
....

List all running executables: ::
....
# lsfd -Q 'ASSOC == "exe"'
....

Do the same in an alternative way: ::
....
# lsfd -Q 'ASSOC eq "exe"'
....

Do the same but print only file names: ::
....
# lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
....

List deleted files associated to processes: ::
....
# lsfd -Q 'DELETED'
....

List non-regular files: ::
....
# lsfd -Q 'TYPE != "REG"'
....

List block devices: ::
....
# lsfd -Q 'DEVTYPE == "blk"'
....

Do the same with TYPE column: ::
....
# lsfd -Q 'TYPE == "BLK"'
....

List files including "dconf" directory in their names: ::
....
# lsfd -Q 'NAME =~ ".\*/dconf/.*"'
....

List files opened in a QEMU virtual machine: ::
....
# lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
....

Hide files associated to kernel threads: ::
....
# lsfd -Q '!KTHREAD'
....

== COUNTER EXAMPLES

Report the numbers of netlink socket descriptors and unix socket descriptors: ::
....
# lsfd --summary=only \
	-C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
	-C 'unix sockets':'(NAME =~ "UNIX:.*")'
VALUE COUNTER
   57 netlink sockets
 1552 unix sockets
....

Do the same but print in JSON format: ::
....
# lsfd --summary=only --json \
	-C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
	-C 'unix sockets':'(NAME =~ "UNIX:.*")'
{
   "lsfd-summary": [
      {
	 "value": 15,
	 "counter": "netlink sockets"
      },{
	 "value": 798,
	 "counter": "unix sockets"
      }
   ]
}
....


== HISTORY

The *lsfd* command is part of the util-linux package since v2.38.

== AUTHORS

mailto:yamato@redhat.com[Masatake YAMATO],
mailto:kzak@redhat.com[Karel Zak]

== SEE ALSO

*lsof*(8)
*pidof*(1)
*proc*(5)
*socket*(2)
*stat*(2)

include::man-common/bugreports.adoc[]

include::man-common/footer.adoc[]

ifdef::translation[]
include::man-common/translation.adoc[]
endif::[]