From 9bb81f8a90ecc8b70c955bff72ec59dd3d9e5ae7 Mon Sep 17 00:00:00 2001 From: Patrick McCarty Date: Fri, 8 Feb 2013 13:26:27 -0800 Subject: Imported Upstream version 4.87 --- lsof.8 | 4431 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4431 insertions(+) create mode 100644 lsof.8 (limited to 'lsof.8') diff --git a/lsof.8 b/lsof.8 new file mode 100644 index 0000000..a0b7212 --- /dev/null +++ b/lsof.8 @@ -0,0 +1,4431 @@ +.ds VN 4.87 +.TH LSOF 8 Revision-\*(VN +.if !\n()P .nr )P 1v +.SH NAME +lsof \- list open files +.SH SYNOPSIS +.B lsof +[ +.B \-?abChKlnNOPRtUvVX +] [ +.BI -A " A" +] [ +.BI \-c " c" +] [ +.BI +c " c" +] [ +.BI +|\-d " d" +] [ +.BI +|\-D " D" +] [ +.BI +|\-e " s" +] [ +.B +|\-f [cfgGn] +] [ +.BI \-F " [f]" +] [ +.BI \-g " [s]" +] [ +.BI \-i " [i]" +] [ +.BI \-k " k" +] [ +.BI +|\-L " [l]" +] [ +.BI +|\-m " m" +] [ +.B +|\-M +] [ +.BI \-o " [o]" +] [ +.BI \-p " s" +] [ +.BI +|\-r " [t[m]]" +] [ +.BI \-s " [p:s]" +] [ +.BI \-S " [t]" +] [ +.BI \-T " [t]" +] [ +.BI \-u " s" +] [ +.B +|\-w +] [ +.BI \-x " [fl]" +] [ +.BI \-z " [z]" +] [ +.BI \-Z " [Z]" +] [ +.B -- +] [\fInames\fP] +.SH DESCRIPTION +.I Lsof +revision \*(VN lists on its standard output file information about files +opened by processes for the following UNIX dialects: +.PP +.nf + Apple Darwin 9 and Mac OS X 10.[567] + FreeBSD 4.9 and 6.4 for x86-based systems + FreeBSD 8.2, 9.0 and 10.0 for AMD64-based systems + Linux 2.1.72 and above for x86-based systems + Solaris 9, 10 and 11 +.fi +.PP +(See the +.B DISTRIBUTION +section of this manual page for information on how to obtain the +latest +.I lsof +revision.) +.PP +An open file may be a regular file, a directory, a block special file, +a character special file, an executing text reference, a library, +a stream or a network file (Internet socket, NFS file or UNIX domain socket.) +A specific file or all the files in a file system may be selected by path. +.PP +Instead of a formatted display, +.I lsof +will produce output that can be parsed by other programs. +See the +.BR \-F , +option description, and the +.B "OUTPUT FOR OTHER PROGRAMS" +section for more information. +.PP +In addition to producing a single output list, +.I lsof +will run in repeat mode. +In repeat mode it will produce output, delay, then repeat the output +operation until stopped with an interrupt or quit signal. +See the +.BI +|\-r " [t[m]]" +option description for more information. +.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, other list requests must be +specifically requested \- e.g., if +.B \-U +is specified for the listing of UNIX socket 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, UNIX domain socket files, belonging to users not in the list, +won't be listed unless the +.B \-U +option is also specified. +.PP +Normally list options that are specifically stated are ORed \- i.e., +specifying the +.B \-i +option without an address and the \fB\-u\fPfoo option produces a +listing of all network files OR files belonging to processes owned +by user ``foo''. +The exceptions are: +.TP \w'1)\ 'u +1) +the `^' (negated) login name or user ID (UID), specified with the +.B \-u +option; +.TP \w'1)\ 'u +2) +the `^' (negated) process ID (PID), specified with the +.B \-p +option; +.TP \w'1)\ 'u +3) +the `^' (negated) process group ID (PGID), specified with the +.B \-g +option; +.TP \w'1)\ 'u +4) +the `^' (negated) command, specified with the +.B \-c +option; +.TP \w'1)\ 'u +5) +the (`^') negated TCP or UDP protocol state names, specified with the +.BI \-s " [p:s]" +option. +.PP +Since they represent exclusions, they are applied without ORing or ANDing +and take effect before any other selection criteria are applied. +.PP +The +.B \-a +option may be used to AND the selections. +For example, specifying +.BR \-a , +.BR \-U , +and \fB\-u\fPfoo produces a listing of only UNIX socket files that +belong to processes owned by user ``foo''. +.PP +Caution: the +.B \-a +option causes all list selection options to be ANDed; it can't +be used to cause ANDing of selected pairs of selection options +by placing it between them, even though its placement there is +acceptable. +Wherever +.B \-a +is placed, it causes the ANDing of all selection options. +.PP +Items of the same selection set \- command names, file descriptors, +network addresses, process identifiers, user identifiers, zone names, +security contexts \- are joined in a single ORed set and applied +before the result participates in ANDing. +Thus, for example, specifying \fB\-i\fP@aaa.bbb, \fB\-i\fP@ccc.ddd, +.BR \-a , +and \fB\-u\fPfff,ggg will select the listing of files that belong to +either login ``fff'' OR ``ggg'' AND have network connections to either +host aaa.bbb OR ccc.ddd. +.PP +Options may be grouped together following a single prefix -- e.g., +the option set ``\fB\-a \-b \-C\fP'' may be stated as +.BR \-abC . +However, since values are optional following +.BR +|\-f , +.BR \-F , +.BR \-g , +.BR \-i , +.BR +|\-L , +.BR \-o , +.BR +|\-r , +.BR \-s , +.BR \-S , +.BR \-T , +.B \-x +and +.BR \-z . +when you have no values for them be careful that the +following character isn't ambiguous. +For example, +.B \-Fn +might represent the +.B \-F +and +.B \-n +options, or it might represent the +.B n +field identifier character following the +.B \-F +option. +When ambiguity is possible, start a new option with a `-' +character \- e.g., ``\fB\-F \-n\fP''. +If the next option is a file name, follow the possibly ambiguous +option with ``--'' \- e.g., ``\fB\-F -- \fIname\fR''. +.PP +Either the `+' or the `\-' prefix may be applied to a group of options. +Options that don't take on separate meanings for each +prefix \- e.g., \fB\-i\fP \- may be grouped under either prefix. +Thus, for example, ``+M -i'' may be stated as ``+Mi'' and the group +means the same as the separate options. +Be careful of prefix grouping when one or more options in the group +does take on separate meanings under different prefixes \- +e.g., \fB+|\-M\fP; ``-iM'' is not the same request as ``\-i +M''. +When in doubt, use separate options with appropriate prefixes. +.TP \w'names'u+4 +.B \-? \-h +These two equivalent options select a usage (help) output list. +.I Lsof +displays a shortened form of this output when it detects an error +in the options supplied to it, after it has displayed messages +explaining each error. +(Escape the `?' character as your shell requires.) +.TP \w'names'u+4 +.B \-a +causes list selection options to be ANDed, as described above. +.TP \w'names'u+4 +.BI \-A " A" +is available on systems configured for AFS whose AFS +kernel code is implemented via dynamic modules. +It allows the +.I lsof +user to specify +.I A +as an alternate name list file where the kernel addresses of the dynamic +modules might be found. +See the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information about dynamic modules, their +symbols, and how they affect +.IR lsof . +.TP \w'names'u+4 +.B \-b +causes +.I lsof +to avoid kernel functions that might block \- +.IR lstat (2), +.IR readlink (2), +and +.IR stat (2). +.IP +See the +.B "BLOCKS AND TIMEOUTS" +and +.B "AVOIDING KERNEL BLOCKS" +sections for information on using this option. +.TP \w'names'u+4 +.BI \-c " c" +selects the listing of files for processes executing the +command that begins with the characters of +.IR c . +Multiple commands may be specified, using multiple +.B \-c +options. +They are joined in a single ORed set before participating in +AND option selection. +.IP +If +.I c +begins with a `^', then the following characters specify a command +name whose processes are to be ignored (excluded.) +.IP +If +.I c +begins and ends with a slash ('/'), the characters between the slashes +are interpreted as a regular expression. +Shell meta\-characters in the regular expression must be quoted to prevent +their interpretation by the shell. +The closing slash may be followed by these modifiers: +.IP +.nf + b the regular expression is a basic one. +.br + i ignore the case of letters. +.br + x the regular expression is an extended one +.br + (default). +.fi +.IP +See the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information on basic and extended regular +expressions. +.IP +The simple command specification is tested first. +If that test fails, the command regular expression is applied. +If the simple command test succeeds, the command regular expression +test isn't made. +This may result in ``no command found for regex:'' messages +when lsof's +.B \-V +option is specified. +.TP \w'names'u+4 +.BI +c " w" +defines the maximum number of initial characters of the name, +supplied by the UNIX dialect, of the UNIX command associated with a process +to be printed in the COMMAND column. +(The +.I lsof +default is nine.) +.IP +Note that many UNIX dialects do not supply all command name characters +to +.I lsof +in the files and structures from which +.I lsof +obtains command name. +Often dialects limit the number of characters supplied in those sources. +For example, Linux 2.4.27 and Solaris 9 both limit command name length to +16 characters. +.IP +If +.I w +is zero ('0'), all command characters supplied to +.I lsof +by the UNIX dialect will be printed. +.IP +If +.I w +is less than the length of the column title, ``COMMAND'', it will +be raised to that length. +.TP \w'names'u+4 +.B \-C +disables the reporting of any path name +components from the kernel's name cache. +See the +.B "KERNEL NAME CACHE" +section for more information. +.TP \w'names'u+4 +.BI +d " s" +causes +.I lsof +to search for all open instances of directory +.I s +and the files and directories it contains at its top level. +.B +d +does NOT descend the directory tree, rooted at +.IR s . +The +.BI +D " D" +option may be used to request a full\-descent directory tree search, +rooted at directory +.IR D . +.IP +Processing of the +.B +d +option does not follow symbolic links within +.I s +unless the +.B \-x +or +.B \-x " l" +option is also specified. +Nor does it +search for open files on file system mount points on subdirectories of +.I s +unless the +.B \-x +or +.B \-x " f" +option is also specified. +.IP +Note: the authority of the user of this option limits it to searching for +files that the user has permission to examine with the system +.IR stat (2) +function. +.TP \w'names'u+4 +.BI \-d " s" +specifies a list of file descriptors (FDs) to exclude from +or include in the output listing. +The file descriptors are specified in the comma\-separated set +.I s +\&\- e.g., ``cwd,1,3'', ``^6,^2''. +(There should be no spaces in the set.) +.IP +The list is an exclusion list if all entries of the set begin with `^'. +It is an inclusion list if no entry begins with `^'. +Mixed lists are not permitted. +.IP +A file descriptor number range may be in the set as long as +neither member is empty, both members are numbers, and the ending +member is larger than the starting one \- e.g., ``0-7'' or ``3-10''. +Ranges may be specified for exclusion if they have the `^' prefix \- +e.g., ``^0-7'' excludes all file descriptors 0 through 7. +.IP +Multiple file descriptor numbers are joined in a single ORed set before +participating in AND option selection. +.IP +When there are exclusion and inclusion members in the set, +.I lsof +reports them as errors and exits with a non\-zero return code. +.IP +See the description of File Descriptor (FD) output values in the +.B OUTPUT +section for more information on file descriptor names. +.TP \w'names'u+4 +.BI +D " D" +causes +.I lsof +to search for all open instances of directory +.I D +and all the files and directories it contains to its complete depth. +.IP +Processing of the +.B +D +option does not follow symbolic links within +.I D +unless the +.B \-x +or +.B \-x " l" +option is also specified. +Nor does it +search for open files on file system mount points on subdirectories of +.I D +unless the +.B \-x +or +.B \-x " f" +option is also specified. +.IP +Note: the authority of the user of this option limits it to searching for +files that the user has permission to examine with the system +.IR stat (2) +function. +.IP +Further note: +.I lsof +may process this option slowly and require a large amount of dynamic memory +to do it. +This is because it must descend the entire directory tree, rooted at +.IR D , +calling +.IR stat (2) +for each file and directory, building a list of all the files it finds, and +searching that list for a match with every open file. +When directory +.I D +is large, these steps can take a long time, so use this option prudently. +.TP \w'names'u+4 +.BI \-D " D" +directs +.I lsof's +use of the device cache file. +The use of this option is sometimes restricted. +See the +.B "DEVICE CACHE FILE" +section and the sections that follow it for more information on this +option. +.IP +.B -D +must be followed by a function letter; the function letter may optionally +be followed by a path name. +.I Lsof +recognizes these function letters: +.IP +.nf + \fB?\fP \- report device cache file paths + \fBb\fP \- build the device cache file + \fBi\fP \- ignore the device cache file + \fBr\fP \- read the device cache file + \fBu\fP \- read and update the device cache file +.fi +.IP +The +.BR b , +.BR r , +and +.B u +functions, accompanied by a path name, are sometimes restricted. +When these functions are restricted, they will not appear in +the description of the +.B \-D +option that accompanies +.B \-h +or +.B \-? +option output. +See the +.B "DEVICE CACHE FILE" +section and the sections that follow it for more information on these +functions and when they're restricted. +.IP +The +.B ? +function reports the read\-only and write paths that lsof can +use for the device cache file, +the names of any environment variables whose values +.I lsof +will examine when forming the device cache file path, +and the format for the personal device cache file path. +(Escape the `?' character as your shell requires.) +.IP +When available, the +.BR b , +.BR r , +and +.B u +functions may be followed by the device cache file's path. +The standard default is +.I .lsof_hostname +in the home directory of the real user ID that executes +.IR lsof , +but this could have been changed when +.I lsof +was configured and compiled. +(The output of the +.B \-h +and +.B \-? +options show the current default prefix \- e.g., ``.lsof''.) +The suffix, +.IR hostname , +is the first component of the host's name returned by +.IR gethostname (2) . +.IP +When available, the +.B b +function directs +.I lsof +to build a new device cache file at the default or specified path. +.IP +The +.B i +function directs +.I lsof +to ignore the default device cache file and obtain its information +about devices via direct calls to the kernel. +.IP +The +.B r +function directs +.I lsof +to read the device cache at the default or specified path, but +prevents it from creating a new device cache file when none +exists or the existing one is improperly structured. +The +.B r +function, when specified without a path name, prevents +.I lsof +from updating an incorrect or outdated device cache file, +or creating a new one in its place. +The +.B r +function is always available when it is specified without a +path name argument; it may be restricted by the permissions of the +.I lsof +process. +.IP +When available, the +.B u +function directs +.I lsof +to read the device cache file at the default or specified path, +if possible, and to rebuild it, if necessary. +This is the default device cache file function when no +.B \-D +option has been specified. +.TP \w'names'u+4 +.BI +|\-e " s" +exempts the file system whose path name is +.I s +from being subjected to kernel function calls that might block. +The +.B +e +option exempts +.IR stat (2), +.IR lstat (2) +and most +.IR readlink (2) +kernel function calls. +The +.B \-e +option exempts only +.IR stat(2) +and +.IR lstat (2) +kernel function calls. +Multiple file systems may be specified with separate +.B +|\-e +specifications and each may have +.IR readlink (2) +calls exempted or not. +.IP +This option is currently implemented only for Linux. +.IP +.B CAUTION: +this option can easily be mis\-applied to other than +the file system of interest, because it uses path name rather +than the more reliable device and inode numbers. +(Device and inode numbers are acquired via the potentially blocking +.IR stat (2) +kernel call and are thus not available, but see the +.BI +|\-m " m" +option as a possible alternative way to supply device numbers.) +\fBUse this option with great care and fully specify the path name of the +file system to be exempted.\fP +.IP +When open files on exempted file systems are reported, it may not be +possible to obtain all their information. +Therefore, some information columns will be blank, the characters ``UNKN'' +preface the values in the TYPE column, and the applicable exemption option +is added in parentheses to the end of the NAME column. +(Some device number information might be made available via the +.BI +|\-m " m" +option.) +.TP \w'names'u+4 +.B +|\-f [cfgGn] +.B f +by itself clarifies how path name arguments are to be interpreted. +When followed by +.BR c , +.BR f , +.BR g , +.BR G , +or +.B n +in any combination it specifies +that the listing of kernel file structure information is to be enabled +(`+') or inhibited (`\-'). +.IP +Normally a path name argument is taken to be a file system name if +it matches a mounted\-on directory name reported by +.IR mount (8), +or if it represents a block device, named in the +.I mount +output and associated with a mounted directory name. +When +.B +f +is specified, all path name arguments will be taken to be file +system names, and +.I lsof +will complain if any are not. +This can be useful, for example, when the file system name +(mounted\-on device) isn't a block device. +This happens for some CD-ROM file systems. +.IP +When +.B \-f +is specified by itself, all path name arguments will be taken to be +simple files. +Thus, for example, the ``\fB\-f\fP\ -- /'' arguments direct lsof to search +for open files with a `/' path name, not all open files in the `/' +(root) file system. +.IP +Be careful to make sure +.B +f +and +.B \-f +are properly terminated and aren't followed by a character (e.g., of +the file or file system name) that might be taken as a parameter. +For example, use ``--'' after +.B +f +and +.B \-f +as in these examples. +.IP +.nf + $ lsof +f -- /file/system/name + $ lsof -f -- /file/name +.fi +.IP +The listing of information from kernel file structures, requested with the +.B +f [cfgGn] +option form, is normally +inhibited, and is not available in whole or part for some dialects \- e.g., +/proc\-based Linux kernels below 2.6.22. +When the prefix to +.B f +is a plus sign (`+'), these characters request file structure information: +.IP +.nf + \fBc\fR file structure use count (not Linux) + \fBf\fR file structure address (not Linux) + \fBg\fR file flag abbreviations (Linux 2.6.22 and up) + \fBG\fR file flags in hexadecimal (Linux 2.6.22 and up) + \fBn\fR file structure node address (not Linux) +.fi +.IP +When the prefix is minus (`\-') the same characters disable the +listing of the indicated values. +.IP +File structure addresses, use counts, flags, and node addresses may be +used to detect more readily identical files inherited by child +processes and identical files in use by different processes. +.I Lsof +column output can be sorted by output columns holding the values +and listed to identify identical file use, or +.I lsof +field output can be parsed by an AWK or Perl post\-filter script, +or by a C program. +.TP \w'names'u+4 +.BI \-F " f" +specifies a character list, +.IR f , +that selects the fields to be output for processing by another program, +and the character that terminates each output field. +Each field to be output is specified with a single character in +.IR f . +The field terminator defaults to NL, but may be changed to NUL (000). +See the +.B "OUTPUT FOR OTHER PROGRAMS" +section for a description of the field identification characters and +the field output process. +.IP +When the field selection character list is empty, all standard fields are +selected (except the raw device field, security context and zone field for +compatibility reasons) +and the NL field terminator is used. +.IP +When the field selection character list contains only a zero (`0'), +all fields are selected (except the raw device field for compatibility +reasons) and the NUL terminator character is used. +.IP +Other combinations of fields and their associated field terminator +character must be set with explicit entries in +.IR f , +as described in the +.B "OUTPUT FOR OTHER PROGRAMS" +section. +.IP +When a field selection character identifies an item +.I lsof +does not normally list \- e.g., PPID, selected with +.BR \-R " \-" +specification of the field character \- e.g., ``\fB\-FR\fP'' \- +also selects the listing of the item. +.IP +When the field selection character list contains the single +character `?', +.I lsof +will display a help list of the field identification characters. +(Escape the `?' character as your shell requires.) +.TP \w'names'u+4 +.BI \-g " [s]" +excludes or selects the listing of files for the processes +whose optional process group IDentification (PGID) numbers are in the +comma\-separated set +.I s +\&\- e.g., ``123'' or ``123,^456''. +(There should be no spaces in the set.) +.IP +PGID numbers that begin with `^' (negation) represent exclusions. +.IP +Multiple PGID numbers are joined in a single ORed set before participating +in AND option selection. +However, PGID exclusions are applied without ORing or ANDing +and take effect before other selection criteria are applied. +.IP +The +.B \-g +option also enables the output display of PGID numbers. +When specified without a PGID set that's all it does. +.TP \w'names'u+4 +.BI \-i " [i]" +selects the listing of files any of whose Internet address +matches the address specified in \fIi\fP. +If no address is specified, this option selects the listing of all +Internet and x.25 (HP\-UX) network files. +.IP +If +.BI \-i 4 +or +.BI \-i 6 +is specified with no following address, only files of the indicated +IP version, IPv4 or IPv6, are displayed. +(An IPv6 specification may be used only if the dialects supports IPv6, +as indicated by ``[46]'' and ``IPv[46]'' in +.I lsof's +.B \-h +or +.B \-? +output.) +Sequentially specifying +.BR \-i 4, +followed by +.BR \-i 6 +is the same as specifying +.BR \-i , +and vice-versa. +Specifying +.BR \-i 4, +or +.BR \-i 6 +after +.B \-i +is the same as specifying +.BR \-i 4 +or +.BR \-i 6 +by itself. +.IP +Multiple addresses (up to a limit of 100) may be specified with multiple +.B \-i +options. +(A port number or service name range is counted as one address.) +They are joined in a single ORed set before participating in +AND option selection. +.IP +An Internet address is specified in the form (Items in square +brackets are optional.): +.IP +[\fI46\fP][\fIprotocol\fP][@\fIhostname\fP\||\|\fIhostaddr\fP][:\fIservice\fP\||\|\fIport\fP] +.IP +where: +.nf +.br + \fI46\fP specifies the IP version, IPv4 or IPv6 +.br + that applies to the following address. +.br + '6' may be be specified only if the UNIX +.br + dialect supports IPv6. If neither '4' nor +.br + '6' is specified, the following address +.br + applies to all IP versions. +.br + \fIprotocol\fP is a protocol name \- \fBTCP\fP, \fBUDP\fP +.br or \fBUDPLITE\fP. +.br + \fIhostname\fP is an Internet host name. Unless a +.br + specific IP version is specified, open +.br + network files associated with host names +.br + of all versions will be selected. +.br + \fIhostaddr\fP is a numeric Internet IPv4 address in +.br + dot form; or an IPv6 numeric address in +.br + colon form, enclosed in brackets, if the +.br + UNIX dialect supports IPv6. When an IP +.br + version is selected, only its numeric +.br + addresses may be specified. +.br + \fIservice\fP is an \fI/etc/services\fP name \- e.g., \fBsmtp\fP \- + or a list of them. +.br + \fIport\fP is a port number, or a list of them. +.fi +.IP +IPv6 options may be used only if the UNIX dialect supports IPv6. +To see if the dialect supports IPv6, run +.I lsof +and specify the +.B \-h +or +.B \-? +(help) option. +If the displayed description of the +.B \-i +option contains ``[46]'' and ``IPv[46]'', IPv6 is supported. +.IP +IPv4 host names and addresses may not be specified if network file selection +is limited to IPv6 with +.BR \-i " 6." +IPv6 host names and addresses may not be specified if network file selection +is limited to IPv4 with +.BR \-i " 4." +When an open IPv4 network file's address is mapped in an IPv6 address, +the open file's type will be IPv6, not IPv4, and its display will be +selected by '6', not '4'. +.IP +At least one address component \- +.BR 4, +.BR 6, +.IR protocol , +.IR hostname , +.IR hostaddr , +or +.I service +\&\- must be supplied. +The `@' character, leading the host specification, is always required; +as is the `:', leading the port specification. +Specify either +.I hostname +or +.IR hostaddr . +Specify either +.I service +name list or +.I port +number list. +If a +.I service +name list is specified, the +.I protocol +may also need to be specified if the TCP, UDP and UDPLITE port numbers for +the service name are different. +Use any case \- lower or upper \- for +.IR protocol . +.IP +.I Service +names and +.I port +numbers may be combined in a list whose entries are separated by commas +and whose numeric range entries are separated by minus signs. +There may be no embedded spaces, and all service names must belong to +the specified +.IR protocol . +Since service names may contain embedded minus signs, the starting entry +of a range can't be a service name; it can be a port number, however. +.IP +Here are some sample addresses: +.nf + +.br + -i6 \- IPv6 only +.br + TCP:25 \- TCP and port 25 +.br + @1.2.3.4 \- Internet IPv4 host address 1.2.3.4 +.br + @[3ffe:1ebc::1]:1234 \- Internet IPv6 host address + 3ffe:1ebc::1, port 1234 +.br + UDP:who \- UDP who service port +.br + TCP@lsof.itap:513 \- TCP, port 513 and host name lsof.itap +.br + tcp@foo:1-10,smtp,99 \- TCP, ports 1 through 10, + service name \fIsmtp\fP, port 99, host name foo +.br + tcp@bar:1-smtp \- TCP, ports 1 through \fIsmtp\fP, host bar +.br + :time \- either TCP, UDP or UDPLITE time service port +.fi +.TP \w'names'u+4 +.B \-K +selects the listing of tasks (threads) of processes, on dialects +where task (thread) reporting is supported. +(If help output \- i.e., the output of the +.B \-h +or +.B \-? +options \- shows this option, then task (thread) reporting is +supported by the dialect.) +.IP +When +.B \-K +and +.B \-a +are both specified on Linux, and the tasks of a main process are +selected by other options, the main process will also be listed +as though it were a task, but without a task ID. +(See the description of the TID column in the +.B OUTPUT +section.) +.IP +Where the FreeBSD version supports threads, all threads will be +listed with their IDs. +.IP +In general threads and tasks inherit the files of the caller, but +may close some and open others, so +.I lsof +always reports all the open files of threads and tasks. +.TP \w'names'u+4 +.BI \-k " k" +specifies a kernel name list file, +.IR k , +in place of /vmunix, /mach, etc. +.B \-k +is not available under AIX on the IBM RISC/System 6000. +.TP \w'names'u+4 +.B \-l +inhibits the conversion of user ID numbers to login names. +It is also useful when login name lookup is working improperly or slowly. +.TP \w'names'u+4 +.BI +|\-L " [l]" +enables (`+') or disables (`-') the listing of file link +counts, where they are available \- e.g., they aren't available +for sockets, or most FIFOs and pipes. +.IP +When +.B +L +is specified without a following number, all link counts will be listed. +When +.B \-L +is specified (the default), no link counts will be listed. +.IP +When +.B +L +is followed by a number, only files having a link count less than +that number will be listed. +(No number may follow +.BR \-L .) +A specification of the form ``\fB+L1\fP'' will select open files that +have been unlinked. +A specification of the form ``\fB+aL1\ \fI\fR'' will select +unlinked open files on the specified file system. +.IP +For other link count comparisons, use field output (\fB\-F\fP) +and a post\-processing script or program. +.TP \w'names'u+4 +.BI +|\-m " m" +specifies an alternate kernel memory file or activates +mount table supplement processing. +.IP +The option form +.BI \-m " m" +specifies a kernel memory file, +.IR m , +in place of +.I /dev/kmem +or +.I /dev/mem +\&\- e.g., a crash dump file. +.IP +The option form +.B +m +requests that a mount supplement file be written to the standard output +file. +All other options are silently ignored. +.IP +There will be a line in the mount supplement file for each mounted file +system, containing the mounted file system directory, followed by a single +space, followed by the device number in hexadecimal "0x" format \- e.g., +.IP +.nf + / 0x801 +.fi +.IP +.I Lsof +can use the mount supplement file to get device numbers for file systems +when it can't get them via +.IR stat (2) +or +.IR lstat (2). +.IP +The option form +.BI +m " m" +identifies +.I m +as a mount supplement file. +.IP +Note: the +.B +m +and +.BI +m " m" +options are not available for all supported dialects. +Check the output of +.I lsof's +.B \-h +or +.B \-? +options to see if the +.B +m +and +.BI +m " m" +options are available. +.TP \w'names'u+4 +.B +|\-M +Enables (\fB+\fP) or disables (\fB-\fP) the +reporting of portmapper registrations for local TCP, UDP and UDPLITE ports, +where port mapping is supported. +(See the last paragraph of this option description for information about +where portmapper registration reporting is suported.) +.IP +The default reporting mode is set by the +.I lsof +builder with the HASPMAPENABLED #define in the dialect's machine.h +header file; +.I lsof +is distributed with the HASPMAPENABLED #define deactivated, so +portmapper reporting is disabled by default and must be requested +with +.BR \+M . +Specifying +.I lsof's +.B \-h +or +.B \-? +option will report the default mode. +Disabling portmapper registration when it is already disabled or +enabling it when already enabled is acceptable. +When portmapper registration reporting is enabled, +.I lsof +displays the portmapper registration (if any) for local TCP, UDP or +UDPLITE ports +in square brackets immediately following the port numbers or service +names \- e.g., ``:1234[name]'' or ``:name[100083]''. +The registration information may be a name or number, depending +on what the registering program supplied to the portmapper when +it registered the port. +.IP +When portmapper registration reporting is enabled, +.I lsof +may run a little more slowly or even become blocked when access to the +portmapper becomes congested or stopped. +Reverse the reporting mode to determine if portmapper registration +reporting is slowing or blocking +.IR lsof . +.IP +For purposes of portmapper registration reporting +.I lsof +considers a TCP, UDP or UDPLITE port local if: it is found in the local part +of its containing kernel structure; +or if it is located in the foreign part of its containing kernel +structure and the local and foreign Internet addresses are the same; +or if it is located in the foreign part of its containing kernel +structure and the foreign Internet address is INADDR_LOOPBACK (127.0.0.1). +This rule may make +.I lsof +ignore some foreign ports on machines with multiple interfaces +when the foreign Internet address is on a different interface +from the local one. +.IP +See the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for further discussion of portmapper registration +reporting issues. +.IP +Portmapper registration reporting is supported only on dialects that +have RPC header files. +(Some Linux distributions with GlibC 2.14 do not have them.) +When portmapper registration reporting is supported, the +.B \-h +or +.B \-? +help output will show the +.B +|\-M +option. +.TP \w'names'u+4 +.B \-n +inhibits the conversion of network numbers to +host names for network files. +Inhibiting conversion may make +.I lsof +run faster. +It is also useful when host name lookup is not working properly. +.TP \w'names'u+4 +.B \-N +selects the listing of NFS files. +.TP \w'names'u+4 +.BI \-o +directs +.I lsof +to display file offset at all times. +It causes the SIZE/OFF output column title to be changed to OFFSET. +Note: on some UNIX dialects +.I lsof +can't obtain accurate or consistent file offset information from its +kernel data sources, sometimes just for particular kinds of files +(e.g., socket files.) +Consult the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information. +.IP +The +.B \-o +and +.B \-s +options are mutually exclusive; they can't both be specified. +When neither is specified, +.I lsof +displays whatever value \- size or offset \- is appropriate and +available for the type of the file. +.TP \w'names'u+4 +.BI \-o " o" +defines the number of decimal digits (\fIo\fP) to be +printed after the ``0t'' for a file offset before the form is switched +to ``0x...''. +An +.I o +value of zero (unlimited) directs +.I lsof +to use the ``0t'' form for all offset output. +.IP +This option does NOT direct +.I lsof +to display offset at all times; specify +.B \-o +(without a trailing number) to do that. +.BI \-o " o" +only specifies the number of digits after ``0t'' in +either mixed size and offset or offset\-only output. +Thus, for example, to direct +.I lsof +to display offset at all times with a decimal digit count of 10, use: +.IP +.nf + -o -o 10 +or + -oo10 +.fi +.IP +The default number of digits allowed after ``0t'' is normally 8, +but may have been changed by the lsof builder. +Consult the description of the +.BI \-o " o" +option in the output of the +.B \-h +or +.B \-? +option to determine the default that is in effect. +.TP \w'names'u+4 +.B \-O +directs +.I lsof +to bypass the strategy it uses to avoid being blocked by some +kernel operations \- i.e., doing them in forked child processes. +See the +.B "BLOCKS AND TIMEOUTS" +and +.B "AVOIDING KERNEL BLOCKS" +sections for more information on kernel operations that may block +.IR lsof . +.IP +While use of this option will reduce +.I lsof +startup overhead, it may also cause +.I lsof +to hang when the kernel doesn't respond to a function. +Use this option cautiously. +.TP \w'names'u+4 +.BI \-p " s" +excludes or selects the listing of files for the processes +whose optional process IDentification (PID) numbers are in the +comma\-separated set +.I s +\&\- e.g., ``123'' or ``123,^456''. +(There should be no spaces in the set.) +.IP +PID numbers that begin with `^' (negation) represent exclusions. +.IP +Multiple process ID numbers are joined in a single ORed set before +participating in AND option selection. +However, PID exclusions are applied without ORing or ANDing +and take effect before other selection criteria are applied. +.TP \w'names'u+4 +.B \-P +inhibits the conversion of port numbers to port +names for network files. +Inhibiting the conversion may make +.I lsof +run a little faster. +It is also useful when port name lookup is not working properly. +.TP \w'names'u+4 +.BI +|\-r " [t[m]]" +puts +.I lsof +in repeat mode. +There +.I lsof +lists open files as selected by other options, delays +.I t +seconds (default fifteen), then repeats the listing, delaying +and listing repetitively until stopped by a condition defined by +the prefix to the option. +.IP +If the prefix is a `\-', repeat mode is endless. +.I Lsof +must be terminated with an interrupt or quit signal. +.IP +If the prefix is `+', repeat mode will end the first cycle no open files +are listed \- and of course when +.I lsof +is stopped with an interrupt or quit signal. +When repeat mode ends because no files are listed, the process exit code +will be zero if any open files were ever listed; one, if none were ever +listed. +.IP +.I Lsof +marks the end of each listing: +if field output is in progress (the +.BR \-F , +option has been specified), the default marker is `m'; otherwise the +default marker is ``========''. +The marker is followed by a NL character. +.IP +The optional "m" argument specifies a format for the marker line. +The characters following `m' are interpreted as a format +specification to the +.IR strftime (3) +function, when both it and the +.IR localtime (3) +function are available in the dialect's C library. +Consult the +.IR strftime (3) +documentation for what may appear in its format specification. +Note that when field output is requested with the +.B \-F +option, cannot contain the NL format, ``%n''. +Note also that when contains spaces or other characters that +affect the shell's interpretation of arguments, must be +quoted appropriately. +.IP +Repeat mode reduces +.I lsof +startup overhead, so it is more efficient to use this mode +than to call +.I lsof +repetitively from a shell script, for example. +.IP +To use repeat mode most efficiently, accompany +.B +|\-r +with specification of other +.I lsof +selection options, so the amount of kernel memory access +.I lsof +does will be kept to a minimum. +Options that filter at the process level \- e.g., +.BR \-c , +.BR \-g , +.BR \-p , +.B \-u +\&\- are the most efficient selectors. +.IP +Repeat mode is useful when coupled with field output (see the +.BR \-F , +option description) and a supervising +.I awk +or +.I Perl +script, or a C program. +.TP \w'names'u+4 +.B \-R +directs lsof to list the Parent Process IDentification +number in the PPID column. +.TP \w'names'u+4 +.BI \-s " [p:s]" +.B s +alone directs +.I lsof +to display file size at all times. +It causes the SIZE/OFF output column title to be changed to SIZE. +If the file does not have a size, nothing is displayed. +.IP +The optional +.BI \-s " p:s" +form is available only for selected dialects, and only when the +.B \-h +or +.B \-? +help output lists it. +.IP +When the optional form is available, the +.B s +may be followed by a protocol name (\fIp\fR), either TCP or UDP, +a colon (`:') and a comma\-separated protocol state name list, +the option causes open TCP and UDP files to be excluded if their +state name(s) are in the list (\fIs\fP) preceded by a `^'; or +included if their name(s) are not preceded by a `^'. +.IP +When an inclusion list is defined, only network files with state +names in the list will be present in the +.I lsof +output. +Thus, specifying one state name means that only network files +with that lone state name will be listed. +.IP +Case is unimportant in the protocol or state names, but there may +be no spaces and the colon (`:') separating the protocol +name (\fIp\fP) and the state name list (\fIs\fP) is required. +.IP +If only TCP and UDP files are to be listed, as controlled by +the specified exclusions and inclusions, the +.B \-i +option must be specified, too. +If only a single protocol's files are to be listed, add its name +as an argument to the +.B \-i +option. +.IP +For example, to list only network files with TCP state LISTEN, use: +.IP +.nf + \-iTCP \-sTCP:LISTEN +.fi +.IP +Or, for example, to list network files with all UDP states except +Idle, use: +.IP +.nf + \-iUDP -sUDP:Idle +.fi +.IP +State names vary with UNIX dialects, so it's not possible to +provide a complete list. Some common TCP state names are: +CLOSED, IDLE, BOUND, LISTEN, ESTABLISHED, SYN_SENT, SYN_RCDV, +ESTABLISHED, CLOSE_WAIT, FIN_WAIT1, CLOSING, LAST_ACK, FIN_WAIT_2, +and TIME_WAIT. +Two common UDP state names are Unbound and Idle. +.IP +See the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information on how to use protocol state exclusion and +inclusion, including examples. +.IP +The +.B \-o +(without a following decimal digit count) and +.B \-s +option (without a following protocol and state name list) +are mutually exclusive; they can't both be specified. +When neither is specified, +.I lsof +displays whatever value \- size or offset \- is appropriate and +available for the type of file. +.IP +Since some types of files don't have true sizes \- sockets, FIFOs, +pipes, etc. \- lsof displays for their sizes the content amounts in +their associated kernel buffers, if possible. +.TP \w'names'u+4 +.BI \-S " [t]" +specifies an optional time-out seconds value for kernel functions \- +.IR lstat (2), +.IR readlink (2), +and +.IR stat (2) +\- that might otherwise deadlock. +The minimum for +.I t +is two; +the default, fifteen; when no value is specified, the default is used. +.IP +See the +.B "BLOCKS AND TIMEOUTS" +section for more information. +.TP \w'names'u+4 +.BI \-T " [t]" +controls the reporting of some TCP/TPI information, also +reported by +.IR netstat (1), +following the network addresses. +In normal output the information appears in parentheses, each item +except TCP or TPI state name identified by a keyword, followed by `=', +separated from others by a single space: +.IP +.nf + + QR= + QS= + SO= + SS= + TF= + WR= + WW= +.fi +.IP +Not all values are reported for all UNIX dialects. +Items values (when available) are reported after the item name and '='. +.IP +When the field output mode is in effect (See +.BR "OUTPUT FOR OTHER PROGRAMS" .) +each item appears as a field with a `T' leading character. +.IP +.B \-T +with no following key characters disables TCP/TPI information reporting. +.IP +.B \-T +with following characters selects the reporting of specific TCP/TPI +information: +.IP +.nf + \fBf\fP selects reporting of socket options, + states and values, and TCP flags and + values. + \fBq\fP selects queue length reporting. + \fBs\fP selects connection state reporting. + \fBw\fP selects window size reporting. +.fi +.IP +Not all selections are enabled for some UNIX dialects. +State may be selected for all dialects and is reported by default. +The +.B \-h +or +.B \-? +help output for the +.B \-T +option will show what selections may be used with the UNIX dialect. +.IP +When +.B \-T +is used to select information \- i.e., it is followed by one or more +selection characters \- the displaying of state is disabled by default, +and it must be explicitly selected again in the characters following +.BR \-T . +(In effect, then, the default is equivalent to +.BR -Ts .) +For example, if queue lengths and state are desired, use +.BR \-Tqs . +.IP +Socket options, socket states, some socket values, TCP flags and +one TCP value may be reported (when available in the UNIX dialect) +in the form of the names that commonly appear after SO_, so_, SS_, +TCP_ and TF_ in the dialect's header files \- +most often , and . +Consult those header files for the meaning of the flags, options, +states and values. +.IP +``SO='' precedes socket options and values; ``SS='', socket states; +and ``TF='', TCP flags and values. +.IP +If a flag or option has a value, the value will follow an '=' and +the name -- e.g., ``SO=LINGER=5'', ``SO=QLIM=5'', ``TF=MSS=512''. +The following seven values may be reported: +.IP +.nf + Name + Reported Description (Common Symbol) + + KEEPALIVE keep alive time (SO_KEEPALIVE) + LINGER linger time (SO_LINGER) + MSS maximum segment size (TCP_MAXSEG) + PQLEN partial listen queue connections + QLEN established listen queue connections + QLIM established listen queue limit + RCVBUF receive buffer length (SO_RCVBUF) + SNDBUF send buffer length (SO_SNDBUF) +.fi +.IP +Details on what socket options and values, socket states, and TCP flags +and values may be displayed for particular UNIX dialects may be found in +the answer to the ``Why doesn't lsof report socket options, socket states, +and TCP flags and values for my dialect?'' and ``Why doesn't lsof report +the partial listen queue connection count for my dialect?'' +questions in the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +.TP \w'names'u+4 +.B \-t +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). +.B \-t +selects the +.B \-w +option. +.TP \w'names'u+4 +.BI \-u " s" +selects the listing of files for the user whose login names +or user ID numbers are in the comma\-separated set +.I s +\&\- e.g., ``abe'', +or ``548,root''. +(There should be no spaces in the set.) +.IP +Multiple login names or user ID numbers are joined in a single ORed set +before participating in AND option selection. +.IP +If a login name or user ID is preceded by a `^', it becomes a negation \- +i.e., files of processes owned by the login name or user ID will never +be listed. +A negated login name or user ID selection is neither ANDed nor ORed +with other selections; it is applied before all other selections and +absolutely excludes the listing of the files of the process. +For example, to direct +.I lsof +to exclude the listing of files belonging to root processes, +specify ``\-u^root'' or ``\-u^0''. +.TP \w'names'u+4 +.B \-U +selects the listing of UNIX domain socket files. +.TP \w'names'u+4 +.B \-v +selects the listing of +.I lsof +version information, including: revision number; +when the +.I lsof +binary was constructed; +who constructed the binary and where; +the name of the compiler used to construct the +.I lsof binary; +the version number of the compiler when readily available; +the compiler and loader flags used to construct the +.I lsof +binary; +and system information, typically the output of +.IR uname 's +.B \-a +option. +.TP \w'names'u+4 +.B \-V +directs +.I lsof +to indicate the items it was asked to list and failed to find \- command +names, file names, Internet addresses or files, login names, NFS files, +PIDs, PGIDs, and UIDs. +.IP +When other options are ANDed to search options, or compile\-time +options restrict the listing of some files, +.I lsof +may not report that it failed to find a search item when an ANDed +option or compile\-time option prevents the listing of the open file +containing the located search item. +.IP +For example, ``lsof -V -iTCP@foobar -a -d 999'' may not report a +failure to locate open files at ``TCP@foobar'' and may not list +any, if none have a file descriptor number of 999. +A similar situation arises when HASSECURITY and HASNOSOCKSECURITY are +defined at compile time and they prevent the listing of open files. +.TP \w'names'u+4 +.B +|\-w +Enables (\fB+\fP) or disables (\fB-\fP) the suppression of warning messages. +.IP +The +.I lsof +builder may choose to have warning messages disabled or enabled by +default. +The default warning message state is indicated in the output of the +.B \-h +or +.B \-? +option. +Disabling warning messages when they are already disabled or enabling +them when already enabled is acceptable. +.IP +The +.B \-t +option selects the +.B \-w +option. +.TP \w'names'u+4 +.BI \-x " [fl]" +may accompany the +.B +d +and +.B +D +options to direct their processing to cross over symbolic +links and|or file system mount points encountered when +scanning the directory (\fB+d\fP) or directory tree (\fB+D\fP). +.IP +If +.B -x +is specified by itself without a following parameter, cross\-over +processing of both symbolic links and file system mount points is +enabled. +Note that when +.B \-x +is specified without a parameter, the next argument must begin with '-' +or '+'. +.IP +The optional 'f' parameter enables file system mount point cross\-over +processing; 'l', symbolic link cross\-over processing. +.IP +The +.B \-x +option may not be supplied without also supplying a +.B +d +or +.B +D +option. +.TP \w'names'u+4 +.B \-X +This is a dialect\-specific option. +.HP \w'names'u+4 +\ \ \ \ AIX: +.br +This IBM AIX RISC/System 6000 option requests the reporting +of executed text file and shared library references. +.IP +.B WARNING: +because this option uses the kernel readx() function, its use on +a busy AIX system might cause an application process to hang so +completely that it can neither be killed nor stopped. +I have never seen this happen or had a report of its happening, +but I think there is a remote possibility it could happen. +.IP +By default use of readx() is disabled. +On AIX 5L and above +.I lsof +may need setuid\-root permission to perform the actions this +option requests. +.IP +The +.I lsof +builder may specify that the +.B \-X +option be restricted to processes whose real UID is root. +If that has been done, the +.B \-X +option will not appear in the +.B \-h +or +.B \-? +help output unless the real UID of the +.I lsof +process is root. +The default +.I lsof +distribution allows any UID to specify +.BR \-X, +so by default it will appear in the help output. +.IP +When AIX readx() use +is disabled, +.I lsof +may not be able to report information for all text and loader file +references, but it may also avoid exacerbating an AIX +kernel directory search kernel error, known as the Stale Segment +ID bug. +.IP +The readx() function, used by +.I lsof +or any other program to access some sections of kernel virtual +memory, can trigger the Stale Segment ID bug. +It can cause the kernel's dir_search() function to believe erroneously +that part of an in\-memory copy of a file system directory has been +zeroed. +Another application process, distinct from +.IR lsof , +asking the kernel to search the directory \- e.g., by using +.IR open "(2) \-" +can cause dir_search() to loop forever, thus hanging the application process. +.IP +Consult the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +and the +.I 00README +file of the +.I lsof +distribution for a more complete description of the Stale Segment ID bug, +its APAR, and methods for defining readx() use when compiling +.IR lsof . +.HP \w'names'u+4 +\ \ \ \ Linux: +.br +This Linux option requests that +.I lsof +skip the reporting of information on all open TCP, UDP and UDPLITE IPv4 +and IPv6 files. +.IP +This Linux option is most useful when the system has an extremely +large number of open TCP, UDP and UDPLITE files, the processing of whose +information in the +.I /proc/net/tcp* +and +.I /proc/net/udp* +files would take +.I lsof +a long time, and whose reporting is not of interest. +.IP +Use this option with care and only when you are sure that the +information you want +.I lsof +to display isn't associated with open TCP, UDP or UDPLITE socket files. +.HP \w'names'u+4 +\ \ \ \ Solaris 10 and above: +.br +This Solaris 10 and above option requests the reporting of cached +paths for files that have been deleted \- i.e., removed with +.IR rm (1) +or +.IR unlink (2). +.IP +The cached path is followed by the string ``\ (deleted)'' to indicate +that the path by which the file was opened has been deleted. +.IP +Because intervening changes made to the path \- i.e., renames with +.IR mv (1) +or +.IR rename (2) +\- are not recorded in the cached path, what +.I lsof +reports is only the path by which the file was opened, not its +possibly different final path. +.TP \w'names'u+4 +.BI \-z " [z]" +specifies how Solaris 10 and higher zone information is to be handled. +.IP +Without a following argument \- e.g., NO +.IR z " \-" +the option specifies that zone names are to be listed in the ZONE +output column. +.IP +The +.B \-z +option may be followed by a zone name, +.BI z . +That causes lsof to list only open files for processes in that zone. +Multiple +.BI \-z " z" +option and argument pairs may be specified to form a list of named zones. +Any open file of any process in any of the zones will be listed, subject +to other conditions specified by other options and arguments. +.TP \w'names'u+4 +.BI \-Z " [Z]" +specifies how SELinux security contexts are to be handled. +It and 'Z' field output character support are inhibited +when SELinux is disabled in the running Linux kernel. +See +.B "OUTPUT FOR OTHER PROGRAMS" +for more information on the 'Z' field output character. +.IP +Without a following argument \- e.g., NO +.IR Z " \-" +the option specifies that security contexts are to be listed in the +SECURITY\-CONTEXT output column. +.IP +The +.B \-Z +option may be followed by a wildcard security context name, +.BI Z . +That causes lsof to list only open files for processes in that security +context. +Multiple +.BI \-Z " Z" +option and argument pairs may be specified to form a list of security +contexts. +Any open file of any process in any of the security contexts will be listed, +subject to other conditions specified by other options and arguments. +Note that +.I Z +can be A:B:C or *:B:C or A:B:* or *:*:C to match against the A:B:C context. +.TP \w'names'u+4 +.B -- +The double minus sign option is a marker that signals the end of +the keyed options. +It may be used, for example, when the first file name begins with +a minus sign. +It may also be used when the absence of a value for the last keyed +option must be signified by the presence of a minus sign in the following +option and before the start of the file names. +.TP \w'names'u+4 +.I names +These are path names of specific files to list. +Symbolic links are resolved before use. +The first name may be separated from the preceding options with +the ``--'' option. +.IP +If a +.I name +is the mounted\-on directory of a file system or the device of the +file system, +.I lsof +will list all the files open on the file system. +To be considered a file system, the +.I name +must match a mounted\-on directory name in +.IR mount (8) +output, or match the name of a block device associated with a mounted\-on +directory name. +The +.B +|\-f +option may be used to force +.I lsof +to consider a +.I name +a file system identifier (\fB+f\fP) or a simple file (\fB\-f\fP). +.IP +If +.I name +is a path to a directory that is not the mounted\-on directory name of +a file system, it is treated just as a regular file is treated \- i.e., +its listing is restricted to processes that have it open as a file or +as a process\-specific directory, such as the root or current working +directory. +To request that +.I lsof +look for open files inside a directory name, use the +.BI +d " s" +and +.BI +D " D" +options. +.IP +If a +.I name +is the base name of a family of multiplexed files \- e. g, AIX's +.IR /dev/pt[cs] " \-" +.I lsof +will list all the associated multiplexed files on the device that +are open \- e.g., +.IR /dev/pt[cs]/1 , +.IR /dev/pt[cs]/2 , +etc. +.IP +If a +.I name +is a UNIX domain socket name, +.I lsof +will usually search for it by the characters of the name alone \- exactly as +it is specified and is recorded in the kernel socket structure. +(See the next paragraph for an exception to that rule for Linux.) +Specifying a relative path \- e.g., +.I ./file +\&\- in place of the +file's absolute path \- e.g., +.I /tmp/file +\&\- won't work because +.I lsof +must match the characters you specify with what it finds in the +kernel UNIX domain socket structures. +.IP +If a +.I name +is a Linux UNIX domain socket name, in one case +.I lsof +is able to search for it by its device and inode number, allowing +.I name +to be a relative path. +The case requires that the absolute path -- i.e., one beginning with a +slash ('/') be used by the process that created the socket, and hence be +stored in the +.I /proc/net/unix +file; and it requires that +.I lsof +be able to obtain the device and node numbers of both the absolute path in +.I /proc/net/unix +and +.I name +via successful +.IR stat (2) +system calls. +When those conditions are met, +.I lsof +will be able to search for the UNIX domain socket when some path to it is +is specified in +.IR name . +Thus, for example, if the path is +.IR /dev/log , +and an +.I lsof +search is initiated when the working directory is +.IR /dev , +then +.I name +could be +.IR ./log . +.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 . +.IP +If you have also specified the +.B \-b +option, +the only +.I names +you may safely specify are file systems for which your mount table +supplies alternate device numbers. +See the +.B "AVOIDING KERNEL BLOCKS" +and +.B "ALTERNATE DEVICE NUMBERS" +sections for more information. +.IP +Multiple file names are joined in a single ORed set before +participating in AND option selection. +.SH AFS +.I Lsof +supports the recognition of AFS files for these dialects (and AFS +versions): +.PP +.nf + AIX 4.1.4 (AFS 3.4a) + HP\-UX 9.0.5 (AFS 3.4a) + Linux 1.2.13 (AFS 3.3) + Solaris 2.[56] (AFS 3.4a) +.fi +.PP +It may recognize AFS files on other versions of these dialects, +but has not been tested there. +Depending on how AFS is implemented, +.I lsof +may recognize AFS files in other dialects, or may have difficulties +recognizing AFS files in the supported dialects. +.PP +.I Lsof +may have trouble identifying all aspects of AFS files in +supported dialects when AFS kernel support is implemented via +dynamic modules whose addresses do not appear in the kernel's +variable name list. +In that case, +.I lsof +may have to guess at the identity of AFS files, and might not be able to +obtain volume information from the kernel that is needed for calculating +AFS volume node numbers. +When +.I lsof +can't compute volume node numbers, it reports blank in the NODE column. +.PP +The +.BI \-A " A" +option is available in some dialect implementations of +.I lsof +for specifying the name list file where dynamic module kernel +addresses may be found. +When this option is available, it will be listed in the +.I lsof +help output, presented in response to the +.B \-h +or +.B \-? +.PP +See the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information about dynamic modules, their +symbols, and how they affect +.I lsof +options. +.PP +Because AFS path lookups don't seem to participate in the +kernel's name cache operations, +.I lsof +can't identify path name components for AFS files. +.SH SECURITY +.I Lsof +has three features that may cause security concerns. +First, its default compilation mode allows anyone to list all +open files with it. +Second, by default it creates a user\-readable and user\-writable device +cache file in the home directory of the real user ID that executes +.IR lsof . +(The list\-all\-open\-files and device cache features may be disabled when +.I lsof +is compiled.) +Third, its +.B \-k +and +.B \-m +options name alternate kernel name list or memory files. +.PP +Restricting the listing of all open files is controlled by the +compile\-time HASSECURITY and HASNOSOCKSECURITY options. +When HASSECURITY is defined, +.I lsof +will allow only the root user to list all open files. +The non\-root user may list only open files of processes with the same user +IDentification number as the real user ID number of the +.I lsof +process (the one that its user logged on with). +.PP +However, if HASSECURITY and HASNOSOCKSECURITY are both defined, +anyone may list open socket files, provided they are selected +with the +.B \-i +option. +.PP +When HASSECURITY is not defined, anyone may list all open files. +.PP +Help output, presented in response to the +.B \-h +or +.B \-? +option, gives the status of the HASSECURITY and HASNOSOCKSECURITY definitions. +.PP +See the +.B Security +section of the +.I 00README +file of the +.I lsof +distribution for information on building +.I lsof +with the HASSECURITY and HASNOSOCKSECURITY options enabled. +.PP +Creation and use of a user\-readable and user\-writable device +cache file is controlled by the compile\-time HASDCACHE option. +See the +.B "DEVICE CACHE FILE" +section and the sections that follow it for details on how its path +is formed. +For security considerations it is important to note that in the default +.I lsof +distribution, if the real user ID under which +.I lsof +is executed is root, the device cache file will be written in root's +home directory \- e.g., +.I / +or +.IR /root . +When HASDCACHE is not defined, +.I lsof +does not write or attempt to read a device cache file. +.PP +When HASDCACHE is defined, the +.I lsof +help output, presented in response to the +.BR \-h , +.BR \-D? , +or +.B \-? +options, will provide device cache file handling information. +When HASDCACHE is not defined, the +.B \-h +or +.B \-? +output will have no +.B \-D +option description. +.PP +Before you decide to disable the device cache file feature \- enabling +it improves the performance of +.I lsof +by reducing the startup overhead of examining all the nodes in +.I /dev +(or +.IR /devices ) +\&\- read the discussion of it in the +.I 00DCACHE +file of the +.I lsof +distribution and the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +.PP +WHEN IN DOUBT, YOU CAN TEMPORARILY DISABLE THE USE OF THE DEVICE CACHE FILE +WITH THE +.B \-Di +OPTION. +.PP +When +.I lsof +user declares alternate kernel name list or memory files with the +.B \-k +and +.B \-m +options, +.I lsof +checks the user's authority to read them with +.IR access (2). +This is intended to prevent whatever special power +.I lsof's +modes might confer on it from letting it read files not normally +accessible via the authority of the real user ID. +.SH OUTPUT +This section describes the information +.I lsof +lists for each open file. +See the +.B "OUTPUT FOR OTHER PROGRAMS" +section for additional information on output that can be processed +by another program. +.PP +.I Lsof +only outputs printable (declared so by +.IR isprint (3)) +8 bit characters. +Non\-printable characters are printed in one of three forms: +the C ``\\[bfrnt]'' form; +the control character `^' form (e.g., ``^@''); +or hexadecimal leading ``\\x'' form (e.g., ``\\xab''). +Space is non\-printable in the COMMAND column (``\\x20'') +and printable elsewhere. +.PP +For some dialects \- if HASSETLOCALE is defined in the dialect's +machine.h header file \- +.I lsof +will print the extended 8 bit characters of a language locale. +The +.I lsof +process must be supplied a language locale environment variable +(e.g., LANG) whose value represents a known language locale +in which the extended characters are considered printable by +.IR isprint (3). +Otherwise +.I lsof +considers the extended characters non\-printable and prints them according +to its rules for non\-printable characters, stated above. +Consult your dialect's +.IR setlocale (3) +man page for the names of other environment variables that may +be used in place of LANG \- e.g., LC_ALL, LC_CTYPE, etc. +.PP +.I Lsof's +language locale support for a dialect also covers wide characters \- e.g., +UTF-8 \- when HASSETLOCALE and HASWIDECHAR are defined in the dialect's +machine.h header file, and when a suitable language locale has been defined +in the appropriate environment variable for the +.I lsof +process. +Wide characters are printable under those conditions if +.IR iswprint (3) +reports them to be. +If HASSETLOCALE, HASWIDECHAR and a suitable language locale aren't defined, +or if +.IR iswprint (3) +reports wide characters that aren't printable, +.I lsof +considers the wide characters non\-printable and prints each of their +8 bits according to its rules for non\-printable characters, stated above. +.PP +Consult the answers to the "Language locale support" questions in the +lsof FAQ (The \fBFAQ\fP section gives its location.) for more information. +.PP +.I Lsof +dynamically sizes the output columns each time it runs, guaranteeing +that each column is a minimum size. +It also guarantees that each column is separated from its predecessor +by at least one space. +.TP \w'COMMAND'u+4 +COMMAND +contains the first nine characters of the name of the UNIX command +associated with the process. +If a non\-zero +.I w +value is specified to the +.BI +c " w" +option, the column contains the first +.I w +characters of the name of the UNIX command associated with the process +up to the limit of characters supplied to +.I lsof +by the UNIX dialect. +(See the description of the +.BI +c " w" +command or the +.I lsof +FAQ for more information. +The \fBFAQ\fP section gives its location.) +.IP +If +.I w +is less than the length of the column title, ``COMMAND'', it will +be raised to that length. +.IP +If a zero +.I w +value is specified to the +.BI +c " w" +option, the column contains all the characters of the name of the UNIX command +associated with the process. +.IP +All command name characters maintained by the kernel in its structures +are displayed in field output when the command name descriptor (`c') +is specified. +See the +.B "OUTPUT FOR OTHER COMMANDS" +section for information on selecting field output and the associated +command name descriptor. +.TP +PID +is the Process IDentification number of the process. +.TP +TID +is the task (thread) IDentification number, if task (thread) +reporting is supported by the dialect and a task (thread) is +being listed. +(If help output \- i.e., the output of the +.B \-h +or +.B \-? +options \- shows this option, then task (thread) reporting is +supported by the dialect.) +.IP +A blank TID column in Linux indicates a process \- i.e., a non\-task. +.TP +ZONE +is the Solaris 10 and higher zone name. +This column must be selected with the +.B \-z +option. +.TP +SECURITY\-CONTEXT +is the SELinux security context. +This column must be selected with the +.B -Z +option. +Note that the +.B -Z +option is inhibited when SELinux is disabled in the running Linux +kernel. +.TP +PPID +is the Parent Process IDentification number of the process. +It is only displayed when the +.B \-R +option has been specified. +.TP +PGID +is the process group IDentification number associated with +the process. +It is only displayed when the +.B \-g +option has been specified. +.TP +USER +is the user ID number or login name of the user to whom +the process belongs, usually the same as reported by +.IR ps (1). +However, on Linux USER is the user ID number or login that owns +the directory in /proc where +.I lsof +finds information about the process. +Usually that is the same value reported by +.IR ps (1), +but may differ when the process has changed its effective user ID. +(See the +.B \-l +option description for information on when a user ID number or +login name is displayed.) +.TP +FD +is the File Descriptor number of the file or: +.IP +.nf + \fBcwd\fP current working directory; +.br + \fBL\fInn\fR library references (AIX); +.br + \fBerr\fR FD information error (see NAME column); +.br + \fBjld\fR jail directory (FreeBSD); +.br + \fBltx\fP shared library text (code and data); +.br + \fBMxx\fP hex memory\-mapped type number xx. +.br + \fBm86\fP DOS Merge mapped file; +.br + \fBmem\fP memory\-mapped file; +.br + \fBmmap\fP memory\-mapped device; +.br + \fBpd\fP parent directory; +.br + \fBrtd\fP root directory; +.br + \fBtr\fR kernel trace file (OpenBSD); +.br + \fBtxt\fP program text (code and data); +.br + \fBv86\fP VP/ix mapped file; +.fi +.IP +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 mode unknown and no lock +.br + character follows; +.br + `\-' if mode unknown and lock +.br + character follows. +.IP +The mode character is followed by one of these lock characters, describing +the type of lock applied to the file: +.IP + \fBN\fP for a Solaris NFS lock of unknown type; +.br + \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 + \fBu\fP for a read and write lock of any length; +.br + \fBU\fP for a lock of unknown type; +.br + \fBx\fP for an SCO OpenServer Xenix lock on part + of the file; +.br + \fBX\fP for an SCO OpenServer Xenix lock on the + entire file; +.br + space if there is no lock. +.IP +See the +.B LOCKS +section for more information on the lock information character. +.IP +The FD column contents constitutes a single field for parsing in +post\-processing scripts. +.TP +TYPE +is the type of the node associated with the file \- e.g., GDIR, GREG, +VDIR, VREG, etc. +.IP +or ``IPv4'' for an IPv4 socket; +.IP +or ``IPv6'' for an open IPv6 network file \- even if its address is +IPv4, mapped in an IPv6 address; +.IP +or ``ax25'' for a Linux AX.25 socket; +.IP +or ``inet'' for an Internet domain socket; +.IP +or ``lla'' for a HP\-UX link level access file; +.IP +or ``rte'' for an AF_ROUTE socket; +.IP +or ``sock'' for a socket of unknown domain; +.IP +or ``unix'' for a UNIX domain socket; +.IP +or ``x.25'' for an HP\-UX x.25 socket; +.IP +or ``BLK'' for a block special file; +.IP +or ``CHR'' for a character special file; +.IP +or ``DEL'' for a Linux map file that has been deleted; +.IP +or ``DIR'' for a directory; +.IP +or ``DOOR'' for a VDOOR file; +.IP +or ``FIFO'' for a FIFO special file; +.IP +or ``KQUEUE'' for a BSD style kernel event queue file; +.IP +or ``LINK'' for a symbolic link file; +.IP +or ``MPB'' for a multiplexed block file; +.IP +or ``MPC'' for a multiplexed character file; +.IP +or ``NOFD'' for a Linux /proc//fd directory that can't be opened \-- +the directory path appears in the NAME column, followed by an error +message; +.IP +or ``PAS'' for a +.I /proc/as +file; +.IP +or ``PAXV'' for a +.I /proc/auxv +file; +.IP +or ``PCRE'' for a +.I /proc/cred +file; +.IP +or ``PCTL'' for a +.I /proc +control file; +.IP +or ``PCUR'' for the current +.I /proc +process; +.IP +or ``PCWD'' for a +.I /proc +current working directory; +.IP +or ``PDIR'' for a +.I /proc +directory; +.IP +or ``PETY'' for a +.I /proc +executable type (\fIetype\fP); +.IP +or ``PFD'' for a +.I /proc +file descriptor; +.IP +or ``PFDR'' for a +.I /proc +file descriptor directory; +.IP +or ``PFIL'' for an executable +.I /proc +file; +.IP +or ``PFPR'' for a +.I /proc +FP register set; +.IP +or ``PGD'' for a +.I /proc/pagedata +file; +.IP +or ``PGID'' for a +.I /proc +group notifier file; +.IP +or ``PIPE'' for pipes; +.IP +or ``PLC'' for a +.I /proc/lwpctl +file; +.IP +or ``PLDR'' for a +.I /proc/lpw +directory; +.IP +or ``PLDT'' for a +.I /proc/ldt +file; +.IP +or ``PLPI'' for a +.I /proc/lpsinfo +file; +.IP +or ``PLST'' for a +.I /proc/lstatus +file; +.IP +or ``PLU'' for a +.I /proc/lusage +file; +.IP +or ``PLWG'' for a +.I /proc/gwindows +file; +.IP +or ``PLWI'' for a +.I /proc/lwpsinfo +file; +.IP +or ``PLWS'' for a +.I /proc/lwpstatus +file; +.IP +or ``PLWU'' for a +.I /proc/lwpusage +file; +.IP +or ``PLWX'' for a +.I /proc/xregs +file' +.IP +or ``PMAP'' for a +.I /proc +map file (\fImap\fP); +.IP +or ``PMEM'' for a +.I /proc +memory image file; +.IP +or ``PNTF'' for a +.I /proc +process notifier file; +.IP +or ``POBJ'' for a +.I /proc/object +file; +.IP +or ``PODR'' for a +.I /proc/object +directory; +.IP +or ``POLP'' for an old format +.I /proc +light weight process file; +.IP +or ``POPF'' for an old format +.I /proc +PID file; +.IP +or ``POPG'' for an old format +.I /proc +page data file; +.IP +or ``PORT'' for a SYSV named pipe; +.IP +or ``PREG'' for a +.I /proc +register file; +.IP +or ``PRMP'' for a +.I /proc/rmap +file; +.IP +or ``PRTD'' for a +.I /proc +root directory; +.IP +or ``PSGA'' for a +.I /proc/sigact +file; +.IP +or ``PSIN'' for a +.I /proc/psinfo +file; +.IP +or ``PSTA'' for a +.I /proc +status file; +.IP +or ``PSXSEM'' for a POSIX semaphore file; +.IP +or ``PSXSHM'' for a POSIX shared memory file; +.IP +or ``PUSG'' for a +.I /proc/usage +file; +.IP +or ``PW'' for a +.I /proc/watch +file; +.IP +or ``PXMP'' for a +.I /proc/xmap +file; +.IP +or ``REG'' for a regular file; +.IP +or ``SMT'' for a shared memory transport file; +.IP +or ``STSO'' for a stream socket; +.IP +or ``UNNM'' for an unnamed type file; +.IP +or ``XNAM'' for an OpenServer Xenix special file of unknown type; +.IP +or ``XSEM'' for an OpenServer Xenix semaphore file; +.IP +or ``XSD'' for an OpenServer Xenix shared data file; +.IP +or the four type number octets if the corresponding name isn't known. +.TP +FILE\-ADDR +contains the kernel file structure address when +.B f +has been specified to +.BR +f ; +.TP +FCT +contains the file reference count from the kernel file structure when +.B c +has been specified to +.BR +f ; +.TP +FILE\-FLAG +when +.B g +or +.B G +has been specified to +.BR +f , +this field contains the contents of the f_flag[s] member of the kernel +file structure and the kernel's per\-process open file flags (if available); +\&`G' causes them to be displayed in hexadecimal; +\&`g', as short\-hand names; +two lists may be displayed with entries separated by commas, the +lists separated by a semicolon (`;'); +the first list may contain short\-hand names for f_flag[s] values from +the following table: +.IP +.nf + AIO asynchronous I/O (e.g., FAIO) + AP append + ASYN asynchronous I/O (e.g., FASYNC) + BAS block, test, and set in use + BKIU block if in use + BL use block offsets + BSK block seek + CA copy avoid + CIO concurrent I/O + CLON clone + CLRD CL read + CR create + DF defer + DFI defer IND + DFLU data flush + DIR direct + DLY delay + DOCL do clone + DSYN data\-only integrity + DTY must be a directory + EVO event only + EX open for exec + EXCL exclusive open + FSYN synchronous writes + GCDF defer during unp_gc() (AIX) + GCMK mark during unp_gc() (AIX) + GTTY accessed via /dev/tty + HUP HUP in progress + KERN kernel + KIOC kernel\-issued ioctl + LCK has lock + LG large file + MBLK stream message block + MK mark + MNT mount + MSYN multiplex synchronization + NATM don't update atime + NB non\-blocking I/O + NBDR no BDRM check + NBIO SYSV non\-blocking I/O + NBF n\-buffering in effect + NC no cache + ND no delay + NDSY no data synchronization + NET network + NFLK don't follow links + NMFS NM file system + NOTO disable background stop + NSH no share + NTTY no controlling TTY + OLRM OLR mirror + PAIO POSIX asynchronous I/O + PP POSIX pipe + R read + RC file and record locking cache + REV revoked + RSH shared read + RSYN read synchronization + RW read and write access + SL shared lock + SNAP cooked snapshot + SOCK socket + SQSH Sequent shared set on open + SQSV Sequent SVM set on open + SQR Sequent set repair on open + SQS1 Sequent full shared open + SQS2 Sequent partial shared open + STPI stop I/O + SWR synchronous read + SYN file integrity while writing + TCPM avoid TCP collision + TR truncate + W write + WKUP parallel I/O synchronization + WTG parallel I/O synchronization + VH vhangup pending + VTXT virtual text + XL exclusive lock +.fi +.IP +this list of names was derived from F* #define's in dialect header files +, , , , and ; +see the lsof.h header file for a list showing the correspondence +between the above short\-hand names and the header file definitions; +.IP +the second list (after the semicolon) may contain short\-hand names +for kernel per\-process open file flags from this table: +.IP +.nf + ALLC allocated + BR the file has been read + BHUP activity stopped by SIGHUP + BW the file has been written + CLSG closing + CX close\-on-exec (see fcntl(F_SETFD)) + LCK lock was applied + MP memory\-mapped + OPIP open pending \- in progress + RSVW reserved wait + SHMT UF_FSHMAT set (AIX) + USE in use (multi\-threaded) +.fi +.TP +NODE\-ID +(or INODE\-ADDR for some dialects) +contains a unique identifier for the file node (usually the kernel +vnode or inode address, but also occasionally a concatenation of +device and node number) when +.B n +has been specified to +.BR +f ; +.TP +DEVICE +contains the device numbers, separated by commas, for a character special, +block special, regular, directory or NFS file; +.IP +or ``memory'' for a memory file system node under Tru64 UNIX; +.IP +or the address of the private data area of a Solaris socket +stream; +.IP +or a kernel reference address that identifies the file +(The kernel reference address may be used for FIFO's, for example.); +.IP +or +the base address or device name of a Linux AX.25 socket device. +.IP +Usually only the lower thirty two bits of Tru64 UNIX kernel addresses +are displayed. +.TP +SIZE, SIZE/OFF, or OFFSET +is the size of the file or the file offset in bytes. +A value is displayed in this column only if it is available. +.I Lsof +displays whatever value \- size or offset \- is appropriate for the type +of the file and the version of +.IR lsof . +.IP +On some UNIX dialects +.I lsof +can't obtain accurate or consistent file offset information from its +kernel data sources, sometimes just for particular kinds of files +(e.g., socket files.) +In other cases, files don't have true sizes \- e.g., sockets, FIFOs, +pipes \- so +.I lsof +displays for their sizes the content amounts it finds in their kernel +buffer descriptors (e.g., socket buffer size counts or TCP/IP window +sizes.) +Consult the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information. +.IP +The file size is displayed in decimal; +the offset is normally displayed in decimal with a leading ``0t'' if +it contains 8 digits or less; in hexadecimal with a leading ``0x'' if +it is longer than 8 digits. +(Consult the +.BI \-o " o" +option description for information on when 8 might default to +some other value.) +.IP +Thus the leading ``0t'' and ``0x'' identify an offset when the column +may contain both a size and an offset (i.e., its title is SIZE/OFF). +.IP +If the +.B \-o +option is specified, +.I lsof +always displays the file offset (or nothing if no offset is available) +and labels the column OFFSET. +The offset always begins with ``0t'' or ``0x'' as described above. +.IP +The +.I lsof +user can control the switch from ``0t'' to ``0x'' with the +.BI \-o " o" +option. +Consult its description for more information. +.IP +If the +.B \-s +option is specified, +.I lsof +always displays the file size (or nothing if no size is available) +and labels the column SIZE. +The +.B \-o +and +.B \-s +options are mutually exclusive; they can't both be specified. +.IP +For files that don't have a fixed size \- e.g., don't reside +on a disk device \- +.I lsof +will display appropriate information about the current size or +position of the file if it is available in the kernel structures +that define the file. +.TP +NLINK +contains the file link count when +.B +L +has been specified; +.TP +NODE +is the node 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''; +.IP +or ``STR'' for a stream; +.IP +or ``CCITT'' for an HP\-UX x.25 socket; +.IP +or the IRQ or inode number of a Linux AX.25 socket device. +.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; +the local host name or IP number is followed by a colon (':'), the +port, ``->'', and the two\-part remote address; +IP addresses may be reported as numbers or names, depending on the +.BR +|\-M , +.BR \-n , +and +.B \-P +options; +colon\-separated IPv6 numbers are enclosed in square brackets; +IPv4 INADDR_ANY and IPv6 IN6_IS_ADDR_UNSPECIFIED addresses, and +zero port numbers are represented by an asterisk ('*'); +a UDP destination address may be followed by the amount of time +elapsed since the last packet was sent to the destination; +TCP, UDP and UDPLITE remote addresses may be followed by TCP/TPI +information in parentheses \- state (e.g., ``(ESTABLISHED)'', ``(Unbound)''), +queue sizes, and window sizes (not all dialects) \- in a fashion +similar to what +.IR netstat (1) +reports; +see the +.B \-T +option description or the description of the TCP/TPI field in +.B "OUTPUT FOR OTHER PROGRAMS" +for more information on state, queue size, and window size; +.IP +or the address or name of a UNIX domain socket, possibly including +a stream clone device name, a file system object's path name, local +and foreign kernel addresses, socket pair information, and a bound +vnode address; +.IP +or the local and remote mount point names of an NFS file; +.IP +or ``STR'', followed by the stream name; +.IP +or a stream character device name, followed by ``->'' and the stream name +or a list of stream module names, separated by ``->''; +.IP +or ``STR:'' followed by the SCO OpenServer stream device and module +names, separated by ``->''; +.IP +or system directory name, `` -- '', and as many components of the path +name as +.I lsof +can find in the kernel's name cache for selected dialects +(See the +.B "KERNEL NAME CACHE" +section for more information.); +.IP +or ``PIPE->'', followed by a Solaris kernel pipe destination address; +.IP +or ``COMMON:'', followed by the vnode device information structure's +device name, for a Solaris common vnode; +.IP +or the address family, followed by a slash (`/'), followed by fourteen +comma\-separated bytes of a non\-Internet raw socket address; +.IP +or the HP\-UX x.25 local address, followed by the virtual connection +number (if any), followed by the remote address (if any); +.IP +or ``(dead)'' for disassociated Tru64 UNIX files \- typically terminal files +that have been flagged with the TIOCNOTTY ioctl and closed by daemons; +.IP +or ``rd='' and ``wr='' for the values of the +read and write offsets of a FIFO; +.IP +or ``clone \fIn\fP:/dev/event'' for SCO OpenServer file clones of the +.I /dev/event +device, where +.I n +is the minor device number of the file; +.IP +or ``(socketpair: n)'' for a Solaris 2.6, 8, 9 or 10 +UNIX domain socket, created by the +.IR socketpair (3N) +network function; +.IP +or ``no PCB'' for socket files that do not have a protocol block +associated with them, optionally followed by ``, CANTSENDMORE'' if +sending on the socket has been disabled, or ``, CANTRCVMORE'' if +receiving on the socket has been disabled (e.g., by the +.IR shutdown (2) +function); +.IP +or the local and remote addresses of a Linux IPX socket file +in the form :[:], followed in parentheses +by the transmit and receive queue sizes, and the connection state; +.IP +or ``dgram'' or ``stream'' for the type UnixWare 7.1.1 and above in\-kernel +UNIX domain sockets, followed by a colon (':') and the local path name +when available, followed by ``->'' and the remote path name or kernel +socket address in hexadecimal when available; +.IP +or the association value, association index, endpoint value, local address, +local port, remote address and remote port for Linux SCTP sockets; +.IP +or ``protocol: '' followed by the Linux socket's protocol attribute. +.PP +For dialects that support a ``namefs'' file system, allowing one +file to be attached to another with +.IR fattach (3C), +.I lsof +will add ``(FA:)'' to the NAME column. + and are hexadecimal vnode addresses. + will be ``<-'' if has been fattach'ed to +this vnode whose address is ; +and ``->'' if , the vnode address of this vnode, has been +fattach'ed to . + may be omitted if it already appears in the DEVICE column. +.PP +.I +Lsof +may add two parenthetical notes to the NAME column for open Solaris 10 files: +\&``(?)'' if +.I lsof +considers the path name of questionable accuracy; +and ``(deleted)'' if the +.B \-X +option has been specified and +.I lsof +detects the open file's path name has been deleted. +Consult the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information on these NAME column additions. +.SH LOCKS +.I Lsof +can't adequately report the wide variety of UNIX dialect file locks +in a single character. +What it reports in a single character is a compromise between the +information it finds in the kernel and the limitations of the reporting +format. +.PP +Moreover, when a process holds several byte level locks on a file, +.I lsof +only reports the status of the first lock it encounters. +If it is a byte level lock, then the lock character will be reported +in lower case \- i.e., `r', `w', or `x' \- rather than the upper case +equivalent reported for a full file lock. +.PP +Generally +.I lsof +can only report on locks held by local processes on local files. +When a local process sets a lock on a remotely mounted (e.g., NFS) +file, the remote server host usually records the lock state. +One exception is Solaris \- at some patch levels of 2.3, and in all +versions above 2.4, the Solaris kernel records information on remote +locks in local structures. +.PP +.I Lsof +has trouble reporting locks for some UNIX dialects. +Consult the +.B BUGS +section of this manual page or the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for more information. +.SH "OUTPUT FOR OTHER PROGRAMS" +When the +.B \-F +option is specified, +.I lsof +produces output that is suitable for processing by another program \- e.g, an +.I awk +or +.I Perl +script, or a C program. +.PP +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. +.PP +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. +.PP +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. +.PP +When the NUL (000) field terminator has been selected with the +0 (zero) field identifier character, +.I lsof +ends each process and file set with a NL (012) character. +.PP +.I 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 +.B \-F +option. +When a field selection character identifies an item +.I lsof +does not normally list \- e.g., PPID, selected with +.BR \-R " \-" +specification of the field character \- e.g., ``\fB\-FR\fP'' \- +also selects the listing of the item. +.PP +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, +.I lsof +supports the +.B \-F +option; it selects the output of all fields with NL terminators +(the +.B \-F0 +option pair selects the output of all fields with NUL terminators). +For compatibility reasons neither +.B \-F +nor +.B \-F0 +select the raw device field. +.PP +These are the fields that +.I lsof +will produce. +The single character listed first is the field identifier. +.PP +.nf + 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) + f file descriptor + F file structure address (0x) + G file flaGs (0x; names if \fB+fg\fP 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 + n file name, comment, Internet address + N node identifier (ox + o file's offset (decimal) + p process ID (always selected) + P protocol name + r raw device number (0x) + 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= + QS= + SO= (not all dialects) + SS= (not all dialects) + ST= + TF= (not all dialects) + WR= (not all dialects) + WW= (not all dialects) + (TCP/TPI information isn't reported for all supported + UNIX dialects. The \fB\-h\fP or \fB\-?\fP help output for the + \fB\-T\fP 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 \fB\-F?\fP identifies the information to be found + in dialect\-specific fields.) +.fi +.PP +You can get on\-line help information on these characters and their +descriptions by specifying the +.B \-F? +option pair. +(Escape the `?' character as your shell requires.) +Additional information on field content can be found in the +.B OUTPUT +section. +.PP +As an example, ``\fB\-F pcfn\fP'' will select the process ID (`p'), +command name (`c'), file descriptor (`f') and file name (`n') +fields with an NL field terminator character; ``\fB\-F pcfn0\fP'' +selects the same output with a NUL (000) field terminator character. +.PP +.I 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. +.PP +Normally +.I 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 +.I 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, +.I lsof +ends each process and file set with a NL (012). +.PP +Three aids to producing programs that can process +.I lsof +field output are included in the +.I lsof +distribution. +The first is a C header file, +.IR 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. +.I Lsof +uses this header file. +.PP +The second aid is a set of sample scripts that process field output, +written in +.IR awk , +.I Perl +4, and +.I Perl +5. +They're located in the +.I scripts +subdirectory of the +.I lsof +distribution. +.PP +The third aid is the C library used for the +.I lsof +test suite. +The test suite is written in C and uses field output to validate +the correct operation of +.IR lsof . +The library can be found in the +.I tests/LTlib.c +file of the +.I lsof +distribution. +The library uses the first aid, the +.I lsof_fields.h +header file. +.SH "BLOCKS AND TIMEOUTS" +.I Lsof +can be blocked by some kernel functions that it uses \- +.IR lstat (2), +.IR readlink (2), +and +.IR stat (2). +These functions are stalled in the kernel, for example, when the +hosts where mounted NFS file systems reside become inaccessible. +.PP +.I Lsof +attempts to break these blocks with timers and child processes, +but the techniques are not wholly reliable. +When +.I lsof +does manage to break a block, it will report the break with an error +message. +The messages may be suppressed with the +.B \-t +and +.B \-w +options. +.PP +The default timeout value may be displayed with the +.B \-h +or +.B \-? +option, and it may be changed with the +.BI \-S " [t]" +option. +The minimum for +.I t +is two seconds, but you should avoid small values, since slow system +responsiveness can cause short timeouts to expire unexpectedly and +perhaps stop +.I lsof +before it can produce any output. +.PP +When +.I lsof +has to break a block during its access of mounted file system +information, it normally continues, although with less information +available to display about open files. +.PP +.I Lsof +can also be directed to avoid the protection of timers and child processes +when using the kernel functions that might block by specifying the +.B \-O +option. +While this will allow +.I lsof +to start up with less overhead, it exposes +.I lsof +completely to the kernel situations that might block it. +Use this option cautiously. +.SH "AVOIDING KERNEL BLOCKS" +.PP +You can use the +.B \-b +option to tell +.I lsof +to avoid using kernel functions that would block. +Some cautions apply. +.PP +First, using this option usually requires that your system supply +alternate device numbers in place of the device numbers that +.I lsof +would normally obtain with the +.IR lstat (2) +and +.IR stat (2) +kernel functions. +See the +.B "ALTERNATE DEVICE NUMBERS" +section for more information on alternate device numbers. +.PP +Second, you can't specify +.I names +for +.I lsof +to locate unless they're file system names. +This is because +.I lsof +needs to know the device and inode numbers of files listed with +.I names +in the +.I lsof +options, and the +.B \-b +option prevents +.I lsof +from obtaining them. +Moreover, since +.I lsof +only has device numbers for the file systems that have alternates, +its ability to locate files on file systems depends completely on the +availability and accuracy of the alternates. +If no alternates are available, or if they're incorrect, +.I lsof +won't be able to locate files on the named file systems. +.PP +Third, if the names of your file system directories that +.I lsof +obtains from your system's mount table are symbolic links, +.I lsof +won't be able to resolve the links. +This is because the +.B \-b +option causes +.I lsof +to avoid the kernel +.IR readlink (2) +function it uses to resolve symbolic links. +.PP +Finally, using the +.B \-b +option causes +.I lsof +to issue warning messages when it needs to use the kernel functions +that the +.B \-b +option directs it to avoid. +You can suppress these messages by specifying the +.B \-w +option, but if you do, you won't see the alternate device numbers +reported in the warning messages. +.SH "ALTERNATE DEVICE NUMBERS" +.PP +On some dialects, when +.I lsof +has to break a block because it can't get information about a +mounted file system via the +.IR lstat (2) +and +.IR stat (2) +kernel functions, or because you specified the +.B \-b +option, +.I lsof +can obtain some of the information it needs \- the device number and +possibly the file system type \- from the system mount table. +When that is possible, +.I lsof +will report the device number it obtained. +(You can suppress the report by specifying the +.B \-w +option.) +.PP +You can assist this process if your mount table is supported with an +.I /etc/mtab +or +.I /etc/mnttab +file that contains an options field by adding a ``dev=xxxx'' field for +mount points that do not have one in their options strings. +Note: you must be able to edit the file \- i.e., some mount tables +like recent Solaris /etc/mnttab or Linux /proc/mounts are read\-only +and can't be modified. +.PP +You may also be able to supply device numbers using the +.B +m +and +.BI +m " m" +options, provided they are supported by your dialect. +Check the output of +.I lsof's +.B \-h +or +.B \-? +options to see if the +.B +m +and +.BI +m " m" +options are available. +.PP +The ``xxxx'' portion of the field is the hexadecimal value +of the file system's device number. +(Consult the +.I st_dev +field of the output of the +.IR lstat (2) +and +.IR stat (2) +functions for the appropriate values for your file systems.) +Here's an example from a Sun Solaris 2.6 +.I /etc/mnttab +for a file system remotely mounted via NFS: +.PP +.nf + nfs ignore,noquota,dev=2a40001 +.fi +.PP +There's an advantage to having ``dev=xxxx'' entries in your mount +table file, especially for file systems that are mounted from remote +NFS servers. +When a remote server crashes and you want to identify its users by running +.I lsof +on one of its clients, +.I lsof +probably won't be able to get output from the +.IR lstat (2) +and +.IR stat (2) +functions for the file system. +If it can obtain the file system's device number from the mount table, +it will be able to display the files open on the crashed NFS server. +.PP +Some dialects that do not use an ASCII +.I /etc/mtab +or +.I /etc/mnttab +file for the mount table may still provide an alternative device number +in their internal mount tables. +This includes AIX, Apple Darwin, FreeBSD, NetBSD, OpenBSD, and Tru64 UNIX. +.I Lsof +knows how to obtain the alternative device number for these dialects +and uses it when its attempt to +.IR lstat (2) +or +.IR stat (2) +the file system is blocked. +.PP +If you're not sure your dialect supplies alternate device numbers +for file systems from its mount table, use this +.I lsof +incantation to see if it reports any alternate device numbers: +.PP +.IP +lsof -b +.PP +Look for standard error file warning messages that +begin ``assuming "dev=xxxx" from ...''. +.SH "KERNEL NAME CACHE" +.PP +.I Lsof +is able to examine the kernel's name cache or use other kernel +facilities (e.g., the ADVFS 4.x tag_to_path() function under +Tru64 UNIX) on some dialects for most file system types, +excluding AFS, and extract recently used path name components from it. +(AFS file system path lookups don't use the kernel's name cache; some +Solaris VxFS file system operations apparently don't use it, either.) +.PP +.I Lsof +reports the complete paths it finds in the NAME column. +If +.I lsof +can't report all components in a path, it reports in the NAME column +the file system name, followed by a space, two `-' characters, another +space, and the name components it has located, separated by +the `/' character. +.PP +When +.I lsof +is run in repeat mode \- i.e., with the +.B \-r +option specified \- the extent to which it can report path name +components for the same file may vary from cycle to cycle. +That's because other running processes can cause the kernel to +remove entries from its name cache and replace them with others. +.PP +.I Lsof's +use of the kernel name cache to identify the paths of files +can lead it to report incorrect components under some circumstances. +This can happen when the kernel name cache uses device and node +number as a key (e.g., SCO OpenServer) and a key on a rapidly +changing file system is reused. +If the UNIX dialect's kernel doesn't purge the name cache entry for +a file when it is unlinked, +.I lsof +may find a reference to the wrong entry in the cache. +The +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +has more information on this situation. +.PP +.I Lsof +can report path name components for these dialects: +.PP +.nf + FreeBSD + HP\-UX + Linux + NetBSD + NEXTSTEP + OpenBSD + OPENSTEP + SCO OpenServer + SCO|Caldera UnixWare + Solaris + Tru64 UNIX +.fi +.PP +.I Lsof +can't report path name components for these dialects: +.PP +.nf + AIX +.fi +.PP +If you want to know why +.I lsof +can't report path name components for some dialects, see the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +.SH "DEVICE CACHE FILE" +.PP +Examining all members of the +.I /dev +(or +.IR /devices ) +node tree with +.IR stat (2) +functions can be time consuming. +What's more, the information that +.I lsof +needs \- device number, inode number, and path \- rarely changes. +.PP +Consequently, +.I lsof +normally maintains an ASCII text file of cached +.I /dev +(or +.IR /devices ) +information (exception: the /proc\-based Linux +.I lsof +where it's not needed.) +The local system administrator who builds +.I lsof +can control the way the device cache file path is formed, selecting +from these options: +.PP +.nf + Path from the \fB\-D\fP option; + Path from an environment variable; + System\-wide path; + Personal path (the default); + Personal path, modified by an environment variable. +.fi +.PP +Consult the output of the +.BR \-h , +.B \-D? , +or +.B \-? +help options for the current state of device cache support. +The help output lists the default read\-mode device cache file path that +is in effect for the current invocation of +.IR lsof . +The +.B \-D? +option output lists the read\-only and write device cache file paths, +the names of any applicable environment variables, and the personal +device cache path format. +.PP +.I Lsof +can detect that the current device cache file has been accidentally +or maliciously modified by integrity checks, including the computation +and verification of a sixteen bit Cyclic Redundancy Check (CRC) sum on +the file's contents. +When +.I lsof +senses something wrong with the file, it issues a warning and attempts +to remove the current cache file and create a new copy, but only to +a path that the process can legitimately write. +.PP +The path from which a +.I lsof +process may attempt to read a device cache file may not be the same +as the path to which it can legitimately write. +Thus when +.I lsof +senses that it needs to update the device cache file, it may +choose a different path for writing it from the path from which +it read an incorrect or outdated version. +.PP +If available, the +.B \-Dr +option will inhibit the writing of a new device cache file. +(It's always available when specified without a path name argument.) +.PP +When a new device is added to the system, the device cache file may +need to be recreated. +Since +.I lsof +compares the mtime of the device cache file with the mtime and ctime +of the +.I /dev +(or +.IR /devices ) +directory, it usually detects that a new device has been added; +in that case +.I lsof +issues a warning message and attempts to rebuild the device cache file. +.PP +Whenever +.I lsof +writes a device cache file, it sets its ownership to the real UID +of the executing process, and its permission modes to 0600, this +restricting its reading and writing to the file's owner. +.SH "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS" +.PP +Two permissions of the +.I lsof +executable affect its ability to access device cache files. +The permissions are set by the local system administrator when +.I lsof +is installed. +.PP +The first and rarer permission is setuid\-root. +It comes into effect when +.I lsof +is executed; its effective UID is then +root, while its real (i.e., that of the logged\-on user) UID is not. +The +.I lsof +distribution recommends that versions for these dialects run setuid\-root. +.PP +.nf + HP-UX 11.11 and 11.23 + Linux +.fi +.PP +The second and more common permission is setgid. +It comes into effect when the effective group IDentification number (GID) +of the +.I lsof +process is set to one that can access kernel memory devices \- +e.g., ``kmem'', ``sys'', or ``system''. +.PP +An +.I lsof +process that has setgid permission usually surrenders the permission +after it has accessed the kernel memory devices. +When it does that, +.I lsof +can allow more liberal device cache path formations. +The +.I lsof +distribution recommends that versions for these dialects run setgid +and be allowed to surrender setgid permission. +.PP +.nf + AIX 5.[12] and 5.3-ML1 + Apple Darwin 7.x Power Macintosh systems + FreeBSD 4.x, 4.1x, 5.x and [6789].x for x86-based systems + FreeBSD 5.x and [6789].x for Alpha, AMD64 and Sparc64-based + systems + HP\-UX 11.00 + NetBSD 1.[456], 2.x and 3.x for Alpha, x86, and SPARC-based + systems + NEXTSTEP 3.[13] for NEXTSTEP architectures + OpenBSD 2.[89] and 3.[0\-9] for x86-based systems + OPENSTEP 4.x + SCO OpenServer Release 5.0.6 for x86-based systems + SCO|Caldera UnixWare 7.1.4 for x86-based systems + Solaris 2.6, 8, 9 and 10 + Tru64 UNIX 5.1 +.fi +.PP +(Note: +.I lsof +for AIX 5L and above needs setuid\-root permission if its +.B \-X +option is used.) +.PP +.I Lsof +for these dialects does not support a device cache, so the permissions +given to the executable don't apply to the device cache file. +.PP +.nf + Linux +.fi +.SH "DEVICE CACHE FILE PATH FROM THE \-D OPTION" +.PP +The +.B \-D +option provides limited means for specifying the device cache file path. +Its +.B ? +function will report the read\-only and write device cache file paths that +.I lsof +will use. +.PP +When the +.B \-D +.BR b , +.BR r , +and +.B u +functions are available, you can use them to request that the cache file be +built in a specific location (\fBb\fR[\fIpath\fR]); +read but not rebuilt (\fBr\fR[\fIpath\fR]); +or read and rebuilt (\fBu\fR[\fIpath\fR]). +The +.BR b , +.BR r , +and +.B u +functions are restricted under some conditions. +They are restricted when the +.I lsof +process is setuid\-root. +The path specified with the +.B r +function is always read\-only, even +when it is available. +.PP +The +.BR b , +.BR r , +and +.B u +functions are also restricted when the +.I lsof +process runs setgid and +.I lsof +doesn't surrender the setgid permission. +(See the +.B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS" +section for a list of implementations that normally don't surrender +their setgid permission.) +.PP +A further +.B \-D +function, +.B i +(for ignore), is always available. +.PP +When available, the +.B b +function tells +.I lsof +to read device information from the kernel with the +.IR stat (2) +function and build a device cache file at the indicated path. +.PP +When available, the +.B r +function tells +.I lsof +to read the device cache file, but not update it. +When a path argument accompanies +.BR \-Dr , +it names the device cache file path. +The +.B r +function is always available when it is specified without a +path name argument. +If +.I lsof +is not running setuid\-root and surrenders its setgid permission, +a path name argument may accompany the +.B r +function. +.PP +When available, the +.B u +function tells +.I lsof +to attempt to read and use the device cache file. +If it can't read the file, or if it finds the contents of the +file incorrect or outdated, it will read information from the kernel, +and attempt to write an updated version of the device cache file, +but only to a path it considers legitimate for the +.I lsof +process effective and real UIDs. +.SH "DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE" +.PP +.I Lsof's +second choice for the device cache file is the contents of the +LSOFDEVCACHE environment variable. +It avoids this choice if the +.I lsof +process is setuid\-root, or the real UID of the process is root. +.PP +A further restriction applies to a device cache file path taken from +the LSOFDEVCACHE environment variable: +.I lsof +will not write a device cache file to the path if the +.I lsof +process doesn't surrender its setgid permission. +(See the +.B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS" +section for information on implementations that don't surrender +their setgid permission.) +.PP +The local system administrator can disable the use of the LSOFDEVCACHE +environment variable or change its name when building +.IR lsof . +Consult the output of +.B \-D? +for the environment variable's name. +.SH "SYSTEM-WIDE DEVICE CACHE PATH" +.PP +The local system administrator may choose to have a system\-wide +device cache file when building +.IR lsof . +That file will generally be constructed by a special system administration +procedure when the system is booted or when the contents of +.I /dev +or +.IR /devices ) +changes. +If defined, it is +.I lsof's +third device cache file path choice. +.PP +You can tell that a system\-wide device cache file is in effect +for your local installation by examining the +.I lsof +help option output \- i.e., the output from the +.B \-h +or +.B \-? +option. +.PP +.I Lsof +will never write to the system\-wide device cache file path by +default. +It must be explicitly named with a +.B \-D +function in a root\-owned procedure. +Once the file has been written, the procedure must change its permission +modes to 0644 (owner\-read and owner\-write, group\-read, and other\-read). +.SH "PERSONAL DEVICE CACHE PATH (DEFAULT)" +.PP +The default device cache file path of the +.I lsof +distribution is one recorded in the home directory of the real UID +that executes +.IR lsof . +Added to the home directory is a second path component of the form +.IR .lsof_hostname . +.PP +This is +.I lsof's +fourth device cache file path choice, and is +usually the default. +If a system\-wide device cache file path was defined when +.I lsof +was built, +this fourth choice will be applied when +.I lsof +can't find the system\-wide device cache file. +This is the +.B only +time +.I lsof +uses two paths when reading the device cache file. +.PP +The +.I hostname +part of the second component is the base +name of the executing host, as returned by +.IR gethostname (2). +The base name is defined to be the characters preceding the first `.' +in the +.IR gethostname (2) +output, or all the +.IR gethostname (2) +output if it contains no `.'. +.PP +The device cache file belongs to the user ID and is readable and +writable by the user ID alone \- i.e., its modes are 0600. +Each distinct real user ID on a given host that executes +.I lsof +has a distinct device cache file. +The +.I hostname +part of the path distinguishes device cache files in an NFS\-mounted +home directory into which device cache files are written from +several different hosts. +.PP +The personal device cache file path formed by this method represents +a device cache file that +.I lsof +will attempt to read, and will attempt to write should it not +exist or should its contents be incorrect or outdated. +.PP +The +.B \-Dr +option without a path name argument will inhibit the writing of a new +device cache file. +.PP +The +.B \-D? +option will list the format specification for constructing the +personal device cache file. +The conversions used in the format specification are described in the +.I 00DCACHE +file of the +.I lsof +distribution. +.SH "MODIFIED PERSONAL DEVICE CACHE PATH" +.PP +If this option is defined by the local system administrator when +.I lsof +is built, the LSOFPERSDCPATH environment variable contents may +be used to add a component of the personal device cache file path. +.PP +The LSOFPERSDCPATH variable contents are inserted in the path at the +place marked by the local system administrator with the ``%p'' +conversion in the HASPERSDC format specification of the dialect's +.I machine.h +header file. +(It's placed right after the home directory in the default +.I lsof +distribution.) +.PP +Thus, for example, if LSOFPERSDCPATH contains ``LSOF'', the home +directory is ``/Homes/abe'', the host name is ``lsof.itap.purdue.edu'', +and the HASPERSDC format is the default (``%h/%p.lsof_%L''), the +modified personal device cache file path is: +.PP +.nf + /Homes/abe/LSOF/.lsof_vic +.fi +.PP +The LSOFPERSDCPATH environment variable is ignored when the +.I lsof +process is setuid\-root or when the real UID of the process is root. +.PP +.I Lsof +will not write to a modified personal device cache file path if the +.I lsof +process doesn't surrender setgid permission. +(See the +.B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS" +section for a list of implementations that normally don't surrender +their setgid permission.) +.PP +If, for example, you want to create a sub\-directory of personal +device cache file paths by using the LSOFPERSDCPATH environment +variable to name it, and +.I lsof +doesn't surrender its setgid permission, you will have to allow +.I lsof +to create device cache files at the standard personal path and +move them to your subdirectory with shell commands. +.PP +The local system administrator may: disable this option when +.I lsof +is built; change the name of the environment variable from +LSOFPERSDCPATH to something else; change the HASPERSDC +format to include the personal path component in another place; +or exclude the personal path component entirely. +Consult the output of the +.B \-D? +option for the environment variable's name and the HASPERSDC +format specification. +.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 command names, file names, Internet addresses or files, login +names, NFS files, PIDs, PGIDs, or UIDs it was asked to list. +If the +.B \-V +option is specified, +.I lsof +will indicate the search items it failed to list. +.PP +It returns a zero (0) if no errors were detected and if it was able to +list some information about all the specified search arguments. +.PP +.PP +When +.I lsof +cannot open access to +.I /dev +(or +.IR /devices ) +or one of its subdirectories, or get information on a file in them with +.IR stat (2), +it issues a warning message and continues. +That +.I lsof +will issue warning messages about inaccessible files in +.I /dev +(or +.IR /devices ) +is indicated in its help output \- requested with the +.B \-h +or +>B \-? +options \- with the message: +.PP +.nf + Inaccessible /dev warnings are enabled. +.fi +.PP +The warning message may be suppressed with the +.B \-w +option. +It may also have been suppressed by the system administrator when +.I lsof +was compiled by the setting of the WARNDEVACCESS definition. +In this case, the output from the help options will include the message: +.PP +.nf + Inaccessible /dev warnings are disabled. +.fi +.PP +Inaccessible device warning messages usually disappear after +.I lsof +has created a working device cache file. +.SH EXAMPLES +For a more extensive set of examples, documented more fully, see the +.I 00QUICKSTART +file of the +.I lsof +distribution. +.PP +To list all open files, use: +.IP +lsof +.PP +To list all open Internet, x.25 (HP\-UX), and UNIX domain files, use: +.IP +lsof -i -U +.PP +To list all open IPv4 network files in use by the process whose PID is +1234, use: +.IP +lsof -i 4 -a -p 1234 +.PP +Presuming the UNIX dialect supports IPv6, to list only open IPv6 +network files, use: +.IP +lsof -i 6 +.PP +To list all files using any protocol on ports 513, 514, or 515 of host +wonderland.cc.purdue.edu, use: +.IP +lsof -i @wonderland.cc.purdue.edu:513-515 +.PP +To list all files using any protocol on any port of mace.cc.purdue.edu +(cc.purdue.edu is the default domain), use: +.IP +lsof -i @mace +.PP +To list all open files for login name ``abe'', or user ID 1234, or +process 456, or process 123, or process 789, use: +.IP +lsof -p 456,123,789 -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` +.PP +To find any open file, including an open UNIX domain socket file, +with the name +.IR /dev/log , +use: +.IP +lsof /dev/log +.PP +To find processes with open files on the NFS file system named +.I /nfs/mount/point +whose server is inaccessible, and presuming your mount table supplies +the device number for +.IR /nfs/mount/point , +use: +.IP +lsof -b /nfs/mount/point +.PP +To do the preceding search with warning messages suppressed, use: +.IP +lsof -bw /nfs/mount/point +.PP +To ignore the device cache file, use: +.IP +lsof -Di +.PP +To obtain PID and command name field output for each process, file +descriptor, file device number, and file inode number for each file +of each process, use: +.IP +lsof -FpcfDi +.PP +To list the files at descriptors 1 and 3 of every process running the +.I lsof +command for login ID ``abe'' every 10 seconds, use: +.IP +lsof -c lsof -a -d 1 -d 3 -u abe -r10 +.PP +To list the current working directory of processes running a command that +is exactly four characters long and has an 'o' or 'O' in character three, +use this regular expression form of the +.BI \-c " c" +option: +.IP +lsof -c /^..o.$/i -a -d cwd +.PP +To find an IP version 4 socket file by its associated numeric dot\-form +address, use: +.IP +lsof -i@128.210.15.17 +.PP +To find an IP version 6 socket file (when the UNIX dialect supports +IPv6) by its associated numeric colon\-form address, use: +.IP +lsof -i@[0:1:2:3:4:5:6:7] +.PP +To find an IP version 6 socket file (when the UNIX dialect supports +IPv6) by an associated numeric colon\-form address that has a run of +zeroes in it \- e.g., the loop\-back address \- use: +.IP +lsof -i@[::1] +.PP +To obtain a repeat mode marker line that contains the current time, use: +.IP +lsof -rm====%T==== +.PP +To add spaces to the previous marker line, use: +.IP +lsof -r "m==== %T ====" +.SH BUGS +Since +.I lsof +reads kernel memory in its search for open files, rapid changes in kernel +memory may produce unpredictable results. +.PP +When a file has multiple record locks, the lock status character +(following the file descriptor) is derived from a test of the first +lock structure, not from any combination of the individual record +locks that might be described by multiple lock structures. +.PP +.I Lsof +can't search for files with restrictive access permissions by +.I name +unless it is installed with root set\-UID permission. +Otherwise it is limited to searching for files to which its user +or its set-GID group (if any) has access permission. +.PP +The display of the destination address of a raw socket (e.g., for +.IR ping ) +depends on the UNIX operating system. +Some dialects store the destination address in the raw socket's protocol +control block, some do not. +.PP +.I Lsof +can't always represent Solaris device numbers in the same way that +.IR ls (1) +does. +For example, the major and minor device numbers that the +.IR lstat (2) +and +.IR stat (2) +functions report for the directory on which CD-ROM files are mounted +(typically +.IR /cdrom ) +are not the same as the ones that it reports for the device on which +CD-ROM files are mounted (typically +.IR /dev/sr0 ). +(\fILsof\fP reports the directory numbers.) +.PP +The support for +.I /proc +file systems is available only for BSD and Tru64 UNIX dialects, Linux, and +dialects derived from SYSV R4 \- e.g., FreeBSD, NetBSD, OpenBSD, Solaris, +UnixWare. +.PP +Some +.I /proc +file items \- device number, inode number, and file size \- +are unavailable in some dialects. +Searching for files in a +.I /proc +file system may require that the full path name be specified. +.PP +No text (\fBtxt\fP) file descriptors are displayed for Linux +processes. +All entries for files other than the current working directory, +the root directory, and numerical file descriptors are labeled +.B mem +descriptors. +.PP +.I Lsof +can't search for Tru64 UNIX named pipes by name, because their kernel +implementation of lstat(2) returns an improper device number for a +named pipe. +.PP +.I Lsof +can't report fully or correctly on HP\-UX 9.01, 10.20, and 11.00 locks +because of insufficient access to kernel data or errors in the +kernel data. +See the +.I lsof +FAQ (The \fBFAQ\fP section gives its location.) +for details. +.PP +The AIX SMT file type is a fabrication. +It's made up for file structures whose type (15) isn't defined in the AIX +.I /usr/include/sys/file.h +header file. +One way to create such file structures is to run X clients with the DISPLAY +variable set to ``:0.0''. +.PP +The +.BI +|\-f [cfgGn] +option is not supported under /proc\-based Linux +.IR lsof , +because it doesn't read kernel structures from kernel memory. +.SH ENVIRONMENT +.I Lsof +may access these environment variables. +.TP \w'LSOFPERSDCPATH'u+4 +LANG +defines a language locale. +See +.IR setlocale (3) +for the names of other variables that can be used in place +of LANG \- e.g., LC_ALL, LC_TYPE, etc. +.TP +LSOFDEVCACHE +defines the path to a device cache file. +See the +.B "DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE" +section for more information. +.TP +LSOFPERSDCPATH +defines the middle component of a modified personal device cache +file path. +See the +.B "MODIFIED PERSONAL DEVICE CACHE PATH" +section for more information. +.SH FAQ +Frequently-asked questions and their answers (an FAQ) are +available in the +.I 00FAQ +file of the +.I lsof +distribution. +.PP +That file is also available via anonymous ftp from +.I lsof.itap.purdue.edu +at +.IR pub/tools/unix/lsof FAQ . +The URL is: +.IP +ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/FAQ +.SH FILES +.TP \w'.lsof_hostname'u+4 +.I /dev/kmem +kernel virtual memory device +.TP +.I /dev/mem +physical memory device +.TP +.I /dev/swap +system paging device +.TP +.I .lsof_hostname +.I lsof's +device cache file +(The suffix, +.IR hostname , +is the first component of the host's name returned by +.IR gethostname (2) .) +.SH AUTHORS +.I Lsof +was written by Victor A. Abell of Purdue University. +Many others have contributed to +.IR lsof . +They're listed in the +.I 00CREDITS +file of the +.I lsof +distribution. +.SH DISTRIBUTION +The latest distribution of +.I lsof +is available via anonymous ftp from the host +.IR lsof.itap.purdue.edu . +You'll find the +.I lsof +distribution in the +.I pub/tools/unix/lsof +directory. +.PP +You can also use this URL: +.IP +ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof +.PP +.I Lsof +is also mirrored elsewhere. +When you access +.I lsof.itap.purdue.edu +and change to its +.I pub/tools/unix/lsof +directory, you'll be given a list of some mirror sites. +The +.I pub/tools/unix/lsof +directory also contains a more complete list in its +.I mirrors +file. +Use mirrors with caution \- not all mirrors always have the latest +.I lsof +revision. +.PP +Some pre\-compiled +.I Lsof +executables are available on +.IR lsof.itap.purdue.edu , +but their use is discouraged \- it's better that you build +your own from the sources. +If you feel you must use a pre\-compiled executable, please +read the cautions that appear in the README files of the +.I pub/tools/unix/lsof/binaries +subdirectories and in the 00* files of the distribution. +.PP +More information on the +.I lsof +distribution can be found in its +.I README.lsof_ +file. +If you intend to get the +.I lsof +distribution and build it, please read +.I README.lsof_ +and the other 00* files of the distribution before sending questions +to the author. +.SH SEE ALSO +.PP +Not all the following manual pages may exist in every UNIX +dialect to which +.I lsof +has been ported. +.PP +access(2), +awk(1), +crash(1), +fattach(3C), +ff(1), +fstat(8), +fuser(1), +gethostname(2), +isprint(3), +kill(1), +localtime(3), +lstat(2), +modload(8), +mount(8), +netstat(1), +ofiles(8L), +perl(1), +ps(1), +readlink(2), +setlocale(3), +stat(2), +strftime(3), +time(2), +uname(1). -- cgit v1.2.3