When the -F option is specified, lsof produces output that is
suitable for processing by another program - e.g, an awk or Perl
script, or a C program.
Each unit of information is output in a field that is identified
with a leading character and terminated by a NL (012) (or a NUL
(000) if the 0 (zero) field identifier character is specified.)
The data of the field follows immediately after the field
identification character and extends to the field terminator.
It is possible to think of field output as process and file sets.
A process set begins with a field whose identifier is `p' (for
process IDentifier (PID)). It extends to the beginning of the
next PID field or the beginning of the first file set of the
process, whichever comes first. Included in the process set are
fields that identify the command, the process group
IDentification (PGID) number, the task (thread) ID (TID), and the
user ID (UID) number or login name.
A file set begins with a field whose identifier is `f' (for file
descriptor). It is followed by lines that describe the file's
access mode, lock state, type, device, size, offset, inode,
protocol, name and stream module names. It extends to the
beginning of the next file or process set, whichever comes first.
When the NUL (000) field terminator has been selected with the 0
(zero) field identifier character, lsof ends each process and
file set with a NL (012) character.
Lsof always produces one field, the PID (`p') field. All other
fields may be declared optionally in the field identifier
character list that follows the -F option. When a field
selection character identifies an item lsof does not normally
list - e.g., PPID, selected with -R - specification of the field
character - e.g., ``-FR'' - also selects the listing of the item.
It is entirely possible to select a set of fields that cannot
easily be parsed - e.g., if the field descriptor field is not
selected, it may be difficult to identify file sets. To help you
avoid this difficulty, lsof supports the -F option; it selects
the output of all fields with NL terminators (the -F0 option pair
selects the output of all fields with NUL terminators). For
compatibility reasons neither -F nor -F0 select the raw device
field.
These are the fields that lsof will produce. The single
character listed first is the field identifier.
a file access mode
c process command name (all characters from proc or
user structure)
C file structure share count
d file's device character code
D file's major/minor device number (0x<hexadecimal>)
f file descriptor (always selected)
F file structure address (0x<hexadecimal>)
G file flaGs (0x<hexadecimal>; names if +fg follows)
g process group ID
i file's inode number
K tasK ID
k link count
l file's lock status
L process login name
m marker between repeated output
M the task comMand name
n file name, comment, Internet address
N node identifier (ox<hexadecimal>
o file's offset (decimal)
p process ID (always selected)
P protocol name
r raw device number (0x<hexadecimal>)
R parent process ID
s file's size (decimal)
S file's stream identification
t file's type
T TCP/TPI information, identified by prefixes (the
`=' is part of the prefix):
QR=<read queue size>
QS=<send queue size>
SO=<socket options and values> (not all dialects)
SS=<socket states> (not all dialects)
ST=<connection state>
TF=<TCP flags and values> (not all dialects)
WR=<window read size> (not all dialects)
WW=<window write size> (not all dialects)
(TCP/TPI information isn't reported for all supported
UNIX dialects. The -h or -? help output for the
-T option will show what TCP/TPI reporting can be
requested.)
u process user ID
z Solaris 10 and higher zone name
Z SELinux security context (inhibited when SELinux is disabled)
0 use NUL field terminator character in place of NL
1-9 dialect-specific field identifiers (The output
of -F? identifies the information to be found
in dialect-specific fields.)
You can get on-line help information on these characters and
their descriptions by specifying the -F? option pair. (Escape
the `?' character as your shell requires.) Additional
information on field content can be found in the OUTPUT section.
As an example, ``-F pcfn'' will select the process ID (`p'),
command name (`c'), file descriptor (`f') and file name (`n')
fields with an NL field terminator character; ``-F pcfn0''
selects the same output with a NUL (000) field terminator
character.
Lsof doesn't produce all fields for every process or file set,
only those that are available. Some fields are mutually
exclusive: file device characters and file major/minor device
numbers; file inode number and protocol name; file name and
stream identification; file size and offset. One or the other
member of these mutually exclusive sets will appear in field
output, but not both.
Normally lsof ends each field with a NL (012) character. The 0
(zero) field identifier character may be specified to change the
field terminator character to a NUL (000). A NUL terminator may
be easier to process with xargs(1), for example, or with programs
whose quoting mechanisms may not easily cope with the range of
characters in the field output. When the NUL field terminator is
in use, lsof ends each process and file set with a NL (012).
Three aids to producing programs that can process lsof field
output are included in the lsof distribution. The first is a C
header file, lsof_fields.h, that contains symbols for the field
identification characters, indexes for storing them in a table,
and explanation strings that may be compiled into programs. Lsof
uses this header file.
The second aid is a set of sample scripts that process field
output, written in awk, Perl 4, and Perl 5. They're located in
the scripts subdirectory of the lsof distribution.
The third aid is the C library used for the lsof test suite. The
test suite is written in C and uses field output to validate the
correct operation of lsof. The library can be found in the
tests/LTlib.c file of the lsof distribution. The library uses
the first aid, the lsof_fields.h header file.
