summaryrefslogtreecommitdiffstats
path: root/misc-utils/lsfd.1.adoc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 19:33:34 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 19:33:34 +0000
commit1272be04be0cb803eec87f602edb2e3e6f111aea (patch)
treebce17f6478cdd9f3c4ec3d751135dc42786d6a56 /misc-utils/lsfd.1.adoc
parentReleasing progress-linux version 2.39.3-11~progress7.99u1. (diff)
downloadutil-linux-1272be04be0cb803eec87f602edb2e3e6f111aea.tar.xz
util-linux-1272be04be0cb803eec87f602edb2e3e6f111aea.zip
Merging upstream version 2.40.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'misc-utils/lsfd.1.adoc')
-rw-r--r--misc-utils/lsfd.1.adoc298
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[]