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 *-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 _PID_,_COMMAND_,_ASSOC_[-r][-w]
 184 +
 185 The last characters ([-r][-w]) represents the read and/or
 186 write mode of the endpoint.
 187
 188 eventfd type:::
 189 _PID_,_COMMAND_,_ASSOC_
 190
 191 UNIX-STREAM:::
 192 _PID_,_COMMAND_,_ASSOC_[-r?][-w?]
 193 +
 194 About the last characters ([-r?][-w?]), see the description
 195 of _SOCK.SHUTDOWN_.
 196
 197 EVENTFD.ID <``number``>::
 198 Eventfd ID.
 199
 200 EVENTPOLL.TFDS <``string``>::
 201 File descriptors targeted by the eventpoll file.
 202
 203 FD <``number``>::
 204 File descriptor for the file.
 205
 206 FLAGS <``string``>::
 207 Flags specified when opening the file.
 208
 209 FUID <``number``>::
 210 User ID number of the file's owner.
 211
 212 INET.LADDR <``string``>::
 213 Local IP address.
 214
 215 INET.RADDR <``string``>::
 216 Remote IP address.
 217
 218 INET6.LADDR <``string``>::
 219 Local IP6 address.
 220
 221 INET6.RADDR <``string``>::
 222 Remote IP6 address.
 223
 224 INODE <``number``>::
 225 Inode number.
 226
 227 INOTIFY.INODES <``string``>::
 228 Cooked version of INOTIFY.INODES.RAW.
 229 The format of the element is
 230 _inode-number_,_source-of-inode_.
 231
 232 INOTIFY.INODES.RAW <``string``>::
 233 List of monitoring inodes. The format of the element
 234 is _inode-number_,_device-major_:_device-minor_.
 235
 236 KNAME <``string``>::
 237 //
 238 // It seems that the manpage backend of asciidoctor has limitations
 239 // about emitting text with nested face specifications like:
 240 //
 241 //   `_u_` p
 242 //
 243 // Not only u but also p is decorated with underline.
 244 //
 245 Raw file name extracted from
 246 from ``/proc/``_pid_``/fd/``_fd_ or ``/proc/``_pid_``/map_files/``_region_.
 247
 248 KTHREAD <``boolean``>::
 249 Whether the process is a kernel thread or not.
 250
 251 MAJ:MIN <``string``>::
 252 Device ID for special, or ID of device containing file.
 253
 254 MAPLEN <``number``>::
 255 Length of file mapping (in page).
 256
 257 MISCDEV <``string``>::
 258 Misc character device name resolved by `/proc/misc`.
 259
 260 MNTID <``number``>::
 261 Mount ID.
 262
 263 MODE <``string``>::
 264 Access mode (rwx).
 265
 266 NAME <``string``>::
 267 Cooked version of KNAME. It is mostly same as KNAME.
 268 +
 269 Some files have special formats and information sources:
 270 +
 271 bpf-map:::
 272 id=_BPF-MAP.ID_ type=_BPF-MAP.TYPE_[ name=_BPF.NAME_]
 273 +
 274 bpf-prog:::
 275 id=_BPF-PROG.ID_ type=_BPF-PROG.TYPE_[ name=_BPF.NAME_]
 276 +
 277 eventpoll:::
 278 tfds=_EVENTPOLL.TFDS_
 279 +
 280 eventfd:::
 281 id=_EVENTFD.ID_
 282 +
 283 inotify:::
 284 inodes=_INOTIFY.INODES_
 285 +
 286 misc:tun:::
 287 iface=_TUN.IFACE_
 288 +
 289 NETLINK:::
 290 protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]]
 291 +
 292 PACKET:::
 293 type=_SOCK.TYPE_[ protocol=_PACKET.PROTOCOL_][ iface=_PACKET.IFACE_]
 294 +
 295 pidfd:::
 296 pid=_TARGET-PID_ comm=_TARGET-COMMAND_ nspid=_TARGET-NSPIDS_
 297 +
 298 *lsfd* extracts _TARGET-PID_ and _TARGET-NSPIDS_ from
 299 ``/proc/``_pid_``/fdinfo/``_fd_.
 300 +
 301 PING:::
 302 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]
 303 +
 304 PINGv6:::
 305 state=_SOCK.STATE_[ id=_PING.ID_][ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]
 306 +
 307 RAW:::
 308 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET.LADDR_ [ raddr=_INET.RADDR_]]]
 309 +
 310 RAWv6:::
 311 state=_SOCK.STATE_[ protocol=_RAW.PROTOCOL_ [ laddr=_INET6.LADDR_ [ raddr=_INET6.RADDR_]]]
 312 +
 313 signalfd:::
 314 mask=_SIGNALFD.MASK_
 315 +
 316 TCP:::
 317 TCPv6:::
 318 state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]]
 319 +
 320 timerfd:::
 321 clockid=_TIMERFD.CLOCKID_[ remaining=_TIMERFD.REMAINING_ [ interval=_TIMERFD.INTERVAL_]]
 322 +
 323 UDP:::
 324 UDPv6:::
 325 state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]]
 326 +
 327 *lsfd* hides ``raddr=`` if _UDP.RADDR_ is ``0.0.0.0`` and _UDP.RPORT_ is 0.
 328 +
 329 UDP-LITE:::
 330 UDPLITEv6:::
 331 state=_SOCK.STATE_[ laddr=_UDPLITE.LADDR_ [ raddr=_UDPLITE.RADDR_]]
 332 +
 333 UNIX-STREAM:::
 334 state=_SOCK.STATE_[ path=_UNIX.PATH_]
 335 +
 336 UNIX:::
 337 state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_
 338
 339 ____
 340 Note that `(deleted)` markers are removed from this column.
 341 Refer to _KNAME_, _DELETED_, or _XMODE_ to know the
 342 readability of the file from the file system.
 343 ____
 344
 345 NETLINK.GROUPS <``number``>::
 346 Netlink multicast groups.
 347
 348 NETLINK.LPORT <``number``>::
 349 Netlink local port id.
 350
 351 NETLINK.PROTOCOL <``string``>::
 352 Netlink protocol.
 353
 354 NLINK <``number``>::
 355 Link count.
 356
 357 NS.NAME <``string``>::
 358 Name (_NS.TYPE_:[_INODE_]) of the namespace specified with the file.
 359
 360 NS.TYPE <``string``>::
 361 Type of the namespace specified with the file.
 362 The type is `mnt`, `cgroup`, `uts`, `ipc`, `user`, `pid`, `net`,
 363 `time`, or `unknown`.
 364
 365 OWNER <``string``>::
 366 Owner of the file.
 367
 368 PACKET.IFACE <``string``>::
 369 Interface name associated with the packet socket.
 370
 371 PACKET.PROTOCOL <``string``>::
 372 L3 protocol associated with the packet socket.
 373
 374 PARTITION <``string``>::
 375 Block device name resolved by `/proc/partition`.
 376
 377 PID <``number``>::
 378 PID of the process opening the file.
 379
 380 PIDFD.COMM <``string``>::
 381 Command of the process targeted by the pidfd.
 382
 383 PIDFD.NSPID <``string``>::
 384 Value of NSpid field in ``/proc/``_pid_``/fdinfo/``_fd_ of the pidfd.
 385 +
 386 Quoted from kernel/fork.c of Linux source tree:
 387 +
 388 ____
 389 If pid namespaces are supported then this function will also print
 390 the pid of a given pidfd refers to for all descendant pid namespaces
 391 starting from the current pid namespace of the instance, i.e. the
 392 Pid field and the first entry in the NSpid field will be identical.
 393
 394 Note that this differs from the Pid and NSpid fields in
 395 /proc/<pid>/status where Pid and NSpid are always shown relative to
 396 the pid namespace of the procfs instance.
 397 ____
 398
 399 PIDFD.PID <``number``>::
 400 PID of the process targeted by the pidfd.
 401
 402 PING.ID <`number`>::
 403 ICMP echo request id used on the PING socket.
 404
 405 POS <``number``>::
 406 File position.
 407
 408 RAW.PROTOCOL <``number``>::
 409 Protocol number of the raw socket.
 410
 411 RDEV <``string``>::
 412 Device ID (if special file).
 413
 414 SIGNALFD.MASK <``string``>::
 415 Masked signals.
 416
 417 SIZE <``number``>::
 418 File size.
 419
 420 SOCK.LISTENING <``boolean``>::
 421 Listening socket.
 422
 423 SOCK.NETS <``number``>::
 424 Inode identifying network namespace where the socket belongs to.
 425
 426 SOCK.PROTONAME <``string``>::
 427 Protocol name.
 428
 429 SOCK.SHUTDOWN <``string``>::
 430 Shutdown state of socket.
 431 +
 432 [-r?]:::
 433 If the first character is _r_, the receptions are allowed.
 434 If it is _-_, the receptions are disallowed.
 435 If it is _?_, the state is unknown.
 436 +
 437 [-w?]:::
 438 If the second character is _w_, the transmissions are allowed.
 439 If it is _-_, the transmissions are disallowed.
 440 If it is _?_, the state is unknown.
 441
 442 SOCK.STATE <``string``>::
 443 State of socket.
 444
 445 SOCK.TYPE <``string``>::
 446 Type of socket. Here type means the second parameter of
 447 socket system call:
 448 +
 449 * stream
 450 * dgram
 451 * raw
 452 * rdm
 453 * seqpacket
 454 * dccp
 455 * packet
 456
 457 SOURCE <``string``>::
 458 File system, partition, or device containing the file.
 459
 460 STTYPE <``string``>::
 461 Raw file types returned from *stat*(2): BLK, CHR, DIR, FIFO, LINK, REG, SOCK, or UNKN.
 462
 463 TCP.LADDR <``string``>::
 464 Local L3 (INET.LADDR or INET6.LADDR) address and local TCP port.
 465
 466 TCP.LPORT <``number``>::
 467 Local TCP port.
 468
 469 TCP.RADDR <``string``>::
 470 Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port.
 471
 472 TCP.RPORT <``number``>::
 473 Remote TCP port.
 474
 475 TID <``number``>::
 476 Thread ID of the process opening the file.
 477
 478 TIMERFD.CLOCKID <``string``>::
 479 Clockid.
 480
 481 TIMERFD.INTERVAL <``number``>::
 482 Interval.
 483
 484 TIMERFD.REMAINING <``number``>::
 485 Remaining time.
 486
 487 TUN.IFACE <``string``>::
 488 Network intrface behind the tun device.
 489
 490 TYPE <``string``>::
 491 Cooked version of STTYPE. It is same as STTYPE with exceptions.
 492 For SOCK, print the value for SOCK.PROTONAME.
 493 For UNKN, print the value for AINODECLASS if SOURCE is anon_inodefs.
 494
 495 UDP.LADDR <``string``>::
 496 Local IP address and local UDP port.
 497
 498 UDP.LPORT <``number``>::
 499 Local UDP port.
 500
 501 UDP.RADDR <``string``>::
 502 Remote IP address and remote UDP port.
 503
 504 UDP.RPORT <``number``>::
 505 Remote UDP port.
 506
 507 UDPLITE.LADDR <``string``>::
 508 Local IP address and local UDPLite port.
 509
 510 UDPLITE.LPORT <``number``>::
 511 Local UDP port.
 512
 513 UDPLITE.RADDR <``string``>::
 514 Remote IP address and remote UDPLite port.
 515
 516 UDPLITE.RPORT <``number``>::
 517 Remote UDP port.
 518
 519 UID <``number``>::
 520 User ID number.
 521
 522 UNIX.PATH <``string``>::
 523 Filesystem pathname for UNIX domain socket.
 524
 525 USER <``string``>::
 526 User of the process.
 527
 528 XMODE <``string``>::
 529 Extended version of _MODE_. This column may grow; new letters may be
 530 appended to _XMODE_ when *lsfd* supports a new state of file descriptors
 531 and/or memory mappings.
 532 +
 533 [-r]:::
 534 opened of mapped for reading. This is also in _MODE_.
 535 +
 536 [-w]:::
 537 opened of mapped for writing. This is also in _MODE_.
 538 +
 539 [-x]:::
 540 mapped for executing the code. This is also in _MODE_.
 541 +
 542 [-D]:::
 543 deleted from  the file system. See also _DELETED._.
 544 +
 545 [-Ll]:::
 546 locked or leased. _l_ represents a read, a shared lock or a read lease.
 547 _L_ represents a write or an exclusive lock or a write lease. If both
 548 read/shared and write/exclusive locks or leases are taken by a file
 549 descriptor, _L_ is used as the flag.
 550 +
 551 [-m]:::
 552 Multiplexed. If the file descriptor is targeted by a eventpoll file
 553 or classical system calls for multiplexing (select, pselect, poll, and
 554 ppoll), this bit flag is set. Note that if an invocaiton of the
 555 classical system calls is interrupted, *lsfd* may fail to mark _m_
 556 on the file descriptors monitored by the invocaiton.
 557 See *restart_syscall*(2).
 558
 559 == FILTER EXPRESSION
 560
 561 *lsfd* evaluates the expression passed to *--filter* option every time
 562 before printing a file line. *lsfd* prints the line only if the result
 563 of evaluation is `true`.
 564
 565 An expression consists of column names, literals and, operators like:
 566 `DELETED`, `(PID == 1)`, `(NAME == "/etc/passwd")`, `(PID == 1) && DELETED`.
 567 `DELETED`, `PID`, and `NAME` are column names in the example.
 568 `1` and "/etc/passwd" are literals.
 569 `==` and `&&` are operators.
 570
 571 Before evaluation, *lsfd* substitutes column names in the given
 572 expression with actual column values in the line. There are three
 573 different data types: `boolean`, `string`, and `number`.  For columns
 574 with a `boolean` type, the value can be stand-alone.  For `string` and
 575 `number` values, the value must be an operand of an operator, for
 576 example, `(PID == 1)`. See *OUTPUT COLUMNS* about the types of
 577 columns.
 578
 579 Literal is for representing a value directly. See BOOLLIT, STRLIT, and
 580 NUMLIT. Different data types have different literal syntax.
 581
 582 An operator works with one or two operand(s). An operator has an
 583 expectation about the data type(s) of its operands. Giving an
 584 unexpected data type to an operator causes a syntax error.
 585
 586 Operators taking two operands are `and`, `or`, `eq`, `ne`, `le`, `lt`, `ge`, `gt`, `=~`, `!~`.
 587 Alphabetically named operators have C-language
 588 flavored aliases: `&&`, `||`, `==`, `!=`, `<`, `<=`, `>=`, and `>`.
 589
 590 `!` is the only operator that takes one operand.
 591
 592 `eq`, `ne`, and their aliases expect operands have the same data type.
 593 Applying these operators return a `boolean`.
 594
 595 `and`, `or`, `not` and their aliases expect operands have `boolean` data
 596 type. Applying these operators return a `boolean`.
 597
 598 `lt`, `le`, `gt`, `ge`, and their aliases expect operands have
 599 `number` data types. Applying these operators return a `boolean`.
 600
 601 `=~` is for regular expression matching; if a string at the right side
 602 matches a regular expression at the left side, the result is true.
 603 The right side operand must be a string literal. See STRLIT about the
 604 syntax.
 605
 606 `!~` is a short-hand version of `not (STR =~ PAT)`; it inverts the
 607 result of `=~`.
 608
 609 === Limitations
 610
 611 The current implementation does not define precedences within
 612 operators.  Use `(` and `)` explicitly for grouping the
 613 sub-expressions if your expression uses more than two operators.
 614
 615 About `number` typed values, the filter engine supports only
 616 non-negative integers, and non-negative floating point numbers.
 617
 618 === Semi-formal syntax
 619
 620 //TRANSLATORS: In the following messages, translate only the <``variables``>.
 621 EXPR :: BOOLEXP
 622
 623 BOOLEXP0 :: COLUMN <``boolean``> | BOOLLIT | _(_ BOOLEXP _)_
 624
 625 BOOLEXP :: BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP | BOOLOP2REG
 626
 627 COLUMN :: [\_A-Za-z][-_:A-Za-z0-9]*
 628
 629 BOOLOP1 :: _!_ BOOLEXP0 | _not_ BOOLEXP0
 630
 631 STREXP :: COLUMN <``string``> | STRLIT
 632
 633 NUMEXP :: COLUMN <``number``> | NUMLIT
 634
 635 BOOLLIT :: _true_ | _false_
 636
 637 CHARS  :: ( [^\] | _\\_ | _\'_ | _\"_ )*
 638
 639 STRLIT :: _'_ CHARS _'_ | _"_ CHARS _"_
 640
 641 NUMLIT :: INTLIT | FNUMLIT
 642
 643 INTLIT :: [1-9][0-9]* | _0_
 644
 645 FNUMLIT :: INTLIT _._ [0-9][0-9]*
 646
 647 BOOLOP2 :: STREXP OP2 STREXP | NUMEXP OP2 NUMEXP | BOOLEXP0 OP2 BOOLEXP0
 648
 649 OP2   :: _==_ | _eq_ | _!=_ | _ne_
 650
 651 BOOLOP2BL :: BOOLEXP0 OP2BL BOOLEXP0
 652
 653 OP2BL ::  _&&_ | _and_ |  _||_ | _or_
 654
 655 BOOLOP2CMP :: NUMEXP OP2CMP NUMEXP
 656
 657 OP2CMP :: _<_ | _lt_ | _\<=_ | _le_ | _>_ | _gt_ | _>=_ | _ge_
 658
 659 BOOLOP2REG :: STREXP OP2REG STRLIT
 660
 661 OP2REG :: _=~_ | _!~_
 662
 663 == FILTER EXAMPLES
 664
 665 *lsfd* has few options for filtering. In most of cases, what you should
 666 know is *-Q* (or *--filter*) option.  Combined with *-o* (or
 667 *--output*) option, you can customize the output as you want.
 668
 669 //TRANSLATORS: In the following messages, don't forget to add whitespace at the end!
 670 List files associated with PID 1 and PID 2 processes: ::
 671 ....
 672 # lsfd -Q '(PID == 1) or (PID == 2)'
 673 ....
 674
 675 Do the same in an alternative way: ::
 676 ....
 677 # lsfd -Q '(PID == 1) || (PID == 2)'
 678 ....
 679
 680 Do the same in a more efficient way: ::
 681 ....
 682 # lsfd --pid 1,2
 683 ....
 684
 685 Whitescapes can be used instead of a comma: ::
 686 ....
 687 # lsfd --pid '1 2'
 688 ....
 689
 690 Utilize *pidof*(1) for list the files associated with "firefox": ::
 691 ....
 692 # lsfd --pid "$(pidof firefox)"
 693 ....
 694
 695 List the 1st file descriptor opened by PID 1 process: ::
 696 ....
 697 # lsfd -Q '(PID == 1) and (FD == 1)'
 698 ....
 699
 700 Do the same in an alternative way: ::
 701 ....
 702 # lsfd -Q '(PID == 1) && (FD == 1)'
 703 ....
 704
 705 List all running executables: ::
 706 ....
 707 # lsfd -Q 'ASSOC == "exe"'
 708 ....
 709
 710 Do the same in an alternative way: ::
 711 ....
 712 # lsfd -Q 'ASSOC eq "exe"'
 713 ....
 714
 715 Do the same but print only file names: ::
 716 ....
 717 # lsfd -o NAME -Q 'ASSOC eq "exe"' | sort -u
 718 ....
 719
 720 List deleted files associated to processes: ::
 721 ....
 722 # lsfd -Q 'DELETED'
 723 ....
 724
 725 List non-regular files: ::
 726 ....
 727 # lsfd -Q 'TYPE != "REG"'
 728 ....
 729
 730 List block devices: ::
 731 ....
 732 # lsfd -Q 'DEVTYPE == "blk"'
 733 ....
 734
 735 Do the same with TYPE column: ::
 736 ....
 737 # lsfd -Q 'TYPE == "BLK"'
 738 ....
 739
 740 List files including "dconf" directory in their names: ::
 741 ....
 742 # lsfd -Q 'NAME =~ ".\*/dconf/.*"'
 743 ....
 744
 745 List files opened in a QEMU virtual machine: ::
 746 ....
 747 # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)'
 748 ....
 749
 750 Hide files associated to kernel threads: ::
 751 ....
 752 # lsfd -Q '!KTHREAD'
 753 ....
 754
 755 List timerfd files expired within 0.5 seconds: ::
 756 ....
 757 # lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)'
 758 ....
 759
 760 == COUNTER EXAMPLES
 761
 762 Report the numbers of netlink socket descriptors and unix socket descriptors: ::
 763 ....
 764 # lsfd --summary=only \
 765         -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
 766         -C 'unix sockets':'(NAME =~ "UNIX:.*")'
 767 VALUE COUNTER
 768    57 netlink sockets
 769  1552 unix sockets
 770 ....
 771
 772 Do the same but print in JSON format: ::
 773 ....
 774 # lsfd --summary=only --json \
 775         -C 'netlink sockets':'(NAME =~ "NETLINK:.*")' \
 776         -C 'unix sockets':'(NAME =~ "UNIX:.*")'
 777 {
 778    "lsfd-summary": [
 779       {
 780          "value": 15,
 781          "counter": "netlink sockets"
 782       },{
 783          "value": 798,
 784          "counter": "unix sockets"
 785       }
 786    ]
 787 }
 788 ....
 789
 790
 791 == HISTORY
 792
 793 The *lsfd* command is part of the util-linux package since v2.38.
 794
 795 == AUTHORS
 796
 797 mailto:yamato@redhat.com[Masatake YAMATO],
 798 mailto:kzak@redhat.com[Karel Zak]
 799
 800 == SEE ALSO
 801 *bpftool*(8)
 802 *bps*(8)
 803 *lslocks*(8)
 804 *lsof*(8)
 805 *pidof*(1)
 806 *proc*(5)
 807 *socket*(2)
 808 *ss*(8)
 809 *stat*(2)
 810
 811 include::man-common/bugreports.adoc[]
 812
 813 include::man-common/footer.adoc[]
 814
 815 ifdef::translation[]
 816 include::man-common/translation.adoc[]
 817 endif::[]