lsfd(1) - f38

1LSFD(1)                          User Commands                         LSFD(1)
2
3
4

NAME

6       lsfd - list file descriptors
7

SYNOPSIS

9       lsfd [option]
10

DESCRIPTION

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
18       lsfd uses Libsmartcols for output formatting and filtering. See the
19       description of --output option for customizing the output format, and
20       --filter option for filtering.
21

OPTIONS

23       -l, --threads
24           List in threads level.
25
26       -J, --json
27           Use JSON output format.
28
29       -n, --noheadings
30           Don’t print headings.
31
32       -o, --output list
33           Specify which output columns to print. See the OUTPUT COLUMNS
34           section for details of available columns.
35
36           The default list of columns may be extended if list is specified in
37           the format +list (e.g., lsfd -o +DELETED).
38
39       -r, --raw
40           Use raw output format.
41
42       --notruncate
43           Don’t truncate text in columns.
44
45       -p, --pid pids
46           Collect information only for specified processes. pids is a list of
47           pids. A comma or whitespaces can be used as separators. You can use
48           this option with pidof(1). See FILTER EXAMPLES.
49
50           Both -Q option with an expression including PID, e.g. -Q (PID ==
51           1), and -p option, e.g. -p 1, may print the same output but using
52           -p option is much more efficient because -p option works at a much
53           earlier stage of processing than the -Q option.
54
55       -Q, --filter expr
56           Print only the files matching the condition represented by the
57           expr. See also FILTER EXAMPLES.
58
59       -C, --counter label:filter_expr
60           Define a custom counter used in --summary output. lsfd makes a
61           counter named label. During collect information, lsfd counts files
62           matching filter_expr, and stores the counted number to the counter
63           named label. lsfd applies filters defined with --filter options
64           before counting; files excluded by the filters are not counted.
65
66           See FILTER EXPRESSION about filter_expr. label should not include {
67           nor :. You can define multiple counters by specifying this option
68           multiple times.
69
70           See also COUNTER EXAMPLES.
71
72       --summary[=when]
73           This option controls summary lines output. The optional argument
74           when can be only, append or never. If the when argument is omitted,
75           it defaults to only.
76
77           The summary reports counters. A counter consists of a label and an
78           integer value. --counter is the option for defining a counter. If a
79           user defines no counter, lsfd uses the definitions of pre-defined
80           built-in counters (default counters) to make the summary output.
81
82           CAUTION: Using --summary and --json may make the output broken.
83           Only combining --summary=only and --json is valid.
84
85       --debug-filter
86           Dump the internal data structure for the filter and exit. This is
87           useful only for lsfd developers.
88
89       --dump-counters
90           Dump the definition of counters used in --summary output.
91
92       -h, --help
93           Display help text and exit.
94
95       -V, --version
96           Print version and exit.
97

OUTPUT COLUMNS

99       Each column has a type. Types are surround by < and >.
100
101       CAUTION: The names and types of columns are not stable yet. They may be
102       changed in the future releases.
103
104       ASSOC <string>
105           Association between file and process.
106
107       BLKDRV <string>
108           Block device driver name resolved by /proc/devices.
109
110       CHRDRV <string>
111           Character device driver name resolved by /proc/devices.
112
113       COMMAND <string>
114           Command of the process opening the file.
115
116       DELETED <boolean>
117           Reachability from the file system.
118
119       DEV <string>
120           ID of the device containing the file.
121
122       DEVTYPE <string>
123           Device type (blk, char, or nodev).
124
125       FD <number>
126           File descriptor for the file.
127
128       FLAGS <string>
129           Flags specified when opening the file.
130
131       FUID <number>
132           User ID number of the file’s owner.
133
134       INODE <number>
135           Inode number.
136
137       KTHREAD <boolean>
138           Whether the process is a kernel thread or not.
139
140       MAJ:MIN <string>
141           Device ID for special, or ID of device containing file.
142
143       MAPLEN <number>
144           Length of file mapping (in page).
145
146       MISCDEV <string>
147           Misc character device name resolved by /proc/misc.
148
149       MNTID <number>
150           Mount ID.
151
152       MODE <string>
153           Access mode (rwx).
154
155       NAME <string>
156           Name of the file.
157
158       NLINK <number>
159           Link count.
160
161       OWNER <string>
162           Owner of the file.
163
164       PARTITION <string>
165           Block device name resolved by /proc/partition.
166
167       PID <number>
168           PID of the process opening the file.
169
170       POS <number>
171           File position.
172
173       PROTONAME <string>
174           Protocol name.
175
176       RDEV <string>
177           Device ID (if special file).
178
179       SIZE <number>
180           File size.
181
182       SOURCE <string>
183           File system, partition, or device containing the file.
184
185       TID <number>
186           Thread ID of the process opening the file.
187
188       TYPE <string>
189           File type.
190
191       UID <number>
192           User ID number.
193
194       USER <string>
195           User of the process.
196

FILTER EXPRESSION

198       lsfd evaluates the expression passed to --filter option every time
199       before printing a file line. lsfd prints the line only if the result of
200       evaluation is true.
201
202       An expression consists of column names, literals and, operators like:
203       DELETED, (PID == 1), (NAME == "/etc/passwd"), (PID == 1) && DELETED.
204       DELETED, PID, and NAME are column names in the example. 1 and
205       "/etc/passwd" are literals. == and && are operators.
206
207       Before evaluation, lsfd substitutes column names in the given
208       expression with actual column values in the line. There are three
209       different data types: boolean, string, and number. For columns with a
210       boolean type, the value can be stand-alone. For string and number
211       values, the value must be an operand of an operator, for example, (PID
212       == 1). See the "OUTPUT COLUMNS" about the types of columns.
213
214       Literal is for representing a value directly. See BOOLLIT, STRLIT, and
215       NUMLIT. Different data types have different literal syntax.
216
217       An operator works with one or two operand(s). An operator has an
218       expectation about the data type(s) of its operands. Giving an
219       unexpected data type to an operator causes a syntax error.
220
221       Operators taking two operands are and, or, eq, ne, le, lt, ge, gt, =~,
222       !~. Alphabetically named operators have C-language flavored aliases:
223       &&, ||, ==, !=, <, ⇐, >=, and >.
224
225       ! is the only operator that takes one operand.
226
227       eq, ne, and their aliases expect operands have the same data type.
228       Applying these operators return a boolean.
229
230       and, or, not and their aliases expect operands have bool data type.
231       Applying these operators return a boolean.
232
233       lt, le, gt, ge, and their aliases expect operands have number data
234       types. Applying these operators return a boolean.
235
236       =~ is for regular expression matching; if a string at the right side
237       matches a regular expression at the left side, the result is true. The
238       right side operand must be a string literal. See STRLIT about the
239       syntax.
240
241       !~ is a short-hand version of not (STR =~ PAT); it inverts the result
242       of =~.
243
244   Limitations
245       The current implementation does not define precedences within
246       operators. Use ( and ) explicitly for grouping the sub-expressions if
247       your expression uses more than two operators.
248
249       About number typed values, the filter engine supports only non-negative
250       integers.
251
252   Semi-formal syntax
253       EXPR
254           BOOLEXP
255
256       BOOLEXP0
257           COLUMN <boolean> | BOOLLIT | ( BOOLEXP )
258
259       BOOLEXP
260           BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG
261
262       COLUMN
263           [_A-Za-z][-_:A-Za-z0-9]*
264
265       BOOLOP1
266           ! BOOLEXP0 | not BOOLEXP0
267
268       STREXP
269           COLUMN <string> | STRLIT
270
271       NUMEXP
272           COLUMN <number> | NUMLIT
273
274       BOOLLIT
275           true | false
276
277       CHARS
278           ( [^\] | \\ | \' | \" )*
279
280       STRLIT
281           ' CHARS ' | " CHARS "
282
283       NUMLIT
284           [1-9][0-9]* | 0
285
286       BOOLOP2
287           STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0
288
289       OP2
290           == | eq | != | ne
291
292       BOOLOP2BL
293           BOOLEXP0 OP2BL BOOLEXP0
294
295       OP2BL
296           && | and |  || | or
297
298       BOOLOP2CMP
299           NUMEXP OP2CMP NUMEXP
300
301       OP2CMP
302           < | lt | <= | le | > | gt | >= | ge
303
304       BOOLOP2REG
305           STREXP OP2REG STRLIT
306
307       OP2REG
308           =~ | !~
309

FILTER EXAMPLES

311       lsfd has few options for filtering. In most of cases, what you should
312       know is -Q (or --filter) option. Combined with -o (or --output) option,
313       you can customize the output as you want.
314
315       List files associated with PID 1 and PID 2 processes:
316
317           # lsfd -Q '(PID == 1) or (PID == 2)'
318
319       Do the same in an alternative way:
320
321           # lsfd -Q '(PID == 1) || (PID == 2)'
322
323       Do the same in a more efficient way:
324
325           # lsfd --pid 1,2
326
327       Whitescapes can be used instead of a comma:
328
329           # lsfd --pid '1 2'
330
331       Utilize pidof(1) for list the files associated with "firefox":
332
333           # lsfd --pid "$(pidof firefox)"
334
335       List the 1st file descriptor opened by PID 1 process:
336
337           # lsfd -Q '(PID == 1) and (FD == 1)'
338
339       Do the same in an alternative way:
340
341           # lsfd -Q '(PID == 1) && (FD == 1)'
342
343       List all running executables:
344
345           # lsfd -Q 'ASSOC == "exe"'
346
347       Do the same in an alternative way:
348
349           # lsfd -Q 'ASSOC eq "exe"'
350
351       Do the same but print only file names:
352
353           # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
354
355       List deleted files associated to processes:
356
357           # lsfd -Q 'DELETED'
358
359       List non-regular files:
360
361           # lsfd -Q 'TYPE != "REG"'
362
363       List block devices:
364
365           # lsfd -Q 'DEVTYPE == "blk"'
366
367       Do the same with TYPE column:
368
369           # lsfd -Q 'TYPE == "BLK"'
370
371       List files including "dconf" directory in their names:
372
373           # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
374
375       List files opened in a QEMU virtual machine:
376
377           # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
378
379       Hide files associated to kernel threads:
380
381           # lsfd -Q '!KTHREAD'
382

COUNTER EXAMPLES

384       Report the numbers of netlink socket descriptors and unix socket
385       descriptors:
386
387           # lsfd --summary=only \
388                   -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
389                   -C 'unix sockets':'(NAME =~ "UNIX:.*")'
390           VALUE COUNTER
391              57 netlink sockets
392            1552 unix sockets
393
394       Do the same but print in JSON format:
395
396           # lsfd --summary=only --json \
397                   -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
398                   -C 'unix sockets':'(NAME =~ "UNIX:.*")'
399           {
400              "lsfd-summary": [
401                 {
402                    "value": 15,
403                    "counter": "netlink sockets"
404                 },{
405                    "value": 798,
406                    "counter": "unix sockets"
407                 }
408              ]
409           }
410

HISTORY

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

AUTHORS

415       Masatake YAMATO <yamato@redhat.com>, Karel Zak <kzak@redhat.com>
416

REPORTING BUGS

421       For bug reports, use the issue tracker at
422       https://github.com/util-linux/util-linux/issues.
423

AVAILABILITY

425       The lsfd command is part of the util-linux package which can be
426       downloaded from Linux Kernel Archive
427       <https://www.kernel.org/pub/linux/utils/util-linux/>.
428
429
430
431util-linux 2.38.1                 2022-08-04                           LSFD(1)