.TH LSOF 8 PUCC
.if !\n()P .nr )P 1v
.SH NAME
lsof \- list open files
.SH SYNOPSIS
.B lsof
[
.B \-dhlnNostU
] [
.BI \-c " c"
] [
.BI \-k " k"
] [
.BI \-p " l"
] [
.BI \-u " l"
]
.I names
.SH DESCRIPTION
.I Lsof
lists information about files opened by processes for the following
operating systems:
.PP
.nf
	AIX 3.1.3, 3.1.5, 3.1.7 and 3.2 for the IBM RISC/System 6000
	Dynix 3.0.12 and 3.1.2 for the Sequent Symmetry S81
	HP\-UX 7.x for the Hewlett Packard 9000/300 and 9000/800
	HP\-UX 8.x for the Hewlett Packard 9000/300, 9000/700 and 9000/800
	NeXTStep 2.0 and 2.1 for the NeXT Work Station
	SunOS 4.1.1
.fi
.PP
An open file may be a regular file, a directory, a character special
file, or a network file (Internet socket, NFS file or Unix domain socket.)
A specific file may be selected by its path
.IR name .
.SH OPTIONS
In the absence of any options,
.I lsof
lists all open files belonging to all active processes.
.PP
If any list request option is specified, all other lists must be
specifically requested \- e.g., if
.B \-n
is specified for the listing of Internet network files, NFS files won't be
listed unless
.B \-N
is also specified;
or if a user list is specified with the
.B \-u
option, Internet network files and Unix domain socket files belonging to
users not in the list won't be listed unless the
.B \-n
and
.B \-U
options are also specified.
.TP \w'names'u+4
.BI \-c " c"
This option specifies a memory (core) file,
.IR c ,
in place of /dev/kmem or /dev/mem.
.TP
.B \-d
This option selects the production of error messages about unreadable
subdirectories of the
.I /dev
directory.
Under SunOS, for example, the
.I /dev/lpd
subdirectory is unreadable for security reasons.
When building its cache of names and device numbers for devices,
.I lsof
skips unreadable subdirectories silently unless
.B \-d
is specified.
.TP
.B \-h
This option selects a brief usage (help) output list.
.TP
.BI \-k " k"
This option specifies a kernel name list file,
.IR k ,
in place of /vmunix, /mach, /dynix, etc.
This option is not available under AIX on the IBM RISC/System 6000.
.TP
.B \-l
This option inhibits the conversion of user ID numbers to login names.
.TP
.B \-n
This option selects the listing of Internet network files.
.TP
.B \-N
This option selects the listing of NFS files.
.TP
.B \-o
This option selects the displaying of the file offset in all cases
in place of file size; it causes the SIZE/OFF output column title
to be changed to OFFSET.
File offsets are normally displayed when they are more meaningful than
file size.
.TP
.BI \-p " l"
This option selects the listing of files for the processes whose ID numbers
are in the comma\-separated list `l' \- e.g., ``123'' or ``123,456''.
(There should be no spaces in the list.)
.TP
.B \-s
This option removes the SIZE/OFF or OFFSET column from the output,
shortening output lines by eleven characters.
.TP
.B \-t 
This option specifies that
.I lsof
should produce terse output with process identifiers only and no header \-
e.g., so that the output may be piped to
.IR kill (1).
.TP
.BI \-u " l"
This option selects the listing of files for the user whose login names
or user ID numbers are in the comma\-separated list `l' \- e.g., ``abe'',
or ``548,root''.
(There should be no spaces in the list.)
.TP
.B \-U
This option selects the listing of Unix domain socket files.
.TP
.I names
These are path names of specific files to list.
Symbolic links are resolved before use.
.IP
If a
.I name 
is the mount point of a file system or the device of the mount point of a
file system,
.I lsof
will list all the files open on the file system.
If a
.I name
is the base name of a family of multiplexed files \- e. g, AIX's
.IR /dev/pts " \-"
.I lsof
will list all the associated multipled files on the device that
are open \- e.g.,
.IR /dev/pts/1 ,
.IR /dev/pts/2 ,
etc.
.IP
If a
.I name
is none of the above,
.I lsof
will list any open files whose device and inode match that of the
specified path
.IR name .
.SH OUTPUT
.I Lsof
lists for each open file:
.TP \w'COMMAND'u+4
COMMAND
contains the first nine characters of the name of the Unix command associated
with the process.
.TP
PID
is the Process IDentification number of the process.
.TP
USER
is the user ID number or login name of the user to whom the process
belongs.
(See the
.B \-l
option.)
.TP
FD
is the File Descriptor number of the file or ``cwd'' if it is the
current working directory of the process.
FD is followed by one of these characters, describing the mode under which
the file is open:
.IP
	\fBr\fP for read access;
.br
	\fBw\fP for write access;
.br
	\fBu\fP for read and write access;
.br
	space if unknown (e.g., ``cwd'').
.IP
The mode character is followed by one of these characters, describing
the type of lock applied to the file:
.IP
	\fBr\fP for read lock on part of the file;
.br
	\fBR\fP for a read lock on the entire file;
.br
	\fBw\fP for a write lock on part of the file;
.br
	\fBW\fP for a write lock on the entire file;
.br
	space if there is no lock.
.TP
TYPE
is the type of the vnode associated with the file (see <sys/vnode.h>);
.IP
or ``inet'' for an Internet domain socket;
.IP
or ``unix'' for a Unix domain socket.
.TP
DEVICE
contains the major and minor device numbers for a character special, block
special, regular, directory or NFS file (an HP\-UX minor device number is
listed in hexadecimal);
.IP
or the protocol control block address of a Unix or Internet domain file
(the number that appears in
.IR netstat (1)'s
.B \-A
output).
.TP
SIZE/OFF or OFFSET
is the size of the file or the file offset in bytes.
.I Lsof
displays whatever value \- size or offset \- is appropriate for the type
of the file.
The file size is displayed in decimal;
the offset is displayed in hexadecimal (with a leading ``0x'').
If the the
.B \-o
option is specified,
.I lsof
always displays the file offset and labels the column OFFSET.
This column may be inhibited by specifying the
.B \-s
option.
.TP
INODE
is the inode number of a local file;
.IP
or the inode number of an NFS file in the server host;
.IP
or the Internet protocol type \- e. g, ``TCP''.
.TP
NAME
is the name of the mount point and file system on which the file resides;
.IP
or the name of a file specified in the
.I names
option (after any symbolic links have been resolved);
.IP
or the name of a character special or block special device;
.IP
or the local and remote Internet addresses of a network file;
.IP
or the address of a Unix domain socket;
.IP
or the local and remote mount point names of an NFS file.
.SH DIAGNOSTICS
Errors are identified with messages on the standard error file.
.PP
.I Lsof
returns a one (1) if any error was detected, including the failure to
locate any
.IR names .
It returns a zero (0) if no errors were detected and if it was able to
list information about all the specified
.IR names .
.SH EXAMPLES
To list all open files, use:
.IP
lsof
.PP
To list all open Internet and Unix domain files, use:
.IP
lsof -n -U
.PP
To list all open files for login name ``abe'', user ID 1234, process 123,
process 456 and process 789, use:
.IP
lsof -p 789,456,123 -u 1234,abe
.PP
To list all open files on device /dev/hd4, use:
.IP
lsof /dev/hd4
.PP
To find the process that has /u/abe/foo open, use:
.IP
lsof /u/abe/foo
.PP
To send a SIGHUP to the processes that have /u/abe/bar open, use:
.IP
kill -HUP `lsof -t /u/abe/bar`
.SH BUGS
Since
.I lsof
reads kernel memory in its search for open files, rapid changes in kernel
memory may produce unpredictable results.
.PP
Absence of hardware or software configurations for some operating systems
\- e.g., HP\-UX 7.x and 8.x and Sequent Dynix 3.1.2 \- means that
.I lsof
has not been fully tested on them.
In particular, the use of alternate kernel (with the
.B \-k
option) and alternate memory (with the
.B \-c
option) files has only been tested under SunOS and the Purdue version
of Sequent Dynix.
Use of an alternate memory file may require a mapping of kernel virtual
to physical addresses that
.I lsof
does not provide.
.PP
The lock status character (following the file descriptor) is derived under
AIX from a test of only the first filock structure of the gnode
(see <sys/flock.h> and <sys/gnode.h>).
.PP
.I Lsof
can't search for any file by
.I name
unless it is installed with root set-UID permission.
Otherwise it is restricted to searching for files to which its user
or its set-GID group (if any) have access.
.PP
.I Lsof
startup time is long on systems where scanning the
.I /dev
directory is a slow operation.
.PP
Output lines are sometimes greater than eighty characters \- e.g.,
for completed Internet connections or NFS files \- causing the output
listing to be irregularly spaced.
The
.B \-s
option may be specified to remove the SIZE/OFF of OFFSET column,
shortening output lines by eleven characters.
.PP
If there are files or subdirectories in
.I /dev
that
.I lsof
can't
.IR stat (2)
or read, it will ignore them without complaint, unless the
.B \-d
option is selected.
Whether
.I lsof
complains or not, it is unable to report major and minor device numbers
for the entries it can't access.
.PP .I Lsof
ignores SunOS loop\-back mounts.
It cannot distinguish between loop\-back file systems and real ones,
using inode and device numbers.
.SH FILES
.TP \w'/dev/swap'u+16
/dev/drum	system paging device
.TP
/dev/kmem	kernel virtual memory device
.TP
/dev/mem	physical memory device
.TP
/dev/swap	system paging device
.SH AUTHORS
.I Lsof
was written by Victor A. Abell of the Purdue University Computing Center
(PUCC), based on the
.I fstat
and
.I ofiles
programs.
He acknowledges his debt to the work of Dan Bernstein, Michael ``Ford''
Ditto, Tom Dunigan, Alexander Dupuy, Vik Lall, Ray Moody, C. Spencer,
Michael Spitzer and those who wrote Berkeley's
.I fstat
program, all contributors to
.I lsof's
predecessors.
He thanks Doug McKenzie for his HP\-UX
.I proctor
program and Rich Kulawiec for pointing it out.
Finally, he is grateful to
Mark Bonsack,
Jim Cooper,
J. Nelson Howell,
Markus Lautenbacher,
Steve Lacey,
Stuart Levy,
Wendy Lin,
Andreas Luik,
Fletcher Mattox,
Dale McCluskey,
Michael Mackenzie,
Dave Stevens,
Jeff Stewart
and Patrick Wolfe
for their help in developing and improving
.IR lsof .
.SH SEE ALSO
ff(1),
fstat(8),
fuser(1),
kill(1),
netstat(1),
ofiles(8L),
ps(1).