diff options
Diffstat (limited to '')
| -rw-r--r-- | misc-utils/lsfd.1.adoc | 667 |
1 files changed, 667 insertions, 0 deletions
diff --git a/misc-utils/lsfd.1.adoc b/misc-utils/lsfd.1.adoc new file mode 100644 index 0000000..23eee28 --- /dev/null +++ b/misc-utils/lsfd.1.adoc @@ -0,0 +1,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::[] |