Adding upstream version 2.40.upstream/2.40

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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[]