diff options
Diffstat (limited to 'misc-utils/lsfd.1.adoc')
| -rw-r--r-- | misc-utils/lsfd.1.adoc | 298 |
1 files changed, 175 insertions, 123 deletions
diff --git a/misc-utils/lsfd.1.adoc b/misc-utils/lsfd.1.adoc index 23eee28..512fb23 100644 --- a/misc-utils/lsfd.1.adoc +++ b/misc-utils/lsfd.1.adoc @@ -33,7 +33,7 @@ default outputs in your scripts. Always explicitly define expected columns by us *--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* +option for customizing the output format, and *--filter* option for filtering. Use *lsfd --list-columns* to get a list of all available columns. == OPTIONS @@ -75,7 +75,7 @@ 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*. +See also *scols-filter*(5) and *FILTER EXAMPLES*. *-C*, *--counter* __label__:__filter_expr__:: Define a custom counter used in *--summary* output. *lsfd* makes a @@ -84,7 +84,7 @@ 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_. +See *scols-filter*(5) about _filter_expr_. _label_ should not include `{` nor `:`. You can define multiple counters by specifying this option multiple times. + @@ -110,6 +110,9 @@ only for *lsfd* developers. *--dump-counters*:: Dump the definition of counters used in *--summary* output. +*-H*, *--list-columns*:: +List available columns that you can specify at *--output* option. + include::man-common/help-version.adoc[] == OUTPUT COLUMNS @@ -129,6 +132,27 @@ Association between file and process. BLKDRV <``string``>:: Block device driver name resolved by `/proc/devices`. +BPF-MAP.ID <``number``>:: +Bpf map ID. + +BPF-MAP.TYPE <``string``>:: +Decoded name of bpf map type. + +BPF-MAP.TYPE.RAW <``number``>:: +Bpf map type (raw). + +BPF.NAME <``string``>:: +Bpf object name. + +BPF-PROG.ID <``number``>:: +Bpf program ID. + +BPF-PROG.TYPE <``string``>:: +Decoded name of bpf program type. + +BPF-PROG.TYPE.RAW <``number``>:: +Bpf program type (raw). + CHRDRV <``string``>:: Character device driver name resolved by `/proc/devices`. @@ -146,19 +170,36 @@ Device type (`blk`, `char`, or `nodev`). ENDPOINT <``string``>:: IPC endpoints information communicated with the fd. ++ +*lsfd* collects endpoints within the processes that +*lsfd* scans; *lsfd* may miss some endpoints +if you limits the processes with *-p* option. ++ The format of the column depends on the object associated with the fd: -+ + FIFO type::: +mqueue type::: +ptmx and pts sources::: _PID_,_COMMAND_,_ASSOC_[-r][-w] + The last characters ([-r][-w]) represents the read and/or write mode of the endpoint. +eventfd type::: +_PID_,_COMMAND_,_ASSOC_ + +UNIX-STREAM::: +_PID_,_COMMAND_,_ASSOC_[-r?][-w?] + -*lsfd* collects endpoints within the processes that -*lsfd* scans; *lsfd* may miss some endpoints -if you limits the processes with *-p* option. +About the last characters ([-r?][-w?]), see the description +of _SOCK.SHUTDOWN_. + +EVENTFD.ID <``number``>:: +Eventfd ID. + +EVENTPOLL.TFDS <``string``>:: +File descriptors targeted by the eventpoll file. FD <``number``>:: File descriptor for the file. @@ -184,6 +225,15 @@ Remote IP6 address. INODE <``number``>:: Inode number. +INOTIFY.INODES <``string``>:: +Cooked version of INOTIFY.INODES.RAW. +The format of the element is +_inode-number_,_source-of-inode_. + +INOTIFY.INODES.RAW <``string``>:: +List of monitoring inodes. The format of the element +is _inode-number_``,``_device-major_``:``_device-minor_. + KNAME <``string``>:: // // It seems that the manpage backend of asciidoctor has limitations @@ -219,6 +269,24 @@ Cooked version of KNAME. It is mostly same as KNAME. + Some files have special formats and information sources: + +bpf-map::: +id=_BPF-MAP.ID_ type=_BPF-MAP.TYPE_[ name=_BPF.NAME_] ++ +bpf-prog::: +id=_BPF-PROG.ID_ type=_BPF-PROG.TYPE_[ name=_BPF.NAME_] ++ +eventpoll::: +tfds=_EVENTPOLL.TFDS_ ++ +eventfd::: +id=_EVENTFD.ID_ ++ +inotify::: +inodes=_INOTIFY.INODES_ ++ +misc:tun::: +iface=_TUN.IFACE_ ++ NETLINK::: protocol=_NETLINK.PROTOCOL_[ lport=_NETLINK.LPORT_[ group=_NETLINK.GROUPS_]] + @@ -237,16 +305,28 @@ 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_]] + +ptmx::: +tty-index=_PTMX.TTY-INDEX_ ++ +*lsfd* extracts _PTMX.TTY-INDEX_ from +``/proc/``_pid_``/fdinfo/``_fd_. ++ 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_]]] + +signalfd::: +mask=_SIGNALFD.MASK_ ++ TCP::: TCPv6::: state=_SOCK.STATE_[ laddr=_TCP.LADDR_ [ raddr=_TCP.RADDR_]] + +timerfd::: +clockid=_TIMERFD.CLOCKID_[ remaining=_TIMERFD.REMAINING_ [ interval=_TIMERFD.INTERVAL_]] ++ UDP::: UDPv6::: state=_SOCK.STATE_[ laddr=_UDP.LADDR_ [ raddr=_UDP.RADDR_]] @@ -263,13 +343,19 @@ state=_SOCK.STATE_[ path=_UNIX.PATH_] UNIX::: state=_SOCK.STATE_[ path=_UNIX.PATH_] type=_SOCK.TYPE_ -NETLINK.GROUPS <``number``>>:: +____ +Note that `(deleted)` markers are removed from this column. +Refer to _KNAME_, _DELETED_, or _XMODE_ to know the +readability of the file from the file system. +____ + +NETLINK.GROUPS <``number``>:: Netlink multicast groups. -NETLINK.LPORT <``number``>>:: +NETLINK.LPORT <``number``>:: Netlink local port id. -NETLINK.PROTOCOL <``string``>>:: +NETLINK.PROTOCOL <``string``>:: Netlink protocol. NLINK <``number``>:: @@ -332,6 +418,9 @@ Protocol number of the raw socket. RDEV <``string``>:: Device ID (if special file). +SIGNALFD.MASK <``string``>:: +Masked signals. + SIZE <``number``>:: File size. @@ -344,6 +433,19 @@ Inode identifying network namespace where the socket belongs to. SOCK.PROTONAME <``string``>:: Protocol name. +SOCK.SHUTDOWN <``string``>:: +Shutdown state of socket. ++ +[-r?]::: +If the first character is _r_, the receptions are allowed. +If it is _-_, the receptions are disallowed. +If it is _?_, the state is unknown. ++ +[-w?]::: +If the second character is _w_, the transmissions are allowed. +If it is _-_, the transmissions are disallowed. +If it is _?_, the state is unknown. + SOCK.STATE <``string``>:: State of socket. @@ -366,47 +468,62 @@ 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. +Local L3 (_INET.LADDR_ or _INET6.LADDR_) address and local TCP port. -TCP.LPORT <``integer``>:: +TCP.LPORT <``number``>:: Local TCP port. TCP.RADDR <``string``>:: -Remote L3 (INET.RADDR or INET6.RADDR) address and remote TCP port. +Remote L3 (_INET.RADDR_ or _INET6.RADDR_) address and remote TCP port. -TCP.RPORT <``integer``>:: +TCP.RPORT <``number``>:: Remote TCP port. TID <``number``>:: Thread ID of the process opening the file. +TIMERFD.CLOCKID <``string``>:: +Clockid. + +TIMERFD.INTERVAL <``number``>:: +Interval. + +TIMERFD.REMAINING <``number``>:: +Remaining time. + +PTMX.TTY-INDEX <``number``>:: +TTY index of the counterpart. + +TUN.IFACE <``string``>:: +Network interface behind the tun device. + 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. +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``>:: +UDP.LPORT <``number``>:: Local UDP port. UDP.RADDR <``string``>:: Remote IP address and remote UDP port. -UDP.RPORT <``integer``>:: +UDP.RPORT <``number``>:: Remote UDP port. UDPLITE.LADDR <``string``>:: Local IP address and local UDPLite port. -UDPLITE.LPORT <``integer``>:: +UDPLITE.LPORT <``number``>:: Local UDP port. UDPLITE.RADDR <``string``>:: Remote IP address and remote UDPLite port. -UDPLITE.RPORT <``integer``>:: +UDPLITE.RPORT <``number``>:: Remote UDP port. UID <``number``>:: @@ -418,105 +535,36 @@ 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 :: _=~_ | _!~_ +XMODE <``string``>:: +Extended version of _MODE_. This column may grow; new letters may be +appended to _XMODE_ when *lsfd* supports a new state of file descriptors +and/or memory mappings. ++ +[-r]::: +opened of mapped for reading. This is also in _MODE_. ++ +[-w]::: +opened of mapped for writing. This is also in _MODE_. ++ +[-x]::: +mapped for executing the code. This is also in _MODE_. ++ +[-D]::: +deleted from the file system. See also _DELETED_. ++ +[-Ll]::: +locked or leased. _l_ represents a read, a shared lock or a read lease. +_L_ represents a write or an exclusive lock or a write lease. If both +read/shared and write/exclusive locks or leases are taken by a file +descriptor, _L_ is used as the flag. ++ +[-m]::: +Multiplexed. If the file descriptor is targeted by a eventpoll file +or classical system calls for multiplexing (select, pselect, poll, and +ppoll), this bit flag is set. Note that if an invocation of the +classical system calls is interrupted, *lsfd* may fail to mark _m_ +on the file descriptors monitored by the invocation. +See *restart_syscall*(2). == FILTER EXAMPLES @@ -605,9 +653,9 @@ List files opened in a QEMU virtual machine: :: # lsfd -Q '(COMMAND =~ ".\*qemu.*") and (FD >= 0)' .... -Hide files associated to kernel threads: :: +List timerfd files expired within 0.5 seconds: :: .... -# lsfd -Q '!KTHREAD' +# lsfd -Q '(TIMERFD.remaining < 0.5) and (TIMERFD.remaining > 0.0)' .... == COUNTER EXAMPLES @@ -651,11 +699,15 @@ mailto:yamato@redhat.com[Masatake YAMATO], mailto:kzak@redhat.com[Karel Zak] == SEE ALSO - +*bpftool*(8) +*bps*(8) +*lslocks*(8) *lsof*(8) *pidof*(1) *proc*(5) +*scols-filter*(5) *socket*(2) +*ss*(8) *stat*(2) include::man-common/bugreports.adoc[] |