7 Agreed, the lsof man page is dense and lsof has a plethora of
8 options. There are examples, but the manual page format buries
9 them at the end. How does one get started with lsof?
11 This file is an attempt to answer that question. It plunges
12 immediately into examples of lsof use to solve problems that
13 involve looking at the open files of Unix processes.
19 2. Finding Uses of a Specific Open File
20 3. Finding Open Files Filling a File System
21 a. Finding an Unlinked Open File
22 4. Finding Processes Blocking Umount
23 5. Finding Listening Sockets
24 6. Finding a Particular Network Connection
25 7. Identifying a Netstat Connection
26 8. Finding Files Open to a Named Command
27 9. Deciphering the Remote Login Trail
29 b. The idrlogin.perl[5] Scripts
30 10. Watching an Ftp or Rcp Transfer
31 11. Listing Open NFS Files
32 12. Listing Files Open by a Specific Login
33 a. Ignoring a Specific Login
34 13. Listing Files Open to a Specific Process Group
35 14. When Lsof Seems to Hang
36 a. Kernel lstat(), readlink(), and stat() Blockages
37 b. Problems with /dev or /devices
38 c. Host and Service Name Lookup Hangs
39 d. UID to Login Name Conversion Delays
40 15. Output for Other Programs
41 16. The Lsof Exit Code and Shell Scripts
42 17. Strange messages in the NAME column
48 C. Precautionary Options
49 D. Miscellaneous Lsof Options
52 2. Finding Uses of a Specific Open File
53 ========================================
55 Often you're interested in knowing who is using a specific file.
56 You know the path to it and you want lsof to tell you the processes
57 that have open references to it.
59 Simple -- execute lsof and give it the path name of the file of
64 Caveat: this only works if lsof has permission to get the status
65 (via stat(2)) of the file at the named path. Unless the lsof
66 process has enough authority -- e.g., it is being run with a
67 real User ID (UID) of root -- this AIX example won't work:
69 Further caveat: this use of lsof will fail if the stat(2) kernel
70 syscall returns different file parameters -- particularly device
71 and inode numbers -- than lsof finds in kernel node structures.
72 This condition is rare and is usually documented in the 00FAQ
73 file of the lsof distribution.
75 $ lsof /etc/security/passwd
76 lsof: status error on /etc/security/passwd: Permission denied
79 3. Finding Open Files Filling a File System
80 ============================================
82 Oh! Oh! /tmp is filling and ls doesn't show that any large files
83 are being created. Can lsof help?
85 Maybe. If there's a process that is writing to a file that has
86 been unlinked, lsof may be able to discover the process for you.
87 You ask it to list all open files on the file system where /tmp
90 Sometimes /tmp is a file system by itself. In that case,
94 is the appropriate command. If, however, /tmp is part of another
95 file system, typically /, then you may have to ask lsof to list
96 all files open on the containing file system and locate the
97 offending file and its process by inspection -- e.g.,
103 Caveat: there must be a file open to a for the lsof search to
104 succeed. Sometimes the kernel may cause a file reference to
105 persist, even where there's no file open to a process. (Can you
106 say kernel bug? Maybe.) In any event, lsof won't be able to
109 a. Finding an Unlinked Open File
110 =================================
112 A pesky variant of a file that is filling a file system is an
113 unlinked file to which some process is still writing. When a
114 process opens a file and then unlinks it, the file's resources
115 remain in use by the process, but the file's directory entries
116 are removed. Hence, even when you know the directory where the
117 file once resided, you can't detect it with ls.
119 This can be an administrative problem when the unlinked file is
120 large, and the process that holds it open continues to write to
121 it. Only when the process closes the file will its resources,
122 particularly disk space, be released.
124 Lsof can help you find unlinked files on local disks. It has an
125 option, +L, that will list the link counts of open files. That
126 helps because an unlinked file on a local disk has a zero link
127 count. Note: this is NOT true for NFS files, accessed from a
130 You could use the option to list all files and look for a zero
131 link count in the NLINK column -- e.g.,
134 COMMAND PID USER FD TYPE DEVICE SIZE/OFF NLINK NODE NAME
136 less 25366 abe txt VREG 6,0 40960 1 76319 /usr/...
138 > less 25366 abe 3r VREG 6,0 17360 0 98768 / (/dev/sd0a)
140 Better yet, you can specify an upper bound to the +L option, and
141 lsof will select only files that have a link count less than the
142 upper bound. For example:
145 COMMAND PID USER FD TYPE DEVICE SIZE/OFF NLINK NODE NAME
146 less 25366 abe 3r VREG 6,0 17360 0 98768 / (/dev/sd0a)
148 You can use lsof's -a (AND) option to narrow the link count search
149 to a particular file system. For example, to look for zero link
150 counts on the /home file system, use:
154 CAUTION: lsof can't always report link counts for all file types
155 -- e.g., it may not report them for FIFOs, pipes, or sockets.
156 Remember also that link counts for NFS files on an NFS client
157 host don't behave as do link counts for files on local disks.
160 4. Finding Processes Blocking Umount
161 =====================================
163 When you need to unmount a file system with the umount command,
164 you may find the operation blocked by a process that has a file
165 open on the file systems. Lsof may be able to help you find the
166 process. In response to:
168 $ lsof <file_system_name>
170 Lsof will display all open files on the named file system. It
171 will also set its exit code zero when it finds some open files
172 and non-zero when it doesn't, making this type of lsof call
173 useful in shell scripts. (See section 16.)
175 Consult the output of the df command for file system names.
177 See the caveat in the preceding section about file references
178 that persist in the kernel without open file traces. That
179 situation may hamper lsof's ability to help with umount, too.
182 5. Finding Listening Sockets
183 =============================
185 Sooner or later you may wonder if someone has installed a network
186 server that you don't know about. Lsof can list for you all the
187 network socket files open on your machine with:
191 The -i option without further qualification lists all open Internet
192 socket files. You can add network names or addresses, protocol
193 names, and service names or port numbers to the -i option to
194 refine the search. (See the next section.)
197 6. Finding a Particular Network Connection
198 ===========================================
200 When you know the source or destination of a network connection
201 whose open files and process you'd like to identify, the -i option
204 If, for example, you want to know what process has a connection
205 open to or from the Internet host named aaa.bbb.ccc, you can ask
206 lsof to search for it with:
208 $ lsof -i@aaa.bbb.ccc
210 If you're interested in a particular protocol -- TCP or UDP --
211 and a specific port number or service name, you can add those
212 discriminators to the -i information:
214 $ lsof -iTCP@aaa.bbb.ccc:ftp-data
216 If you're interested in a particular IP version -- IPv4 or IPv6
217 -- and your UNIX dialect supports both (It does if "IPv[46]"
218 appears in the lsof -h output.), you can add the '4' or '6'
219 selector immediately after -i:
225 7. Identifying a Netstat Connection
226 ====================================
228 How do I identify the process that has a network connection
229 described in netstat output? For example, if netstat says:
231 Proto Recv-Q Send-Q Local Address Foreign Address (state)
232 tcp 0 0 vic.1023 ipscgate.login ESTABLISHED
234 What process is connected to service name ``login'' on ipscgate?
236 Use lsof's -i option:
238 $lsof -iTCP@ipscgate:login
239 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
240 rlogin 25023 abe 3u inet 0x10144168 0t184 TCP lsof.itap.purdue.edu:1023->ipscgate.cc.purdue.edu:login
243 There's another way. Notice the 0x10144168 in the DEVICE column
244 of the lsof output? That's the protocol control block (PCB)
245 address. Many netstat applications will display it when given
249 PCB Proto Recv-Q Send-Q Local Address Foreign Address (state)
250 10144168 tcp 0 0 vic.1023 ipscgate.login ESTABLISHED
253 Using the PCB address, lsof, and grep, you can find the process this
256 $ lsof -i | grep 10144168
257 rlogin 25023 abe 3u inet 0x10144168 0t184 TCP lsof.itap.purdue.edu:1023->ipscgate.cc.purdue.edu:login
260 If the file is a UNIX socket and netstat reveals and adress for it,
261 like this Solaris 11 example:
264 Active UNIX domain sockets
265 Address Type Vnode Conn Local Addr Remote Addr
266 ffffff0084253b68 stream-ord 0000000 0000000
268 Using lsof's -U opetion and its output piped to a grep on the address
271 $ lsof -U | grep ffffff0084253b68
272 squid 1638 nobody 12u unix 18,98 0t10 9437188 /devices/pseudo/tl@0:ticots->0xffffff0084253b68 stream-ord
276 8. Finding Files Open to a Named Command
277 =========================================
279 When you want to look at the files open to a particular command,
280 you can look up the PID of the process running the command and
281 use lsof's -p option to specify it.
285 However, there's a quicker way, using lsof's -c option, provided
286 you don't mind seeing output for every process running the named
289 $ lsof -c <first_characters_of_command_name_that_interest_you>
291 The lsof -c option is useful when you want to see how many instances
292 of a given command are executing and what their open files are.
293 One useful example is for the sendmail command.
298 9. Deciphering the Remote Login Trail
299 ======================================
301 If the network connection you're interested in tracing has been
302 initiated externally and is connected to an rlogind, sshd, or
303 telnetd process, asking lsof to identify that process might not
304 give a wholly satisfying answer. The report may be that the
305 connection exists, but to a process owned by root.
310 How do you get from there to the login name really using the
311 connection? You have to know a little about how real and pseudo
312 ttys are paired in your system, and then use several lsof probes
313 to identify the login.
315 This example comes from a Solaris 2.4 system, named klaatu.cc.
316 I've logged on to it via rlogin from lsof.itap. The first lsof
321 yields (among other things):
323 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
324 in.rlogin 7362 root 0u inet 0xfc0193b0 0t242 TCP klaatu.cc.purdue.edu:login->lsof.itap.purdue.edu:1023
327 This confirms that a connection exists. A second lsof probe
331 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
333 in.rlogin 7362 root 0u inet 0xfc0193b0 0t242 TCP klaatu.cc.purdue.edu:login->lsof.itap.purdue.edu:1023
335 in.rlogin 7362 root 3u VCHR 23, 0 0t66 52928 /devices/pseudo/clone@0:ptmx->pckt->ptm
337 7362 is the Process ID (PID) of the in.rlogin process, discovered
338 in the first lsof probe. (I've abbreviated the output to simplify
339 the example.) Now comes a need to understand Solaris pseudo-ttys.
340 The key indicator is in the DEVICE column for FD 3, the major/minor
341 device number of 23,0. This translates to /dev/pts/0, so a third
345 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
346 ksh 7364 abe 0u VCHR 24, 0 0t2410 53410 /dev/pts/../../devices/pseudo/pts@0:0
348 shows in part that login abe has a ksh process on /dev/pts/0.
349 (The NAME that lsof shows is not /dev/pts/0 but the full expansion
350 of the symbolic link that lsof finds at /dev/pts/0.)
352 Here's a second example, done on an HP-UX 9.01 host named ghg.ecn.
353 Again, I've logged on to it from lsof.itap, so I start with:
356 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
357 rlogind 10214 root 0u inet 0x041d5f00 0t1536 TCP ghg.ecn.purdue.edu:login->lsof.itap.purdue.edu:1023
363 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
365 rlogind 10214 root 0u inet 0x041d5f00 0t2005 TCP ghg.ecn.purdue.edu:login->lsof.itap.purdue.edu:1023
367 rlogind 10214 root 3u VCHR 16,0x000030 0t2037 24642 /dev/ptym/ptys0
369 Here the key is the NAME /dev/ptym/ptys0. In HP-UX 9.01 tty and
370 pseudo tty devices are paired with the names like /dev/ptym/ptys0
371 and /dev/pty/ttys0, so the following lsof probe is the final step.
373 $ lsof /dev/pty/ttys0
374 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
375 ksh 10215 abe 0u VCHR 17,0x000030 0t3399 22607 /dev/pty/ttys0
378 Here's a third example for an AIX 4.1.4 system. I've used telnet
379 to connect to it from lsof.itap.purdue.edu. I start with:
381 $ lsof -i@lsof.itap.purdue.edu
382 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
384 telnetd 15616 root 0u inet 0x05a93400 0t5156 TCP cloud.cc.purdue.edu:telnet->lsof.itap.purdue.edu:3369
386 Then I look at the telnetd process:
389 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
391 telnetd 15616 root 0u inet 0x05a93400 0t5641 TCP cloud.cc.purdue.edu:telnet->lsof.itap.purdue.edu:3369
393 telnetd 15616 root 3u VCHR 25, 0 0t5493 103 /dev/ptc/0
395 Here the key is /dev/ptc/0. In AIX it's paired with /dev/pts/0.
396 The last probe for that shows:
399 COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
401 ksh 16642 abe 0u VCHR 26, 0 0t6461 360 /dev/pts/0
403 b. The idrlogin.perl[5] Scripts
404 ================================
406 There's another, perhaps easier way, to go about the job of
407 tracing a network connection. The lsof distribution contains
408 two Perl scripts, idrlogin.perl (Perl 4) and idrlogin.perl5
409 (Perl 5), that use lsof field output to display values for
410 shells that are parented by rlogind, sshd, or telnetd, or
411 connected directly to TCP sockets. The lsof test suite contains
412 a C library that can be adapted for use with C programs that
413 need to call lsof and process its field output.
415 The two Perl scripts use the lsof -R option; it causes the
416 paRent process ID (PPID) to be listed in the lsof output. The
417 scripts identify all shell processes -- e.g., ones whose command
418 names end in ``sh'' -- and determine if: 1) the ultimate ancestor
419 process before a PID greater than 2 (e.g., init's PID is 1) is
420 rlogind, sshd, or telnetd; or 2) the shell process has open
423 Here's an example of output from idlogin.perl on a Solaris 2.4
426 centurion: 1 = cd src/lsof4/scripts
427 centurion: 2 = ./idrlogin.perl
428 Login Shell PID Via PID TTY From
429 oboyle ksh 12640 in.telnetd 12638 pts/5 opal.cc.purdue.edu
430 icdtest ksh 15158 in.rlogind 15155 pts/6 localhost
431 sh csh 18207 in.rlogind 18205 pts/1 babylon5.cc.purdue.edu
432 root csh 18242 in.rlogind 18205 pts/1 babylon5.cc.purdue.edu
433 trouble ksh 19208 in.rlogind 18205 pts/1 babylon5.cc.purdue.edu
434 abe ksh 21334 in.rlogind 21332 pts/2 lsof.itap.purdue.edu
436 The scripts assume that its parent directory contains an
437 executable lsof. If you decide to use one of the scripts, you
438 may want to customize it for your local lsof and perl paths.
440 Note that processes executing as remote shells are also
443 Here's another example from a UnixWare 7.1.0 system.
445 tweeker: 1 = cd src/lsof4/scripts
446 tweeker: 9 = ./idrlogin.perl
447 Login Shell PID Via PID TTY From
448 abe ksh 9438 in.telnetd 9436 pts/3 lsof.itap.purdue.edu
451 10. Watching an Ftp or Rcp Transfer
452 ===================================
454 The nature of the Internet being one of unpredictable performance
455 at times, occasionally you want to know if a file transfer, being
456 done by ftp or rcp, is making any progress.
458 To use lsof for watching a file transfer, you need to know the
459 PID of the file transfer process. You can use ps to find that.
464 to examine the files open to the transfer process. Usually the
465 ftp files or interest are at file descriptors 9 and 10 or 10 and
466 11; for rcp, 3 and 4. They describe the network socket file and
469 If you want to watch only those file descriptors as the file
470 transfer progresses, try these lsof forms (for ftp in the example):
472 $ lsof -p<PID> -ad9,10 -r
474 $ lsof -p<PID> -ad10,11 -r
476 Some options need explaining:
478 -p<PID> specifies that lsof is to restrict its attention
479 to the process whose ID is <PID>. You can specify
480 a set of PIDs by separating them with commas.
482 $ lsof -p 1234,5678,9012
484 -a specifies that lsof is to AND its tests together.
485 The two tests that are specified are tests on the
486 PID and tests on file descriptions (``d9,10'').
488 d9,10 specifies that lsof is to test only file descriptors
489 9 and 10. Note that the `-' is absent, since ``-a''
490 is a unary option and can be followed immediately
491 by another lsof option.
493 -r tells lsof to list the requested open file information,
494 sleep for a default 15 seconds, then list the open
495 file information again. You can specify a different
496 time (in seconds) after -r and override the default.
497 Lsof issues a short line of equal signs between
498 each set of output to distinguish it.
500 For an rcp transfer, the above example becomes:
502 $ lsof -p<PID> -ad3,4 -r
505 11. Listing Open NFS Files
506 ==========================
508 Lsof will list all files open on remote file systems, supported
509 by an NFS server. Just use:
513 Note, however, that when run on an NFS server, lsof will not list
514 files open to the server from one of its clients. That's because
515 lsof can only examine the processes running on the machine where
516 it is called -- i.e., on the NFS server.
518 If you run lsof on the NFS client, using the -N option, it will
519 list files open by processes on the client that are on remote
523 12. Listing Files Open by a Specific Login
524 ==========================================
526 If you're interested in knowing what files the processes owned
527 by a particular login name have open, lsof can help.
531 $ lsof -u<User ID number>
533 You can specify either the login name or the UID associated with
534 it. You can specify multiple login names and UID numbers, mixed
535 together, by separating them with commas.
539 On the subject of login names and UIDs, it's worth noting that
540 lsof can be told to report either. By default it reports login
541 names; the -l option switches reporting to UIDs. You might want
542 to use -l if login name lookup is slow for some reason.
544 a. Ignoring a Specific Login
545 =============================
547 The -u option can also be used to direct lsof to ignore a
548 specific login name or UID, or a list of them. Simply prefix
549 the login names or UIDs with a `^' character, as you might do
550 in a regular expression. The `^' prefix is useful, for example,
551 when you want to have lsof ignore the files open to system
552 processes, owned by the root (UID 0) login. Try:
559 13. Listing Files Open to a Specific Process Group
560 ==================================================
562 There's a Unix collection of processes called a process group.
563 The name indicates that the processes of the group have a common
564 association and are grouped so that a signal sent to one (e.g.,
565 a keyboard kill stroke) is delivered to all.
567 This causes Unix to create a two element process group:
571 You can use lsof to look at the open files of all members of a
572 process group, if you know the process group ID number. Assuming
573 that it is 12717 for the above example, this lsof command:
575 $ lsof -g12717 -adcwd
577 would produce on a Solaris 8 system:
579 $ lsof -g12717 -adcwd
580 COMMAND PID PGID USER FD TYPE DEVICE SIZE/OFF NODE NAME
581 sshd 11369 12717 root cwd VDIR 0,2 189 1449175 /tmp (swap)
582 sshd 12717 12717 root cwd VDIR 136,0 1024 2 /
584 The ``-g12717'' option specifies the process group ID of interest;
585 the ``-adcwd'' option specifies that options are to be ANDed and
586 that lsof should limit file output to information about current
587 working directory (``cwd'') files.
590 14. When Lsof Seems to Hang
591 ===========================
593 On occasion when you run lsof it seems to hang and produce no
594 output. This may result from system conditions beyond the control
595 of lsof. Lsof has a number of options that may allow you to
598 a. Kernel lstat(), readlink(), and stat() Blockages
599 ====================================================
601 Lsof uses the kernel (system) calls lstat(), readlink(), and
602 stat() to locate mounted file system information. When a file
603 system has been mounted from an NFS server and that server is
604 temporarily unavailable, the calls lsof uses may block in the
607 Lsof will announce that it is being blocked with warning messages
608 (unless they have been suppressed by the lsof builder), but
609 only after a default waiting period of fifteen seconds has
610 expired for each file system whose server is unavailable. If
611 you have a number of such file systems, the total wait may be
614 You can do two things to shorten your suffering: 1) reduce the
615 wait time with the -S option; or 2) tell lsof to avoid the
616 kernel calls that might block by specifying the -b option.
622 Avoiding the kernel calls that might block may result in the
623 lack of some information that lsof needs to know about mounted
624 file systems. Thus, when you use -b, lsof warns that it might
625 lack important information.
627 The warnings that result from using -b (unless suppressed by
628 the lsof builder) can themselves be annoying. You can suppress
629 them by adding the -w option. (Of course, if you do, you won't
630 know what warning messages lsof might have issued.)
634 Note: if the lsof builder suppressed warning message issuance,
635 you don't need to use -w to suppress them. You can tell what
636 the default state of message warning issuance is by looking at
637 the -h (help) output. If it says ``-w enable warnings'' then
638 warnings are disabled by default; ``-w disable warnings'', they
639 are enabled by default.
641 b. Problems with /dev or /devices
642 ==================================
644 Lsof scans the /dev or /devices branch of your file system to
645 obtain information about your system's devices. (The scan isn't
646 necessary when a device cache file exists.)
648 Sometimes that scan can take a very long time, especially if
649 you have a large number of devices, and if your kernel is
650 relatively slow to process the stat() system call on device
651 nodes. You can't do anything about the stat() system call
654 However, you can make sure that lsof is allowed to use its
655 device cache file feature. When lsof can use a device cache
656 file, it retains information it gleans via the stat() calls
657 on /dev or /devices in a separate file for later, faster
660 The device cache file feature is described in the lsof man
661 page. See the DEVICE CACHE FILE, LSOF PERMISSIONS THAT AFFECT
662 DEVICE CACHE FILE ACCESS, DEVICE CACHE FILE PATH FROM THE -D
663 OPTION, DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE,
664 SYSTEM-WIDE DEVICE CACHE PATH, PERSONAL DEVICE CACHE PATH
665 (DEFAULT), and MODIFIED PERSONAL DEVICE CACHE PATH sections.
667 There is also a separate file in the lsof distribution, named
668 00DCACHE, that describes the device cache file in detail,
669 including information about possible security problems.
671 One final observation: don't overlook the possibility that your
672 /dev or /devices tree might be damaged. See if
678 completes or hangs. If it hangs, then lsof will probably hang,
679 too, and you should try to discover why ls hangs.
681 c. Host and Service Name Lookup Hangs
682 ======================================
684 Lsof can hang up when it tries to convert an Internet dot-form
685 address to a host name, or a port number to a service name. Both
686 hangs are caused by the lookup functions of your system.
688 An independent check for both types of hangs can be made with
689 the netstat program. Run it without arguments. If it hangs,
690 then it is probably having lookup difficulties. When you run
691 it with -n it shouldn't hang and should report network and port
692 numbers instead of names.
694 Lsof has two options that serve the same purpose as netstat's
695 -n option. The lsof -n option tells it to avoid host name
696 lookups; and -P, service name lookups. Try those options when
697 you suspect lsof may be hanging because of lookup problems.
705 d. UID to Login Name Conversion Delays
706 =======================================
708 By default lsof converts User IDentification (UID) numbers to
709 login names when it produces output. That conversion process
710 may sometimes hang because of system problems or interlocks.
712 You can tell lsof to skip the lookup with the -l option; it
713 will then report UIDs in the USER column.
718 15. Output for Other Programs
719 =============================
721 The -F option allows you to specify that lsof should describe
722 open files with a special form of output, called field output,
723 that can be parsed easily by a subsequent program. The lsof
724 distribution comes with sample AWK, Perl 4, and Perl 5 scripts
725 that post-process field output. The lsof test suite has a C
726 library that could be adapted for use by C programs that want to
727 process lsof field output from an in-bound pipe.
729 The lsof manual page describes field output in detail in its
730 OUTPUT FOR OTHER PROGRAMS section. A quick look at a sample
731 script in the scripts/ subdirectory of the lsof distribution will
732 also give you an idea how field output works.
734 The most important thing about field output is that it is relatively
735 homogeneous across Unix dialects. Thus, if you write a script
736 to post-process field output for AIX, it probably will work for
737 HP-UX, Solaris, and Ultrix as well.
740 16. The Lsof Exit Code and Shell Scripts
741 ========================================
743 When lsof exits successfully it returns an exit code based on
744 the result of its search for specified files. (If no files were
745 specified, then the successful exit code is 0 (zero).)
747 If lsof was asked to search for specific files, including any
748 files on specified file systems, it returns an exit code of 0
749 (zero) if it found all the specified files and at least one file
750 on each specified file system. Otherwise it returns a 1 (one).
752 If lsof detects an error and makes an unsuccessful exit, it
753 returns an exit code of 1 (one).
755 You can use the exit code in a shell script to search for files
756 on a file system and take action based on the result -- e.g.,
759 lsof <file_system_name> > /dev/null 2>&1
762 echo "<file_system_name> has some users."
764 echo "<file_system_name> may have no users."
768 17. Strange messages in the NAME column
769 =======================================
771 When lsof encounters problems analyzing a particular file, it may
772 put a message in the file's NAME column. Many of those messages
773 are explained in the 00FAQ file of the lsof distribution.
775 So consult 00FAQ first if you encounter a NAME column message you
776 don't understand. (00FAQ is a possible source of information
777 about other unfamiliar things in lsof output, too.)
779 If you can't find help in 00FAQ, you can use grep to look in the
780 lsof source files for the message -- e.g.,
782 $ cd .../lsof_4.76_src
783 $ grep "can't identify protocol" *.[ch]
785 The code associated with the message will usually make clear the
786 reason for the message.
788 If you have an lsof source tree that has been processed by the
789 lsof Configure script, you need grep only there. If, however,
790 your source tree hasn't been processed by Configure, you may
791 have to look in the top-level lsof source directory and in the
792 dialects sub-directory for the UNIX dialect you are using - e.g.,
794 $ cd .../lsof_4.76_src
795 $ grep "can't identify protocol" *.[ch]
797 $ grep "can't identify protocol" *.[ch]
799 In rare cases you may have to look in the lsof library, too --
802 $ cd .../lsof_4.76_src
803 $ grep "can't identify protocol" *.[ch]
805 $ grep "can't identify protocol" *.[ch]
807 $ grep "can't identify protocol" *.[ch]
813 The following appendices describe the lsof options in detail.
819 Lsof has a rich set of options for selecting the files to be
820 displayed. These include:
822 -a tells lsof to AND the set of selection options that
823 are specified. Normally lsof ORs them.
825 For example, if you specify the -p<PID> and -u<UID>
826 options, lsof will display all files for the
827 specified PID or for the specified UID.
829 By adding -a, you specify that the listed files
830 should be limited to PIDs owned by the specified
831 UIDs -- i.e., they match the PIDs *and* the UIDs.
833 $ lsof -p1234 -au 5678
835 -c specifies that lsof should list files belonging
836 to processes having the associated command name.
838 Hint: if you want to select files based on more than
839 one command name, use multiple -c<name> specifications.
843 -d tells lsof to select by the associated file descriptor
844 (FD) set. An FD set is a comma-separated list of
845 numbers and the names lsof normally displays in
846 its FD column: cwd, Lnn, ltx, <number>, etc. See
847 the OUTPUT section of the lsof man page for the
848 complete list of possible file descriptors. Example:
852 -g tells lsof to select by the associated process
853 group ID (PGID) set. The PGID set is a comma-separated
854 list of PGID numbers. When -g is specified, it also
855 enables the display of PGID numbers.
857 Note: when -g isn't followed by a PGID set, it
858 simply selects the listing of PGID for all processes.
864 -i tells lsof to display Internet socket files. If no
865 protocol/address/port specification follows -i,
866 lsof lists all Internet socket files.
868 If a specification follows -i, lsof lists only the
869 socket files whose Internet addresses match the
872 Hint: multiple addresses may be specified with
873 multiple -i options. Examples:
876 $ lsof -i@lsof.itap.purdue.edu:sendmail
878 -N selects the listing of files mounted on NFS devices.
880 -U selects the listing of socket files in the Unix
887 Lsof has these options to control its output format:
889 -F produce output that can be parsed by a subsequent
892 -g print process group (PGID) IDs.
894 -l list UID numbers instead of login names.
896 -n list network numbers instead of host names.
898 -o always list file offset.
900 -P list port numbers instead of port service names.
902 -s always list file size.
905 C. Precautionary Options
906 =========================
908 Lsof uses system functions that can block or take a long time,
909 depending on the health of the Unix dialect supporting it. These
912 -b directs lsof to avoid system functions -- e.g.,
913 lstat(2), readlink(2), stat(2) -- that might block
914 in the kernel. See the BLOCKS AND TIMEOUTS
915 section of the lsof man page.
917 You might want to use this option when you have
918 a mount from an NFS server that is not responding.
920 -C tells lsof to ignore the kernel's name cache. As
921 a precaution this option will have little effect on
922 lsof performance, but might be useful if the kernel's
923 name cache is scrambled. (I've never seen that
926 -D might be used to direct lsof to ignore an existing
927 device cache file and generate a new one from /dev
928 (and /devices). This might be useful if you have
929 doubts about the integrity of an existing device
932 -l tells lsof to list UID numbers instead of login
933 names -- this is useful when UID to login name
934 conversion is slow or inoperative.
936 -n tells lsof to avoid converting Internet addresses
937 to host numbers. This might be useful when your
938 host name lookup (e.g., DNS) is inoperative.
940 -O tells lsof to avoid its strategy of forking to
941 perform potentially blocking kernel operations.
942 While the forking allows lsof to detect that a
943 block has occurred (and possibly break it), the
944 fork operation is a costly one. Use the -O option
945 with care, lest your lsof be blocked.
947 -P directs lsof to list port numbers instead of trying
948 to convert them to port service names. This might
949 be useful if port to service name lookups (e.g.,
950 via NIS) are slow or failing.
952 -S can be used to change the lstat/readlink/stat
953 timeout interval that governs how long lsof waits
954 for response from the kernel. This might be useful
955 when an NFS server is slow or unresponsive. When
956 lsof times out of a kernel function, it may have
957 less information to display. Example:
961 -w tells lsof to avoid issuing warning messages, if
962 they are enabled by default, or enable them if they
963 are disabled by default. Check the -h (help) output
964 to determine their status. If it says ``-w enable
965 warnings'', then warning messages are disabled by
966 default; ``-w disable warnings'', they are enabled
969 This may be a useful option, for example, when you
970 specify -b, if warning messages are enabled, because
971 it will suppress the warning messages lsof issues
972 about avoiding functions that might block in the
976 D. Miscellaneous Lsof Options
977 ==============================
979 There are some lsof options that are hard to classify, including:
981 -? these options select help output.
984 -F selects field output. Field output is a mode where
985 lsof produces output that can be parsed easily by
986 subsequent programs -- e.g., AWK or Perl scripts.
987 See ``15. Output for Other Programs'' for more
990 -k specifies an alternate kernel symbol file -- i.e.,
991 where nlist() will get its information. Example:
993 $ lsof -k/usr/crash/vmunix.1
995 -m specifies an alternate kernel memory file from
996 which lsof will read kernel structures in place
997 of /dev/kmem or kvm_read(). Example:
999 $ lsof -m/usr/crash/vmcore.n
1001 -r tells lsof to repeat its scan every 15 seconds (the
1002 default when no associated value is specified). A
1003 repeat time, different from the default, can follow
1008 -v displays information about the building of the
1011 -- The double minus sign option may be used to
1012 signal the end of options. It's particularly useful
1013 when arguments to the last option are optional and
1014 you want to supply a file path that could be confused
1015 for arguments to the last option. Example:
1019 Where `1' is a file path, not PGID ID 1.
1022 Vic Abell <abe@purdue.edu>