2 .TH LSOF 8 Revision-\*(VN
3 \" Register )P is used neither by this file nor any groff macro. However,
4 \" some versions of nroff require it.
9 lsof \- list open files
51 .BI +|\-r " [t[m<fmt>]]"
73 revision \*(VN lists on its standard output file information about files
74 opened by processes for the following UNIX dialects:
77 Apple Darwin 9 and Mac OS X 10.[567]
78 FreeBSD 8.[234], 9.0 and 1[012].0 for AMD64-based systems
79 Linux 2.1.72 and above for x86-based systems
85 section of this manual page for information on how to obtain the
90 An open file may be a regular file, a directory, a block special file,
91 a character special file, an executing text reference, a library,
92 a stream or a network file (Internet socket, NFS file or UNIX domain socket.)
93 A specific file or all the files in a file system may be selected by path.
95 Instead of a formatted display,
97 will produce output that can be parsed by other programs.
100 option description, and the
101 .B "OUTPUT FOR OTHER PROGRAMS"
102 section for more information.
104 In addition to producing a single output list,
106 will run in repeat mode.
107 In repeat mode it will produce output, delay, then repeat the output
108 operation until stopped with an interrupt or quit signal.
110 .BI +|\-r " [t[m<fmt>]]"
111 option description for more information.
113 In the absence of any options,
115 lists all open files belonging to all active processes.
117 If any list request option is specified, other list requests must be
118 specifically requested \- e.g., if
120 is specified for the listing of UNIX socket files, NFS files won't be
124 or if a user list is specified with the
126 option, UNIX domain socket files, belonging to users not in the list,
127 won't be listed unless the
129 option is also specified.
131 Normally list options that are specifically stated are ORed \- i.e.,
134 option without an address and the \fB\-u\fPfoo option produces a
135 listing of all network files OR files belonging to processes owned
140 the `^' (negated) login name or user ID (UID), specified with the
145 the `^' (negated) process ID (PID), specified with the
150 the `^' (negated) process group ID (PGID), specified with the
155 the `^' (negated) command, specified with the
160 the (`^') negated TCP or UDP protocol state names, specified with the
164 Since they represent exclusions, they are applied without ORing or ANDing
165 and take effect before any other selection criteria are applied.
169 option may be used to AND the selections.
170 For example, specifying
173 and \fB\-u\fPfoo produces a listing of only UNIX socket files that
174 belong to processes owned by user ``foo''.
178 option causes all list selection options to be ANDed; it can't
179 be used to cause ANDing of selected pairs of selection options
180 by placing it between them, even though its placement there is
184 is placed, it causes the ANDing of all selection options.
186 Items of the same selection set \- command names, file descriptors,
187 network addresses, process identifiers, user identifiers, zone names,
188 security contexts \- are joined in a single ORed set and applied
189 before the result participates in ANDing.
190 Thus, for example, specifying \fB\-i\fP@aaa.bbb, \fB\-i\fP@ccc.ddd,
192 and \fB\-u\fPfff,ggg will select the listing of files that belong to
193 either login ``fff'' OR ``ggg'' AND have network connections to either
194 host aaa.bbb OR ccc.ddd.
196 Options may be grouped together following a single prefix -- e.g.,
197 the option set ``\fB\-a \-b \-C\fP'' may be stated as
199 However, since values are optional following
213 when you have no values for them be careful that the
214 following character isn't ambiguous.
221 options, or it might represent the
223 field identifier character following the
226 When ambiguity is possible, start a new option with a `-'
227 character \- e.g., ``\fB\-F \-n\fP''.
228 If the next option is a file name, follow the possibly ambiguous
229 option with ``--'' \- e.g., ``\fB\-F -- \fIname\fR''.
231 Either the `+' or the `\-' prefix may be applied to a group of options.
232 Options that don't take on separate meanings for each
233 prefix \- e.g., \fB\-i\fP \- may be grouped under either prefix.
234 Thus, for example, ``+M -i'' may be stated as ``+Mi'' and the group
235 means the same as the separate options.
236 Be careful of prefix grouping when one or more options in the group
237 does take on separate meanings under different prefixes \-
238 e.g., \fB+|\-M\fP; ``-iM'' is not the same request as ``\-i +M''.
239 When in doubt, use separate options with appropriate prefixes.
242 These two equivalent options select a usage (help) output list.
244 displays a shortened form of this output when it detects an error
245 in the options supplied to it, after it has displayed messages
246 explaining each error.
247 (Escape the `?' character as your shell requires.)
250 causes list selection options to be ANDed, as described above.
253 is available on systems configured for AFS whose AFS
254 kernel code is implemented via dynamic modules.
259 as an alternate name list file where the kernel addresses of the dynamic
260 modules might be found.
263 FAQ (The \fBFAQ\fP section gives its location.)
264 for more information about dynamic modules, their
265 symbols, and how they affect
271 to avoid kernel functions that might block \-
278 .B "BLOCKS AND TIMEOUTS"
280 .B "AVOIDING KERNEL BLOCKS"
281 sections for information on using this option.
284 selects the listing of files for processes executing the
285 command that begins with the characters of
287 Multiple commands may be specified, using multiple
290 They are joined in a single ORed set before participating in
291 AND option selection.
295 begins with a `^', then the following characters specify a command
296 name whose processes are to be ignored (excluded.)
300 begins and ends with a slash ('/'), the characters between the slashes
301 are interpreted as a regular expression.
302 Shell meta\-characters in the regular expression must be quoted to prevent
303 their interpretation by the shell.
304 The closing slash may be followed by these modifiers:
307 b the regular expression is a basic one.
309 i ignore the case of letters.
311 x the regular expression is an extended one
318 FAQ (The \fBFAQ\fP section gives its location.)
319 for more information on basic and extended regular
322 The simple command specification is tested first.
323 If that test fails, the command regular expression is applied.
324 If the simple command test succeeds, the command regular expression
326 This may result in ``no command found for regex:'' messages
332 defines the maximum number of initial characters of the name,
333 supplied by the UNIX dialect, of the UNIX command associated with a process
334 to be printed in the COMMAND column.
339 Note that many UNIX dialects do not supply all command name characters
342 in the files and structures from which
344 obtains command name.
345 Often dialects limit the number of characters supplied in those sources.
346 For example, Linux 2.4.27 and Solaris 9 both limit command name length to
351 is zero ('0'), all command characters supplied to
353 by the UNIX dialect will be printed.
357 is less than the length of the column title, ``COMMAND'', it will
358 be raised to that length.
361 disables the reporting of any path name
362 components from the kernel's name cache.
364 .B "KERNEL NAME CACHE"
365 section for more information.
370 to search for all open instances of directory
372 and the files and directories it contains at its top level.
374 does NOT descend the directory tree, rooted at
378 option may be used to request a full\-descent directory tree search,
384 option does not follow symbolic links within
390 option is also specified.
392 search for open files on file system mount points on subdirectories of
398 option is also specified.
400 Note: the authority of the user of this option limits it to searching for
401 files that the user has permission to examine with the system
406 specifies a list of file descriptors (FDs) to exclude from
407 or include in the output listing.
408 The file descriptors are specified in the comma\-separated set
410 \&\- e.g., ``cwd,1,3'', ``^6,^2''.
411 (There should be no spaces in the set.)
413 The list is an exclusion list if all entries of the set begin with `^'.
414 It is an inclusion list if no entry begins with `^'.
415 Mixed lists are not permitted.
417 A file descriptor number range may be in the set as long as
418 neither member is empty, both members are numbers, and the ending
419 member is larger than the starting one \- e.g., ``0-7'' or ``3-10''.
420 Ranges may be specified for exclusion if they have the `^' prefix \-
421 e.g., ``^0-7'' excludes all file descriptors 0 through 7.
423 Multiple file descriptor numbers are joined in a single ORed set before
424 participating in AND option selection.
426 When there are exclusion and inclusion members in the set,
428 reports them as errors and exits with a non\-zero return code.
430 See the description of File Descriptor (FD) output values in the
432 section for more information on file descriptor names.
437 to search for all open instances of directory
439 and all the files and directories it contains to its complete depth.
443 option does not follow symbolic links within
449 option is also specified.
451 search for open files on file system mount points on subdirectories of
457 option is also specified.
459 Note: the authority of the user of this option limits it to searching for
460 files that the user has permission to examine with the system
466 may process this option slowly and require a large amount of dynamic memory
468 This is because it must descend the entire directory tree, rooted at
472 for each file and directory, building a list of all the files it finds, and
473 searching that list for a match with every open file.
476 is large, these steps can take a long time, so use this option prudently.
481 use of the device cache file.
482 The use of this option is sometimes restricted.
484 .B "DEVICE CACHE FILE"
485 section and the sections that follow it for more information on this
489 must be followed by a function letter; the function letter may optionally
490 be followed by a path name.
492 recognizes these function letters:
495 \fB?\fP \- report device cache file paths
496 \fBb\fP \- build the device cache file
497 \fBi\fP \- ignore the device cache file
498 \fBr\fP \- read the device cache file
499 \fBu\fP \- read and update the device cache file
507 functions, accompanied by a path name, are sometimes restricted.
508 When these functions are restricted, they will not appear in
509 the description of the
511 option that accompanies
517 .B "DEVICE CACHE FILE"
518 section and the sections that follow it for more information on these
519 functions and when they're restricted.
523 function reports the read\-only and write paths that lsof can
524 use for the device cache file,
525 the names of any environment variables whose values
527 will examine when forming the device cache file path,
528 and the format for the personal device cache file path.
529 (Escape the `?' character as your shell requires.)
536 functions may be followed by the device cache file's path.
537 The standard default is
539 in the home directory of the real user ID that executes
541 but this could have been changed when
543 was configured and compiled.
548 options show the current default prefix \- e.g., ``.lsof''.)
551 is the first component of the host's name returned by
558 to build a new device cache file at the default or specified path.
564 to ignore the default device cache file and obtain its information
565 about devices via direct calls to the kernel.
571 to read the device cache at the default or specified path, but
572 prevents it from creating a new device cache file when none
573 exists or the existing one is improperly structured.
576 function, when specified without a path name, prevents
578 from updating an incorrect or outdated device cache file,
579 or creating a new one in its place.
582 function is always available when it is specified without a
583 path name argument; it may be restricted by the permissions of the
591 to read the device cache file at the default or specified path,
592 if possible, and to rebuild it, if necessary.
593 This is the default device cache file function when no
595 option has been specified.
598 exempts the file system whose path name is
600 from being subjected to kernel function calls that might block.
608 kernel function calls.
615 kernel function calls.
616 Multiple file systems may be specified with separate
618 specifications and each may have
620 calls exempted or not.
622 This option is currently implemented only for Linux.
625 this option can easily be mis\-applied to other than
626 the file system of interest, because it uses path name rather
627 than the more reliable device and inode numbers.
628 (Device and inode numbers are acquired via the potentially blocking
630 kernel call and are thus not available, but see the
632 option as a possible alternative way to supply device numbers.)
633 \fBUse this option with great care and fully specify the path name of the
634 file system to be exempted.\fP
636 When open files on exempted file systems are reported, it may not be
637 possible to obtain all their information.
638 Therefore, some information columns will be blank, the characters ``UNKN''
639 preface the values in the TYPE column, and the applicable exemption option
640 is added in parentheses to the end of the NAME column.
641 (Some device number information might be made available via the
647 specifies that Linux pipe, Linux UNIX socket and Linux pseudoterminal files
648 should be displayed with endpoint information and the files of the endpoints should also be displayed.
649 Note: UNIX socket file endpoint information is only available when the
650 compile flags line of
652 output contains HASUXSOCKEPT, and psudoterminal endpoint information is only
653 available when the compile flags line contains HASPTYEPT.
655 Pipe endpoint information is displayed in the NAME column in the
656 form ``\fIPID,cmd,FDmode\fP'', where
658 is the endpoint process ID;
660 is the endpoint process command;
662 is the endpoint file's descriptor; and
664 is the endpoint file's access mode.
667 endpoint information is displayed in the NAME column as
668 ``->/dev/pts\fImin\fP\ \fIPID,cmd,FDmode\fP'' or ``\fIPID,cmd,FDmode\fP''.
669 The first form is for a master device; the second, for a slave device.
671 is a slave device's minor device number; and
675 are the same as with pipe endpoint information.
676 Note: psudoterminal endpoint information is only available when the compile
679 output contains HASPTYEPT.
681 UNIX socket file endpoint information is displayed in the NAME column
684 ``type=\fITYPE\fP\ ->INO=\fIINODE\fP\ \fIPID,cmd,FDmode\fP'', where
688 is the i-node number of the connected socket;
693 are the same as with pipe endpoint information.
694 Note: UNIX socket file endpoint information is available only when the
695 compile flags line of
697 output contains HASUXSOCKEPT.
699 Multiple occurrences of this information can appear in a file's
703 specfies that Linux pipe and Linux UNIX socket files should be displayed
704 with endpoint information, but not the files of the endpoints.
708 by itself clarifies how path name arguments are to be interpreted.
716 in any combination it specifies
717 that the listing of kernel file structure information is to be enabled
718 (`+') or inhibited (`\-').
720 Normally a path name argument is taken to be a file system name if
721 it matches a mounted\-on directory name reported by
723 or if it represents a block device, named in the
725 output and associated with a mounted directory name.
728 is specified, all path name arguments will be taken to be file
731 will complain if any are not.
732 This can be useful, for example, when the file system name
733 (mounted\-on device) isn't a block device.
734 This happens for some CD-ROM file systems.
738 is specified by itself, all path name arguments will be taken to be
740 Thus, for example, the ``\fB\-f\fP\ -- /'' arguments direct lsof to search
741 for open files with a `/' path name, not all open files in the `/'
744 Be careful to make sure
748 are properly terminated and aren't followed by a character (e.g., of
749 the file or file system name) that might be taken as a parameter.
750 For example, use ``--'' after
754 as in these examples.
757 $ lsof +f -- /file/system/name
758 $ lsof -f -- /file/name
761 The listing of information from kernel file structures, requested with the
763 option form, is normally
764 inhibited, and is not available in whole or part for some dialects \- e.g.,
765 /proc\-based Linux kernels below 2.6.22.
768 is a plus sign (`+'), these characters request file structure information:
771 \fBc\fR file structure use count (not Linux)
772 \fBf\fR file structure address (not Linux)
773 \fBg\fR file flag abbreviations (Linux 2.6.22 and up)
774 \fBG\fR file flags in hexadecimal (Linux 2.6.22 and up)
775 \fBn\fR file structure node address (not Linux)
778 When the prefix is minus (`\-') the same characters disable the
779 listing of the indicated values.
781 File structure addresses, use counts, flags, and node addresses may be
782 used to detect more readily identical files inherited by child
783 processes and identical files in use by different processes.
785 column output can be sorted by output columns holding the values
786 and listed to identify identical file use, or
788 field output can be parsed by an AWK or Perl post\-filter script,
792 specifies a character list,
794 that selects the fields to be output for processing by another program,
795 and the character that terminates each output field.
796 Each field to be output is specified with a single character in
798 The field terminator defaults to NL, but may be changed to NUL (000).
800 .B "OUTPUT FOR OTHER PROGRAMS"
801 section for a description of the field identification characters and
802 the field output process.
804 When the field selection character list is empty, all standard fields are
805 selected (except the raw device field, security context and zone field for
806 compatibility reasons)
807 and the NL field terminator is used.
809 When the field selection character list contains only a zero (`0'),
810 all fields are selected (except the raw device field for compatibility
811 reasons) and the NUL terminator character is used.
813 Other combinations of fields and their associated field terminator
814 character must be set with explicit entries in
817 .B "OUTPUT FOR OTHER PROGRAMS"
820 When a field selection character identifies an item
822 does not normally list \- e.g., PPID, selected with
824 specification of the field character \- e.g., ``\fB\-FR\fP'' \-
825 also selects the listing of the item.
827 When the field selection character list contains the single
830 will display a help list of the field identification characters.
831 (Escape the `?' character as your shell requires.)
834 excludes or selects the listing of files for the processes
835 whose optional process group IDentification (PGID) numbers are in the
838 \&\- e.g., ``123'' or ``123,^456''.
839 (There should be no spaces in the set.)
841 PGID numbers that begin with `^' (negation) represent exclusions.
843 Multiple PGID numbers are joined in a single ORed set before participating
844 in AND option selection.
845 However, PGID exclusions are applied without ORing or ANDing
846 and take effect before other selection criteria are applied.
850 option also enables the output display of PGID numbers.
851 When specified without a PGID set that's all it does.
854 selects the listing of files any of whose Internet address
855 matches the address specified in \fIi\fP.
856 If no address is specified, this option selects the listing of all
857 Internet and x.25 (HP\-UX) network files.
863 is specified with no following address, only files of the indicated
864 IP version, IPv4 or IPv6, are displayed.
865 (An IPv6 specification may be used only if the dialects supports IPv6,
866 as indicated by ``[46]'' and ``IPv[46]'' in
872 Sequentially specifying
876 is the same as specifying
885 is the same as specifying
891 Multiple addresses (up to a limit of 100) may be specified with multiple
894 (A port number or service name range is counted as one address.)
895 They are joined in a single ORed set before participating in
896 AND option selection.
898 An Internet address is specified in the form (Items in square
899 brackets are optional.):
902 [\fI46\fP][\fIprotocol\fP][@\fIhostname\fP\||\|\fIhostaddr\fP][:\fIservice\fP\||\|\fIport\fP]
905 .RI [ 46 ][ protocol ][@ hostname \||\| hostaddr ][: service \||\| port ]
911 \fI46\fP specifies the IP version, IPv4 or IPv6
913 that applies to the following address.
915 '6' may be be specified only if the UNIX
917 dialect supports IPv6. If neither '4' nor
919 '6' is specified, the following address
921 applies to all IP versions.
923 \fIprotocol\fP is a protocol name \- \fBTCP\fP, \fBUDP\fP
924 .br or \fBUDPLITE\fP.
926 \fIhostname\fP is an Internet host name. Unless a
928 specific IP version is specified, open
930 network files associated with host names
932 of all versions will be selected.
934 \fIhostaddr\fP is a numeric Internet IPv4 address in
936 dot form; or an IPv6 numeric address in
938 colon form, enclosed in brackets, if the
940 UNIX dialect supports IPv6. When an IP
942 version is selected, only its numeric
944 addresses may be specified.
946 \fIservice\fP is an \fI/etc/services\fP name \- e.g., \fBsmtp\fP \-
949 \fIport\fP is a port number, or a list of them.
952 IPv6 options may be used only if the UNIX dialect supports IPv6.
953 To see if the dialect supports IPv6, run
960 If the displayed description of the
962 option contains ``[46]'' and ``IPv[46]'', IPv6 is supported.
964 IPv4 host names and addresses may not be specified if network file selection
965 is limited to IPv6 with
967 IPv6 host names and addresses may not be specified if network file selection
968 is limited to IPv4 with
970 When an open IPv4 network file's address is mapped in an IPv6 address,
971 the open file's type will be IPv6, not IPv4, and its display will be
972 selected by '6', not '4'.
974 At least one address component \-
982 \&\- must be supplied.
983 The `@' character, leading the host specification, is always required;
984 as is the `:', leading the port specification.
996 name list is specified, the
998 may also need to be specified if the TCP, UDP and UDPLITE port numbers for
999 the service name are different.
1000 Use any case \- lower or upper \- for
1006 numbers may be combined in a list whose entries are separated by commas
1007 and whose numeric range entries are separated by minus signs.
1008 There may be no embedded spaces, and all service names must belong to
1011 Since service names may contain embedded minus signs, the starting entry
1012 of a range can't be a service name; it can be a port number, however.
1014 Here are some sample addresses:
1020 TCP:25 \- TCP and port 25
1022 @1.2.3.4 \- Internet IPv4 host address 1.2.3.4
1024 @[3ffe:1ebc::1]:1234 \- Internet IPv6 host address
1025 3ffe:1ebc::1, port 1234
1027 UDP:who \- UDP who service port
1029 TCP@lsof.itap:513 \- TCP, port 513 and host name lsof.itap
1031 tcp@foo:1-10,smtp,99 \- TCP, ports 1 through 10,
1032 service name \fIsmtp\fP, port 99, host name foo
1034 tcp@bar:1-smtp \- TCP, ports 1 through \fIsmtp\fP, host bar
1036 :time \- either TCP, UDP or UDPLITE time service port
1040 selects the listing of tasks (threads) of processes, on dialects
1041 where task (thread) reporting is supported.
1042 (If help output \- i.e., the output of the
1046 options \- shows this option, then task (thread) reporting is
1047 supported by the dialect.)
1051 is followed by a value,
1053 it must be ``i''. That causes
1055 to ignore tasks, particularly in the default, list\-everything case
1056 when no other options are specified.
1062 are both specified on Linux, and the tasks of a main process are
1063 selected by other options, the main process will also be listed
1064 as though it were a task, but without a task ID.
1065 (See the description of the TID column in the
1069 Where the FreeBSD version supports threads, all threads will be
1070 listed with their IDs.
1072 In general threads and tasks inherit the files of the caller, but
1073 may close some and open others, so
1075 always reports all the open files of threads and tasks.
1078 specifies a kernel name list file,
1080 in place of /vmunix, /mach, etc.
1082 is not available under AIX on the IBM RISC/System 6000.
1085 inhibits the conversion of user ID numbers to login names.
1086 It is also useful when login name lookup is working improperly or slowly.
1089 enables (`+') or disables (`-') the listing of file link
1090 counts, where they are available \- e.g., they aren't available
1091 for sockets, or most FIFOs and pipes.
1095 is specified without a following number, all link counts will be listed.
1098 is specified (the default), no link counts will be listed.
1102 is followed by a number, only files having a link count less than
1103 that number will be listed.
1104 (No number may follow
1106 A specification of the form ``\fB+L1\fP'' will select open files that
1108 A specification of the form ``\fB+aL1\ \fI<file_system>\fR'' will select
1109 unlinked open files on the specified file system.
1111 For other link count comparisons, use field output (\fB\-F\fP)
1112 and a post\-processing script or program.
1115 specifies an alternate kernel memory file or activates
1116 mount table supplement processing.
1120 specifies a kernel memory file,
1126 \&\- e.g., a crash dump file.
1130 requests that a mount supplement file be written to the standard output
1132 All other options are silently ignored.
1134 There will be a line in the mount supplement file for each mounted file
1135 system, containing the mounted file system directory, followed by a single
1136 space, followed by the device number in hexadecimal "0x" format \- e.g.,
1143 can use the mount supplement file to get device numbers for file systems
1144 when it can't get them via
1153 as a mount supplement file.
1159 options are not available for all supported dialects.
1165 options to see if the
1169 options are available.
1172 Enables (\fB+\fP) or disables (\fB\-\fP) the
1173 reporting of portmapper registrations for local TCP, UDP and UDPLITE ports,
1174 where port mapping is supported.
1175 (See the last paragraph of this option description for information about
1176 where portmapper registration reporting is supported.)
1178 The default reporting mode is set by the
1180 builder with the HASPMAPENABLED #define in the dialect's machine.h
1183 is distributed with the HASPMAPENABLED #define deactivated, so
1184 portmapper reporting is disabled by default and must be requested
1192 option will report the default mode.
1193 Disabling portmapper registration when it is already disabled or
1194 enabling it when already enabled is acceptable.
1195 When portmapper registration reporting is enabled,
1197 displays the portmapper registration (if any) for local TCP, UDP or
1199 in square brackets immediately following the port numbers or service
1200 names \- e.g., ``:1234[name]'' or ``:name[100083]''.
1201 The registration information may be a name or number, depending
1202 on what the registering program supplied to the portmapper when
1203 it registered the port.
1205 When portmapper registration reporting is enabled,
1207 may run a little more slowly or even become blocked when access to the
1208 portmapper becomes congested or stopped.
1209 Reverse the reporting mode to determine if portmapper registration
1210 reporting is slowing or blocking
1213 For purposes of portmapper registration reporting
1215 considers a TCP, UDP or UDPLITE port local if: it is found in the local part
1216 of its containing kernel structure;
1217 or if it is located in the foreign part of its containing kernel
1218 structure and the local and foreign Internet addresses are the same;
1219 or if it is located in the foreign part of its containing kernel
1220 structure and the foreign Internet address is INADDR_LOOPBACK (127.0.0.1).
1223 ignore some foreign ports on machines with multiple interfaces
1224 when the foreign Internet address is on a different interface
1229 FAQ (The \fBFAQ\fP section gives its location.)
1230 for further discussion of portmapper registration
1233 Portmapper registration reporting is supported only on dialects that
1234 have RPC header files.
1235 (Some Linux distributions with GlibC 2.14 do not have them.)
1236 When portmapper registration reporting is supported, the
1240 help output will show the
1245 inhibits the conversion of network numbers to
1246 host names for network files.
1247 Inhibiting conversion may make
1250 It is also useful when host name lookup is not working properly.
1253 selects the listing of NFS files.
1258 to display file offset at all times.
1259 It causes the SIZE/OFF output column title to be changed to OFFSET.
1260 Note: on some UNIX dialects
1262 can't obtain accurate or consistent file offset information from its
1263 kernel data sources, sometimes just for particular kinds of files
1264 (e.g., socket files.)
1267 FAQ (The \fBFAQ\fP section gives its location.)
1268 for more information.
1274 options are mutually exclusive; they can't both be specified.
1275 When neither is specified,
1277 displays whatever value \- size or offset \- is appropriate and
1278 available for the type of the file.
1281 defines the number of decimal digits (\fIo\fP) to be
1282 printed after the ``0t'' for a file offset before the form is switched
1286 value of zero (unlimited) directs
1288 to use the ``0t'' form for all offset output.
1290 This option does NOT direct
1292 to display offset at all times; specify
1294 (without a trailing number) to do that.
1296 only specifies the number of digits after ``0t'' in
1297 either mixed size and offset or offset\-only output.
1298 Thus, for example, to direct
1300 to display offset at all times with a decimal digit count of 10, use:
1308 The default number of digits allowed after ``0t'' is normally 8,
1309 but may have been changed by the lsof builder.
1310 Consult the description of the
1312 option in the output of the
1316 option to determine the default that is in effect.
1321 to bypass the strategy it uses to avoid being blocked by some
1322 kernel operations \- i.e., doing them in forked child processes.
1324 .B "BLOCKS AND TIMEOUTS"
1326 .B "AVOIDING KERNEL BLOCKS"
1327 sections for more information on kernel operations that may block
1330 While use of this option will reduce
1332 startup overhead, it may also cause
1334 to hang when the kernel doesn't respond to a function.
1335 Use this option cautiously.
1338 excludes or selects the listing of files for the processes
1339 whose optional process IDentification (PID) numbers are in the
1340 comma\-separated set
1342 \&\- e.g., ``123'' or ``123,^456''.
1343 (There should be no spaces in the set.)
1345 PID numbers that begin with `^' (negation) represent exclusions.
1347 Multiple process ID numbers are joined in a single ORed set before
1348 participating in AND option selection.
1349 However, PID exclusions are applied without ORing or ANDing
1350 and take effect before other selection criteria are applied.
1353 inhibits the conversion of port numbers to port
1354 names for network files.
1355 Inhibiting the conversion may make
1357 run a little faster.
1358 It is also useful when port name lookup is not working properly.
1360 .BI +|\-r " [t[m<fmt>]]"
1366 lists open files as selected by other options, delays
1368 seconds (default fifteen), then repeats the listing, delaying
1369 and listing repetitively until stopped by a condition defined by
1370 the prefix to the option.
1372 If the prefix is a `\-', repeat mode is endless.
1374 must be terminated with an interrupt or quit signal.
1376 If the prefix is `+', repeat mode will end the first cycle no open files
1377 are listed \- and of course when
1379 is stopped with an interrupt or quit signal.
1380 When repeat mode ends because no files are listed, the process exit code
1381 will be zero if any open files were ever listed; one, if none were ever
1385 marks the end of each listing:
1386 if field output is in progress (the
1388 option has been specified), the default marker is `m'; otherwise the
1389 default marker is ``========''.
1390 The marker is followed by a NL character.
1392 The optional "m<fmt>" argument specifies a format for the marker line.
1393 The <fmt> characters following `m' are interpreted as a format
1394 specification to the
1396 function, when both it and the
1398 function are available in the dialect's C library.
1401 documentation for what may appear in its format specification.
1402 Note that when field output is requested with the
1404 option, <fmt> cannot contain the NL format, ``%n''.
1405 Note also that when <fmt> contains spaces or other characters that
1406 affect the shell's interpretation of arguments, <fmt> must be
1407 quoted appropriately.
1411 startup overhead, so it is more efficient to use this mode
1414 repetitively from a shell script, for example.
1416 To use repeat mode most efficiently, accompany
1418 with specification of other
1420 selection options, so the amount of kernel memory access
1422 does will be kept to a minimum.
1423 Options that filter at the process level \- e.g.,
1428 \&\- are the most efficient selectors.
1430 Repeat mode is useful when coupled with field output (see the
1432 option description) and a supervising
1436 script, or a C program.
1439 directs lsof to list the Parent Process IDentification
1440 number in the PPID column.
1446 to display file size at all times.
1447 It causes the SIZE/OFF output column title to be changed to SIZE.
1448 If the file does not have a size, nothing is displayed.
1452 form is available only for selected dialects, and only when the
1456 help output lists it.
1458 When the optional form is available, the
1460 may be followed by a protocol name (\fIp\fR), either TCP or UDP,
1461 a colon (`:') and a comma\-separated protocol state name list,
1462 the option causes open TCP and UDP files to be excluded if their
1463 state name(s) are in the list (\fIs\fP) preceded by a `^'; or
1464 included if their name(s) are not preceded by a `^'.
1466 Dialects that support this option may support only one protocol.
1467 When an unsupported protocol is specified, a message will be
1468 displayed indicating state names for the protocol are unavailable.
1470 When an inclusion list is defined, only network files with state
1471 names in the list will be present in the
1474 Thus, specifying one state name means that only network files
1475 with that lone state name will be listed.
1477 Case is unimportant in the protocol or state names, but there may
1478 be no spaces and the colon (`:') separating the protocol
1479 name (\fIp\fP) and the state name list (\fIs\fP) is required.
1481 If only TCP and UDP files are to be listed, as controlled by
1482 the specified exclusions and inclusions, the
1484 option must be specified, too.
1485 If only a single protocol's files are to be listed, add its name
1486 as an argument to the
1490 For example, to list only network files with TCP state LISTEN, use:
1493 \-iTCP \-sTCP:LISTEN
1496 Or, for example, to list network files with all UDP states except
1503 State names vary with UNIX dialects, so it's not possible to
1504 provide a complete list. Some common TCP state names are:
1505 CLOSED, IDLE, BOUND, LISTEN, ESTABLISHED, SYN_SENT, SYN_RCDV,
1506 ESTABLISHED, CLOSE_WAIT, FIN_WAIT1, CLOSING, LAST_ACK, FIN_WAIT_2,
1508 Two common UDP state names are Unbound and Idle.
1512 FAQ (The \fBFAQ\fP section gives its location.)
1513 for more information on how to use protocol state exclusion and
1514 inclusion, including examples.
1518 (without a following decimal digit count) and
1520 option (without a following protocol and state name list)
1521 are mutually exclusive; they can't both be specified.
1522 When neither is specified,
1524 displays whatever value \- size or offset \- is appropriate and
1525 available for the type of file.
1527 Since some types of files don't have true sizes \- sockets, FIFOs,
1528 pipes, etc.\& \- lsof displays for their sizes the content amounts in
1529 their associated kernel buffers, if possible.
1532 specifies an optional time-out seconds value for kernel functions \-
1537 \- that might otherwise deadlock.
1541 the default, fifteen; when no value is specified, the default is used.
1544 .B "BLOCKS AND TIMEOUTS"
1545 section for more information.
1548 controls the reporting of some TCP/TPI information, also
1551 following the network addresses.
1552 In normal output the information appears in parentheses, each item
1553 except TCP or TPI state name identified by a keyword, followed by `=',
1554 separated from others by a single space:
1557 <TCP or TPI state name>
1558 QR=<read queue length>
1559 QS=<send queue length>
1560 SO=<socket options and values>
1562 TF=<TCP flags and values>
1563 WR=<window read length>
1564 WW=<window write length>
1567 Not all values are reported for all UNIX dialects.
1568 Items values (when available) are reported after the item name and '='.
1570 When the field output mode is in effect (See
1571 .BR "OUTPUT FOR OTHER PROGRAMS" .)
1572 each item appears as a field with a `T' leading character.
1575 with no following key characters disables TCP/TPI information reporting.
1578 with following characters selects the reporting of specific TCP/TPI
1582 \fBf\fP selects reporting of socket options,
1583 states and values, and TCP flags and
1585 \fBq\fP selects queue length reporting.
1586 \fBs\fP selects connection state reporting.
1587 \fBw\fP selects window size reporting.
1590 Not all selections are enabled for some UNIX dialects.
1591 State may be selected for all dialects and is reported by default.
1598 option will show what selections may be used with the UNIX dialect.
1602 is used to select information \- i.e., it is followed by one or more
1603 selection characters \- the displaying of state is disabled by default,
1604 and it must be explicitly selected again in the characters following
1606 (In effect, then, the default is equivalent to
1608 For example, if queue lengths and state are desired, use
1611 Socket options, socket states, some socket values, TCP flags and
1612 one TCP value may be reported (when available in the UNIX dialect)
1613 in the form of the names that commonly appear after SO_, so_, SS_,
1614 TCP_ and TF_ in the dialect's header files \-
1615 most often <sys/socket.h>, <sys/socketvar.h> and <netinet/tcp_var.h>.
1616 Consult those header files for the meaning of the flags, options,
1619 ``SO='' precedes socket options and values; ``SS='', socket states;
1620 and ``TF='', TCP flags and values.
1622 If a flag or option has a value, the value will follow an '=' and
1623 the name -- e.g., ``SO=LINGER=5'', ``SO=QLIM=5'', ``TF=MSS=512''.
1624 The following seven values may be reported:
1628 Reported Description (Common Symbol)
1630 KEEPALIVE keep alive time (SO_KEEPALIVE)
1631 LINGER linger time (SO_LINGER)
1632 MSS maximum segment size (TCP_MAXSEG)
1633 PQLEN partial listen queue connections
1634 QLEN established listen queue connections
1635 QLIM established listen queue limit
1636 RCVBUF receive buffer length (SO_RCVBUF)
1637 SNDBUF send buffer length (SO_SNDBUF)
1640 Details on what socket options and values, socket states, and TCP flags
1641 and values may be displayed for particular UNIX dialects may be found in
1642 the answer to the ``Why doesn't lsof report socket options, socket states,
1643 and TCP flags and values for my dialect?'' and ``Why doesn't lsof report
1644 the partial listen queue connection count for my dialect?''
1647 FAQ (The \fBFAQ\fP section gives its location.)
1652 should produce terse output with process identifiers only and no header \-
1653 e.g., so that the output may be piped to
1661 selects the listing of files for the user whose login names
1662 or user ID numbers are in the comma\-separated set
1666 (There should be no spaces in the set.)
1668 Multiple login names or user ID numbers are joined in a single ORed set
1669 before participating in AND option selection.
1671 If a login name or user ID is preceded by a `^', it becomes a negation \-
1672 i.e., files of processes owned by the login name or user ID will never
1674 A negated login name or user ID selection is neither ANDed nor ORed
1675 with other selections; it is applied before all other selections and
1676 absolutely excludes the listing of the files of the process.
1677 For example, to direct
1679 to exclude the listing of files belonging to root processes,
1680 specify ``\-u^root'' or ``\-u^0''.
1683 selects the listing of UNIX domain socket files.
1686 selects the listing of
1688 version information, including: revision number;
1691 binary was constructed;
1692 who constructed the binary and where;
1693 the name of the compiler used to construct the
1695 the version number of the compiler when readily available;
1696 the compiler and loader flags used to construct the
1699 and system information, typically the output of
1707 to indicate the items it was asked to list and failed to find \- command
1708 names, file names, Internet addresses or files, login names, NFS files,
1709 PIDs, PGIDs, and UIDs.
1711 When other options are ANDed to search options, or compile\-time
1712 options restrict the listing of some files,
1714 may not report that it failed to find a search item when an ANDed
1715 option or compile\-time option prevents the listing of the open file
1716 containing the located search item.
1718 For example, ``lsof -V -iTCP@foobar -a -d 999'' may not report a
1719 failure to locate open files at ``TCP@foobar'' and may not list
1720 any, if none have a file descriptor number of 999.
1721 A similar situation arises when HASSECURITY and HASNOSOCKSECURITY are
1722 defined at compile time and they prevent the listing of open files.
1725 Enables (\fB+\fP) or disables (\fB-\fP) the suppression of warning messages.
1729 builder may choose to have warning messages disabled or enabled by
1731 The default warning message state is indicated in the output of the
1736 Disabling warning messages when they are already disabled or enabling
1737 them when already enabled is acceptable.
1750 options to direct their processing to cross over symbolic
1751 links and|or file system mount points encountered when
1752 scanning the directory (\fB+d\fP) or directory tree (\fB+D\fP).
1756 is specified by itself without a following parameter, cross\-over
1757 processing of both symbolic links and file system mount points is
1761 is specified without a parameter, the next argument must begin with '-'
1764 The optional 'f' parameter enables file system mount point cross\-over
1765 processing; 'l', symbolic link cross\-over processing.
1769 option may not be supplied without also supplying a
1776 This is a dialect\-specific option.
1780 This IBM AIX RISC/System 6000 option requests the reporting
1781 of executed text file and shared library references.
1784 because this option uses the kernel readx() function, its use on
1785 a busy AIX system might cause an application process to hang so
1786 completely that it can neither be killed nor stopped.
1787 I have never seen this happen or had a report of its happening,
1788 but I think there is a remote possibility it could happen.
1790 By default use of readx() is disabled.
1793 may need setuid\-root permission to perform the actions this
1798 builder may specify that the
1800 option be restricted to processes whose real UID is root.
1801 If that has been done, the
1803 option will not appear in the
1807 help output unless the real UID of the
1812 distribution allows any UID to specify
1814 so by default it will appear in the help output.
1816 When AIX readx() use
1819 may not be able to report information for all text and loader file
1820 references, but it may also avoid exacerbating an AIX
1821 kernel directory search kernel error, known as the Stale Segment
1824 The readx() function, used by
1826 or any other program to access some sections of kernel virtual
1827 memory, can trigger the Stale Segment ID bug.
1828 It can cause the kernel's dir_search() function to believe erroneously
1829 that part of an in\-memory copy of a file system directory has been
1831 Another application process, distinct from
1833 asking the kernel to search the directory \- e.g., by using
1835 can cause dir_search() to loop forever, thus hanging the application process.
1839 FAQ (The \fBFAQ\fP section gives its location.)
1844 distribution for a more complete description of the Stale Segment ID bug,
1845 its APAR, and methods for defining readx() use when compiling
1850 This Linux option requests that
1852 skip the reporting of information on all open TCP, UDP and UDPLITE IPv4
1855 This Linux option is most useful when the system has an extremely
1856 large number of open TCP, UDP and UDPLITE files, the processing of whose
1863 a long time, and whose reporting is not of interest.
1865 Use this option with care and only when you are sure that the
1866 information you want
1868 to display isn't associated with open TCP, UDP or UDPLITE socket files.
1870 \ \ \ \ Solaris 10 and above:
1872 This Solaris 10 and above option requests the reporting of cached
1873 paths for files that have been deleted \- i.e., removed with
1878 The cached path is followed by the string ``\ (deleted)'' to indicate
1879 that the path by which the file was opened has been deleted.
1881 Because intervening changes made to the path \- i.e., renames with
1885 \- are not recorded in the cached path, what
1887 reports is only the path by which the file was opened, not its
1888 possibly different final path.
1891 specifies how Solaris 10 and higher zone information is to be handled.
1893 Without a following argument \- e.g., NO
1895 the option specifies that zone names are to be listed in the ZONE
1900 option may be followed by a zone name,
1902 That causes lsof to list only open files for processes in that zone.
1905 option and argument pairs may be specified to form a list of named zones.
1906 Any open file of any process in any of the zones will be listed, subject
1907 to other conditions specified by other options and arguments.
1910 specifies how SELinux security contexts are to be handled.
1911 It and 'Z' field output character support are inhibited
1912 when SELinux is disabled in the running Linux kernel.
1914 .B "OUTPUT FOR OTHER PROGRAMS"
1915 for more information on the 'Z' field output character.
1917 Without a following argument \- e.g., NO
1919 the option specifies that security contexts are to be listed in the
1920 SECURITY\-CONTEXT output column.
1924 option may be followed by a wildcard security context name,
1926 That causes lsof to list only open files for processes in that security
1930 option and argument pairs may be specified to form a list of security
1932 Any open file of any process in any of the security contexts will be listed,
1933 subject to other conditions specified by other options and arguments.
1936 can be A:B:C or *:B:C or A:B:* or *:*:C to match against the A:B:C context.
1939 The double minus sign option is a marker that signals the end of
1941 It may be used, for example, when the first file name begins with
1943 It may also be used when the absence of a value for the last keyed
1944 option must be signified by the presence of a minus sign in the following
1945 option and before the start of the file names.
1948 These are path names of specific files to list.
1949 Symbolic links are resolved before use.
1950 The first name may be separated from the preceding options with
1955 is the mounted\-on directory of a file system or the device of the
1958 will list all the files open on the file system.
1959 To be considered a file system, the
1961 must match a mounted\-on directory name in
1963 output, or match the name of a block device associated with a mounted\-on
1967 option may be used to force
1971 a file system identifier (\fB+f\fP) or a simple file (\fB\-f\fP).
1975 is a path to a directory that is not the mounted\-on directory name of
1976 a file system, it is treated just as a regular file is treated \- i.e.,
1977 its listing is restricted to processes that have it open as a file or
1978 as a process\-specific directory, such as the root or current working
1982 look for open files inside a directory name, use the
1990 is the base name of a family of multiplexed files \- e.g, AIX's
1991 .IR /dev/pt[cs] " \-"
1993 will list all the associated multiplexed files on the device that
2001 is a UNIX domain socket name,
2003 will usually search for it by the characters of the name alone \- exactly as
2004 it is specified and is recorded in the kernel socket structure.
2005 (See the next paragraph for an exception to that rule for Linux.)
2006 Specifying a relative path \- e.g.,
2008 \&\- in place of the
2009 file's absolute path \- e.g.,
2011 \&\- won't work because
2013 must match the characters you specify with what it finds in the
2014 kernel UNIX domain socket structures.
2018 is a Linux UNIX domain socket name, in one case
2020 is able to search for it by its device and inode number, allowing
2022 to be a relative path.
2023 The case requires that the absolute path -- i.e., one beginning with a
2024 slash ('/') be used by the process that created the socket, and hence be
2027 file; and it requires that
2029 be able to obtain the device and node numbers of both the absolute path in
2036 When those conditions are met,
2038 will be able to search for the UNIX domain socket when some path to it is
2041 Thus, for example, if the path is
2045 search is initiated when the working directory is
2054 is none of the above,
2056 will list any open files whose device and inode match that of the
2060 If you have also specified the
2065 you may safely specify are file systems for which your mount table
2066 supplies alternate device numbers.
2068 .B "AVOIDING KERNEL BLOCKS"
2070 .B "ALTERNATE DEVICE NUMBERS"
2071 sections for more information.
2073 Multiple file names are joined in a single ORed set before
2074 participating in AND option selection.
2077 supports the recognition of AFS files for these dialects (and AFS
2081 AIX 4.1.4 (AFS 3.4a)
2082 HP\-UX 9.0.5 (AFS 3.4a)
2083 Linux 1.2.13 (AFS 3.3)
2084 Solaris 2.[56] (AFS 3.4a)
2087 It may recognize AFS files on other versions of these dialects,
2088 but has not been tested there.
2089 Depending on how AFS is implemented,
2091 may recognize AFS files in other dialects, or may have difficulties
2092 recognizing AFS files in the supported dialects.
2095 may have trouble identifying all aspects of AFS files in
2096 supported dialects when AFS kernel support is implemented via
2097 dynamic modules whose addresses do not appear in the kernel's
2101 may have to guess at the identity of AFS files, and might not be able to
2102 obtain volume information from the kernel that is needed for calculating
2103 AFS volume node numbers.
2106 can't compute volume node numbers, it reports blank in the NODE column.
2110 option is available in some dialect implementations of
2112 for specifying the name list file where dynamic module kernel
2113 addresses may be found.
2114 When this option is available, it will be listed in the
2116 help output, presented in response to the
2123 FAQ (The \fBFAQ\fP section gives its location.)
2124 for more information about dynamic modules, their
2125 symbols, and how they affect
2129 Because AFS path lookups don't seem to participate in the
2130 kernel's name cache operations,
2132 can't identify path name components for AFS files.
2135 has three features that may cause security concerns.
2136 First, its default compilation mode allows anyone to list all
2138 Second, by default it creates a user\-readable and user\-writable device
2139 cache file in the home directory of the real user ID that executes
2141 (The list\-all\-open\-files and device cache features may be disabled when
2148 options name alternate kernel name list or memory files.
2150 Restricting the listing of all open files is controlled by the
2151 compile\-time HASSECURITY and HASNOSOCKSECURITY options.
2152 When HASSECURITY is defined,
2154 will allow only the root user to list all open files.
2155 The non\-root user may list only open files of processes with the same user
2156 IDentification number as the real user ID number of the
2158 process (the one that its user logged on with).
2160 However, if HASSECURITY and HASNOSOCKSECURITY are both defined,
2161 anyone may list open socket files, provided they are selected
2166 When HASSECURITY is not defined, anyone may list all open files.
2168 Help output, presented in response to the
2172 option, gives the status of the HASSECURITY and HASNOSOCKSECURITY definitions.
2180 distribution for information on building
2182 with the HASSECURITY and HASNOSOCKSECURITY options enabled.
2184 Creation and use of a user\-readable and user\-writable device
2185 cache file is controlled by the compile\-time HASDCACHE option.
2187 .B "DEVICE CACHE FILE"
2188 section and the sections that follow it for details on how its path
2190 For security considerations it is important to note that in the default
2192 distribution, if the real user ID under which
2194 is executed is root, the device cache file will be written in root's
2195 home directory \- e.g.,
2199 When HASDCACHE is not defined,
2201 does not write or attempt to read a device cache file.
2203 When HASDCACHE is defined, the
2205 help output, presented in response to the
2210 options, will provide device cache file handling information.
2211 When HASDCACHE is not defined, the
2219 Before you decide to disable the device cache file feature \- enabling
2220 it improves the performance of
2222 by reducing the startup overhead of examining all the nodes in
2226 \&\- read the discussion of it in the
2230 distribution and the
2232 FAQ (The \fBFAQ\fP section gives its location.)
2234 WHEN IN DOUBT, YOU CAN TEMPORARILY DISABLE THE USE OF THE DEVICE CACHE FILE
2241 user declares alternate kernel name list or memory files with the
2247 checks the user's authority to read them with
2249 This is intended to prevent whatever special power
2251 modes might confer on it from letting it read files not normally
2252 accessible via the authority of the real user ID.
2254 This section describes the information
2256 lists for each open file.
2258 .B "OUTPUT FOR OTHER PROGRAMS"
2259 section for additional information on output that can be processed
2263 only outputs printable (declared so by
2266 Non\-printable characters are printed in one of three forms:
2267 the C ``\\[bfrnt]'' form;
2268 the control character `^' form (e.g., ``^@'');
2269 or hexadecimal leading ``\\x'' form (e.g., ``\\xab'').
2270 Space is non\-printable in the COMMAND column (``\\x20'')
2271 and printable elsewhere.
2273 For some dialects \- if HASSETLOCALE is defined in the dialect's
2274 machine.h header file \-
2276 will print the extended 8 bit characters of a language locale.
2279 process must be supplied a language locale environment variable
2280 (e.g., LANG) whose value represents a known language locale
2281 in which the extended characters are considered printable by
2285 considers the extended characters non\-printable and prints them according
2286 to its rules for non\-printable characters, stated above.
2287 Consult your dialect's
2289 man page for the names of other environment variables that may
2290 be used in place of LANG \- e.g., LC_ALL, LC_CTYPE, etc.
2293 language locale support for a dialect also covers wide characters \- e.g.,
2294 UTF-8 \- when HASSETLOCALE and HASWIDECHAR are defined in the dialect's
2295 machine.h header file, and when a suitable language locale has been defined
2296 in the appropriate environment variable for the
2299 Wide characters are printable under those conditions if
2302 If HASSETLOCALE, HASWIDECHAR and a suitable language locale aren't defined,
2305 reports wide characters that aren't printable,
2307 considers the wide characters non\-printable and prints each of their
2308 8 bits according to its rules for non\-printable characters, stated above.
2310 Consult the answers to the "Language locale support" questions in the
2311 lsof FAQ (The \fBFAQ\fP section gives its location.) for more information.
2314 dynamically sizes the output columns each time it runs, guaranteeing
2315 that each column is a minimum size.
2316 It also guarantees that each column is separated from its predecessor
2317 by at least one space.
2320 contains the first nine characters of the name of the UNIX command
2321 associated with the process.
2324 value is specified to the
2326 option, the column contains the first
2328 characters of the name of the UNIX command associated with the process
2329 up to the limit of characters supplied to
2331 by the UNIX dialect.
2332 (See the description of the
2336 FAQ for more information.
2337 The \fBFAQ\fP section gives its location.)
2341 is less than the length of the column title, ``COMMAND'', it will
2342 be raised to that length.
2346 value is specified to the
2348 option, the column contains all the characters of the name of the UNIX command
2349 associated with the process.
2351 All command name characters maintained by the kernel in its structures
2352 are displayed in field output when the command name descriptor (`c')
2355 .B "OUTPUT FOR OTHER COMMANDS"
2356 section for information on selecting field output and the associated
2357 command name descriptor.
2360 is the Process IDentification number of the process.
2363 is the task (thread) IDentification number, if task (thread)
2364 reporting is supported by the dialect and a task (thread) is
2366 (If help output \- i.e., the output of the
2370 options \- shows this option, then task (thread) reporting is
2371 supported by the dialect.)
2373 A blank TID column in Linux indicates a process \- i.e., a non\-task.
2376 is the task command name.
2377 Generally this will be the same as the process named in the COMMAND
2378 column, but some task implementations (e.g., Linux) permit a task to
2379 change its command name.
2381 The TASKCMD column width is subject to the same size limitation as the
2385 is the Solaris 10 and higher zone name.
2386 This column must be selected with the
2391 is the SELinux security context.
2392 This column must be selected with the
2397 option is inhibited when SELinux is disabled in the running Linux
2401 is the Parent Process IDentification number of the process.
2402 It is only displayed when the
2404 option has been specified.
2407 is the process group IDentification number associated with
2409 It is only displayed when the
2411 option has been specified.
2414 is the user ID number or login name of the user to whom
2415 the process belongs, usually the same as reported by
2417 However, on Linux USER is the user ID number or login that owns
2418 the directory in /proc where
2420 finds information about the process.
2421 Usually that is the same value reported by
2423 but may differ when the process has changed its effective user ID.
2426 option description for information on when a user ID number or
2427 login name is displayed.)
2430 is the File Descriptor number of the file or:
2433 \fBcwd\fP current working directory;
2435 \fBL\fInn\fR library references (AIX);
2437 \fBerr\fR FD information error (see NAME column);
2439 \fBjld\fR jail directory (FreeBSD);
2441 \fBltx\fP shared library text (code and data);
2443 \fBMxx\fP hex memory\-mapped type number xx.
2445 \fBm86\fP DOS Merge mapped file;
2447 \fBmem\fP memory\-mapped file;
2449 \fBmmap\fP memory\-mapped device;
2451 \fBpd\fP parent directory;
2453 \fBrtd\fP root directory;
2455 \fBtr\fR kernel trace file (OpenBSD);
2457 \fBtxt\fP program text (code and data);
2459 \fBv86\fP VP/ix mapped file;
2462 FD is followed by one of these characters, describing the mode under which
2465 \fBr\fP for read access;
2467 \fBw\fP for write access;
2469 \fBu\fP for read and write access;
2471 space if mode unknown and no lock
2475 `\-' if mode unknown and lock
2479 The mode character is followed by one of these lock characters, describing
2480 the type of lock applied to the file:
2482 \fBN\fP for a Solaris NFS lock of unknown type;
2484 \fBr\fP for read lock on part of the file;
2486 \fBR\fP for a read lock on the entire file;
2488 \fBw\fP for a write lock on part of the file;
2490 \fBW\fP for a write lock on the entire file;
2492 \fBu\fP for a read and write lock of any length;
2494 \fBU\fP for a lock of unknown type;
2496 \fBx\fP for an SCO OpenServer Xenix lock on part
2499 \fBX\fP for an SCO OpenServer Xenix lock on the entire file;
2501 space if there is no lock.
2505 section for more information on the lock information character.
2507 The FD column contents constitutes a single field for parsing in
2508 post\-processing scripts.
2511 is the type of the node associated with the file \- e.g., GDIR, GREG,
2514 or ``IPv4'' for an IPv4 socket;
2516 or ``IPv6'' for an open IPv6 network file \- even if its address is
2517 IPv4, mapped in an IPv6 address;
2519 or ``ax25'' for a Linux AX.25 socket;
2521 or ``inet'' for an Internet domain socket;
2523 or ``lla'' for a HP\-UX link level access file;
2525 or ``rte'' for an AF_ROUTE socket;
2527 or ``sock'' for a socket of unknown domain;
2529 or ``unix'' for a UNIX domain socket;
2531 or ``x.25'' for an HP\-UX x.25 socket;
2533 or ``BLK'' for a block special file;
2535 or ``CHR'' for a character special file;
2537 or ``DEL'' for a Linux map file that has been deleted;
2539 or ``DIR'' for a directory;
2541 or ``DOOR'' for a VDOOR file;
2543 or ``FIFO'' for a FIFO special file;
2545 or ``KQUEUE'' for a BSD style kernel event queue file;
2547 or ``LINK'' for a symbolic link file;
2549 or ``MPB'' for a multiplexed block file;
2551 or ``MPC'' for a multiplexed character file;
2553 or ``NOFD'' for a Linux /proc/<PID>/fd directory that can't be opened \--
2554 the directory path appears in the NAME column, followed by an error
2573 or ``PCUR'' for the current
2579 current working directory;
2587 executable type (\fIetype\fP);
2595 file descriptor directory;
2597 or ``PFIL'' for an executable
2611 group notifier file;
2613 or ``PIPE'' for pipes;
2661 map file (\fImap\fP);
2669 process notifier file;
2679 or ``POLP'' for an old format
2681 light weight process file;
2683 or ``POPF'' for an old format
2687 or ``POPG'' for an old format
2691 or ``PORT'' for a SYSV named pipe;
2717 or ``PSXSEM'' for a POSIX semaphore file;
2719 or ``PSXSHM'' for a POSIX shared memory file;
2737 or ``REG'' for a regular file;
2739 or ``SMT'' for a shared memory transport file;
2741 or ``STSO'' for a stream socket;
2743 or ``UNNM'' for an unnamed type file;
2745 or ``XNAM'' for an OpenServer Xenix special file of unknown type;
2747 or ``XSEM'' for an OpenServer Xenix semaphore file;
2749 or ``XSD'' for an OpenServer Xenix shared data file;
2751 or the four type number octets if the corresponding name isn't known.
2754 contains the kernel file structure address when
2756 has been specified to
2760 contains the file reference count from the kernel file structure when
2762 has been specified to
2770 has been specified to
2772 this field contains the contents of the f_flag[s] member of the kernel
2773 file structure and the kernel's per\-process open file flags (if available);
2774 \&`G' causes them to be displayed in hexadecimal;
2775 \&`g', as short\-hand names;
2776 two lists may be displayed with entries separated by commas, the
2777 lists separated by a semicolon (`;');
2778 the first list may contain short\-hand names for f_flag[s] values from
2779 the following table:
2782 AIO asynchronous I/O (e.g., FAIO)
2784 ASYN asynchronous I/O (e.g., FASYNC)
2785 BAS block, test, and set in use
2786 BKIU block if in use
2787 BL use block offsets
2800 DSYN data\-only integrity
2801 DTY must be a directory
2805 FSYN synchronous writes
2806 GCDF defer during unp_gc() (AIX)
2807 GCMK mark during unp_gc() (AIX)
2808 GTTY accessed via /dev/tty
2811 KIOC kernel\-issued ioctl
2814 MBLK stream message block
2817 MSYN multiplex synchronization
2818 NATM don't update atime
2819 NB non\-blocking I/O
2821 NBIO SYSV non\-blocking I/O
2822 NBF n\-buffering in effect
2825 NDSY no data synchronization
2827 NFLK don't follow links
2829 NOTO disable background stop
2831 NTTY no controlling TTY
2833 PAIO POSIX asynchronous I/O
2836 RC file and record locking cache
2839 RSYN read synchronization
2840 RW read and write access
2842 SNAP cooked snapshot
2844 SQSH Sequent shared set on open
2845 SQSV Sequent SVM set on open
2846 SQR Sequent set repair on open
2847 SQS1 Sequent full shared open
2848 SQS2 Sequent partial shared open
2850 SWR synchronous read
2851 SYN file integrity while writing
2852 TCPM avoid TCP collision
2855 WKUP parallel I/O synchronization
2856 WTG parallel I/O synchronization
2862 this list of names was derived from F* #define's in dialect header files
2863 <fcntl.h>, <linux</fs.h>, <sys/fcntl.c>, <sys/fcntlcom.h>, and <sys/file.h>;
2864 see the lsof.h header file for a list showing the correspondence
2865 between the above short\-hand names and the header file definitions;
2867 the second list (after the semicolon) may contain short\-hand names
2868 for kernel per\-process open file flags from this table:
2872 BR the file has been read
2873 BHUP activity stopped by SIGHUP
2874 BW the file has been written
2876 CX close\-on-exec (see fcntl(F_SETFD))
2877 LCK lock was applied
2879 OPIP open pending \- in progress
2881 SHMT UF_FSHMAT set (AIX)
2882 USE in use (multi\-threaded)
2886 (or INODE\-ADDR for some dialects)
2887 contains a unique identifier for the file node (usually the kernel
2888 vnode or inode address, but also occasionally a concatenation of
2889 device and node number) when
2891 has been specified to
2895 contains the device numbers, separated by commas, for a character special,
2896 block special, regular, directory or NFS file;
2898 or ``memory'' for a memory file system node under Tru64 UNIX;
2900 or the address of the private data area of a Solaris socket
2903 or a kernel reference address that identifies the file
2904 (The kernel reference address may be used for FIFO's, for example.);
2907 the base address or device name of a Linux AX.25 socket device.
2909 Usually only the lower thirty two bits of Tru64 UNIX kernel addresses
2912 SIZE, SIZE/OFF, or OFFSET
2913 is the size of the file or the file offset in bytes.
2914 A value is displayed in this column only if it is available.
2916 displays whatever value \- size or offset \- is appropriate for the type
2917 of the file and the version of
2920 On some UNIX dialects
2922 can't obtain accurate or consistent file offset information from its
2923 kernel data sources, sometimes just for particular kinds of files
2924 (e.g., socket files.)
2925 In other cases, files don't have true sizes \- e.g., sockets, FIFOs,
2928 displays for their sizes the content amounts it finds in their kernel
2929 buffer descriptors (e.g., socket buffer size counts or TCP/IP window
2933 FAQ (The \fBFAQ\fP section gives its location.)
2934 for more information.
2936 The file size is displayed in decimal;
2937 the offset is normally displayed in decimal with a leading ``0t'' if
2938 it contains 8 digits or less; in hexadecimal with a leading ``0x'' if
2939 it is longer than 8 digits.
2942 option description for information on when 8 might default to
2945 Thus the leading ``0t'' and ``0x'' identify an offset when the column
2946 may contain both a size and an offset (i.e., its title is SIZE/OFF).
2950 option is specified,
2952 always displays the file offset (or nothing if no offset is available)
2953 and labels the column OFFSET.
2954 The offset always begins with ``0t'' or ``0x'' as described above.
2958 user can control the switch from ``0t'' to ``0x'' with the
2961 Consult its description for more information.
2965 option is specified,
2967 always displays the file size (or nothing if no size is available)
2968 and labels the column SIZE.
2973 options are mutually exclusive; they can't both be specified.
2975 For files that don't have a fixed size \- e.g., don't reside
2978 will display appropriate information about the current size or
2979 position of the file if it is available in the kernel structures
2980 that define the file.
2983 contains the file link count when
2988 is the node number of a local file;
2990 or the inode number of an NFS file in the server host;
2992 or the Internet protocol type \- e.g, ``TCP'';
2994 or ``STR'' for a stream;
2996 or ``CCITT'' for an HP\-UX x.25 socket;
2998 or the IRQ or inode number of a Linux AX.25 socket device.
3001 is the name of the mount point and file system on which the file resides;
3003 or the name of a file specified in the
3005 option (after any symbolic links have been resolved);
3007 or the name of a character special or block special device;
3009 or the local and remote Internet addresses of a network file;
3010 the local host name or IP number is followed by a colon (':'), the
3011 port, ``->'', and the two\-part remote address;
3012 IP addresses may be reported as numbers or names, depending on the
3018 colon\-separated IPv6 numbers are enclosed in square brackets;
3019 IPv4 INADDR_ANY and IPv6 IN6_IS_ADDR_UNSPECIFIED addresses, and
3020 zero port numbers are represented by an asterisk ('*');
3021 a UDP destination address may be followed by the amount of time
3022 elapsed since the last packet was sent to the destination;
3023 TCP, UDP and UDPLITE remote addresses may be followed by TCP/TPI
3024 information in parentheses \- state (e.g., ``(ESTABLISHED)'', ``(Unbound)''),
3025 queue sizes, and window sizes (not all dialects) \- in a fashion
3031 option description or the description of the TCP/TPI field in
3032 .B "OUTPUT FOR OTHER PROGRAMS"
3033 for more information on state, queue size, and window size;
3035 or the address or name of a UNIX domain socket, possibly including
3036 a stream clone device name, a file system object's path name, local
3037 and foreign kernel addresses, socket pair information, and a bound
3040 or the local and remote mount point names of an NFS file;
3042 or ``STR'', followed by the stream name;
3044 or a stream character device name, followed by ``->'' and the stream name
3045 or a list of stream module names, separated by ``->'';
3047 or ``STR:'' followed by the SCO OpenServer stream device and module
3048 names, separated by ``->'';
3050 or system directory name, `` -- '', and as many components of the path
3053 can find in the kernel's name cache for selected dialects
3055 .B "KERNEL NAME CACHE"
3056 section for more information.);
3058 or ``PIPE->'', followed by a Solaris kernel pipe destination address;
3060 or ``COMMON:'', followed by the vnode device information structure's
3061 device name, for a Solaris common vnode;
3063 or the address family, followed by a slash (`/'), followed by fourteen
3064 comma\-separated bytes of a non\-Internet raw socket address;
3066 or the HP\-UX x.25 local address, followed by the virtual connection
3067 number (if any), followed by the remote address (if any);
3069 or ``(dead)'' for disassociated Tru64 UNIX files \- typically terminal files
3070 that have been flagged with the TIOCNOTTY ioctl and closed by daemons;
3072 or ``rd=<offset>'' and ``wr=<offset>'' for the values of the
3073 read and write offsets of a FIFO;
3075 or ``clone \fIn\fP:/dev/event'' for SCO OpenServer file clones of the
3079 is the minor device number of the file;
3081 or ``(socketpair: n)'' for a Solaris 2.6, 8, 9 or 10
3082 UNIX domain socket, created by the
3086 or ``no PCB'' for socket files that do not have a protocol block
3087 associated with them, optionally followed by ``, CANTSENDMORE'' if
3088 sending on the socket has been disabled, or ``, CANTRCVMORE'' if
3089 receiving on the socket has been disabled (e.g., by the
3093 or the local and remote addresses of a Linux IPX socket file
3094 in the form <net>:[<node>:]<port>, followed in parentheses
3095 by the transmit and receive queue sizes, and the connection state;
3097 or ``dgram'' or ``stream'' for the type UnixWare 7.1.1 and above in\-kernel
3098 UNIX domain sockets, followed by a colon (':') and the local path name
3099 when available, followed by ``->'' and the remote path name or kernel
3100 socket address in hexadecimal when available;
3102 or the association value, association index, endpoint value, local address,
3103 local port, remote address and remote port for Linux SCTP sockets;
3105 or ``protocol: '' followed by the Linux socket's protocol attribute.
3107 For dialects that support a ``namefs'' file system, allowing one
3108 file to be attached to another with
3111 will add ``(FA:<address1><direction><address2>)'' to the NAME column.
3112 <address1> and <address2> are hexadecimal vnode addresses.
3113 <direction> will be ``<-'' if <address2> has been fattach'ed to
3114 this vnode whose address is <address1>;
3115 and ``->'' if <address1>, the vnode address of this vnode, has been
3116 fattach'ed to <address2>.
3117 <address1> may be omitted if it already appears in the DEVICE column.
3121 may add two parenthetical notes to the NAME column for open Solaris 10 files:
3124 considers the path name of questionable accuracy;
3125 and ``(deleted)'' if the
3127 option has been specified and
3129 detects the open file's path name has been deleted.
3132 FAQ (The \fBFAQ\fP section gives its location.)
3133 for more information on these NAME column additions.
3136 can't adequately report the wide variety of UNIX dialect file locks
3137 in a single character.
3138 What it reports in a single character is a compromise between the
3139 information it finds in the kernel and the limitations of the reporting
3142 Moreover, when a process holds several byte level locks on a file,
3144 only reports the status of the first lock it encounters.
3145 If it is a byte level lock, then the lock character will be reported
3146 in lower case \- i.e., `r', `w', or `x' \- rather than the upper case
3147 equivalent reported for a full file lock.
3151 can only report on locks held by local processes on local files.
3152 When a local process sets a lock on a remotely mounted (e.g., NFS)
3153 file, the remote server host usually records the lock state.
3154 One exception is Solaris \- at some patch levels of 2.3, and in all
3155 versions above 2.4, the Solaris kernel records information on remote
3156 locks in local structures.
3159 has trouble reporting locks for some UNIX dialects.
3162 section of this manual page or the
3164 FAQ (The \fBFAQ\fP section gives its location.)
3165 for more information.
3166 .SH "OUTPUT FOR OTHER PROGRAMS"
3169 option is specified,
3171 produces output that is suitable for processing by another program \- e.g, an
3175 script, or a C program.
3177 Each unit of information is output in a field that is identified
3178 with a leading character and terminated by a NL (012) (or a NUL
3179 (000) if the 0 (zero) field identifier character is specified.)
3180 The data of the field follows immediately after the field identification
3181 character and extends to the field terminator.
3183 It is possible to think of field output as process and file sets.
3184 A process set begins with a field whose identifier is `p' (for
3185 process IDentifier (PID)).
3186 It extends to the beginning of the next PID field or the beginning
3187 of the first file set of the process, whichever comes first.
3188 Included in the process set are fields that identify the command,
3189 the process group IDentification (PGID) number, the task (thread)
3190 ID (TID), and the user ID (UID) number or login name.
3192 A file set begins with a field whose identifier is `f' (for
3194 It is followed by lines that describe the file's access mode,
3195 lock state, type, device, size, offset, inode, protocol, name
3196 and stream module names.
3197 It extends to the beginning of the next file or process set,
3198 whichever comes first.
3200 When the NUL (000) field terminator has been selected with the
3201 0 (zero) field identifier character,
3203 ends each process and file set with a NL (012) character.
3206 always produces one field, the PID (`p') field.
3207 All other fields may be declared optionally in the field identifier
3208 character list that follows the
3211 When a field selection character identifies an item
3213 does not normally list \- e.g., PPID, selected with
3215 specification of the field character \- e.g., ``\fB\-FR\fP'' \-
3216 also selects the listing of the item.
3218 It is entirely possible to select a set of fields that cannot
3219 easily be parsed \- e.g., if the field descriptor field is not
3220 selected, it may be difficult to identify file sets.
3221 To help you avoid this difficulty,
3225 option; it selects the output of all fields with NL terminators
3228 option pair selects the output of all fields with NUL terminators).
3229 For compatibility reasons neither
3233 select the raw device field.
3235 These are the fields that
3238 The single character listed first is the field identifier.
3242 c process command name (all characters from proc or
3244 C file structure share count
3245 d file's device character code
3246 D file's major/minor device number (0x<hexadecimal>)
3247 f file descriptor (always selected)
3248 F file structure address (0x<hexadecimal>)
3249 G file flaGs (0x<hexadecimal>; names if \fB+fg\fP follows)
3251 i file's inode number
3254 l file's lock status
3255 L process login name
3256 m marker between repeated output
3257 M the task comMand name
3258 n file name, comment, Internet address
3259 N node identifier (ox<hexadecimal>
3260 o file's offset (decimal)
3261 p process ID (always selected)
3263 r raw device number (0x<hexadecimal>)
3265 s file's size (decimal)
3266 S file's stream identification
3268 T TCP/TPI information, identified by prefixes (the
3269 `=' is part of the prefix):
3270 QR=<read queue size>
3271 QS=<send queue size>
3272 SO=<socket options and values> (not all dialects)
3273 SS=<socket states> (not all dialects)
3274 ST=<connection state>
3275 TF=<TCP flags and values> (not all dialects)
3276 WR=<window read size> (not all dialects)
3277 WW=<window write size> (not all dialects)
3278 (TCP/TPI information isn't reported for all supported
3279 UNIX dialects. The \fB\-h\fP or \fB\-?\fP help output for the
3280 \fB\-T\fP option will show what TCP/TPI reporting can be
3283 z Solaris 10 and higher zone name
3284 Z SELinux security context (inhibited when SELinux is disabled)
3285 0 use NUL field terminator character in place of NL
3286 1\-9 dialect\-specific field identifiers (The output
3287 of \fB\-F?\fP identifies the information to be found
3288 in dialect\-specific fields.)
3291 You can get on\-line help information on these characters and their
3292 descriptions by specifying the
3295 (Escape the `?' character as your shell requires.)
3296 Additional information on field content can be found in the
3300 As an example, ``\fB\-F pcfn\fP'' will select the process ID (`p'),
3301 command name (`c'), file descriptor (`f') and file name (`n')
3302 fields with an NL field terminator character; ``\fB\-F pcfn0\fP''
3303 selects the same output with a NUL (000) field terminator character.
3306 doesn't produce all fields for every process or file set, only
3307 those that are available.
3308 Some fields are mutually exclusive: file device characters and
3309 file major/minor device numbers; file inode number and protocol
3310 name; file name and stream identification; file size and offset.
3311 One or the other member of these mutually exclusive sets will appear
3312 in field output, but not both.
3316 ends each field with a NL (012) character.
3318 0 (zero) field identifier character may be specified to change the
3319 field terminator character
3321 A NUL terminator may be easier to process with
3323 for example, or with programs whose quoting mechanisms may not
3324 easily cope with the range of characters in the field output.
3325 When the NUL field terminator is in use,
3327 ends each process and file set with a NL (012).
3329 Three aids to producing programs that can process
3331 field output are included in the
3334 The first is a C header file,
3336 that contains symbols for the field identification characters, indexes for
3337 storing them in a table, and explanation strings that may be compiled into
3340 uses this header file.
3342 The second aid is a set of sample scripts that process field output,
3349 They're located in the
3355 The third aid is the C library used for the
3358 The test suite is written in C and uses field output to validate
3359 the correct operation of
3361 The library can be found in the
3366 The library uses the first aid, the
3369 .SH "BLOCKS AND TIMEOUTS"
3371 can be blocked by some kernel functions that it uses \-
3376 These functions are stalled in the kernel, for example, when the
3377 hosts where mounted NFS file systems reside become inaccessible.
3380 attempts to break these blocks with timers and child processes,
3381 but the techniques are not wholly reliable.
3384 does manage to break a block, it will report the break with an error
3386 The messages may be suppressed with the
3392 The default timeout value may be displayed with the
3396 option, and it may be changed with the
3401 is two seconds, but you should avoid small values, since slow system
3402 responsiveness can cause short timeouts to expire unexpectedly and
3405 before it can produce any output.
3409 has to break a block during its access of mounted file system
3410 information, it normally continues, although with less information
3411 available to display about open files.
3414 can also be directed to avoid the protection of timers and child processes
3415 when using the kernel functions that might block by specifying the
3418 While this will allow
3420 to start up with less overhead, it exposes
3422 completely to the kernel situations that might block it.
3423 Use this option cautiously.
3424 .SH "AVOIDING KERNEL BLOCKS"
3430 to avoid using kernel functions that would block.
3431 Some cautions apply.
3433 First, using this option usually requires that your system supply
3434 alternate device numbers in place of the device numbers that
3436 would normally obtain with the
3442 .B "ALTERNATE DEVICE NUMBERS"
3443 section for more information on alternate device numbers.
3445 Second, you can't specify
3449 to locate unless they're file system names.
3452 needs to know the device and inode numbers of files listed with
3460 from obtaining them.
3463 only has device numbers for the file systems that have alternates,
3464 its ability to locate files on file systems depends completely on the
3465 availability and accuracy of the alternates.
3466 If no alternates are available, or if they're incorrect,
3468 won't be able to locate files on the named file systems.
3470 Third, if the names of your file system directories that
3472 obtains from your system's mount table are symbolic links,
3474 won't be able to resolve the links.
3481 function it uses to resolve symbolic links.
3487 to issue warning messages when it needs to use the kernel functions
3490 option directs it to avoid.
3491 You can suppress these messages by specifying the
3493 option, but if you do, you won't see the alternate device numbers
3494 reported in the warning messages.
3495 .SH "ALTERNATE DEVICE NUMBERS"
3497 On some dialects, when
3499 has to break a block because it can't get information about a
3500 mounted file system via the
3504 kernel functions, or because you specified the
3508 can obtain some of the information it needs \- the device number and
3509 possibly the file system type \- from the system mount table.
3510 When that is possible,
3512 will report the device number it obtained.
3513 (You can suppress the report by specifying the
3517 You can assist this process if your mount table is supported with an
3521 file that contains an options field by adding a ``dev=xxxx'' field for
3522 mount points that do not have one in their options strings.
3523 Note: you must be able to edit the file \- i.e., some mount tables
3524 like recent Solaris /etc/mnttab or Linux /proc/mounts are read\-only
3525 and can't be modified.
3527 You may also be able to supply device numbers using the
3531 options, provided they are supported by your dialect.
3537 options to see if the
3541 options are available.
3543 The ``xxxx'' portion of the field is the hexadecimal value
3544 of the file system's device number.
3547 field of the output of the
3551 functions for the appropriate values for your file systems.)
3552 Here's an example from a Sun Solaris 2.6
3554 for a file system remotely mounted via NFS:
3557 nfs ignore,noquota,dev=2a40001
3560 There's an advantage to having ``dev=xxxx'' entries in your mount
3561 table file, especially for file systems that are mounted from remote
3563 When a remote server crashes and you want to identify its users by running
3565 on one of its clients,
3567 probably won't be able to get output from the
3571 functions for the file system.
3572 If it can obtain the file system's device number from the mount table,
3573 it will be able to display the files open on the crashed NFS server.
3575 Some dialects that do not use an ASCII
3579 file for the mount table may still provide an alternative device number
3580 in their internal mount tables.
3581 This includes AIX, Apple Darwin, FreeBSD, NetBSD, OpenBSD, and Tru64 UNIX.
3583 knows how to obtain the alternative device number for these dialects
3584 and uses it when its attempt to
3588 the file system is blocked.
3590 If you're not sure your dialect supplies alternate device numbers
3591 for file systems from its mount table, use this
3593 incantation to see if it reports any alternate device numbers:
3598 Look for standard error file warning messages that
3599 begin ``assuming "dev=xxxx" from ...''.
3600 .SH "KERNEL NAME CACHE"
3603 is able to examine the kernel's name cache or use other kernel
3604 facilities (e.g., the ADVFS 4.x tag_to_path() function under
3605 Tru64 UNIX) on some dialects for most file system types,
3606 excluding AFS, and extract recently used path name components from it.
3607 (AFS file system path lookups don't use the kernel's name cache; some
3608 Solaris VxFS file system operations apparently don't use it, either.)
3611 reports the complete paths it finds in the NAME column.
3614 can't report all components in a path, it reports in the NAME column
3615 the file system name, followed by a space, two `-' characters, another
3616 space, and the name components it has located, separated by
3621 is run in repeat mode \- i.e., with the
3623 option specified \- the extent to which it can report path name
3624 components for the same file may vary from cycle to cycle.
3625 That's because other running processes can cause the kernel to
3626 remove entries from its name cache and replace them with others.
3629 use of the kernel name cache to identify the paths of files
3630 can lead it to report incorrect components under some circumstances.
3631 This can happen when the kernel name cache uses device and node
3632 number as a key (e.g., SCO OpenServer) and a key on a rapidly
3633 changing file system is reused.
3634 If the UNIX dialect's kernel doesn't purge the name cache entry for
3635 a file when it is unlinked,
3637 may find a reference to the wrong entry in the cache.
3640 FAQ (The \fBFAQ\fP section gives its location.)
3641 has more information on this situation.
3644 can report path name components for these dialects:
3655 SCO|Caldera UnixWare
3661 can't report path name components for these dialects:
3667 If you want to know why
3669 can't report path name components for some dialects, see the
3671 FAQ (The \fBFAQ\fP section gives its location.)
3672 .SH "DEVICE CACHE FILE"
3674 Examining all members of the
3680 functions can be time consuming.
3681 What's more, the information that
3683 needs \- device number, inode number, and path \- rarely changes.
3687 normally maintains an ASCII text file of cached
3691 information (exception: the /proc\-based Linux
3693 where it's not needed.)
3694 The local system administrator who builds
3696 can control the way the device cache file path is formed, selecting
3700 Path from the \fB\-D\fP option;
3701 Path from an environment variable;
3703 Personal path (the default);
3704 Personal path, modified by an environment variable.
3707 Consult the output of the
3712 help options for the current state of device cache support.
3713 The help output lists the default read\-mode device cache file path that
3714 is in effect for the current invocation of
3718 option output lists the read\-only and write device cache file paths,
3719 the names of any applicable environment variables, and the personal
3720 device cache path format.
3723 can detect that the current device cache file has been accidentally
3724 or maliciously modified by integrity checks, including the computation
3725 and verification of a sixteen bit Cyclic Redundancy Check (CRC) sum on
3726 the file's contents.
3729 senses something wrong with the file, it issues a warning and attempts
3730 to remove the current cache file and create a new copy, but only to
3731 a path that the process can legitimately write.
3733 The path from which a
3735 process may attempt to read a device cache file may not be the same
3736 as the path to which it can legitimately write.
3739 senses that it needs to update the device cache file, it may
3740 choose a different path for writing it from the path from which
3741 it read an incorrect or outdated version.
3745 option will inhibit the writing of a new device cache file.
3746 (It's always available when specified without a path name argument.)
3748 When a new device is added to the system, the device cache file may
3749 need to be recreated.
3752 compares the mtime of the device cache file with the mtime and ctime
3757 directory, it usually detects that a new device has been added;
3760 issues a warning message and attempts to rebuild the device cache file.
3764 writes a device cache file, it sets its ownership to the real UID
3765 of the executing process, and its permission modes to 0600, this
3766 restricting its reading and writing to the file's owner.
3767 .SH "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
3769 Two permissions of the
3771 executable affect its ability to access device cache files.
3772 The permissions are set by the local system administrator when
3776 The first and rarer permission is setuid\-root.
3777 It comes into effect when
3779 is executed; its effective UID is then
3780 root, while its real (i.e., that of the logged\-on user) UID is not.
3783 distribution recommends that versions for these dialects run setuid\-root.
3786 HP-UX 11.11 and 11.23
3790 The second and more common permission is setgid.
3791 It comes into effect when the effective group IDentification number (GID)
3794 process is set to one that can access kernel memory devices \-
3795 e.g., ``kmem'', ``sys'', or ``system''.
3799 process that has setgid permission usually surrenders the permission
3800 after it has accessed the kernel memory devices.
3803 can allow more liberal device cache path formations.
3806 distribution recommends that versions for these dialects run setgid
3807 and be allowed to surrender setgid permission.
3810 AIX 5.[12] and 5.3-ML1
3811 Apple Darwin 7.x Power Macintosh systems
3812 FreeBSD 4.x, 4.1x, 5.x and [6789].x for x86-based systems
3813 FreeBSD 5.x, [6789].x and 1[012].8for Alpha, AMD64 and Sparc64
3816 NetBSD 1.[456], 2.x and 3.x for Alpha, x86, and SPARC-based
3818 NEXTSTEP 3.[13] for NEXTSTEP architectures
3819 OpenBSD 2.[89] and 3.[0\-9] for x86-based systems
3821 SCO OpenServer Release 5.0.6 for x86-based systems
3822 SCO|Caldera UnixWare 7.1.4 for x86-based systems
3823 Solaris 2.6, 8, 9 and 10
3829 for AIX 5L and above needs setuid\-root permission if its
3834 for these dialects does not support a device cache, so the permissions
3835 given to the executable don't apply to the device cache file.
3840 .SH "DEVICE CACHE FILE PATH FROM THE \-D OPTION"
3844 option provides limited means for specifying the device cache file path.
3847 function will report the read\-only and write device cache file paths that
3857 functions are available, you can use them to request that the cache file be
3858 built in a specific location (\fBb\fR[\fIpath\fR]);
3859 read but not rebuilt (\fBr\fR[\fIpath\fR]);
3860 or read and rebuilt (\fBu\fR[\fIpath\fR]).
3866 functions are restricted under some conditions.
3867 They are restricted when the
3869 process is setuid\-root.
3870 The path specified with the
3872 function is always read\-only, even
3873 when it is available.
3880 functions are also restricted when the
3882 process runs setgid and
3884 doesn't surrender the setgid permission.
3886 .B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
3887 section for a list of implementations that normally don't surrender
3888 their setgid permission.)
3894 (for ignore), is always available.
3900 to read device information from the kernel with the
3902 function and build a device cache file at the indicated path.
3908 to read the device cache file, but not update it.
3909 When a path argument accompanies
3911 it names the device cache file path.
3914 function is always available when it is specified without a
3918 is not running setuid\-root and surrenders its setgid permission,
3919 a path name argument may accompany the
3927 to attempt to read and use the device cache file.
3928 If it can't read the file, or if it finds the contents of the
3929 file incorrect or outdated, it will read information from the kernel,
3930 and attempt to write an updated version of the device cache file,
3931 but only to a path it considers legitimate for the
3933 process effective and real UIDs.
3934 .SH "DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE"
3937 second choice for the device cache file is the contents of the
3938 LSOFDEVCACHE environment variable.
3939 It avoids this choice if the
3941 process is setuid\-root, or the real UID of the process is root.
3943 A further restriction applies to a device cache file path taken from
3944 the LSOFDEVCACHE environment variable:
3946 will not write a device cache file to the path if the
3948 process doesn't surrender its setgid permission.
3950 .B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
3951 section for information on implementations that don't surrender
3952 their setgid permission.)
3954 The local system administrator can disable the use of the LSOFDEVCACHE
3955 environment variable or change its name when building
3957 Consult the output of
3959 for the environment variable's name.
3960 .SH "SYSTEM-WIDE DEVICE CACHE PATH"
3962 The local system administrator may choose to have a system\-wide
3963 device cache file when building
3965 That file will generally be constructed by a special system administration
3966 procedure when the system is booted or when the contents of
3973 third device cache file path choice.
3975 You can tell that a system\-wide device cache file is in effect
3976 for your local installation by examining the
3978 help option output \- i.e., the output from the
3985 will never write to the system\-wide device cache file path by
3987 It must be explicitly named with a
3989 function in a root\-owned procedure.
3990 Once the file has been written, the procedure must change its permission
3991 modes to 0644 (owner\-read and owner\-write, group\-read, and other\-read).
3992 .SH "PERSONAL DEVICE CACHE PATH (DEFAULT)"
3994 The default device cache file path of the
3996 distribution is one recorded in the home directory of the real UID
3999 Added to the home directory is a second path component of the form
4000 .IR .lsof_hostname .
4004 fourth device cache file path choice, and is
4005 usually the default.
4006 If a system\-wide device cache file path was defined when
4009 this fourth choice will be applied when
4011 can't find the system\-wide device cache file.
4016 uses two paths when reading the device cache file.
4020 part of the second component is the base
4021 name of the executing host, as returned by
4022 .IR gethostname (2).
4023 The base name is defined to be the characters preceding the first `.'
4028 output if it contains no `.'.
4030 The device cache file belongs to the user ID and is readable and
4031 writable by the user ID alone \- i.e., its modes are 0600.
4032 Each distinct real user ID on a given host that executes
4034 has a distinct device cache file.
4037 part of the path distinguishes device cache files in an NFS\-mounted
4038 home directory into which device cache files are written from
4039 several different hosts.
4041 The personal device cache file path formed by this method represents
4042 a device cache file that
4044 will attempt to read, and will attempt to write should it not
4045 exist or should its contents be incorrect or outdated.
4049 option without a path name argument will inhibit the writing of a new
4054 option will list the format specification for constructing the
4055 personal device cache file.
4056 The conversions used in the format specification are described in the
4061 .SH "MODIFIED PERSONAL DEVICE CACHE PATH"
4063 If this option is defined by the local system administrator when
4065 is built, the LSOFPERSDCPATH environment variable contents may
4066 be used to add a component of the personal device cache file path.
4068 The LSOFPERSDCPATH variable contents are inserted in the path at the
4069 place marked by the local system administrator with the ``%p''
4070 conversion in the HASPERSDC format specification of the dialect's
4073 (It's placed right after the home directory in the default
4077 Thus, for example, if LSOFPERSDCPATH contains ``LSOF'', the home
4078 directory is ``/Homes/abe'', the host name is ``lsof.itap.purdue.edu'',
4079 and the HASPERSDC format is the default (``%h/%p.lsof_%L''), the
4080 modified personal device cache file path is:
4083 /Homes/abe/LSOF/.lsof_vic
4086 The LSOFPERSDCPATH environment variable is ignored when the
4088 process is setuid\-root or when the real UID of the process is root.
4091 will not write to a modified personal device cache file path if the
4093 process doesn't surrender setgid permission.
4095 .B "LSOF PERMISSIONS THAT AFFECT DEVICE CACHE FILE ACCESS"
4096 section for a list of implementations that normally don't surrender
4097 their setgid permission.)
4099 If, for example, you want to create a sub\-directory of personal
4100 device cache file paths by using the LSOFPERSDCPATH environment
4101 variable to name it, and
4103 doesn't surrender its setgid permission, you will have to allow
4105 to create device cache files at the standard personal path and
4106 move them to your subdirectory with shell commands.
4108 The local system administrator may: disable this option when
4110 is built; change the name of the environment variable from
4111 LSOFPERSDCPATH to something else; change the HASPERSDC
4112 format to include the personal path component in another place;
4113 or exclude the personal path component entirely.
4114 Consult the output of the
4116 option for the environment variable's name and the HASPERSDC
4117 format specification.
4119 Errors are identified with messages on the standard error file.
4122 returns a one (1) if any error was detected, including the failure to
4123 locate command names, file names, Internet addresses or files, login
4124 names, NFS files, PIDs, PGIDs, or UIDs it was asked to list.
4127 option is specified,
4129 will indicate the search items it failed to list.
4131 It returns a zero (0) if no errors were detected and if it was able to
4132 list some information about all the specified search arguments.
4137 cannot open access to
4141 or one of its subdirectories, or get information on a file in them with
4143 it issues a warning message and continues.
4146 will issue warning messages about inaccessible files in
4150 is indicated in its help output \- requested with the
4154 options \- with the message:
4157 Inaccessible /dev warnings are enabled.
4160 The warning message may be suppressed with the
4163 It may also have been suppressed by the system administrator when
4165 was compiled by the setting of the WARNDEVACCESS definition.
4166 In this case, the output from the help options will include the message:
4169 Inaccessible /dev warnings are disabled.
4172 Inaccessible device warning messages usually disappear after
4174 has created a working device cache file.
4176 For a more extensive set of examples, documented more fully, see the
4182 To list all open files, use:
4186 To list all open Internet, x.25 (HP\-UX), and UNIX domain files, use:
4190 To list all open IPv4 network files in use by the process whose PID is
4193 lsof -i 4 -a -p 1234
4195 Presuming the UNIX dialect supports IPv6, to list only open IPv6
4200 To list all files using any protocol on ports 513, 514, or 515 of host
4201 wonderland.cc.purdue.edu, use:
4203 lsof -i @wonderland.cc.purdue.edu:513-515
4205 To list all files using any protocol on any port of mace.cc.purdue.edu
4206 (cc.purdue.edu is the default domain), use:
4210 To list all open files for login name ``abe'', or user ID 1234, or
4211 process 456, or process 123, or process 789, use:
4213 lsof -p 456,123,789 -u 1234,abe
4215 To list all open files on device /dev/hd4, use:
4219 To find the process that has /u/abe/foo open, use:
4223 To send a SIGHUP to the processes that have /u/abe/bar open, use:
4225 kill -HUP `lsof -t /u/abe/bar`
4227 To find any open file, including an open UNIX domain socket file,
4234 To find processes with open files on the NFS file system named
4236 whose server is inaccessible, and presuming your mount table supplies
4237 the device number for
4238 .IR /nfs/mount/point ,
4241 lsof -b /nfs/mount/point
4243 To do the preceding search with warning messages suppressed, use:
4245 lsof -bw /nfs/mount/point
4247 To ignore the device cache file, use:
4251 To obtain PID and command name field output for each process, file
4252 descriptor, file device number, and file inode number for each file
4253 of each process, use:
4257 To list the files at descriptors 1 and 3 of every process running the
4259 command for login ID ``abe'' every 10 seconds, use:
4261 lsof -c lsof -a -d 1 -d 3 -u abe -r10
4263 To list the current working directory of processes running a command that
4264 is exactly four characters long and has an 'o' or 'O' in character three,
4265 use this regular expression form of the
4269 lsof -c /^..o.$/i -a -d cwd
4271 To find an IP version 4 socket file by its associated numeric dot\-form
4274 lsof -i@128.210.15.17
4276 To find an IP version 6 socket file (when the UNIX dialect supports
4277 IPv6) by its associated numeric colon\-form address, use:
4279 lsof -i@[0:1:2:3:4:5:6:7]
4281 To find an IP version 6 socket file (when the UNIX dialect supports
4282 IPv6) by an associated numeric colon\-form address that has a run of
4283 zeroes in it \- e.g., the loop\-back address \- use:
4287 To obtain a repeat mode marker line that contains the current time, use:
4291 To add spaces to the previous marker line, use:
4293 lsof -r "m==== %T ===="
4297 reads kernel memory in its search for open files, rapid changes in kernel
4298 memory may produce unpredictable results.
4300 When a file has multiple record locks, the lock status character
4301 (following the file descriptor) is derived from a test of the first
4302 lock structure, not from any combination of the individual record
4303 locks that might be described by multiple lock structures.
4306 can't search for files with restrictive access permissions by
4308 unless it is installed with root set\-UID permission.
4309 Otherwise it is limited to searching for files to which its user
4310 or its set-GID group (if any) has access permission.
4312 The display of the destination address of a raw socket (e.g., for
4314 depends on the UNIX operating system.
4315 Some dialects store the destination address in the raw socket's protocol
4316 control block, some do not.
4319 can't always represent Solaris device numbers in the same way that
4322 For example, the major and minor device numbers that the
4326 functions report for the directory on which CD-ROM files are mounted
4329 are not the same as the ones that it reports for the device on which
4330 CD-ROM files are mounted (typically
4332 (\fILsof\fP reports the directory numbers.)
4336 file systems is available only for BSD and Tru64 UNIX dialects, Linux, and
4337 dialects derived from SYSV R4 \- e.g., FreeBSD, NetBSD, OpenBSD, Solaris,
4342 file items \- device number, inode number, and file size \-
4343 are unavailable in some dialects.
4344 Searching for files in a
4346 file system may require that the full path name be specified.
4348 No text (\fBtxt\fP) file descriptors are displayed for Linux
4350 All entries for files other than the current working directory,
4351 the root directory, and numerical file descriptors are labeled
4356 can't search for Tru64 UNIX named pipes by name, because their kernel
4357 implementation of lstat(2) returns an improper device number for a
4361 can't report fully or correctly on HP\-UX 9.01, 10.20, and 11.00 locks
4362 because of insufficient access to kernel data or errors in the
4366 FAQ (The \fBFAQ\fP section gives its location.)
4369 The AIX SMT file type is a fabrication.
4370 It's made up for file structures whose type (15) isn't defined in the AIX
4371 .I /usr/include/sys/file.h
4373 One way to create such file structures is to run X clients with the DISPLAY
4374 variable set to ``:0.0''.
4378 option is not supported under /proc\-based Linux
4380 because it doesn't read kernel structures from kernel memory.
4383 may access these environment variables.
4384 .TP \w'LSOFPERSDCPATH'u+4
4386 defines a language locale.
4389 for the names of other variables that can be used in place
4390 of LANG \- e.g., LC_ALL, LC_TYPE, etc.
4393 defines the path to a device cache file.
4395 .B "DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE"
4396 section for more information.
4399 defines the middle component of a modified personal device cache
4402 .B "MODIFIED PERSONAL DEVICE CACHE PATH"
4403 section for more information.
4405 Frequently-asked questions and their answers (an FAQ) are
4412 That file is also available via anonymous ftp from
4413 .I lsof.itap.purdue.edu
4415 .IR pub/tools/unix/lsof FAQ .
4418 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/FAQ
4420 .TP \w'.lsof_hostname'u+4
4422 kernel virtual memory device
4425 physical memory device
4428 system paging device
4435 is the first component of the host's name returned by
4436 .IR gethostname (2).)
4439 was written by Victor A.\&Abell <abe@purdue.edu> of Purdue University.
4440 Many others have contributed to
4442 They're listed in the
4448 The latest distribution of
4450 is available via anonymous ftp from the host
4451 .IR lsof.itap.purdue.edu .
4455 .I pub/tools/unix/lsof
4458 You can also use this URL:
4460 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof
4463 is also mirrored elsewhere.
4465 .I lsof.itap.purdue.edu
4467 .I pub/tools/unix/lsof
4468 directory, you'll be given a list of some mirror sites.
4470 .I pub/tools/unix/lsof
4471 directory also contains a more complete list in its
4474 Use mirrors with caution \- not all mirrors always have the latest
4480 executables are available on
4481 .IR lsof.itap.purdue.edu ,
4482 but their use is discouraged \- it's better that you build
4483 your own from the sources.
4484 If you feel you must use a pre\-compiled executable, please
4485 read the cautions that appear in the README files of the
4486 .I pub/tools/unix/lsof/binaries
4487 subdirectories and in the 00* files of the distribution.
4489 More information on the
4491 distribution can be found in its
4492 .I README.lsof_<version>
4494 If you intend to get the
4496 distribution and build it, please read
4497 .I README.lsof_<version>
4498 and the other 00* files of the distribution before sending questions
4502 Not all the following manual pages may exist in every UNIX
projects / platform / upstream / lsof.git / blob