2 .TH LSOF 8 Revision-\*(VN
5 lsof \- list open files
45 .BI +|\-r " [t[m<fmt>]]"
67 revision \*(VN lists on its standard output file information about files
68 opened by processes for the following UNIX dialects:
71 Apple Darwin 9 and Mac OS X 10.[567]
72 FreeBSD 8.[234], 9.0, 10.0 and 11.0 for AMD64-based systems
73 Linux 2.1.72 and above for x86-based systems
79 section of this manual page for information on how to obtain the
84 An open file may be a regular file, a directory, a block special file,
85 a character special file, an executing text reference, a library,
86 a stream or a network file (Internet socket, NFS file or UNIX domain socket.)
87 A specific file or all the files in a file system may be selected by path.
89 Instead of a formatted display,
91 will produce output that can be parsed by other programs.
94 option description, and the
95 .B "OUTPUT FOR OTHER PROGRAMS"
96 section for more information.
98 In addition to producing a single output list,
100 will run in repeat mode.
101 In repeat mode it will produce output, delay, then repeat the output
102 operation until stopped with an interrupt or quit signal.
104 .BI +|\-r " [t[m<fmt>]]"
105 option description for more information.
107 In the absence of any options,
109 lists all open files belonging to all active processes.
111 If any list request option is specified, other list requests must be
112 specifically requested \- e.g., if
114 is specified for the listing of UNIX socket files, NFS files won't be
118 or if a user list is specified with the
120 option, UNIX domain socket files, belonging to users not in the list,
121 won't be listed unless the
123 option is also specified.
125 Normally list options that are specifically stated are ORed \- i.e.,
128 option without an address and the \fB\-u\fPfoo option produces a
129 listing of all network files OR files belonging to processes owned
134 the `^' (negated) login name or user ID (UID), specified with the
139 the `^' (negated) process ID (PID), specified with the
144 the `^' (negated) process group ID (PGID), specified with the
149 the `^' (negated) command, specified with the
154 the (`^') negated TCP or UDP protocol state names, specified with the
158 Since they represent exclusions, they are applied without ORing or ANDing
159 and take effect before any other selection criteria are applied.
163 option may be used to AND the selections.
164 For example, specifying
167 and \fB\-u\fPfoo produces a listing of only UNIX socket files that
168 belong to processes owned by user ``foo''.
172 option causes all list selection options to be ANDed; it can't
173 be used to cause ANDing of selected pairs of selection options
174 by placing it between them, even though its placement there is
178 is placed, it causes the ANDing of all selection options.
180 Items of the same selection set \- command names, file descriptors,
181 network addresses, process identifiers, user identifiers, zone names,
182 security contexts \- are joined in a single ORed set and applied
183 before the result participates in ANDing.
184 Thus, for example, specifying \fB\-i\fP@aaa.bbb, \fB\-i\fP@ccc.ddd,
186 and \fB\-u\fPfff,ggg will select the listing of files that belong to
187 either login ``fff'' OR ``ggg'' AND have network connections to either
188 host aaa.bbb OR ccc.ddd.
190 Options may be grouped together following a single prefix -- e.g.,
191 the option set ``\fB\-a \-b \-C\fP'' may be stated as
193 However, since values are optional following
207 when you have no values for them be careful that the
208 following character isn't ambiguous.
215 options, or it might represent the
217 field identifier character following the
220 When ambiguity is possible, start a new option with a `-'
221 character \- e.g., ``\fB\-F \-n\fP''.
222 If the next option is a file name, follow the possibly ambiguous
223 option with ``--'' \- e.g., ``\fB\-F -- \fIname\fR''.
225 Either the `+' or the `\-' prefix may be applied to a group of options.
226 Options that don't take on separate meanings for each
227 prefix \- e.g., \fB\-i\fP \- may be grouped under either prefix.
228 Thus, for example, ``+M -i'' may be stated as ``+Mi'' and the group
229 means the same as the separate options.
230 Be careful of prefix grouping when one or more options in the group
231 does take on separate meanings under different prefixes \-
232 e.g., \fB+|\-M\fP; ``-iM'' is not the same request as ``\-i +M''.
233 When in doubt, use separate options with appropriate prefixes.
236 These two equivalent options select a usage (help) output list.
238 displays a shortened form of this output when it detects an error
239 in the options supplied to it, after it has displayed messages
240 explaining each error.
241 (Escape the `?' character as your shell requires.)
244 causes list selection options to be ANDed, as described above.
247 is available on systems configured for AFS whose AFS
248 kernel code is implemented via dynamic modules.
253 as an alternate name list file where the kernel addresses of the dynamic
254 modules might be found.
257 FAQ (The \fBFAQ\fP section gives its location.)
258 for more information about dynamic modules, their
259 symbols, and how they affect
265 to avoid kernel functions that might block \-
272 .B "BLOCKS AND TIMEOUTS"
274 .B "AVOIDING KERNEL BLOCKS"
275 sections for information on using this option.
278 selects the listing of files for processes executing the
279 command that begins with the characters of
281 Multiple commands may be specified, using multiple
284 They are joined in a single ORed set before participating in
285 AND option selection.
289 begins with a `^', then the following characters specify a command
290 name whose processes are to be ignored (excluded.)
294 begins and ends with a slash ('/'), the characters between the slashes
295 are interpreted as a regular expression.
296 Shell meta\-characters in the regular expression must be quoted to prevent
297 their interpretation by the shell.
298 The closing slash may be followed by these modifiers:
301 b the regular expression is a basic one.
303 i ignore the case of letters.
305 x the regular expression is an extended one
312 FAQ (The \fBFAQ\fP section gives its location.)
313 for more information on basic and extended regular
316 The simple command specification is tested first.
317 If that test fails, the command regular expression is applied.
318 If the simple command test succeeds, the command regular expression
320 This may result in ``no command found for regex:'' messages
326 defines the maximum number of initial characters of the name,
327 supplied by the UNIX dialect, of the UNIX command associated with a process
328 to be printed in the COMMAND column.
333 Note that many UNIX dialects do not supply all command name characters
336 in the files and structures from which
338 obtains command name.
339 Often dialects limit the number of characters supplied in those sources.
340 For example, Linux 2.4.27 and Solaris 9 both limit command name length to
345 is zero ('0'), all command characters supplied to
347 by the UNIX dialect will be printed.
351 is less than the length of the column title, ``COMMAND'', it will
352 be raised to that length.
355 disables the reporting of any path name
356 components from the kernel's name cache.
358 .B "KERNEL NAME CACHE"
359 section for more information.
364 to search for all open instances of directory
366 and the files and directories it contains at its top level.
368 does NOT descend the directory tree, rooted at
372 option may be used to request a full\-descent directory tree search,
378 option does not follow symbolic links within
384 option is also specified.
386 search for open files on file system mount points on subdirectories of
392 option is also specified.
394 Note: the authority of the user of this option limits it to searching for
395 files that the user has permission to examine with the system
400 specifies a list of file descriptors (FDs) to exclude from
401 or include in the output listing.
402 The file descriptors are specified in the comma\-separated set
404 \&\- e.g., ``cwd,1,3'', ``^6,^2''.
405 (There should be no spaces in the set.)
407 The list is an exclusion list if all entries of the set begin with `^'.
408 It is an inclusion list if no entry begins with `^'.
409 Mixed lists are not permitted.
411 A file descriptor number range may be in the set as long as
412 neither member is empty, both members are numbers, and the ending
413 member is larger than the starting one \- e.g., ``0-7'' or ``3-10''.
414 Ranges may be specified for exclusion if they have the `^' prefix \-
415 e.g., ``^0-7'' excludes all file descriptors 0 through 7.
417 Multiple file descriptor numbers are joined in a single ORed set before
418 participating in AND option selection.
420 When there are exclusion and inclusion members in the set,
422 reports them as errors and exits with a non\-zero return code.
424 See the description of File Descriptor (FD) output values in the
426 section for more information on file descriptor names.
431 to search for all open instances of directory
433 and all the files and directories it contains to its complete depth.
437 option does not follow symbolic links within
443 option is also specified.
445 search for open files on file system mount points on subdirectories of
451 option is also specified.
453 Note: the authority of the user of this option limits it to searching for
454 files that the user has permission to examine with the system
460 may process this option slowly and require a large amount of dynamic memory
462 This is because it must descend the entire directory tree, rooted at
466 for each file and directory, building a list of all the files it finds, and
467 searching that list for a match with every open file.
470 is large, these steps can take a long time, so use this option prudently.
475 use of the device cache file.
476 The use of this option is sometimes restricted.
478 .B "DEVICE CACHE FILE"
479 section and the sections that follow it for more information on this
483 must be followed by a function letter; the function letter may optionally
484 be followed by a path name.
486 recognizes these function letters:
489 \fB?\fP \- report device cache file paths
490 \fBb\fP \- build the device cache file
491 \fBi\fP \- ignore the device cache file
492 \fBr\fP \- read the device cache file
493 \fBu\fP \- read and update the device cache file
501 functions, accompanied by a path name, are sometimes restricted.
502 When these functions are restricted, they will not appear in
503 the description of the
505 option that accompanies
511 .B "DEVICE CACHE FILE"
512 section and the sections that follow it for more information on these
513 functions and when they're restricted.
517 function reports the read\-only and write paths that lsof can
518 use for the device cache file,
519 the names of any environment variables whose values
521 will examine when forming the device cache file path,
522 and the format for the personal device cache file path.
523 (Escape the `?' character as your shell requires.)
530 functions may be followed by the device cache file's path.
531 The standard default is
533 in the home directory of the real user ID that executes
535 but this could have been changed when
537 was configured and compiled.
542 options show the current default prefix \- e.g., ``.lsof''.)
545 is the first component of the host's name returned by
546 .IR gethostname (2) .
552 to build a new device cache file at the default or specified path.
558 to ignore the default device cache file and obtain its information
559 about devices via direct calls to the kernel.
565 to read the device cache at the default or specified path, but
566 prevents it from creating a new device cache file when none
567 exists or the existing one is improperly structured.
570 function, when specified without a path name, prevents
572 from updating an incorrect or outdated device cache file,
573 or creating a new one in its place.
576 function is always available when it is specified without a
577 path name argument; it may be restricted by the permissions of the
585 to read the device cache file at the default or specified path,
586 if possible, and to rebuild it, if necessary.
587 This is the default device cache file function when no
589 option has been specified.
592 exempts the file system whose path name is
594 from being subjected to kernel function calls that might block.
602 kernel function calls.
609 kernel function calls.
610 Multiple file systems may be specified with separate
612 specifications and each may have
614 calls exempted or not.
616 This option is currently implemented only for Linux.
619 this option can easily be mis\-applied to other than
620 the file system of interest, because it uses path name rather
621 than the more reliable device and inode numbers.
622 (Device and inode numbers are acquired via the potentially blocking
624 kernel call and are thus not available, but see the
626 option as a possible alternative way to supply device numbers.)
627 \fBUse this option with great care and fully specify the path name of the
628 file system to be exempted.\fP
630 When open files on exempted file systems are reported, it may not be
631 possible to obtain all their information.
632 Therefore, some information columns will be blank, the characters ``UNKN''
633 preface the values in the TYPE column, and the applicable exemption option
634 is added in parentheses to the end of the NAME column.
635 (Some device number information might be made available via the
641 specifies that Linux files should be displayed with endpoint
642 information and the files of the endpoints should also be
645 Endpoint information is displayed in the NAME column in the
646 form ``\fIPID,cmd,FDmode\fP''.
648 is the endpoint process ID;
650 is the endpoint process command;
652 is the endpoint file's descriptor; and
654 is the endpoint file's access mode.
655 Multiple occurrences of this information can appear in a file's
659 specfies that Linux pipe files should only be displayed with endpoint
664 by itself clarifies how path name arguments are to be interpreted.
672 in any combination it specifies
673 that the listing of kernel file structure information is to be enabled
674 (`+') or inhibited (`\-').
676 Normally a path name argument is taken to be a file system name if
677 it matches a mounted\-on directory name reported by
679 or if it represents a block device, named in the
681 output and associated with a mounted directory name.
684 is specified, all path name arguments will be taken to be file
687 will complain if any are not.
688 This can be useful, for example, when the file system name
689 (mounted\-on device) isn't a block device.
690 This happens for some CD-ROM file systems.
694 is specified by itself, all path name arguments will be taken to be
696 Thus, for example, the ``\fB\-f\fP\ -- /'' arguments direct lsof to search
697 for open files with a `/' path name, not all open files in the `/'
700 Be careful to make sure
704 are properly terminated and aren't followed by a character (e.g., of
705 the file or file system name) that might be taken as a parameter.
706 For example, use ``--'' after
710 as in these examples.
713 $ lsof +f -- /file/system/name
714 $ lsof -f -- /file/name
717 The listing of information from kernel file structures, requested with the
719 option form, is normally
720 inhibited, and is not available in whole or part for some dialects \- e.g.,
721 /proc\-based Linux kernels below 2.6.22.
724 is a plus sign (`+'), these characters request file structure information:
727 \fBc\fR file structure use count (not Linux)
728 \fBf\fR file structure address (not Linux)
729 \fBg\fR file flag abbreviations (Linux 2.6.22 and up)
730 \fBG\fR file flags in hexadecimal (Linux 2.6.22 and up)
731 \fBn\fR file structure node address (not Linux)
734 When the prefix is minus (`\-') the same characters disable the
735 listing of the indicated values.
737 File structure addresses, use counts, flags, and node addresses may be
738 used to detect more readily identical files inherited by child
739 processes and identical files in use by different processes.
741 column output can be sorted by output columns holding the values
742 and listed to identify identical file use, or
744 field output can be parsed by an AWK or Perl post\-filter script,
748 specifies a character list,
750 that selects the fields to be output for processing by another program,
751 and the character that terminates each output field.
752 Each field to be output is specified with a single character in
754 The field terminator defaults to NL, but may be changed to NUL (000).
756 .B "OUTPUT FOR OTHER PROGRAMS"
757 section for a description of the field identification characters and
758 the field output process.
760 When the field selection character list is empty, all standard fields are
761 selected (except the raw device field, security context and zone field for
762 compatibility reasons)
763 and the NL field terminator is used.
765 When the field selection character list contains only a zero (`0'),
766 all fields are selected (except the raw device field for compatibility
767 reasons) and the NUL terminator character is used.
769 Other combinations of fields and their associated field terminator
770 character must be set with explicit entries in
773 .B "OUTPUT FOR OTHER PROGRAMS"
776 When a field selection character identifies an item
778 does not normally list \- e.g., PPID, selected with
780 specification of the field character \- e.g., ``\fB\-FR\fP'' \-
781 also selects the listing of the item.
783 When the field selection character list contains the single
786 will display a help list of the field identification characters.
787 (Escape the `?' character as your shell requires.)
790 excludes or selects the listing of files for the processes
791 whose optional process group IDentification (PGID) numbers are in the
794 \&\- e.g., ``123'' or ``123,^456''.
795 (There should be no spaces in the set.)
797 PGID numbers that begin with `^' (negation) represent exclusions.
799 Multiple PGID numbers are joined in a single ORed set before participating
800 in AND option selection.
801 However, PGID exclusions are applied without ORing or ANDing
802 and take effect before other selection criteria are applied.
806 option also enables the output display of PGID numbers.
807 When specified without a PGID set that's all it does.
810 selects the listing of files any of whose Internet address
811 matches the address specified in \fIi\fP.
812 If no address is specified, this option selects the listing of all
813 Internet and x.25 (HP\-UX) network files.
819 is specified with no following address, only files of the indicated
820 IP version, IPv4 or IPv6, are displayed.
821 (An IPv6 specification may be used only if the dialects supports IPv6,
822 as indicated by ``[46]'' and ``IPv[46]'' in
828 Sequentially specifying
832 is the same as specifying
841 is the same as specifying
847 Multiple addresses (up to a limit of 100) may be specified with multiple
850 (A port number or service name range is counted as one address.)
851 They are joined in a single ORed set before participating in
852 AND option selection.
854 An Internet address is specified in the form (Items in square
855 brackets are optional.):
857 [\fI46\fP][\fIprotocol\fP][@\fIhostname\fP\||\|\fIhostaddr\fP][:\fIservice\fP\||\|\fIport\fP]
862 \fI46\fP specifies the IP version, IPv4 or IPv6
864 that applies to the following address.
866 '6' may be be specified only if the UNIX
868 dialect supports IPv6. If neither '4' nor
870 '6' is specified, the following address
872 applies to all IP versions.
874 \fIprotocol\fP is a protocol name \- \fBTCP\fP, \fBUDP\fP
875 .br or \fBUDPLITE\fP.
877 \fIhostname\fP is an Internet host name. Unless a
879 specific IP version is specified, open
881 network files associated with host names
883 of all versions will be selected.
885 \fIhostaddr\fP is a numeric Internet IPv4 address in
887 dot form; or an IPv6 numeric address in
889 colon form, enclosed in brackets, if the
891 UNIX dialect supports IPv6. When an IP
893 version is selected, only its numeric
895 addresses may be specified.
897 \fIservice\fP is an \fI/etc/services\fP name \- e.g., \fBsmtp\fP \-
900 \fIport\fP is a port number, or a list of them.
903 IPv6 options may be used only if the UNIX dialect supports IPv6.
904 To see if the dialect supports IPv6, run
911 If the displayed description of the
913 option contains ``[46]'' and ``IPv[46]'', IPv6 is supported.
915 IPv4 host names and addresses may not be specified if network file selection
916 is limited to IPv6 with
918 IPv6 host names and addresses may not be specified if network file selection
919 is limited to IPv4 with
921 When an open IPv4 network file's address is mapped in an IPv6 address,
922 the open file's type will be IPv6, not IPv4, and its display will be
923 selected by '6', not '4'.
925 At least one address component \-
933 \&\- must be supplied.
934 The `@' character, leading the host specification, is always required;
935 as is the `:', leading the port specification.
947 name list is specified, the
949 may also need to be specified if the TCP, UDP and UDPLITE port numbers for
950 the service name are different.
951 Use any case \- lower or upper \- for
957 numbers may be combined in a list whose entries are separated by commas
958 and whose numeric range entries are separated by minus signs.
959 There may be no embedded spaces, and all service names must belong to
962 Since service names may contain embedded minus signs, the starting entry
963 of a range can't be a service name; it can be a port number, however.
965 Here are some sample addresses:
971 TCP:25 \- TCP and port 25
973 @1.2.3.4 \- Internet IPv4 host address 1.2.3.4
975 @[3ffe:1ebc::1]:1234 \- Internet IPv6 host address
976 3ffe:1ebc::1, port 1234
978 UDP:who \- UDP who service port
980 TCP@lsof.itap:513 \- TCP, port 513 and host name lsof.itap
982 tcp@foo:1-10,smtp,99 \- TCP, ports 1 through 10,
983 service name \fIsmtp\fP, port 99, host name foo
985 tcp@bar:1-smtp \- TCP, ports 1 through \fIsmtp\fP, host bar
987 :time \- either TCP, UDP or UDPLITE time service port
991 selects the listing of tasks (threads) of processes, on dialects
992 where task (thread) reporting is supported.
993 (If help output \- i.e., the output of the
997 options \- shows this option, then task (thread) reporting is
998 supported by the dialect.)
1004 are both specified on Linux, and the tasks of a main process are
1005 selected by other options, the main process will also be listed
1006 as though it were a task, but without a task ID.
1007 (See the description of the TID column in the
1011 Where the FreeBSD version supports threads, all threads will be
1012 listed with their IDs.
1014 In general threads and tasks inherit the files of the caller, but
1015 may close some and open others, so
1017 always reports all the open files of threads and tasks.
1020 specifies a kernel name list file,
1022 in place of /vmunix, /mach, etc.
1024 is not available under AIX on the IBM RISC/System 6000.
1027 inhibits the conversion of user ID numbers to login names.
1028 It is also useful when login name lookup is working improperly or slowly.
1031 enables (`+') or disables (`-') the listing of file link
1032 counts, where they are available \- e.g., they aren't available
1033 for sockets, or most FIFOs and pipes.
1037 is specified without a following number, all link counts will be listed.
1040 is specified (the default), no link counts will be listed.
1044 is followed by a number, only files having a link count less than
1045 that number will be listed.
1046 (No number may follow
1048 A specification of the form ``\fB+L1\fP'' will select open files that
1050 A specification of the form ``\fB+aL1\ \fI<file_system>\fR'' will select
1051 unlinked open files on the specified file system.
1053 For other link count comparisons, use field output (\fB\-F\fP)
1054 and a post\-processing script or program.
1057 specifies an alternate kernel memory file or activates
1058 mount table supplement processing.
1062 specifies a kernel memory file,
1068 \&\- e.g., a crash dump file.
1072 requests that a mount supplement file be written to the standard output
1074 All other options are silently ignored.
1076 There will be a line in the mount supplement file for each mounted file
1077 system, containing the mounted file system directory, followed by a single
1078 space, followed by the device number in hexadecimal "0x" format \- e.g.,
1085 can use the mount supplement file to get device numbers for file systems
1086 when it can't get them via
1095 as a mount supplement file.
1101 options are not available for all supported dialects.
1107 options to see if the
1111 options are available.
1114 Enables (\fB+\fP) or disables (\fB-\fP) the
1115 reporting of portmapper registrations for local TCP, UDP and UDPLITE ports,
1116 where port mapping is supported.
1117 (See the last paragraph of this option description for information about
1118 where portmapper registration reporting is suported.)
1120 The default reporting mode is set by the
1122 builder with the HASPMAPENABLED #define in the dialect's machine.h
1125 is distributed with the HASPMAPENABLED #define deactivated, so
1126 portmapper reporting is disabled by default and must be requested
1134 option will report the default mode.
1135 Disabling portmapper registration when it is already disabled or
1136 enabling it when already enabled is acceptable.
1137 When portmapper registration reporting is enabled,
1139 displays the portmapper registration (if any) for local TCP, UDP or
1141 in square brackets immediately following the port numbers or service
1142 names \- e.g., ``:1234[name]'' or ``:name[100083]''.
1143 The registration information may be a name or number, depending
1144 on what the registering program supplied to the portmapper when
1145 it registered the port.
1147 When portmapper registration reporting is enabled,
1149 may run a little more slowly or even become blocked when access to the
1150 portmapper becomes congested or stopped.
1151 Reverse the reporting mode to determine if portmapper registration
1152 reporting is slowing or blocking
1155 For purposes of portmapper registration reporting
1157 considers a TCP, UDP or UDPLITE port local if: it is found in the local part
1158 of its containing kernel structure;
1159 or if it is located in the foreign part of its containing kernel
1160 structure and the local and foreign Internet addresses are the same;
1161 or if it is located in the foreign part of its containing kernel
1162 structure and the foreign Internet address is INADDR_LOOPBACK (127.0.0.1).
1165 ignore some foreign ports on machines with multiple interfaces
1166 when the foreign Internet address is on a different interface
1171 FAQ (The \fBFAQ\fP section gives its location.)
1172 for further discussion of portmapper registration
1175 Portmapper registration reporting is supported only on dialects that
1176 have RPC header files.
1177 (Some Linux distributions with GlibC 2.14 do not have them.)
1178 When portmapper registration reporting is supported, the
1182 help output will show the
1187 inhibits the conversion of network numbers to
1188 host names for network files.
1189 Inhibiting conversion may make
1192 It is also useful when host name lookup is not working properly.
1195 selects the listing of NFS files.
1200 to display file offset at all times.
1201 It causes the SIZE/OFF output column title to be changed to OFFSET.
1202 Note: on some UNIX dialects
1204 can't obtain accurate or consistent file offset information from its
1205 kernel data sources, sometimes just for particular kinds of files
1206 (e.g., socket files.)
1209 FAQ (The \fBFAQ\fP section gives its location.)
1210 for more information.
1216 options are mutually exclusive; they can't both be specified.
1217 When neither is specified,
1219 displays whatever value \- size or offset \- is appropriate and
1220 available for the type of the file.
1223 defines the number of decimal digits (\fIo\fP) to be
1224 printed after the ``0t'' for a file offset before the form is switched
1228 value of zero (unlimited) directs
1230 to use the ``0t'' form for all offset output.
1232 This option does NOT direct
1234 to display offset at all times; specify
1236 (without a trailing number) to do that.
1238 only specifies the number of digits after ``0t'' in
1239 either mixed size and offset or offset\-only output.
1240 Thus, for example, to direct
1242 to display offset at all times with a decimal digit count of 10, use:
1250 The default number of digits allowed after ``0t'' is normally 8,
1251 but may have been changed by the lsof builder.
1252 Consult the description of the
1254 option in the output of the
1258 option to determine the default that is in effect.
1263 to bypass the strategy it uses to avoid being blocked by some
1264 kernel operations \- i.e., doing them in forked child processes.
1266 .B "BLOCKS AND TIMEOUTS"
1268 .B "AVOIDING KERNEL BLOCKS"
1269 sections for more information on kernel operations that may block
1272 While use of this option will reduce
1274 startup overhead, it may also cause
1276 to hang when the kernel doesn't respond to a function.
1277 Use this option cautiously.
1280 excludes or selects the listing of files for the processes
1281 whose optional process IDentification (PID) numbers are in the
1282 comma\-separated set
1284 \&\- e.g., ``123'' or ``123,^456''.
1285 (There should be no spaces in the set.)
1287 PID numbers that begin with `^' (negation) represent exclusions.
1289 Multiple process ID numbers are joined in a single ORed set before
1290 participating in AND option selection.
1291 However, PID exclusions are applied without ORing or ANDing
1292 and take effect before other selection criteria are applied.
1295 inhibits the conversion of port numbers to port
1296 names for network files.
1297 Inhibiting the conversion may make
1299 run a little faster.
1300 It is also useful when port name lookup is not working properly.
1302 .BI +|\-r " [t[m<fmt>]]"
1308 lists open files as selected by other options, delays
1310 seconds (default fifteen), then repeats the listing, delaying
1311 and listing repetitively until stopped by a condition defined by
1312 the prefix to the option.
1314 If the prefix is a `\-', repeat mode is endless.
1316 must be terminated with an interrupt or quit signal.
1318 If the prefix is `+', repeat mode will end the first cycle no open files
1319 are listed \- and of course when
1321 is stopped with an interrupt or quit signal.
1322 When repeat mode ends because no files are listed, the process exit code
1323 will be zero if any open files were ever listed; one, if none were ever
1327 marks the end of each listing:
1328 if field output is in progress (the
1330 option has been specified), the default marker is `m'; otherwise the
1331 default marker is ``========''.
1332 The marker is followed by a NL character.
1334 The optional "m<fmt>" argument specifies a format for the marker line.
1335 The <fmt> characters following `m' are interpreted as a format
1336 specification to the
1338 function, when both it and the
1340 function are available in the dialect's C library.
1343 documentation for what may appear in its format specification.
1344 Note that when field output is requested with the
1346 option, <fmt> cannot contain the NL format, ``%n''.
1347 Note also that when <fmt> contains spaces or other characters that
1348 affect the shell's interpretation of arguments, <fmt> must be
1349 quoted appropriately.
1353 startup overhead, so it is more efficient to use this mode
1356 repetitively from a shell script, for example.
1358 To use repeat mode most efficiently, accompany
1360 with specification of other
1362 selection options, so the amount of kernel memory access
1364 does will be kept to a minimum.
1365 Options that filter at the process level \- e.g.,
1370 \&\- are the most efficient selectors.
1372 Repeat mode is useful when coupled with field output (see the
1374 option description) and a supervising
1378 script, or a C program.
1381 directs lsof to list the Parent Process IDentification
1382 number in the PPID column.
1388 to display file size at all times.
1389 It causes the SIZE/OFF output column title to be changed to SIZE.
1390 If the file does not have a size, nothing is displayed.
1394 form is available only for selected dialects, and only when the
1398 help output lists it.
1400 When the optional form is available, the
1402 may be followed by a protocol name (\fIp\fR), either TCP or UDP,
1403 a colon (`:') and a comma\-separated protocol state name list,
1404 the option causes open TCP and UDP files to be excluded if their
1405 state name(s) are in the list (\fIs\fP) preceded by a `^'; or
1406 included if their name(s) are not preceded by a `^'.
1408 When an inclusion list is defined, only network files with state
1409 names in the list will be present in the
1412 Thus, specifying one state name means that only network files
1413 with that lone state name will be listed.
1415 Case is unimportant in the protocol or state names, but there may
1416 be no spaces and the colon (`:') separating the protocol
1417 name (\fIp\fP) and the state name list (\fIs\fP) is required.
1419 If only TCP and UDP files are to be listed, as controlled by
1420 the specified exclusions and inclusions, the
1422 option must be specified, too.
1423 If only a single protocol's files are to be listed, add its name
1424 as an argument to the
1428 For example, to list only network files with TCP state LISTEN, use:
1431 \-iTCP \-sTCP:LISTEN
1434 Or, for example, to list network files with all UDP states except
1441 State names vary with UNIX dialects, so it's not possible to
1442 provide a complete list. Some common TCP state names are:
1443 CLOSED, IDLE, BOUND, LISTEN, ESTABLISHED, SYN_SENT, SYN_RCDV,
1444 ESTABLISHED, CLOSE_WAIT, FIN_WAIT1, CLOSING, LAST_ACK, FIN_WAIT_2,
1446 Two common UDP state names are Unbound and Idle.
1450 FAQ (The \fBFAQ\fP section gives its location.)
1451 for more information on how to use protocol state exclusion and
1452 inclusion, including examples.
1456 (without a following decimal digit count) and
1458 option (without a following protocol and state name list)
1459 are mutually exclusive; they can't both be specified.
1460 When neither is specified,
1462 displays whatever value \- size or offset \- is appropriate and
1463 available for the type of file.
1465 Since some types of files don't have true sizes \- sockets, FIFOs,
1466 pipes, etc. \- lsof displays for their sizes the content amounts in
1467 their associated kernel buffers, if possible.
1470 specifies an optional time-out seconds value for kernel functions \-
1475 \- that might otherwise deadlock.
1479 the default, fifteen; when no value is specified, the default is used.
1482 .B "BLOCKS AND TIMEOUTS"
1483 section for more information.
1486 controls the reporting of some TCP/TPI information, also
1489 following the network addresses.
1490 In normal output the information appears in parentheses, each item
1491 except TCP or TPI state name identified by a keyword, followed by `=',
1492 separated from others by a single space:
1495 <TCP or TPI state name>
1496 QR=<read queue length>
1497 QS=<send queue length>
1498 SO=<socket options and values>
1500 TF=<TCP flags and values>
1501 WR=<window read length>
1502 WW=<window write length>
1505 Not all values are reported for all UNIX dialects.
1506 Items values (when available) are reported after the item name and '='.
1508 When the field output mode is in effect (See
1509 .BR "OUTPUT FOR OTHER PROGRAMS" .)
1510 each item appears as a field with a `T' leading character.
1513 with no following key characters disables TCP/TPI information reporting.
1516 with following characters selects the reporting of specific TCP/TPI
1520 \fBf\fP selects reporting of socket options,
1521 states and values, and TCP flags and
1523 \fBq\fP selects queue length reporting.
1524 \fBs\fP selects connection state reporting.
1525 \fBw\fP selects window size reporting.
1528 Not all selections are enabled for some UNIX dialects.
1529 State may be selected for all dialects and is reported by default.
1536 option will show what selections may be used with the UNIX dialect.
1540 is used to select information \- i.e., it is followed by one or more
1541 selection characters \- the displaying of state is disabled by default,
1542 and it must be explicitly selected again in the characters following
1544 (In effect, then, the default is equivalent to
1546 For example, if queue lengths and state are desired, use
1549 Socket options, socket states, some socket values, TCP flags and
1550 one TCP value may be reported (when available in the UNIX dialect)
1551 in the form of the names that commonly appear after SO_, so_, SS_,
1552 TCP_ and TF_ in the dialect's header files \-
1553 most often <sys/socket.h>, <sys/socketvar.h> and <netinet/tcp_var.h>.
1554 Consult those header files for the meaning of the flags, options,
1557 ``SO='' precedes socket options and values; ``SS='', socket states;
1558 and ``TF='', TCP flags and values.
1560 If a flag or option has a value, the value will follow an '=' and
1561 the name -- e.g., ``SO=LINGER=5'', ``SO=QLIM=5'', ``TF=MSS=512''.
1562 The following seven values may be reported:
1566 Reported Description (Common Symbol)
1568 KEEPALIVE keep alive time (SO_KEEPALIVE)
1569 LINGER linger time (SO_LINGER)
1570 MSS maximum segment size (TCP_MAXSEG)
1571 PQLEN partial listen queue connections
1572 QLEN established listen queue connections
1573 QLIM established listen queue limit
1574 RCVBUF receive buffer length (SO_RCVBUF)
1575 SNDBUF send buffer length (SO_SNDBUF)
1578 Details on what socket options and values, socket states, and TCP flags
1579 and values may be displayed for particular UNIX dialects may be found in
1580 the answer to the ``Why doesn't lsof report socket options, socket states,
1581 and TCP flags and values for my dialect?'' and ``Why doesn't lsof report
1582 the partial listen queue connection count for my dialect?''
1585 FAQ (The \fBFAQ\fP section gives its location.)
1590 should produce terse output with process identifiers only and no header \-
1591 e.g., so that the output may be piped to
1599 selects the listing of files for the user whose login names
1600 or user ID numbers are in the comma\-separated set
1604 (There should be no spaces in the set.)
1606 Multiple login names or user ID numbers are joined in a single ORed set
1607 before participating in AND option selection.
1609 If a login name or user ID is preceded by a `^', it becomes a negation \-
1610 i.e., files of processes owned by the login name or user ID will never
1612 A negated login name or user ID selection is neither ANDed nor ORed
1613 with other selections; it is applied before all other selections and
1614 absolutely excludes the listing of the files of the process.
1615 For example, to direct
1617 to exclude the listing of files belonging to root processes,
1618 specify ``\-u^root'' or ``\-u^0''.
1621 selects the listing of UNIX domain socket files.
1624 selects the listing of
1626 version information, including: revision number;
1629 binary was constructed;
1630 who constructed the binary and where;
1631 the name of the compiler used to construct the
1633 the version number of the compiler when readily available;
1634 the compiler and loader flags used to construct the
1637 and system information, typically the output of
1645 to indicate the items it was asked to list and failed to find \- command
1646 names, file names, Internet addresses or files, login names, NFS files,
1647 PIDs, PGIDs, and UIDs.
1649 When other options are ANDed to search options, or compile\-time
1650 options restrict the listing of some files,
1652 may not report that it failed to find a search item when an ANDed
1653 option or compile\-time option prevents the listing of the open file
1654 containing the located search item.
1656 For example, ``lsof -V -iTCP@foobar -a -d 999'' may not report a
1657 failure to locate open files at ``TCP@foobar'' and may not list
1658 any, if none have a file descriptor number of 999.
1659 A similar situation arises when HASSECURITY and HASNOSOCKSECURITY are
1660 defined at compile time and they prevent the listing of open files.
1663 Enables (\fB+\fP) or disables (\fB-\fP) the suppression of warning messages.
1667 builder may choose to have warning messages disabled or enabled by
1669 The default warning message state is indicated in the output of the
1674 Disabling warning messages when they are already disabled or enabling
1675 them when already enabled is acceptable.
1688 options to direct their processing to cross over symbolic
1689 links and|or file system mount points encountered when
1690 scanning the directory (\fB+d\fP) or directory tree (\fB+D\fP).
1694 is specified by itself without a following parameter, cross\-over
1695 processing of both symbolic links and file system mount points is
1699 is specified without a parameter, the next argument must begin with '-'
1702 The optional 'f' parameter enables file system mount point cross\-over
1703 processing; 'l', symbolic link cross\-over processing.
1707 option may not be supplied without also supplying a
1714 This is a dialect\-specific option.
1718 This IBM AIX RISC/System 6000 option requests the reporting
1719 of executed text file and shared library references.
1722 because this option uses the kernel readx() function, its use on
1723 a busy AIX system might cause an application process to hang so
1724 completely that it can neither be killed nor stopped.
1725 I have never seen this happen or had a report of its happening,
1726 but I think there is a remote possibility it could happen.
1728 By default use of readx() is disabled.
1731 may need setuid\-root permission to perform the actions this
1736 builder may specify that the
1738 option be restricted to processes whose real UID is root.
1739 If that has been done, the
1741 option will not appear in the
1745 help output unless the real UID of the
1750 distribution allows any UID to specify
1752 so by default it will appear in the help output.
1754 When AIX readx() use
1757 may not be able to report information for all text and loader file
1758 references, but it may also avoid exacerbating an AIX
1759 kernel directory search kernel error, known as the Stale Segment
1762 The readx() function, used by
1764 or any other program to access some sections of kernel virtual
1765 memory, can trigger the Stale Segment ID bug.
1766 It can cause the kernel's dir_search() function to believe erroneously
1767 that part of an in\-memory copy of a file system directory has been
1769 Another application process, distinct from
1771 asking the kernel to search the directory \- e.g., by using
1773 can cause dir_search() to loop forever, thus hanging the application process.
1777 FAQ (The \fBFAQ\fP section gives its location.)
1782 distribution for a more complete description of the Stale Segment ID bug,
1783 its APAR, and methods for defining readx() use when compiling
1788 This Linux option requests that
1790 skip the reporting of information on all open TCP, UDP and UDPLITE IPv4
1793 This Linux option is most useful when the system has an extremely
1794 large number of open TCP, UDP and UDPLITE files, the processing of whose
1801 a long time, and whose reporting is not of interest.
1803 Use this option with care and only when you are sure that the
1804 information you want
1806 to display isn't associated with open TCP, UDP or UDPLITE socket files.
1808 \ \ \ \ Solaris 10 and above:
1810 This Solaris 10 and above option requests the reporting of cached
1811 paths for files that have been deleted \- i.e., removed with
1816 The cached path is followed by the string ``\ (deleted)'' to indicate
1817 that the path by which the file was opened has been deleted.
1819 Because intervening changes made to the path \- i.e., renames with
1823 \- are not recorded in the cached path, what
1825 reports is only the path by which the file was opened, not its
1826 possibly different final path.
1829 specifies how Solaris 10 and higher zone information is to be handled.
1831 Without a following argument \- e.g., NO
1833 the option specifies that zone names are to be listed in the ZONE
1838 option may be followed by a zone name,
1840 That causes lsof to list only open files for processes in that zone.
1843 option and argument pairs may be specified to form a list of named zones.
1844 Any open file of any process in any of the zones will be listed, subject
1845 to other conditions specified by other options and arguments.
1848 specifies how SELinux security contexts are to be handled.
1849 It and 'Z' field output character support are inhibited
1850 when SELinux is disabled in the running Linux kernel.
1852 .B "OUTPUT FOR OTHER PROGRAMS"
1853 for more information on the 'Z' field output character.
1855 Without a following argument \- e.g., NO
1857 the option specifies that security contexts are to be listed in the
1858 SECURITY\-CONTEXT output column.
1862 option may be followed by a wildcard security context name,
1864 That causes lsof to list only open files for processes in that security
1868 option and argument pairs may be specified to form a list of security
1870 Any open file of any process in any of the security contexts will be listed,
1871 subject to other conditions specified by other options and arguments.
1874 can be A:B:C or *:B:C or A:B:* or *:*:C to match against the A:B:C context.
1877 The double minus sign option is a marker that signals the end of
1879 It may be used, for example, when the first file name begins with
1881 It may also be used when the absence of a value for the last keyed
1882 option must be signified by the presence of a minus sign in the following
1883 option and before the start of the file names.
1886 These are path names of specific files to list.
1887 Symbolic links are resolved before use.
1888 The first name may be separated from the preceding options with
1893 is the mounted\-on directory of a file system or the device of the
1896 will list all the files open on the file system.
1897 To be considered a file system, the
1899 must match a mounted\-on directory name in
1901 output, or match the name of a block device associated with a mounted\-on
1905 option may be used to force
1909 a file system identifier (\fB+f\fP) or a simple file (\fB\-f\fP).
1913 is a path to a directory that is not the mounted\-on directory name of
1914 a file system, it is treated just as a regular file is treated \- i.e.,
1915 its listing is restricted to processes that have it open as a file or
1916 as a process\-specific directory, such as the root or current working
1920 look for open files inside a directory name, use the
1928 is the base name of a family of multiplexed files \- e. g, AIX's
1929 .IR /dev/pt[cs] " \-"
1931 will list all the associated multiplexed files on the device that
1939 is a UNIX domain socket name,
1941 will usually search for it by the characters of the name alone \- exactly as
1942 it is specified and is recorded in the kernel socket structure.
1943 (See the next paragraph for an exception to that rule for Linux.)
1944 Specifying a relative path \- e.g.,
1946 \&\- in place of the
1947 file's absolute path \- e.g.,
1949 \&\- won't work because
1951 must match the characters you specify with what it finds in the
1952 kernel UNIX domain socket structures.
1956 is a Linux UNIX domain socket name, in one case
1958 is able to search for it by its device and inode number, allowing
1960 to be a relative path.
1961 The case requires that the absolute path -- i.e., one beginning with a
1962 slash ('/') be used by the process that created the socket, and hence be
1965 file; and it requires that
1967 be able to obtain the device and node numbers of both the absolute path in
1974 When those conditions are met,
1976 will be able to search for the UNIX domain socket when some path to it is
1979 Thus, for example, if the path is
1983 search is initiated when the working directory is
1992 is none of the above,
1994 will list any open files whose device and inode match that of the
1998 If you have also specified the
2003 you may safely specify are file systems for which your mount table
2004 supplies alternate device numbers.
2006 .B "AVOIDING KERNEL BLOCKS"
2008 .B "ALTERNATE DEVICE NUMBERS"
2009 sections for more information.
2011 Multiple file names are joined in a single ORed set before
2012 participating in AND option selection.
2015 supports the recognition of AFS files for these dialects (and AFS
2019 AIX 4.1.4 (AFS 3.4a)
2020 HP\-UX 9.0.5 (AFS 3.4a)
2021 Linux 1.2.13 (AFS 3.3)
2022 Solaris 2.[56] (AFS 3.4a)
2025 It may recognize AFS files on other versions of these dialects,
2026 but has not been tested there.
2027 Depending on how AFS is implemented,
2029 may recognize AFS files in other dialects, or may have difficulties
2030 recognizing AFS files in the supported dialects.
2033 may have trouble identifying all aspects of AFS files in
2034 supported dialects when AFS kernel support is implemented via
2035 dynamic modules whose addresses do not appear in the kernel's
2039 may have to guess at the identity of AFS files, and might not be able to
2040 obtain volume information from the kernel that is needed for calculating
2041 AFS volume node numbers.
2044 can't compute volume node numbers, it reports blank in the NODE column.
2048 option is available in some dialect implementations of
2050 for specifying the name list file where dynamic module kernel
2051 addresses may be found.
2052 When this option is available, it will be listed in the
2054 help output, presented in response to the
2061 FAQ (The \fBFAQ\fP section gives its location.)
2062 for more information about dynamic modules, their
2063 symbols, and how they affect
2067 Because AFS path lookups don't seem to participate in the
2068 kernel's name cache operations,
2070 can't identify path name components for AFS files.
2073 has three features that may cause security concerns.
2074 First, its default compilation mode allows anyone to list all
2076 Second, by default it creates a user\-readable and user\-writable device
2077 cache file in the home directory of the real user ID that executes
2079 (The list\-all\-open\-files and device cache features may be disabled when
2086 options name alternate kernel name list or memory files.
2088 Restricting the listing of all open files is controlled by the
2089 compile\-time HASSECURITY and HASNOSOCKSECURITY options.
2090 When HASSECURITY is defined,
2092 will allow only the root user to list all open files.
2093 The non\-root user may list only open files of processes with the same user
2094 IDentification number as the real user ID number of the
2096 process (the one that its user logged on with).
2098 However, if HASSECURITY and HASNOSOCKSECURITY are both defined,
2099 anyone may list open socket files, provided they are selected
2104 When HASSECURITY is not defined, anyone may list all open files.
2106 Help output, presented in response to the
2110 option, gives the status of the HASSECURITY and HASNOSOCKSECURITY definitions.
2118 distribution for information on building
2120 with the HASSECURITY and HASNOSOCKSECURITY options enabled.
2122 Creation and use of a user\-readable and user\-writable device
2123 cache file is controlled by the compile\-time HASDCACHE option.
2125 .B "DEVICE CACHE FILE"
2126 section and the sections that follow it for details on how its path
2128 For security considerations it is important to note that in the default
2130 distribution, if the real user ID under which
2132 is executed is root, the device cache file will be written in root's
2133 home directory \- e.g.,
2137 When HASDCACHE is not defined,
2139 does not write or attempt to read a device cache file.
2141 When HASDCACHE is defined, the
2143 help output, presented in response to the
2148 options, will provide device cache file handling information.
2149 When HASDCACHE is not defined, the
2157 Before you decide to disable the device cache file feature \- enabling
2158 it improves the performance of
2160 by reducing the startup overhead of examining all the nodes in
2164 \&\- read the discussion of it in the
2168 distribution and the
2170 FAQ (The \fBFAQ\fP section gives its location.)
2172 WHEN IN DOUBT, YOU CAN TEMPORARILY DISABLE THE USE OF THE DEVICE CACHE FILE
2179 user declares alternate kernel name list or memory files with the
2185 checks the user's authority to read them with
2187 This is intended to prevent whatever special power
2189 modes might confer on it from letting it read files not normally
2190 accessible via the authority of the real user ID.
2192 This section describes the information
2194 lists for each open file.
2196 .B "OUTPUT FOR OTHER PROGRAMS"
2197 section for additional information on output that can be processed
2201 only outputs printable (declared so by
2204 Non\-printable characters are printed in one of three forms:
2205 the C ``\\[bfrnt]'' form;
2206 the control character `^' form (e.g., ``^@'');
2207 or hexadecimal leading ``\\x'' form (e.g., ``\\xab'').
2208 Space is non\-printable in the COMMAND column (``\\x20'')
2209 and printable elsewhere.
2211 For some dialects \- if HASSETLOCALE is defined in the dialect's
2212 machine.h header file \-
2214 will print the extended 8 bit characters of a language locale.
2217 process must be supplied a language locale environment variable
2218 (e.g., LANG) whose value represents a known language locale
2219 in which the extended characters are considered printable by
2223 considers the extended characters non\-printable and prints them according
2224 to its rules for non\-printable characters, stated above.
2225 Consult your dialect's
2227 man page for the names of other environment variables that may
2228 be used in place of LANG \- e.g., LC_ALL, LC_CTYPE, etc.
2231 language locale support for a dialect also covers wide characters \- e.g.,
2232 UTF-8 \- when HASSETLOCALE and HASWIDECHAR are defined in the dialect's
2233 machine.h header file, and when a suitable language locale has been defined
2234 in the appropriate environment variable for the
2237 Wide characters are printable under those conditions if
2240 If HASSETLOCALE, HASWIDECHAR and a suitable language locale aren't defined,
2243 reports wide characters that aren't printable,
2245 considers the wide characters non\-printable and prints each of their
2246 8 bits according to its rules for non\-printable characters, stated above.
2248 Consult the answers to the "Language locale support" questions in the
2249 lsof FAQ (The \fBFAQ\fP section gives its location.) for more information.
2252 dynamically sizes the output columns each time it runs, guaranteeing
2253 that each column is a minimum size.
2254 It also guarantees that each column is separated from its predecessor
2255 by at least one space.
2258 contains the first nine characters of the name of the UNIX command
2259 associated with the process.
2262 value is specified to the
2264 option, the column contains the first
2266 characters of the name of the UNIX command associated with the process
2267 up to the limit of characters supplied to
2269 by the UNIX dialect.
2270 (See the description of the
2274 FAQ for more information.
2275 The \fBFAQ\fP section gives its location.)
2279 is less than the length of the column title, ``COMMAND'', it will
2280 be raised to that length.
2284 value is specified to the
2286 option, the column contains all the characters of the name of the UNIX command
2287 associated with the process.
2289 All command name characters maintained by the kernel in its structures
2290 are displayed in field output when the command name descriptor (`c')
2293 .B "OUTPUT FOR OTHER COMMANDS"
2294 section for information on selecting field output and the associated
2295 command name descriptor.
2298 is the Process IDentification number of the process.
2301 is the task (thread) IDentification number, if task (thread)
2302 reporting is supported by the dialect and a task (thread) is
2304 (If help output \- i.e., the output of the
2308 options \- shows this option, then task (thread) reporting is
2309 supported by the dialect.)
2311 A blank TID column in Linux indicates a process \- i.e., a non\-task.
2314 is the Solaris 10 and higher zone name.
2315 This column must be selected with the
2320 is the SELinux security context.
2321 This column must be selected with the
2326 option is inhibited when SELinux is disabled in the running Linux
2330 is the Parent Process IDentification number of the process.
2331 It is only displayed when the
2333 option has been specified.
2336 is the process group IDentification number associated with
2338 It is only displayed when the
2340 option has been specified.
2343 is the user ID number or login name of the user to whom
2344 the process belongs, usually the same as reported by
2346 However, on Linux USER is the user ID number or login that owns
2347 the directory in /proc where
2349 finds information about the process.
2350 Usually that is the same value reported by
2352 but may differ when the process has changed its effective user ID.
2355 option description for information on when a user ID number or
2356 login name is displayed.)
2359 is the File Descriptor number of the file or:
2362 \fBcwd\fP current working directory;
2364 \fBL\fInn\fR library references (AIX);
2366 \fBerr\fR FD information error (see NAME column);
2368 \fBjld\fR jail directory (FreeBSD);
2370 \fBltx\fP shared library text (code and data);
2372 \fBMxx\fP hex memory\-mapped type number xx.
2374 \fBm86\fP DOS Merge mapped file;
2376 \fBmem\fP memory\-mapped file;
2378 \fBmmap\fP memory\-mapped device;
2380 \fBpd\fP parent directory;
2382 \fBrtd\fP root directory;
2384 \fBtr\fR kernel trace file (OpenBSD);
2386 \fBtxt\fP program text (code and data);
2388 \fBv86\fP VP/ix mapped file;
2391 FD is followed by one of these characters, describing the mode under which
2394 \fBr\fP for read access;
2396 \fBw\fP for write access;
2398 \fBu\fP for read and write access;
2400 space if mode unknown and no lock
2404 `\-' if mode unknown and lock
2408 The mode character is followed by one of these lock characters, describing
2409 the type of lock applied to the file:
2411 \fBN\fP for a Solaris NFS lock of unknown type;
2413 \fBr\fP for read lock on part of the file;
2415 \fBR\fP for a read lock on the entire file;
2417 \fBw\fP for a write lock on part of the file;
2419 \fBW\fP for a write lock on the entire file;
2421 \fBu\fP for a read and write lock of any length;
2423 \fBU\fP for a lock of unknown type;
2425 \fBx\fP for an SCO OpenServer Xenix lock on part
2428 \fBX\fP for an SCO OpenServer Xenix lock on the
2431 space if there is no lock.
2435 section for more information on the lock information character.
2437 The FD column contents constitutes a single field for parsing in
2438 post\-processing scripts.
2441 is the type of the node associated with the file \- e.g., GDIR, GREG,
2444 or ``IPv4'' for an IPv4 socket;
2446 or ``IPv6'' for an open IPv6 network file \- even if its address is
2447 IPv4, mapped in an IPv6 address;
2449 or ``ax25'' for a Linux AX.25 socket;
2451 or ``inet'' for an Internet domain socket;
2453 or ``lla'' for a HP\-UX link level access file;
2455 or ``rte'' for an AF_ROUTE socket;
2457 or ``sock'' for a socket of unknown domain;
2459 or ``unix'' for a UNIX domain socket;
2461 or ``x.25'' for an HP\-UX x.25 socket;
2463 or ``BLK'' for a block special file;
2465 or ``CHR'' for a character special file;
2467 or ``DEL'' for a Linux map file that has been deleted;
2469 or ``DIR'' for a directory;
2471 or ``DOOR'' for a VDOOR file;
2473 or ``FIFO'' for a FIFO special file;
2475 or ``KQUEUE'' for a BSD style kernel event queue file;
2477 or ``LINK'' for a symbolic link file;
2479 or ``MPB'' for a multiplexed block file;
2481 or ``MPC'' for a multiplexed character file;
2483 or ``NOFD'' for a Linux /proc/<PID>/fd directory that can't be opened \--
2484 the directory path appears in the NAME column, followed by an error
2503 or ``PCUR'' for the current
2509 current working directory;
2517 executable type (\fIetype\fP);
2525 file descriptor directory;
2527 or ``PFIL'' for an executable
2541 group notifier file;
2543 or ``PIPE'' for pipes;
2591 map file (\fImap\fP);
2599 process notifier file;
2609 or ``POLP'' for an old format
2611 light weight process file;
2613 or ``POPF'' for an old format
2617 or ``POPG'' for an old format
2621 or ``PORT'' for a SYSV named pipe;
2647 or ``PSXSEM'' for a POSIX semaphore file;
2649 or ``PSXSHM'' for a POSIX shared memory file;
2663 or ``REG'' for a regular file;
2665 or ``SMT'' for a shared memory transport file;
2667 or ``STSO'' for a stream socket;
2669 or ``UNNM'' for an unnamed type file;
2671 or ``XNAM'' for an OpenServer Xenix special file of unknown type;
2673 or ``XSEM'' for an OpenServer Xenix semaphore file;
2675 or ``XSD'' for an OpenServer Xenix shared data file;
2677 or the four type number octets if the corresponding name isn't known.
2680 contains the kernel file structure address when
2682 has been specified to
2686 contains the file reference count from the kernel file structure when
2688 has been specified to
2696 has been specified to
2698 this field contains the contents of the f_flag[s] member of the kernel
2699 file structure and the kernel's per\-process open file flags (if available);
2700 \&`G' causes them to be displayed in hexadecimal;
2701 \&`g', as short\-hand names;
2702 two lists may be displayed with entries separated by commas, the
2703 lists separated by a semicolon (`;');
2704 the first list may contain short\-hand names for f_flag[s] values from
2705 the following table:
2708 AIO asynchronous I/O (e.g., FAIO)
2710 ASYN asynchronous I/O (e.g., FASYNC)
2711 BAS block, test, and set in use
2712 BKIU block if in use
2713 BL use block offsets
2726 DSYN data\-only integrity
2727 DTY must be a directory
2731 FSYN synchronous writes
2732 GCDF defer during unp_gc() (AIX)
2733 GCMK mark during unp_gc() (AIX)
2734 GTTY accessed via /dev/tty
2737 KIOC kernel\-issued ioctl
2740 MBLK stream message block
2743 MSYN multiplex synchronization
2744 NATM don't update atime
2745 NB non\-blocking I/O
2747 NBIO SYSV non\-blocking I/O
2748 NBF n\-buffering in effect
2751 NDSY no data synchronization
2753 NFLK don't follow links
2755 NOTO disable background stop
2757 NTTY no controlling TTY
2759 PAIO POSIX asynchronous I/O
2762 RC file and record locking cache
2765 RSYN read synchronization
2766 RW read and write access
2768 SNAP cooked snapshot
2770 SQSH Sequent shared set on open
2771 SQSV Sequent SVM set on open
2772 SQR Sequent set repair on open
2773 SQS1 Sequent full shared open
2774 SQS2 Sequent partial shared open
2776 SWR synchronous read
2777 SYN file integrity while writing
2778 TCPM avoid TCP collision
2781 WKUP parallel I/O synchronization
2782 WTG parallel I/O synchronization
2788 this list of names was derived from F* #define's in dialect header files
2789 <fcntl.h>, <linux</fs.h>, <sys/fcntl.c>, <sys/fcntlcom.h>, and <sys/file.h>;
2790 see the lsof.h header file for a list showing the correspondence
2791 between the above short\-hand names and the header file definitions;
2793 the second list (after the semicolon) may contain short\-hand names
2794 for kernel per\-process open file flags from this table:
2798 BR the file has been read
2799 BHUP activity stopped by SIGHUP
2800 BW the file has been written
2802 CX close\-on-exec (see fcntl(F_SETFD))
2803 LCK lock was applied
2805 OPIP open pending \- in progress
2807 SHMT UF_FSHMAT set (AIX)
2808 USE in use (multi\-threaded)
2812 (or INODE\-ADDR for some dialects)
2813 contains a unique identifier for the file node (usually the kernel
2814 vnode or inode address, but also occasionally a concatenation of
2815 device and node number) when
2817 has been specified to
2821 contains the device numbers, separated by commas, for a character special,
2822 block special, regular, directory or NFS file;
2824 or ``memory'' for a memory file system node under Tru64 UNIX;
2826 or the address of the private data area of a Solaris socket
2829 or a kernel reference address that identifies the file
2830 (The kernel reference address may be used for FIFO's, for example.);
2833 the base address or device name of a Linux AX.25 socket device.
2835 Usually only the lower thirty two bits of Tru64 UNIX kernel addresses
2838 SIZE, SIZE/OFF, or OFFSET
2839 is the size of the file or the file offset in bytes.
2840 A value is displayed in this column only if it is available.
2842 displays whatever value \- size or offset \- is appropriate for the type
2843 of the file and the version of
2846 On some UNIX dialects
2848 can't obtain accurate or consistent file offset information from its
2849 kernel data sources, sometimes just for particular kinds of files
2850 (e.g., socket files.)
2851 In other cases, files don't have true sizes \- e.g., sockets, FIFOs,
2854 displays for their sizes the content amounts it finds in their kernel
2855 buffer descriptors (e.g., socket buffer size counts or TCP/IP window
2859 FAQ (The \fBFAQ\fP section gives its location.)
2860 for more information.
2862 The file size is displayed in decimal;
2863 the offset is normally displayed in decimal with a leading ``0t'' if
2864 it contains 8 digits or less; in hexadecimal with a leading ``0x'' if
2865 it is longer than 8 digits.
2868 option description for information on when 8 might default to
2871 Thus the leading ``0t'' and ``0x'' identify an offset when the column
2872 may contain both a size and an offset (i.e., its title is SIZE/OFF).
2876 option is specified,
2878 always displays the file offset (or nothing if no offset is available)
2879 and labels the column OFFSET.
2880 The offset always begins with ``0t'' or ``0x'' as described above.
2884 user can control the switch from ``0t'' to ``0x'' with the
2887 Consult its description for more information.
2891 option is specified,
2893 always displays the file size (or nothing if no size is available)
2894 and labels the column SIZE.
2899 options are mutually exclusive; they can't both be specified.
2901 For files that don't have a fixed size \- e.g., don't reside
2904 will display appropriate information about the current size or
2905 position of the file if it is available in the kernel structures
2906 that define the file.
2909 contains the file link count when
2914 is the node number of a local file;
2916 or the inode number of an NFS file in the server host;
2918 or the Internet protocol type \- e. g, ``TCP'';
2920 or ``STR'' for a stream;
2922 or ``CCITT'' for an HP\-UX x.25 socket;
2924 or the IRQ or inode number of a Linux AX.25 socket device.
2927 is the name of the mount point and file system on which the file resides;
2929 or the name of a file specified in the
2931 option (after any symbolic links have been resolved);
2933 or the name of a character special or block special device;
2935 or the local and remote Internet addresses of a network file;
2936 the local host name or IP number is followed by a colon (':'), the
2937 port, ``->'', and the two\-part remote address;
2938 IP addresses may be reported as numbers or names, depending on the
2944 colon\-separated IPv6 numbers are enclosed in square brackets;
2945 IPv4 INADDR_ANY and IPv6 IN6_IS_ADDR_UNSPECIFIED addresses, and
2946 zero port numbers are represented by an asterisk ('*');
2947 a UDP destination address may be followed by the amount of time
2948 elapsed since the last packet was sent to the destination;
2949 TCP, UDP and UDPLITE remote addresses may be followed by TCP/TPI
2950 information in parentheses \- state (e.g., ``(ESTABLISHED)'', ``(Unbound)''),
2951 queue sizes, and window sizes (not all dialects) \- in a fashion
2957 option description or the description of the TCP/TPI field in
2958 .B "OUTPUT FOR OTHER PROGRAMS"
2959 for more information on state, queue size, and window size;
2961 or the address or name of a UNIX domain socket, possibly including
2962 a stream clone device name, a file system object's path name, local
2963 and foreign kernel addresses, socket pair information, and a bound
2966 or the local and remote mount point names of an NFS file;
2968 or ``STR'', followed by the stream name;
2970 or a stream character device name, followed by ``->'' and the stream name
2971 or a list of stream module names, separated by ``->'';
2973 or ``STR:'' followed by the SCO OpenServer stream device and module
2974 names, separated by ``->'';
2976 or system directory name, `` -- '', and as many components of the path
2979 can find in the kernel's name cache for selected dialects
2981 .B "KERNEL NAME CACHE"
2982 section for more information.);
2984 or ``PIPE->'', followed by a Solaris kernel pipe destination address;
2986 or ``COMMON:'', followed by the vnode device information structure's
2987 device name, for a Solaris common vnode;
2989 or the address family, followed by a slash (`/'), followed by fourteen
2990 comma\-separated bytes of a non\-Internet raw socket address;
2992 or the HP\-UX x.25 local address, followed by the virtual connection
2993 number (if any), followed by the remote address (if any);
2995 or ``(dead)'' for disassociated Tru64 UNIX files \- typically terminal files
2996 that have been flagged with the TIOCNOTTY ioctl and closed by daemons;
2998 or ``rd=<offset>'' and ``wr=<offset>'' for the values of the
2999 read and write offsets of a FIFO;
3001 or ``clone \fIn\fP:/dev/event'' for SCO OpenServer file clones of the
3005 is the minor device number of the file;
3007 or ``(socketpair: n)'' for a Solaris 2.6, 8, 9 or 10
3008 UNIX domain socket, created by the
3012 or ``no PCB'' for socket files that do not have a protocol block
3013 associated with them, optionally followed by ``, CANTSENDMORE'' if
3014 sending on the socket has been disabled, or ``, CANTRCVMORE'' if
3015 receiving on the socket has been disabled (e.g., by the
3019 or the local and remote addresses of a Linux IPX socket file
3020 in the form <net>:[<node>:]<port>, followed in parentheses
3021 by the transmit and receive queue sizes, and the connection state;
3023 or ``dgram'' or ``stream'' for the type UnixWare 7.1.1 and above in\-kernel
3024 UNIX domain sockets, followed by a colon (':') and the local path name
3025 when available, followed by ``->'' and the remote path name or kernel
3026 socket address in hexadecimal when available;
3028 or the association value, association index, endpoint value, local address,
3029 local port, remote address and remote port for Linux SCTP sockets;
3031 or ``protocol: '' followed by the Linux socket's protocol attribute.
3033 For dialects that support a ``namefs'' file system, allowing one
3034 file to be attached to another with
3037 will add ``(FA:<address1><direction><address2>)'' to the NAME column.
3038 <address1> and <address2> are hexadecimal vnode addresses.
3039 <direction> will be ``<-'' if <address2> has been fattach'ed to
3040 this vnode whose address is <address1>;
3041 and ``->'' if <address1>, the vnode address of this vnode, has been
3042 fattach'ed to <address2>.
3043 <address1> may be omitted if it already appears in the DEVICE column.
3047 may add two parenthetical notes to the NAME column for open Solaris 10 files:
3050 considers the path name of questionable accuracy;
3051 and ``(deleted)'' if the
3053 option has been specified and
3055 detects the open file's path name has been deleted.
3058 FAQ (The \fBFAQ\fP section gives its location.)
3059 for more information on these NAME column additions.
3062 can't adequately report the wide variety of UNIX dialect file locks
3063 in a single character.
3064 What it reports in a single character is a compromise between the
3065 information it finds in the kernel and the limitations of the reporting
3068 Moreover, when a process holds several byte level locks on a file,
3070 only reports the status of the first lock it encounters.
3071 If it is a byte level lock, then the lock character will be reported
3072 in lower case \- i.e., `r', `w', or `x' \- rather than the upper case
3073 equivalent reported for a full file lock.
3077 can only report on locks held by local processes on local files.
3078 When a local process sets a lock on a remotely mounted (e.g., NFS)
3079 file, the remote server host usually records the lock state.
3080 One exception is Solaris \- at some patch levels of 2.3, and in all
3081 versions above 2.4, the Solaris kernel records information on remote
3082 locks in local structures.
3085 has trouble reporting locks for some UNIX dialects.
3088 section of this manual page or the
3090 FAQ (The \fBFAQ\fP section gives its location.)
3091 for more information.
3092 .SH "OUTPUT FOR OTHER PROGRAMS"
3095 option is specified,
3097 produces output that is suitable for processing by another program \- e.g, an
3101 script, or a C program.
3103 Each unit of information is output in a field that is identified
3104 with a leading character and terminated by a NL (012) (or a NUL
3105 (000) if the 0 (zero) field identifier character is specified.)
3106 The data of the field follows immediately after the field identification
3107 character and extends to the field terminator.
3109 It is possible to think of field output as process and file sets.
3110 A process set begins with a field whose identifier is `p' (for
3111 process IDentifier (PID)).
3112 It extends to the beginning of the next PID field or the beginning
3113 of the first file set of the process, whichever comes first.
3114 Included in the process set are fields that identify the command,
3115 the process group IDentification (PGID) number, the task (thread)
3116 ID (TID), and the user ID (UID) number or login name.
3118 A file set begins with a field whose identifier is `f' (for
3120 It is followed by lines that describe the file's access mode,
3121 lock state, type, device, size, offset, inode, protocol, name
3122 and stream module names.
3123 It extends to the beginning of the next file or process set,
3124 whichever comes first.
3126 When the NUL (000) field terminator has been selected with the
3127 0 (zero) field identifier character,
3129 ends each process and file set with a NL (012) character.
3132 always produces one field, the PID (`p') field.
3133 All other fields may be declared optionally in the field identifier
3134 character list that follows the
3137 When a field selection character identifies an item
3139 does not normally list \- e.g., PPID, selected with
3141 specification of the field character \- e.g., ``\fB\-FR\fP'' \-
3142 also selects the listing of the item.
3144 It is entirely possible to select a set of fields that cannot
3145 easily be parsed \- e.g., if the field descriptor field is not
3146 selected, it may be difficult to identify file sets.
3147 To help you avoid this difficulty,
3151 option; it selects the output of all fields with NL terminators
3154 option pair selects the output of all fields with NUL terminators).
3155 For compatibility reasons neither
3159 select the raw device field.
3161 These are the fields that
3164 The single character listed first is the field identifier.
3168 c process command name (all characters from proc or
3170 C file structure share count
3171 d file's device character code
3172 D file's major/minor device number (0x<hexadecimal>)
3173 f file descriptor (always selected)
3174 F file structure address (0x<hexadecimal>)
3175 G file flaGs (0x<hexadecimal>; names if \fB+fg\fP follows)
3177 i file's inode number
3180 l file's lock status
3181 L process login name
3182 m marker between repeated output
3183 n file name, comment, Internet address
3184 N node identifier (ox<hexadecimal>
3185 o file's offset (decimal)
3186 p process ID (always selected)
3188 r raw device number (0x<hexadecimal>)
3190 s file's size (decimal)
3191 S file's stream identification
3193 T TCP/TPI information, identified by prefixes (the
3194 `=' is part of the prefix):
3195 QR=<read queue size>
3196 QS=<send queue size>
3197 SO=<socket options and values> (not all dialects)
3198 SS=<socket states> (not all dialects)
3199 ST=<connection state>
3200 TF=<TCP flags and values> (not all dialects)
3201 WR=<window read size> (not all dialects)
3202 WW=<window write size> (not all dialects)
3203 (TCP/TPI information isn't reported for all supported
3204 UNIX dialects. The \fB\-h\fP or \fB\-?\fP help output for the
3205 \fB\-T\fP option will show what TCP/TPI reporting can be
3208 z Solaris 10 and higher zone name
3209 Z SELinux security context (inhibited when SELinux is disabled)
3210 0 use NUL field terminator character in place of NL
3211 1\-9 dialect\-specific field identifiers (The output
3212 of \fB\-F?\fP identifies the information to be found
3213 in dialect\-specific fields.)
3216 You can get on\-line help information on these characters and their
3217 descriptions by specifying the
3220 (Escape the `?' character as your shell requires.)
3221 Additional information on field content can be found in the
3225 As an example, ``\fB\-F pcfn\fP'' will select the process ID (`p'),
3226 command name (`c'), file descriptor (`f') and file name (`n')
3227 fields with an NL field terminator character; ``\fB\-F pcfn0\fP''
3228 selects the same output with a NUL (000) field terminator character.
3231 doesn't produce all fields for every process or file set, only
3232 those that are available.
3233 Some fields are mutually exclusive: file device characters and
3234 file major/minor device numbers; file inode number and protocol
3235 name; file name and stream identification; file size and offset.
3236 One or the other member of these mutually exclusive sets will appear
3237 in field output, but not both.
3241 ends each field with a NL (012) character.
3243 0 (zero) field identifier character may be specified to change the
3244 field terminator character
3246 A NUL terminator may be easier to process with
3248 for example, or with programs whose quoting mechanisms may not
3249 easily cope with the range of characters in the field output.
3250 When the NUL field terminator is in use,
3252 ends each process and file set with a NL (012).
3254 Three aids to producing programs that can process
3256 field output are included in the
3259 The first is a C header file,
3261 that contains symbols for the field identification characters, indexes for
3262 storing them in a table, and explanation strings that may be compiled into
3265 uses this header file.
3267 The second aid is a set of sample scripts that process field output,
3274 They're located in the
3280 The third aid is the C library used for the
3283 The test suite is written in C and uses field output to validate
3284 the correct operation of
3286 The library can be found in the
3291 The library uses the first aid, the
3294 .SH "BLOCKS AND TIMEOUTS"
3296 can be blocked by some kernel functions that it uses \-
3301 These functions are stalled in the kernel, for example, when the
3302 hosts where mounted NFS file systems reside become inaccessible.
3305 attempts to break these blocks with timers and child processes,
3306 but the techniques are not wholly reliable.
3309 does manage to break a block, it will report the break with an error
3311 The messages may be suppressed with the
3317 The default timeout value may be displayed with the
3321 option, and it may be changed with the
3326 is two seconds, but you should avoid small values, since slow system
3327 responsiveness can cause short timeouts to expire unexpectedly and
3330 before it can produce any output.
3334 has to break a block during its access of mounted file system
3335 information, it normally continues, although with less information
3336 available to display about open files.
3339 can also be directed to avoid the protection of timers and child processes
3340 when using the kernel functions that might block by specifying the
3343 While this will allow
3345 to start up with less overhead, it exposes
3347 completely to the kernel situations that might block it.
3348 Use this option cautiously.
3349 .SH "AVOIDING KERNEL BLOCKS"
3355 to avoid using kernel functions that would block.
3356 Some cautions apply.
3358 First, using this option usually requires that your system supply
3359 alternate device numbers in place of the device numbers that
3361 would normally obtain with the
3367 .B "ALTERNATE DEVICE NUMBERS"
3368 section for more information on alternate device numbers.
3370 Second, you can't specify
3374 to locate unless they're file system names.
3377 needs to know the device and inode numbers of files listed with
3385 from obtaining them.
3388 only has device numbers for the file systems that have alternates,
3389 its ability to locate files on file systems depends completely on the
3390 availability and accuracy of the alternates.
3391 If no alternates are available, or if they're incorrect,
3393 won't be able to locate files on the named file systems.
3395 Third, if the names of your file system directories that
3397 obtains from your system's mount table are symbolic links,
3399 won't be able to resolve the links.
3406 function it uses to resolve symbolic links.
3412 to issue warning messages when it needs to use the kernel functions
3415 option directs it to avoid.
3416 You can suppress these messages by specifying the
3418 option, but if you do, you won't see the alternate device numbers
3419 reported in the warning messages.
3420 .SH "ALTERNATE DEVICE NUMBERS"
3422 On some dialects, when
3424 has to break a block because it can't get information about a
3425 mounted file system via the
3429 kernel functions, or because you specified the
3433 can obtain some of the information it needs \- the device number and
3434 possibly the file system type \- from the system mount table.
3435 When that is possible,
3437 will report the device number it obtained.
3438 (You can suppress the report by specifying the
3442 You can assist this process if your mount table is supported with an
3446 file that contains an options field by adding a ``dev=xxxx'' field for
3447 mount points that do not have one in their options strings.
3448 Note: you must be able to edit the file \- i.e., some mount tables
3449 like recent Solaris /etc/mnttab or Linux /proc/mounts are read\-only
3450 and can't be modified.
3452 You may also be able to supply device numbers using the
3456 options, provided they are supported by your dialect.
3462 options to see if the
3466 options are available.
3468 The ``xxxx'' portion of the field is the hexadecimal value
3469 of the file system's device number.
3472 field of the output of the
3476 functions for the appropriate values for your file systems.)
3477 Here's an example from a Sun Solaris 2.6
3479 for a file system remotely mounted via NFS:
3482 nfs ignore,noquota,dev=2a40001
3485 There's an advantage to having ``dev=xxxx'' entries in your mount
3486 table file, especially for file systems that are mounted from remote
3488 When a remote server crashes and you want to identify its users by running
3490 on one of its clients,
3492 probably won't be able to get output from the
3496 functions for the file system.
3497 If it can obtain the file system's device number from the mount table,
3498 it will be able to display the files open on the crashed NFS server.
3500 Some dialects that do not use an ASCII
3504 file for the mount table may still provide an alternative device number
3505 in their internal mount tables.
3506 This includes AIX, Apple Darwin, FreeBSD, NetBSD, OpenBSD, and Tru64 UNIX.
3508 knows how to obtain the alternative device number for these dialects
3509 and uses it when its attempt to
3513 the file system is blocked.
3515 If you're not sure your dialect supplies alternate device numbers
3516 for file systems from its mount table, use this
3518 incantation to see if it reports any alternate device numbers:
3523 Look for standard error file warning messages that
3524 begin ``assuming "dev=xxxx" from ...''.
3525 .SH "KERNEL NAME CACHE"
3528 is able to examine the kernel's name cache or use other kernel
3529 facilities (e.g., the ADVFS 4.x tag_to_path() function under
3530 Tru64 UNIX) on some dialects for most file system types,
3531 excluding AFS, and extract recently used path name components from it.
3532 (AFS file system path lookups don't use the kernel's name cache; some
3533 Solaris VxFS file system operations apparently don't use it, either.)
3536 reports the complete paths it finds in the NAME column.
3539 can't report all components in a path, it reports in the NAME column
3540 the file system name, followed by a space, two `-' characters, another
3541 space, and the name components it has located, separated by
3546 is run in repeat mode \- i.e., with the
3548 option specified \- the extent to which it can report path name
3549 components for the same file may vary from cycle to cycle.
3550 That's because other running processes can cause the kernel to
3551 remove entries from its name cache and replace them with others.
3554 use of the kernel name cache to identify the paths of files
3555 can lead it to report incorrect components under some circumstances.
3556 This can happen when the kernel name cache uses device and node
3557 number as a key (e.g., SCO OpenServer) and a key on a rapidly
3558 changing file system is reused.
3559 If the UNIX dialect's kernel doesn't purge the name cache entry for
3560 a file when it is unlinked,
3562 may find a reference to the wrong entry in the cache.
3565 FAQ (The \fBFAQ\fP section gives its location.)
3566 has more information on this situation.
3569 can report path name components for these dialects:
3580 SCO|Caldera UnixWare
3586 can't report path name components for these dialects:
3592 If you want to know why
3594 can't report path name components for some dialects, see the
3596 FAQ (The \fBFAQ\fP section gives its location.)
3597 .SH "DEVICE CACHE FILE"
3599 Examining all members of the
3605 functions can be time consuming.
3606 What's more, the information that
3608 needs \- device number, inode number, and path \- rarely changes.
3612 normally maintains an ASCII text file of cached
3616 information (exception: the /proc\-based Linux
3618 where it's not needed.)
3619 The local system administrator who builds
3621 can control the way the device cache file path is formed, selecting
3625 Path from the \fB\-D\fP option;
3626 Path from an environment variable;
3628 Personal path (the default);
3629 Personal path, modified by an environment variable.
3632 Consult the output of the
3637 help options for the current state of device cache support.
3638 The help output lists the default read\-mode device cache file path that
3639 is in effect for the current invocation of
3643 option output lists the read\-only and write device cache file paths,
3644 the names of any applicable environment variables, and the personal
3645 device cache path format.
3648 can detect that the current device cache file has been accidentally
3649 or maliciously modified by integrity checks, including the computation
3650 and verification of a sixteen bit Cyclic Redundancy Check (CRC) sum on
3651 the file's contents.
3654 senses something wrong with the file, it issues a warning and attempts
3655 to remove the current cache file and create a new copy, but only to
3656 a path that the process can legitimately write.
3658 The path from which a
3660 process may attempt to read a device cache file may not be the same
3661 as the path to which it can legitimately write.
3664 senses that it needs to update the device cache file, it may
3665 choose a different path for writing it from the path from which
3666 it read an incorrect or outdated version.
3670 option will inhibit the writing of a new device cache file.
3671 (It's always available when specified without a path name argument.)
3673 When a new device is added to the system, the device cache file may
3674 need to be recreated.
3677 compares the mtime of the device cache file with the mtime and ctime
3682 directory, it usually detects that a new device has been added;
3685 issues a warning message and attempts to rebuild the device cache file.
3689 writes a device cache file, it sets its ownership to the real UID
3690 of the executing process, and its permission modes to 0600, this
3691 restricting its reading and writing to the file's owner.
3692 .SH "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
3694 Two permissions of the
3696 executable affect its ability to access device cache files.
3697 The permissions are set by the local system administrator when
3701 The first and rarer permission is setuid\-root.
3702 It comes into effect when
3704 is executed; its effective UID is then
3705 root, while its real (i.e., that of the logged\-on user) UID is not.
3708 distribution recommends that versions for these dialects run setuid\-root.
3711 HP-UX 11.11 and 11.23
3715 The second and more common permission is setgid.
3716 It comes into effect when the effective group IDentification number (GID)
3719 process is set to one that can access kernel memory devices \-
3720 e.g., ``kmem'', ``sys'', or ``system''.
3724 process that has setgid permission usually surrenders the permission
3725 after it has accessed the kernel memory devices.
3728 can allow more liberal device cache path formations.
3731 distribution recommends that versions for these dialects run setgid
3732 and be allowed to surrender setgid permission.
3735 AIX 5.[12] and 5.3-ML1
3736 Apple Darwin 7.x Power Macintosh systems
3737 FreeBSD 4.x, 4.1x, 5.x and [6789].x for x86-based systems
3738 FreeBSD 5.x and [6789].x for Alpha, AMD64 and Sparc64-based
3741 NetBSD 1.[456], 2.x and 3.x for Alpha, x86, and SPARC-based
3743 NEXTSTEP 3.[13] for NEXTSTEP architectures
3744 OpenBSD 2.[89] and 3.[0\-9] for x86-based systems
3746 SCO OpenServer Release 5.0.6 for x86-based systems
3747 SCO|Caldera UnixWare 7.1.4 for x86-based systems
3748 Solaris 2.6, 8, 9 and 10
3754 for AIX 5L and above needs setuid\-root permission if its
3759 for these dialects does not support a device cache, so the permissions
3760 given to the executable don't apply to the device cache file.
3765 .SH "DEVICE CACHE FILE PATH FROM THE \-D OPTION"
3769 option provides limited means for specifying the device cache file path.
3772 function will report the read\-only and write device cache file paths that
3782 functions are available, you can use them to request that the cache file be
3783 built in a specific location (\fBb\fR[\fIpath\fR]);
3784 read but not rebuilt (\fBr\fR[\fIpath\fR]);
3785 or read and rebuilt (\fBu\fR[\fIpath\fR]).
3791 functions are restricted under some conditions.
3792 They are restricted when the
3794 process is setuid\-root.
3795 The path specified with the
3797 function is always read\-only, even
3798 when it is available.
3805 functions are also restricted when the
3807 process runs setgid and
3809 doesn't surrender the setgid permission.
3811 .B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
3812 section for a list of implementations that normally don't surrender
3813 their setgid permission.)
3819 (for ignore), is always available.
3825 to read device information from the kernel with the
3827 function and build a device cache file at the indicated path.
3833 to read the device cache file, but not update it.
3834 When a path argument accompanies
3836 it names the device cache file path.
3839 function is always available when it is specified without a
3843 is not running setuid\-root and surrenders its setgid permission,
3844 a path name argument may accompany the
3852 to attempt to read and use the device cache file.
3853 If it can't read the file, or if it finds the contents of the
3854 file incorrect or outdated, it will read information from the kernel,
3855 and attempt to write an updated version of the device cache file,
3856 but only to a path it considers legitimate for the
3858 process effective and real UIDs.
3859 .SH "DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE"
3862 second choice for the device cache file is the contents of the
3863 LSOFDEVCACHE environment variable.
3864 It avoids this choice if the
3866 process is setuid\-root, or the real UID of the process is root.
3868 A further restriction applies to a device cache file path taken from
3869 the LSOFDEVCACHE environment variable:
3871 will not write a device cache file to the path if the
3873 process doesn't surrender its setgid permission.
3875 .B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
3876 section for information on implementations that don't surrender
3877 their setgid permission.)
3879 The local system administrator can disable the use of the LSOFDEVCACHE
3880 environment variable or change its name when building
3882 Consult the output of
3884 for the environment variable's name.
3885 .SH "SYSTEM-WIDE DEVICE CACHE PATH"
3887 The local system administrator may choose to have a system\-wide
3888 device cache file when building
3890 That file will generally be constructed by a special system administration
3891 procedure when the system is booted or when the contents of
3898 third device cache file path choice.
3900 You can tell that a system\-wide device cache file is in effect
3901 for your local installation by examining the
3903 help option output \- i.e., the output from the
3910 will never write to the system\-wide device cache file path by
3912 It must be explicitly named with a
3914 function in a root\-owned procedure.
3915 Once the file has been written, the procedure must change its permission
3916 modes to 0644 (owner\-read and owner\-write, group\-read, and other\-read).
3917 .SH "PERSONAL DEVICE CACHE PATH (DEFAULT)"
3919 The default device cache file path of the
3921 distribution is one recorded in the home directory of the real UID
3924 Added to the home directory is a second path component of the form
3925 .IR .lsof_hostname .
3929 fourth device cache file path choice, and is
3930 usually the default.
3931 If a system\-wide device cache file path was defined when
3934 this fourth choice will be applied when
3936 can't find the system\-wide device cache file.
3941 uses two paths when reading the device cache file.
3945 part of the second component is the base
3946 name of the executing host, as returned by
3947 .IR gethostname (2).
3948 The base name is defined to be the characters preceding the first `.'
3953 output if it contains no `.'.
3955 The device cache file belongs to the user ID and is readable and
3956 writable by the user ID alone \- i.e., its modes are 0600.
3957 Each distinct real user ID on a given host that executes
3959 has a distinct device cache file.
3962 part of the path distinguishes device cache files in an NFS\-mounted
3963 home directory into which device cache files are written from
3964 several different hosts.
3966 The personal device cache file path formed by this method represents
3967 a device cache file that
3969 will attempt to read, and will attempt to write should it not
3970 exist or should its contents be incorrect or outdated.
3974 option without a path name argument will inhibit the writing of a new
3979 option will list the format specification for constructing the
3980 personal device cache file.
3981 The conversions used in the format specification are described in the
3986 .SH "MODIFIED PERSONAL DEVICE CACHE PATH"
3988 If this option is defined by the local system administrator when
3990 is built, the LSOFPERSDCPATH environment variable contents may
3991 be used to add a component of the personal device cache file path.
3993 The LSOFPERSDCPATH variable contents are inserted in the path at the
3994 place marked by the local system administrator with the ``%p''
3995 conversion in the HASPERSDC format specification of the dialect's
3998 (It's placed right after the home directory in the default
4002 Thus, for example, if LSOFPERSDCPATH contains ``LSOF'', the home
4003 directory is ``/Homes/abe'', the host name is ``lsof.itap.purdue.edu'',
4004 and the HASPERSDC format is the default (``%h/%p.lsof_%L''), the
4005 modified personal device cache file path is:
4008 /Homes/abe/LSOF/.lsof_vic
4011 The LSOFPERSDCPATH environment variable is ignored when the
4013 process is setuid\-root or when the real UID of the process is root.
4016 will not write to a modified personal device cache file path if the
4018 process doesn't surrender setgid permission.
4020 .B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
4021 section for a list of implementations that normally don't surrender
4022 their setgid permission.)
4024 If, for example, you want to create a sub\-directory of personal
4025 device cache file paths by using the LSOFPERSDCPATH environment
4026 variable to name it, and
4028 doesn't surrender its setgid permission, you will have to allow
4030 to create device cache files at the standard personal path and
4031 move them to your subdirectory with shell commands.
4033 The local system administrator may: disable this option when
4035 is built; change the name of the environment variable from
4036 LSOFPERSDCPATH to something else; change the HASPERSDC
4037 format to include the personal path component in another place;
4038 or exclude the personal path component entirely.
4039 Consult the output of the
4041 option for the environment variable's name and the HASPERSDC
4042 format specification.
4044 Errors are identified with messages on the standard error file.
4047 returns a one (1) if any error was detected, including the failure to
4048 locate command names, file names, Internet addresses or files, login
4049 names, NFS files, PIDs, PGIDs, or UIDs it was asked to list.
4052 option is specified,
4054 will indicate the search items it failed to list.
4056 It returns a zero (0) if no errors were detected and if it was able to
4057 list some information about all the specified search arguments.
4062 cannot open access to
4066 or one of its subdirectories, or get information on a file in them with
4068 it issues a warning message and continues.
4071 will issue warning messages about inaccessible files in
4075 is indicated in its help output \- requested with the
4079 options \- with the message:
4082 Inaccessible /dev warnings are enabled.
4085 The warning message may be suppressed with the
4088 It may also have been suppressed by the system administrator when
4090 was compiled by the setting of the WARNDEVACCESS definition.
4091 In this case, the output from the help options will include the message:
4094 Inaccessible /dev warnings are disabled.
4097 Inaccessible device warning messages usually disappear after
4099 has created a working device cache file.
4101 For a more extensive set of examples, documented more fully, see the
4107 To list all open files, use:
4111 To list all open Internet, x.25 (HP\-UX), and UNIX domain files, use:
4115 To list all open IPv4 network files in use by the process whose PID is
4118 lsof -i 4 -a -p 1234
4120 Presuming the UNIX dialect supports IPv6, to list only open IPv6
4125 To list all files using any protocol on ports 513, 514, or 515 of host
4126 wonderland.cc.purdue.edu, use:
4128 lsof -i @wonderland.cc.purdue.edu:513-515
4130 To list all files using any protocol on any port of mace.cc.purdue.edu
4131 (cc.purdue.edu is the default domain), use:
4135 To list all open files for login name ``abe'', or user ID 1234, or
4136 process 456, or process 123, or process 789, use:
4138 lsof -p 456,123,789 -u 1234,abe
4140 To list all open files on device /dev/hd4, use:
4144 To find the process that has /u/abe/foo open, use:
4148 To send a SIGHUP to the processes that have /u/abe/bar open, use:
4150 kill -HUP `lsof -t /u/abe/bar`
4152 To find any open file, including an open UNIX domain socket file,
4159 To find processes with open files on the NFS file system named
4161 whose server is inaccessible, and presuming your mount table supplies
4162 the device number for
4163 .IR /nfs/mount/point ,
4166 lsof -b /nfs/mount/point
4168 To do the preceding search with warning messages suppressed, use:
4170 lsof -bw /nfs/mount/point
4172 To ignore the device cache file, use:
4176 To obtain PID and command name field output for each process, file
4177 descriptor, file device number, and file inode number for each file
4178 of each process, use:
4182 To list the files at descriptors 1 and 3 of every process running the
4184 command for login ID ``abe'' every 10 seconds, use:
4186 lsof -c lsof -a -d 1 -d 3 -u abe -r10
4188 To list the current working directory of processes running a command that
4189 is exactly four characters long and has an 'o' or 'O' in character three,
4190 use this regular expression form of the
4194 lsof -c /^..o.$/i -a -d cwd
4196 To find an IP version 4 socket file by its associated numeric dot\-form
4199 lsof -i@128.210.15.17
4201 To find an IP version 6 socket file (when the UNIX dialect supports
4202 IPv6) by its associated numeric colon\-form address, use:
4204 lsof -i@[0:1:2:3:4:5:6:7]
4206 To find an IP version 6 socket file (when the UNIX dialect supports
4207 IPv6) by an associated numeric colon\-form address that has a run of
4208 zeroes in it \- e.g., the loop\-back address \- use:
4212 To obtain a repeat mode marker line that contains the current time, use:
4216 To add spaces to the previous marker line, use:
4218 lsof -r "m==== %T ===="
4222 reads kernel memory in its search for open files, rapid changes in kernel
4223 memory may produce unpredictable results.
4225 When a file has multiple record locks, the lock status character
4226 (following the file descriptor) is derived from a test of the first
4227 lock structure, not from any combination of the individual record
4228 locks that might be described by multiple lock structures.
4231 can't search for files with restrictive access permissions by
4233 unless it is installed with root set\-UID permission.
4234 Otherwise it is limited to searching for files to which its user
4235 or its set-GID group (if any) has access permission.
4237 The display of the destination address of a raw socket (e.g., for
4239 depends on the UNIX operating system.
4240 Some dialects store the destination address in the raw socket's protocol
4241 control block, some do not.
4244 can't always represent Solaris device numbers in the same way that
4247 For example, the major and minor device numbers that the
4251 functions report for the directory on which CD-ROM files are mounted
4254 are not the same as the ones that it reports for the device on which
4255 CD-ROM files are mounted (typically
4257 (\fILsof\fP reports the directory numbers.)
4261 file systems is available only for BSD and Tru64 UNIX dialects, Linux, and
4262 dialects derived from SYSV R4 \- e.g., FreeBSD, NetBSD, OpenBSD, Solaris,
4267 file items \- device number, inode number, and file size \-
4268 are unavailable in some dialects.
4269 Searching for files in a
4271 file system may require that the full path name be specified.
4273 No text (\fBtxt\fP) file descriptors are displayed for Linux
4275 All entries for files other than the current working directory,
4276 the root directory, and numerical file descriptors are labeled
4281 can't search for Tru64 UNIX named pipes by name, because their kernel
4282 implementation of lstat(2) returns an improper device number for a
4286 can't report fully or correctly on HP\-UX 9.01, 10.20, and 11.00 locks
4287 because of insufficient access to kernel data or errors in the
4291 FAQ (The \fBFAQ\fP section gives its location.)
4294 The AIX SMT file type is a fabrication.
4295 It's made up for file structures whose type (15) isn't defined in the AIX
4296 .I /usr/include/sys/file.h
4298 One way to create such file structures is to run X clients with the DISPLAY
4299 variable set to ``:0.0''.
4303 option is not supported under /proc\-based Linux
4305 because it doesn't read kernel structures from kernel memory.
4308 may access these environment variables.
4309 .TP \w'LSOFPERSDCPATH'u+4
4311 defines a language locale.
4314 for the names of other variables that can be used in place
4315 of LANG \- e.g., LC_ALL, LC_TYPE, etc.
4318 defines the path to a device cache file.
4320 .B "DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE"
4321 section for more information.
4324 defines the middle component of a modified personal device cache
4327 .B "MODIFIED PERSONAL DEVICE CACHE PATH"
4328 section for more information.
4330 Frequently-asked questions and their answers (an FAQ) are
4337 That file is also available via anonymous ftp from
4338 .I lsof.itap.purdue.edu
4340 .IR pub/tools/unix/lsof FAQ .
4343 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/FAQ
4345 .TP \w'.lsof_hostname'u+4
4347 kernel virtual memory device
4350 physical memory device
4353 system paging device
4360 is the first component of the host's name returned by
4361 .IR gethostname (2) .)
4364 was written by Victor A. Abell <abe@purdue.edu> of Purdue University.
4365 Many others have contributed to
4367 They're listed in the
4373 The latest distribution of
4375 is available via anonymous ftp from the host
4376 .IR lsof.itap.purdue.edu .
4380 .I pub/tools/unix/lsof
4383 You can also use this URL:
4385 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof
4388 is also mirrored elsewhere.
4390 .I lsof.itap.purdue.edu
4392 .I pub/tools/unix/lsof
4393 directory, you'll be given a list of some mirror sites.
4395 .I pub/tools/unix/lsof
4396 directory also contains a more complete list in its
4399 Use mirrors with caution \- not all mirrors always have the latest
4405 executables are available on
4406 .IR lsof.itap.purdue.edu ,
4407 but their use is discouraged \- it's better that you build
4408 your own from the sources.
4409 If you feel you must use a pre\-compiled executable, please
4410 read the cautions that appear in the README files of the
4411 .I pub/tools/unix/lsof/binaries
4412 subdirectories and in the 00* files of the distribution.
4414 More information on the
4416 distribution can be found in its
4417 .I README.lsof_<version>
4419 If you intend to get the
4421 distribution and build it, please read
4422 .I README.lsof_<version>
4423 and the other 00* files of the distribution before sending questions
4427 Not all the following manual pages may exist in every UNIX
projects / platform / upstream / lsof.git / blob