lsfd man page

//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

== 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.

*lsfd* uses Libsmartcols for output formatting and filtering. See the description of *--output*
option for customizing the output format, and *--filter* option for filtering.

== 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 column.
+
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.

*--sysroot* _dir_::
Use specified directory as system root.

*--notruncate*::
Don't truncate text in columns.

*-Q*, *--filter* _expr_::
Print the files only satisfying with the condition represented by the _expr_.

*-h*, *--help*::
Display help text and exit.

*-V*, *--version*::
Display version information and exit.

== OUTPUT COLUMNS

Each column has a type. A type for a column is surround by < and >.

ASSOC <__string__>::
Association between file and process.

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_).

FD <__number__>::
File descriptor for the file.

FLAGS <__string__>::
Flags specified when opening the file.

INODE <__number__>::
Inode number.

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__>::
Name of the file.

NLINK <__number__>::
Link count.

PARTITION <__string__>::
Block device name resolved by _/proc/partition_.

PID <__number__>::
PID of the process opening the file.

POS <__number__>::
File position.

PROTONAME <__string__>::
Protocol name.

RDEV <__string__>::
Device ID (if special file).

SIZE <__number__>::
File size.

SOURCE <__string__>::
File system, partition, or device containing the file.

TID <__number__>::
Thread ID of the process opening the file.

TYPE <__string__>::
File type.

UID <__number__>::
User ID number.

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.

*lsfd* substitutes column names in the given expression with actual
column values in the line before evaluation. Only a name of a column
having _boolean_ typed value can be used stand-alone. Use a name of
a column having the other data type, _string_ or _number_, as an operand
of an operator. See the "OUTPUT COLUMNS" about the types of columns.

Literal is for representing a value directly. see BOOLLIT, STRLIT, and
NUMLIT. Different data type has different literal syntax.

An operator works with one or two operads(s). An operator has an
expectation about the data type(s) of its operads. Giving an
unexpected data type to an operator causes a syntax error.

Operators taking two operads are _and_, _or_, _eq_, _ne_, _le_, _lt_, _ge_, and _gt_.
Thay have C-language flavored aliases: _&&_, _||_, _==_, _!=_, _<_, _<=_, _>=_, and _>_.
_!_ is the only operator taking one operad.

_eq_, _ne_, and their aliases expect operands have the same data type.

_and_, _or_, _not_ and their aliases expect operands have _bool_ data type.

_lt_, _le_, _gt_, _ge_, and their aliases expect operands have _numhber_ data types.

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.

EXPR :: BOOLEXP

BOOLEXP0 :: COLUMN <__boolean__> | BOOLLIT | _(_ BOOLEXP _)_

BOOLEXP :: BOOLEXP0 | BOOLOP1 | BOOLOP2 | BOOLOP2BL | BOOLOP2CMP

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_

== EXAMPLES

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)'

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 non-regular files::

  # lsfd -Q 'DELETED and (TYPE != "REG")'

== 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)
*proc*(5)

include::man-common/bugreports.adoc[]

include::man-common/footer.adoc[]

ifdef::translation[]
include::man-common/translation.adoc[]
endif::[]