2 Making and Installing lsof 4
4 ********************************************************************
5 | The latest release of lsof is always available via anonymous ftp |
6 | from lsof.itap.purdue.edu. Look in pub/tools/unix/lsof. |
7 ********************************************************************
11 Pre-built Lsof Binaries
13 Other Configure Script Options
17 Device Access Warnings
19 Caches -- Name and Device
21 Other Compile-time Definitions
30 The lsof-l Mailing List
31 Field Output Example Scripts
32 Field Output C Library
38 Auspex LFS (no longer maintained)
40 DEC OSF/1, Digital UNIX, Tru64 UNIX
48 Pyramid DC/OSx and Reliant UNIX (no longer available)
52 Solaris 2.x, 7, 8, 9 and 10
53 Ultrix (no longer available)
55 User-contributed Dialect Support
56 Dialects No Longer Supported
58 Setuid-root Lsof Dialects
60 Porting lsof 4 to a New UNIX Dialect
61 Quick Start to Using lsof
62 Cross-configuring Lsof
63 Environment Variables Affecting the Configure Script
66 =======================
67 Pre-built Lsof Binaries
68 =======================
70 Avoid using pre-built lsof binaries if you can; build your own
73 I do not support lsof binaries built and packaged by third parties nor
74 lsof binaries built from anything but the latest lsof revision. (See
75 the Bug Reports section for more information on the details of lsof
78 One important reasone for those support restrictions is that when lsof
79 is built its Configure script tunes lsof to the features available on
80 the building system, often embodied in supporting header files and
81 libraries. If the building system doesn't have support for a
82 particular feature, lsof won't be built to support the feature on any
85 The Veritas VxFS file system is a good example of a feature that
86 requires build-time support.
88 UNIX dialect version differences -- Solaris 8 versus 9, AIX 4.3.3
89 vesus 5.2, etc. -- can also render a pre-built lsof binary useless
90 on a different version. So can kernel bit size.
92 There are so many potential pitfalls to using an lsof binary
93 improperly that I strongly recommend lsof be used only where it is
101 $ cd <lsof source directory>
102 $ ./Configure <your dialect's abbreviation>
105 (Consult the 00FAQ and 00XCONFIG files of the lsof distribution
106 for information about using make command invocations and environment
107 variables to override lsof default Makefile strings.)
109 This lsof distribution can be used with many UNIX dialects. However,
110 it must be configured specifically for each dialect. Configuration
111 is done in three ways: 1) by changing definitions in the machine.h
112 header file of the UNIX dialect of interest; 2) by defining
113 environment variable values prior to calling Configure (see the
114 00XCONFIG file, the Environment Variabls and Environment Variables
115 Affecting the Configure Script sections of this file); and 3) by
116 running the Configure shell script found in the top level of the
117 distribution directory.
119 You may not need to change any machine.h definitions, but you might
120 want to look at them anyway. Pay particular attention to the
121 definitions that are discussed in the Security section of this
122 file. Please read that section.
124 The Configure script calls three other scripts in the lsof
125 distribution: AFSConfig; Inventory; and Customize. The AFSConfig
126 script is called for selected dialects (AIX, HP-UX, NEXTSTEP, and
127 Solaris) to locate AFS header files and determine the AFS version.
128 See The AFSConfig Script section of this file for more information.
130 The Inventory script checks the completeness of the lsof distribution.
131 Configure calls Inventory after it has accepted the dialect
132 abbreviation, but before it configures the top-level directory for
133 the dialect. See The Inventory Script section of this file for
136 Configure calls the Customize script after it has configured the
137 top-level lsof directory for the declared dialect. Customize helps
138 you modify some of the important compile-time definitions of
139 machine.h. See the The Customize Script section.
141 You should also think about where you will install lsof and its
142 man page, and whom you will let execute lsof. Please read the
143 Installing Lsof section of this file for information on installation
146 Once you have inspected the machine.h file for the dialect for
147 which you want to build lsof, and made any changes you need, run
148 the Configure script, supplying it with the abbreviation for the
149 dialect. (See the following table.) Configure selects the
150 appropriate options for the dialect and runs the Mksrc shell script
151 in the dialect sub-directory to construct the appropriate source
152 files in the top-level distribution directory.
154 Configure may also run the MkKernOpts script in the dialect
155 sub-directory to propagate kernel build options to the dialect
156 Makefile. This is done for only a few dialects -- e.g., DC/OSx,
159 Configure creates a dialect-specific Makefile. You may want to
160 inspect or edit this Makefile to make it conform to local conventions.
161 If you want the Makefile to install lsof and its man page, you will
162 have to create an appropriate install rule.
164 Lsof may be configured using UNIX dialect abbreviations from the
165 following table. Alternative abbreviations are indicated by a
166 separating `|'. For example, for SCO OpenServer you can use either
167 the ``osr'' or the ``sco'' abbreviation:
173 Abbreviations UNIX Dialect
174 ------------- ------------
176 aix IBM AIX 5.[23] and 5.3-ML1 using IBM's C Compiler
177 aixgcc IBM AIX 5.[12] and 5.3-ML1 using gcc
178 darwin Apple Darwin 7.x and 8.x for Power Macintosh systems
179 decosf DEC OSF/1, Digital UNIX, Tru64 UNIX 4.0 and 5.1
180 digital_unix Digital UNIX, DEC OSF/1, Tru64 UNIX 4.0 and 5.1
181 du Digital UNIX, DEC OSF/1, Tru64 UNIX 4.0 and 5.1
182 freebsd FreeBSD 4.x, 4.1x, 5.x and [67].x
183 hpux HP-UX 11.00, 11.11 and 11.23, using HP's C
184 Compiler, both /dev/kmem-based and PSTAT-based
185 hpuxgcc HP-UX 11.00, 11.11 and 11.23, using gcc, both
186 /dev/kmem-based and PSTAT-based
187 linux Linux 2.1.72 and above for x86-based systems
188 netbsd NetBSD 1.[456], 2.x and 3.x
190 nextstep NEXTSTEP 3.[13]
193 openbsd OpenBSD 2.[89] and 3.[0-9]
194 openstep OPENSTEP 4.x
196 osr SCO OpenServer Release 5.0.6, using the C compiler
197 from the SCO developer's kit
198 osrgcc SCO OpenServer Release 5.0.6, using gcc
199 osr6 SCO Openserver 6.0.0, using the SCO C compiler
200 sco SCO OpenServer Release 5.0.6, using the C compiler
201 from the SCO developer's kit
202 scogcc SCO OpenServer Release 5.0.6, using gcc
203 solaris Solaris 2.x, 7, 8, 9 and 10 using gcc
204 solariscc Solaris 2.x, 7, 8, 9 and 10 using Sun's cc
205 tru64 Tru64 UNIX, DEC OSF/1, Digital UNIX 4.0 and 5.1
206 unixware SCO|Caldera UnixWare 7.1.4
207 uw SCO|Caldera UnixWare 7.1.4
209 If you have an earlier version of a dialect not named in the above
210 list, lsof may still work on your system. I have no way of testing
211 that myself. Try configuring for the named dialect -- e.g., if
212 you're using Solaris 2.1, try configuring for Solaris 2.5.1.
214 After you have configured lsof for your UNIX dialect and have
215 selected options via the Customize script (See the The Customize
216 Script section.) , use the make command to build lsof -- e.g.,
221 Other Configure Script Options
222 ==============================
224 There are three other useful options to the Configure script besides
225 the dialect abbreviation:
227 -clean may be specified to remove all traces of
228 a dialect configuration, including the
229 Makefile, symbolic links, and library files.
231 -h may be specified to obtain a list of
232 -help Configure options, including dialect
235 -n may be specified to stop the Configure
236 script from calling the Customize and
239 Caution: -n also suppresses the AFSConfig
244 Environment Variables
245 =====================
247 Lsof configuration, building, and execution may be affected by
248 environment variable settings. See the Definitions That Affect
249 Compilation section in the 00PORTING file, the General Environment
250 Variables section in the 00XCONFIG file, the Dialect-Specific
251 Environment Variables section in the 00XCONFIG file, and the
252 Environment Variables Affecting the Configure Script section of
253 this file for more information.
255 Note in the General Environment Variables section of the 00XCONFIG
256 file that there are five environment variables that can be used to
257 pre-define values in lsof's -v output: LSOF_BLDCMT, LSOF_HOST,
258 LSOF_LOGNAME, LSOF_SYSINFO, and LSOF_USER.
264 If the symbol HASSECURITY is defined, a security mode is enabled,
265 and lsof will allow only the root user to list all open files.
266 Non-root users may list only open files whose processes have the
267 same user ID as the real user ID of the lsof process (the one that
268 its user logged on with).
270 However, if HASNOSOCKSECURITY is also defined, anyone may list
271 anyone else's open socket files, provided their listing is enabled
272 with the "-i" option.
274 Lsof is distributed with the security mode disabled -- HASSECURITY
275 is not defined. (When HASSECURITY is not defined, the definition
276 of HASNOSOCKSECURITY has no meaning.) You can enable the security
277 mode by defining HASSECURITY in the Makefile or in the machine.h
278 header file for the specific dialect you're using -- e.g.
279 dialects/aix/machine.h.
281 The Customize script, run by Configure when it has finished its
282 work, gives you the opportunity to define HASSECURITY and
283 HASNOSOCKSECURITY. (See the The Customize Script section.)
285 The lsof -h output indicates the state HASSECURITY and HASNOSOCKSECURITY
286 had when lsof was built, reporting:
288 "Only root can list all files;"
289 if HASSECURITY was defined and HASNOSOCKSECURITY wasn't
292 "Only root can list all files, but anyone can list socket files."
293 if HASSECURITY and HASNOSOCKSECURITY were both defined;
295 "Anyone can list all files;"
296 if HASSECURITY wasn't defined. (The definition of
297 HASNOSOCKSECURITY doesn't matter when HASSECURITY isn't
300 You should carefully consider the implications of using the default
301 security mode. When lsof is compiled in the absence of the
302 HASSECURITY definition, anyone who can execute lsof may be able to
303 see the presence of all open files. This may allow the lsof user
304 to observe open files -- e.g., log files used to track intrusions
305 -- whose presence you would rather not disclose.
307 As distributed, lsof writes a user-readable and user-writable device
308 cache file in the home directory of the real user ID executing
309 lsof. There are other options for constructing the device cache file
310 path, and they each have security implications.
312 The 00DCACHE file in the lsof distribution discusses device cache
313 file path construction in great detail. It tells how to disable
314 the various device cache file path options, or how to disable the
315 entire device cache file feature by removing the HASDCACHE definition
316 from the dialect's machine.h file. There is also information on
317 the device cache file feature in the 00FAQ file. (The 00DCACHE
318 and 00FAQ files are part of the lsof distribution package.)
320 The Customize script, run by Configure after it has finished its
321 work, gives you the opportunity to change the compile-time options
322 related to the device cache file. (See The Customize Script
325 Since lsof may need setgid or setuid-root permission (See the Setgid
326 Lsof Dialects and Setuid-root Lsof Dialects sections.), its security
327 should always be viewed with skepticism. Lest the setgid and
328 setuid-root permissions allow lsof to read kernel name list or
329 memory files, declared with the -k and -m options, that the lsof
330 user can't normally access, lsof uses access(2) to establish its
331 real user's authority to read such files when it can't surrender
332 its power before opening them. This change was added at the
333 suggestion of Tim Ramsey.
335 Lsof surrenders setgid permission on most dialects when it has
336 gained access to the kernel's memory devices. There are exceptions
337 to this rule, and some lsof implementations need to run setuid-root.
338 (The Setgid Lsof Dialects and Setuid-root Lsof Dialects sections
339 contains a list of lsof implementations and the permissions
340 recommended in the distribution's Makefiles.)
342 The surrendering of setgid permission is controlled by the WILLDROPGID
343 definition in the dialect machine.h header files.
345 In the end you must judge for yourself and your installation the
346 risks that lsof presents and restrict access to it according to
347 your circumstances and judgement.
353 Lsof can issue warning messages when it runs -- e.g., about the
354 state of the device cache file, about an inability to access an
355 NFS file system, etc. Issuance of warnings are enabled by default
356 in the lsof distribution.
358 Issuance or warnings may be disabled by default by defining
359 WARNINGSTATE in the dialect's machine.h. The Customize script may
360 also be used to change the default warning message issuance state.
361 (See The Customize Script section.)
363 The ``-w'' option description of the ``-h'' option (help) output
364 will indicate the default warning issuance state. Whatever the
365 state may be, it can be reversed with ``-w''.
368 Device Access Warnings
369 ======================
371 When lsof encounters a /dev (or /devices) directory, one of its
372 sub-directories, or one of their files that it cannot access with
373 opendir(3) or stat(2), it issues a warning message and continues.
374 Lsof will be more likely to issue such a warning when it has been
375 installed with setgid(<some group name>) permission; it won't have
376 trouble if it has been installed with setuid(root) permission or
377 is being run under the root login.
379 The lsof caller can inhibit or enable the warning with the -w
380 option, depending on the issuance state of run-time warnings. (See
381 the Run-time Warnings section.)
383 The warning messages do not appear when lsof obtains device
384 information from a device cache file that it has built and believes
385 to be current or when warning message issuance is disabled by
386 default. (See the "Caches -- Name and Device" section for more
387 information on the device cache file.)
389 The lsof builder can inhibit the warning by disabling the definition
390 of WARNDEVACCESS in the dialect's machine.h or disable all warnings
391 by defining WARNINGSTATE. WARNDEVACCESS is defined by default for
392 most dialects. However, some dialects have some device directory
393 elements that are private -- e.g., HP-UX -- and it is more convenient
394 for the lsof user if warning messages about them are inhibited.
396 Output from lsof's -h option indicates the status of WARNDEVACCESS.
397 If it was defined when lsof was compiled, this message will appear:
399 /dev warnings = enabled
401 If WARNDEVACCESS was not defined when lsof was compiled, this
402 message will appear instead:
404 /dev warnings = disabled
406 The Customize script, run by Configure after it has finished its
407 work, gives you the opportunity to change the WARNDEVACCESS
408 definition. (See The Customize Script section.)
414 Lsof is susceptible to NFS blocks when it tries to lstat() mounted
415 file systems and when it does further processing -- lstat() and
416 readlink() -- on its optional file and file system arguments.
418 Lsof tries to avoid being stopped completely by NFS blocks by doing
419 the lstat() and readlink() functions in a child process, which
420 returns the function response via a pipe. The lsof parent limits
421 the wait for data to arrive in the pipe with a SIGALRM, and, if
422 the alarm trips, terminates the child process with a SIGINT and a
425 This is as reliable and portable a method for breaking NFS deadlocks
426 as I have found, although it still fails under some combinations
427 of NFS version, UNIX dialect, and NFS file system mount options.
428 It generally succeeds when the "intr" or "soft" mount options are
429 used; it generally fails when the "hard" mount option is used.
431 When lsof cannot kill the child process, a second timeout causes
432 it to stop waiting for the killed child to complete. While the
433 second timeout allows lsof to complete, it may leave behind a hung
434 child process. Unless warnings are inhibited by default or with
435 the -w option, lsof reports the possible hung child.
437 NFS block handling was updated with suggestions made by Andreas
438 Stolcke. Andreas suggested using the alternate device numbers that
439 appear in the mount tables of some dialects when it is not possible
440 to stat(2) the mount points.
442 The -b option was added to direct lsof to avoid the stat(2) and
443 readlink(2) calls that might block on NFS mount points and always
444 use the alternate device numbers. If warning message issuance is
445 enabled and you don't want warning messages about what lsof is
446 doing, use the -w option, too.
448 The -O option directs lsof to avoid doing the potentially blocking
449 operations in child processes. Instead, when -O is specified, lsof
450 does them directly. While this consumes far less system overhead,
451 it can cause lsof to hang, so I advise you to use -O sparingly.
454 Caches -- Name and Device
455 ==========================
457 Robert Ehrlich suggested that lsof obtain path name components for
458 open files from the kernel's name cache. Where possible, lsof
459 dialect implementations do that. The -C option inhibits kernel
460 name cache examination.
462 Since AFS apparently does not use the kernel's name cache, where
463 lsof supports AFS it is unable to identify AFS files with path name
466 Robert also suggested that lsof cache the information it obtains
467 via stat(2) for nodes in /dev (or /devices) to reduce subsequent
468 running time. Lsof does that, too.
470 In the default distribution the device cache file is stored in
471 .lsof_hostname, mode 0600, in the home directory of the login of
472 the user ID that executes lsof. The suffix, hostname, is the first
473 component of the host's name returned by gethostname(2). If lsof
474 is executed by a user ID whose home directory is NFS-mounted from
475 several hosts, the user ID's home directory may collect several
476 device cache files, one for each host from which it was executed.
478 Lsof senses accidental or malicious damage to the device cache file
479 with extensive integrity checks, including the use of a 16 bit CRC.
480 It also tries to sense changes in /dev (or /devices) that indicate
481 the device cache file is out of date.
483 There are other options for forming the device cache file path.
484 Methods the lsof builder can use to control and employ them are
485 documented in the separate 00DCACHE file of the lsof distribution.
491 On many UNIX systems raw sockets use a separate network control
492 block structure. Display of files for applications using raw
493 sockets -- ping, using ICMP, for example -- need special support
494 for displaying their information. This support is so dialect-specific
495 and information to provide it so difficult to find that not all
496 dialect revisions of lsof handle raw sockets completely.
499 Other Compile-time Definitions
500 ==============================
502 The machine.h and dlsof.h header files for each dialect contains
503 definitions that affect the compilation of lsof. Check the
504 Definitions That Affect Compilation section of the 00PORTING file
505 of the lsof distribution for their descriptions. (Also see The
506 Customize Script section.)
512 Lsof supports AFS on some combinations of UNIX dialect and AFS
513 version. See the AFS section of this document for a list of
514 supported combinations.
516 When configuring for dialects where AFS is supported, the Configure
517 script calls the AFSConfig script to determine the location of AFS
518 header files and the AFS version. Configure will not call AFSConfig,
519 even for the selected dialects, unless the file /usr/vice/etc/ThisCell
522 The AFS header file location is recorded in the AFSHeaders file;
523 version, AFSVersion. Once these values have been recorded, Configure
524 can be told to skip the calling of AFSConfig by specifying its
525 (Configure's) -n option.
531 The lsof distribution contains a script, called Inventory, that
532 checks the distribution for completeness. It uses the file 00MANIFEST
533 in the distribution as a reference point.
535 After the Configure script has accepted the dialect abbreviation,
536 it normally calls the Inventory script to make sure the distribution
539 After Inventory has run, it creates the file ".ck00MAN" in the
540 top-level directory to record for itself the fact that the inventory
541 has been check. Should Inventory be called again, it senses this
542 file and asks the caller if another check is in order, or if the
543 check should be skipped.
545 The -n option may be supplied to Configure to make it bypass the
546 calling of the Inventory script. (The option also causes Configure
547 to avoid calling the Customize script.)
549 The lsof power user may want to define (touch) the file ".neverInv".
550 Configure avoids calling the Inventory script when ".neverInv"
557 Normally when the Configure script has finished its work, it calls
558 another shell script in the lsof distribution called Customize.
559 (You can tell Configure to bypass Customize with its -n option.)
561 Customize leads you through the specification of these important
562 compile-time definitions for the dialect's machine.h header file:
564 HASDCACHE device cache file control
565 HASENVDC device cache file environment
567 HASPERSDC personal device cache file path
569 HASPERSDCPATH name of environment variable that
570 provides an additional component
571 of the personal device cache file
573 HASSYSDC system-wide device cache file path
574 HASKERNIDCK the build-time to run-time kernel
576 HASSECURITY the security option
577 HASNOSOCKSECURITY the open socket listing option whe
578 HASSECURITY is defined
579 WARNDEVACCESS /dev (or /devices) warning message
581 WARNINGSTATE warning message issuance state
583 The Customize script accompanies its prompting for entry of new
584 values for these definitions with brief descriptions of each of
585 them. More information on these definitions may be found in this
586 file or in the 00DCACHE and 00FAQ files of the lsof distribution.
588 You don't need to run Customize after Configure. You can run it
589 later or you can edit machine.h directly.
591 The -n option may be supplied to Configure to make it bypass the
592 calling of the Customize script. (The option also causes Configure
593 to avoid calling the Inventory script.)
595 The lsof power user may want to define (touch) the file ".neverCust".
596 Configure avoids calling the Customize script when ".neverCust"
599 Customize CAUTION: the Customize script works best when it is
600 applied to a newly configured lsof source base -- i.e., the machine.h
601 header file has not been previously modified by the Customize
602 script. If you have previously configured lsof, and want to rerun
603 the Customize script, I recommend you clean out the previous
604 configuration and create a new one:
607 $ Configure <dialect_abbreviation>
609 Customize in response to the Customize script prompts.
615 Lsof is a tool that is closely tied to the UNIX operating system
616 version. It uses header files that describe kernel structures and
617 reads kernel structures that typically change from OS version to
618 OS version, and even within a version as vendor patches are applied.
620 DON'T TRY TO USE AN LSOF BINARY, COMPILED FOR ONE UNIX OS VERSION,
621 ON ANOTHER. VENDOR PATCHES INFLUENCE THE VERSION IDENTITY.
623 On some UNIX dialects lsof versions may be even more restricted by
626 The bottom line is use lsof where you built it. If you intend to
627 use a common lsof binary on multiple systems, make sure all systems
628 run exactly the same OS version and have exactly the same patches.
634 Lsof is provided as-is without any warranty of any kind, either
635 expressed or implied, including, but not limited to, the implied
636 warranties of merchantability and fitness for a particular purpose.
637 The entire risk as to the quality and performance of lsof is with
638 you. Should lsof prove defective, you assume the cost of all
639 necessary servicing, repair, or correction.
645 Lsof has no license. Its use and distribution are subject to these
646 terms and conditions, found in each lsof source file. (The copyright
647 year in or format of the notice may vary slightly.)
650 * Copyright 2002 Purdue Research Foundation, West Lafayette,
651 * Indiana 47907. All rights reserved.
653 * Written by Victor A. Abell
655 * This software is not subject to any license of the American
656 * Telephone and Telegraph Company or the Regents of the
657 * University of California.
659 * Permission is granted to anyone to use this software for
660 * any purpose on any computer system, and to alter it and
661 * redistribute it freely, subject to the following
664 * 1. Neither the authors nor Purdue University are responsible
665 * for any consequences of the use of this software.
667 * 2. The origin of this software must not be misrepresented,
668 * either by explicit claim or by omission. Credit to the
669 * authors and Purdue University must appear in documentation
672 * 3. Altered versions must be plainly marked as such, and must
673 * not be misrepresented as being the original software.
675 * 4. This notice may not be removed or altered.
682 Now that the obligatory disclaimer is out of the way, let me hasten to
683 add that I accept lsof bug reports and try hard to respond to them. I
684 will also consider and discuss requests for new features, ports to new
685 dialects, or ports to new OS versions.
687 PLEASE DON'T SEND BUG REPORTS ABOUT LSOF TO THE UNIX DIALECT OR DIALECT
690 At worst such bug reports will confuse the vendor; at best, the vendor
691 will forward the bug report to me.
693 PLEASE DON'T SEND BUG REPORTS ABOUT LSOF BINARIES BUILT OR DISTRIBUTED
694 BY SOMEONE ELSE, BECAUSE I CAN'T SUPPORT THEM.
696 Before you send me a bug report, please do these things:
698 * Make sure you try the latest lsof revision.
700 + Download the latest revision from:
702 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof
704 + Verify the signatures of what you have downloaded;
706 + While connected to lsof.itap.purdue.edu, check for patches:
708 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/patches
710 + If patches exist, install them in the latest revision
711 you just downloaded. Then build the latest revision and
712 see if it fixes your bug.
714 * If you're having trouble compiling lsof with gcc, try the
715 UNIX dialect vendor's compiler. I don't have access to gcc on
716 all test systems, so my support for it is hit-and-miss, and so
717 is my ability to respond to gcc compilation problem reports.
719 * Check the lsof frequently asked questions file, 00FAQ,
720 to see if there's a question and answer relevant to your
723 * Make sure you're running the lsof you think you are by
724 checking the path to it with which(1). When in doubt, use an
725 absolute path to lsof. Make sure that lsof binary has
726 sufficient permissions to do what you ask, including internal
727 permissions given it (e.g., restrictions on what files lsof may
728 report for whom) during its build.
730 When you send a bug report, make sure you include output from your
731 running of lsof's Configure script. If you were able to compile a
732 running lsof, please also include:
734 * Output from which(1) that shows the absolute path to the
735 lsof binary in question;
737 * Output from running lsof with its -h and -v options at
738 lsof's absolute path;
740 * Output from "ls -l" directed to lsof's absolute path.
742 If you weren't able to compile a running lsof, please send me: the
743 compiler error output; identification of the lsof revision you're using
744 (contents of the lsof version.c file); identification of your system
745 (full uname output or output from whatever other tool identifies the
746 system); and compiler identification (e.g., gcc -v output).
748 Either set of output will help me understand how lsof was configured
749 and what UNIX dialect and lsof revision is involved.
751 Please send all bug reports, requests, etc. to me via e-mail at
752 <abe@purdue.edu>. Make sure "lsof" appears in the "Subject:" line so
753 my e-mail filter won't classify your letter as Spam.
759 The lsof distribution contains an extensive frequently asked
760 questions file on lsof features and problems. I recommend you
761 consult it before sending me e-mail. Use your favorite editor or
762 pager to search 00FAQ -- e.g., supplying as a search argument some
763 fixed text from an lsof error message.
766 The lsof-l Mailing List
767 =======================
769 Information about lsof, including notices about the availability
770 of new revisions, may be found in mailings of the lsof-l listserv.
771 For more information about it, including instructions on how to
772 subscribe, read the 00LSOF-L file of the lsof distribution.
775 Field Output Example Scripts
776 ============================
778 Example AWK and Perl 4 or 5 scripts for post-processing lsof field
779 output are locate in the scripts sub-directory of the lsof distribution.
780 The scripts sub-directory contains a 00README file with information
784 Field Output C Library
785 ======================
787 The lsof test suite (See "Testing Lsof."), checks basic lsof
788 operations using field output. The test suite has its own library
789 of C functions for common test program operations, including
790 processing of field output. The library or selections of its
791 functions could be adapted for use by C programs that want to
792 process lsof field output. See the library in the file LTlib.c
793 in the tests/ sub-directory
799 Lsof has an automated test suite in the tests/ sub-directory that
800 can be used to test some basic lsof features -- once lsof has been
801 configured and made. Tests are arranged in three groups: basic
802 tests that should run on all dialects; standard tests that should
803 run on all dialects; and optional tests that may not run on all
804 dialects or may need special resources to run. See 00TEST for more
807 CAUTION!!! Before you attempt to use the test suite make sure that
808 the lsof you want to test can access the necessary kernel resources
809 -- e.g., /dev/mem, /dev/kmem, /proc, etc. Usually you want to test
810 the lsof you just built, so this is an important check. (See
813 To run the basic and standard tests, using the lsof in the parent
814 directory of tests/, do this:
821 The basic and standard tests may be run as silently as possible,
822 using the lsof in the parent directory of tests/, with:
827 This is the "automatic" test mode, designed for use by scripts that
828 build lsof. The caller is expected to test the make exit code to
829 determine if the tests succeeded. The caller should divert standard
830 output and standard error to /dev/null to suppress make's error
833 The optional tests may be run, using the lsof in the parent directory
840 It's possible to excute individual tests, too. See the 00TEST file
841 of this distribution for more informaiton on the tests, what they
842 do, and how to run and possibly customize each test.
844 It's possible to run the tests, using an lsof other than the one
845 in the parent directory of /tests, too. See 00TEST for information
846 about using the LT_LSOF_PATH environment variable to do that.
857 Lsof recognizes AFS files on the following combinations of UNIX
858 dialect and AFS versions:
861 Linux 1.2.13 (AFS 3.3)
862 NEXTSTEP 3.2 (AFS 3.3) (untested on recent lsof revisions)
863 Solaris 2.6 (AFS 3.4a)
864 Ultrix 4.2 RISC (AFS 3.2b) (no longer available)
866 Lsof has not been tested under other combinations -- e.g. HP-UX
867 10.10 and AFS 3.4a -- and probably won't even compile there. Often
868 when a UNIX dialect version or AFS version changes, the new header
869 files come into conflict, causing compiler objections.
875 Specify the aix Configure abbreviation for AIX 4.1.[45], 4.2[.1],
876 4.3[.123], 5L, and 5.[123].
878 Specify aixgcc on AIX above 4.1 to use the gcc compiler. (Gcc can't be
879 used to compile lsof on AIX 4.1 and below because of kernel structure
880 alignment differences between it and xlc.) Gcc results sometimes
881 depend on the version of the gcc compiler that is used.
883 Compilation of lsof with gcc on AIX 4.3[.123], 5L, and 5.[123] has been
884 sparsely tested with varying degrees of success: it has been reported
885 to succeed on AIX 4.3.3 and 32 bit Power AIX 5.1; to fail on ia64 AIX
886 5.1 and 64 bit Power AIX 5.1; and to succeed on 32 and 64 bit Power AIX
887 5.2. Lsof compilation with gcc hasn't been tested on AIX 5.3.
889 At revision 4.61 and above lsof is configured and built to match the
890 bit size of the kernel of Power architecture AIX 5.1 systems. Lsof
891 binaries built for 32 and 64 bit kernels are not interchangeable. See
892 00FAQ for more information.
894 The Configure script uses /usr/bin/oslevel to determine the AIX version
895 for AIX less than 5 and ``uname -rv'' for AIX 5 and higher. If
896 /usr/bin/oslevel isn't executable on AIX less than 5, the Configure
897 script issues a warning message and uses ``uname -rv'' to determine the
900 When Configure must use ``uname -rv'' on AIX less than 5 to determine
901 the AIX version, the result will lack a correct third component --
902 e.g., the `4' of ``4.1.4''. If your AIX less than 5 system lacks lacks
903 an executable oslevel, I suggest you edit the Configure-produced
904 Makefile and complete the _AIXV definition in the CFGF string.
906 By default lsof avoids using the kernel's readx() function, causing
907 it to be unable to report information on some text and library file
908 references. The ``-X'' option allows the lsof user to ask for the
909 information readx() supplies.
911 Lsof avoids readx() to avoid the possibility of triggering a kernel
912 problem, known as the Stale Segment ID kernel bug. Kevin Ruderman
913 reported this bug to me. The bug shows up when the kernel's
914 dir_search() function hangs, hanging the application process that
915 called it so completely that the application process can neither
916 be killed nor stopped. The hang is the consequence of another
917 process (perhaps lsof) making legitimate use of the kernel's readx()
918 function to access the kernel memory that dir_search() is examining.
919 IBM has indicated they have no plans to fix the bug.
921 A fuller discussion of this bug may be found in the 00FAQ file of
922 the lsof distribution. There you will find a description of the
923 Stale Segment ID bug, the APAR on it, and a discussion of the
924 sequence of events that exposes it.
926 I added the ``-X'' function so you can tell lsof to use readx(),
927 but if you use ``-X'', you should be alert to its possibly serious
928 side effects. Although readx() is normally disabled, its state is
929 controlled with the HASXOPT, HASXOPT_ROOT, and HASXOPT_VALUE
930 definitions in dialects/aix/machine.h, and you can change its
931 default state by changing those definitions. You can also change
932 HASXOPT_ROOT via the Customize script.
934 You can also compile lsof with readx() use permanently enabled or
935 disabled -- see the comments about the definitions in the
936 dialects/aix/machine.h header file. You may want to permanently
937 disable lsof's use of readx() if you plan to make lsof publicly
938 executable. You can also restrict -X to processes whose real UID
939 is root by defining HASXOPT_ROOT.
941 I have never seen lsof cause the Stale Segment ID bug to occur and
942 haven't had a report that it has, but I believe there is a possibility
945 AFS support for AIX was added with help help from Bob Cook and Jan
946 Tax who provided test systems.
948 Henry Grebler and David J. Wilson helped with lsof for AIX 4.2.
950 Bill Pemberton provided an AIX 4.3 test system. Andrew Kephart
951 and Tom Weaver provided AIX 4.3 technical assistance. Niklas
952 Edmundsson did 4.3.1 testing. Doug Crabill provided an AIX 4.3.2
953 test system. Jeff W. Stewart provided an AIX 4.3.3 test system.
955 The SMT file type for AIX 4.1.[45], 4.2[.1], and 4.3[.12] is my
956 fabrication. See the 00FAQ file more information on it.
958 Loc Le and Nasser Momtaheni of IBM provided test systems for AIX 5L and
959 5.1. Lsof for AIX 5L and 5.1 needs setuid-root permission to process
960 the -X option on systems whose architecture type is ia64.
962 Dale Talcott of Purdue provided AIX 5.1 and 5.2 test systems. Dale and
963 John Jackson of Purdue provided an AIX 5.3 test system.
969 The Apple Darwin port was provided by Allan Nathanson for version
970 1.2. Allan also arranged for access to a test system for maintenance
971 and regression testing. Dale Talcott provided a test system, too.
973 Allan supplied patches for updates to 1.4, 5.x, 6.x, 7.x and 8.x.
979 As of lsof revision 4.77 support for BSDI BSD/OS has been
980 discontinued. Lsof revision 4.76 with BSDI BSD/OS support may be found
981 on lsof.itap.purdue.edu in pub/tools/unix/lsof/src.
984 DEC OSF/1, Digital UNIX, Tru64 UNIX
985 ===================================
987 Robert Benites, Dean Brock, Angel Li, Dwight McKay, Berkley Shands,
988 Ron Young and Steve Wilson have kindly provided test systems.
989 Jeffrey Mogul has provided technical assistance. Dave Morrison
990 and Lawrence MacIntyre did Digital UNIX V3.2 testing.
992 Lsof supports the ADVFS/MSFS layered file system product. Lsof
993 can locate all the open files of an ADVFS/MSFS file system when
994 its path is specified, provided the file system is listed in
995 /etc/fstab with an ``advfs'' type. (This /etc/fstab caveat applies
996 only to Digital UNIX 2.0.) At Digital UNIX 4.0 and Tru64 UNIX,
997 using code provided by David Brock, lsof 4.20 and above can locate
1000 Testing of lsof on DEC OSF/1 and Digital UNIX 4.0 ended with lsof
1001 revision 4.74. Hence, the lsof documentation has dropped the claim
1002 that it works there. For a distribution of lsof 4.74 that was tested
1003 on DEC OSF/1 and Digital UNIX 4.0, check pub/tools/unix/lsof/OLD/src
1004 on the lsof ftp home, lsof.itap.purdue.edu.
1006 Lsof revisions past 4.74 have only been tested on Tru64 UNIX 5.1.
1012 Bill Bormann of Purdue University provided access to several FreeBSD
1013 test systems. Ade Barkah, John Clear, Ralph Forsythe, Michael
1014 Haro, Kurt Jaeger, and William McVey have also provided FreeBSD
1017 The FreeBSD distribution header files are augmented by header files
1018 in the dialects/freebsd/include directory.
1020 David O'Brien maintains the lsof FreeBSD port package.
1026 Lsof has two HP-UX bases: /dev/kmem for HP-UX 11.0 and earlier;
1027 and PSTAT for HP-UX 11.11 and later. The lsof Configure script
1028 will pick the appropriate base.
1030 To use the CCITT x.25 socket support for HP-UX, you must have the
1031 x.25 header files in /etc/conf/x25
1033 Pasi Kaara helped with the HP-UX port, especially with its CCITT
1034 x.25 socket support.
1036 Richard Allen provided HP-UX 10.x and 11.x test systems, as did
1037 Mark Bixby, and Elias Halldor Agustsson. Marc Winkler helped test
1038 the 10.20 port. Richard J. Rauenzahn provided a 64 bit HP-UX 11
1039 test system and an HP-UX 11.11 development system.
1041 AFS support for HP-UX was added thanks to help from Chaskiel Moses
1042 Grundman, who provided a test system.
1044 The /dev/kmem-based HP-UX 11.00 support is extremely fragile. It
1045 depends on privately developed kernel structure definitions. (See
1046 .../dialects/hpux/hpux11 for the header files making the definitions.)
1047 Those header files and their definitions will not be updated by
1048 HP-UX 11.00 patches, making it likely that any patch changing a
1049 kernel structure critical to lsof will break lsof in some way.
1051 It's possible to build a 64 bit lsof for 64 bit HP-UX 11.00 with
1052 gcc, but you must have a gcc compiler capable of producing 64 bit
1053 executables. See the 00FAQ file for more information.
1055 The PSTAT-based lsof for HP-UX 11.11 and later is much more solid.
1056 I am indebted to the vision of HP for providing an lsof kernel API
1057 through the PSTAT implementation. Specifically I appreciate the
1058 help of HP staff members Carl Davidson, Louis Huemiller, Rich
1059 Rauenzahn, and Sailu Yallapragada that made PSTAT-based HP-UX lsof
1066 Lsof has IPv6 support that has been tested for these UNIX dialects:
1067 AIX 4.3.x; Apple Darwin 5.[12] and 6.0; the INRIA and KAME FreeBSD IPv6
1068 implementations; PSTAT-based HP-UX; /proc-based Linux; the INRIA and
1069 KAME NetBSD implementations; and Solaris 8 and 9. Lsof has IPv6
1070 support that hasn't been tested for: OpenBSD (KAME); OpenUNIX 8; Tru64
1071 Unix 5.[01]; and UnixWare 7.1.[34].
1073 Please let me know if your UNIX dialect has IPv6 support and I'll
1074 see if it can be supported by lsof.
1080 Tim Korb, Steve Logue, Joseph J. Nuspl Jr., and Jonathan Sergent
1081 have provided Linux test systems.
1083 Michael Shields helped add and test automatic handling of ELF/COFF
1084 form names in /System.map, Marty Leisner and Keith Parks have helped
1085 test many lsof revisions. Marty has provided valuable suggestions,
1086 Linux hints, and code, too.
1088 The 00FAQ file gives some Linux tips, including information on
1089 coping with system map file problems.
1091 To determine the state of the Linux 2.1.x C library lseek() function,
1092 the lsof Configure script runs a test program that must have
1093 permission to read /dev/kmem. The test determines if the lseek()
1094 function properly handles kernel offsets, which appear to be negative
1095 because their high order bit is set. If the lseek() test reveals
1096 a faulty lseek(), Configure activates the use of a private lseek()
1097 function for kernel offset positioning. See the Linux problems
1098 section of the 00FAQ file of the lsof distribution for more
1105 Greg Earle and Paul Kranenburg have assisted with the NetBSD ports.
1106 Paul has provided test systems. Ray Phillips provided a NetBSA
1107 Alpha test system. Andrew Brown also provided a test system.
1109 The NetBSD dialect version of lsof is compiled using the dialect
1110 sources it shares with OpenBSD in the n+obsd dialect sub-directory.
1113 NEXTSTEP and OPENSTEP
1114 =====================
1116 Virtual memory header files that allow lsof to display text references
1117 were derived from the contents of /usr/include/vm of NEXTSTEP 2.0.
1118 NeXT did not ship the virtual memory header files with other NEXTSTEP
1119 or OPENSTEP versions.
1121 You may use the RC_FLAGS environment variable to declare compiler
1122 options outside the Makefile. A common use of this variable is to
1123 define the architecture types to be included in a "fat" executable.
1124 See the comments in dialects/next/Makefile for an example.
1130 David Mazieres has provided OpenBSD test systems. The OpenBSD
1131 dialect version of lsof is compiled using the dialect sources it
1132 shares with NetBSD in the n+obsd dialect sub-directory.
1134 Kenneth Stailey has provided OpenBSD testing and advice.
1136 John Dzubera (Zube) reports, "lsof 4.33 compiles and runs on OpenBSD
1137 2.3 for the pmax architecture (decstation 3100)."
1139 I have not tested lsof on OpenBSD 3.8, but David Mazieres reports
1140 revision 4.76 worked on OpenBSD 3.8.
1143 Pyramid DC/OSx and Reliant UNIX
1144 ===============================
1146 As of lsof revision 4.52 support for all Pyramid dialects has been
1147 discontinued. Lsof revision 4.51 with Pyramid support may be
1148 obtained upon request. Send the request to abe@purdue.edu.
1150 These two UNIX dialects are very similar and share dialect-specific
1151 source files from the pyramid sub-directory.
1153 The Reliant Unix Pyramid C compiler issues warning messages that
1154 I haven't found a convenient way to suppress. You can ignore
1155 warning messages about casts and conversions that lose bits. The
1156 message "warning: undefining __STDC__" is intentionally caused by
1157 the lsof MkKernOpts configuration script to suppress warning messages
1158 about cast and conversion problems in standard system header files,
1159 such as <stdio.h> and <string.h>.
1161 Bruce Beare and Kevin Smith provided test systems.
1167 Larry Rosenman provided an OpenUNIX 8 test system. Matthew Thurmaier
1168 provided technical assistance, along with these people from Caldera:
1169 Jack Craig, Robert Lipe, and Bela Lubkin.
1171 Robert Lipe supplied changes to lsof for OpenUNIX 8.0.1. Those
1172 changes were also incorporated in UnixWare 7.1.3 when it became
1173 the release name for OpenUNIX 8.0.1.
1175 Support for lsof on OpenUNIX ended at lsof revision 4.74. The last
1176 lsof revision, 4.74, tested on OpenUNIX, may be found at the lsof
1177 "home" ftp site, lsof.itap.purdue.edu, in pub/tools/unix/lsof/OLD/src.
1183 Dion Johnson, Bela Lubkin, and Nathan Peterson of SCO gave me copies
1184 of SCO OpenServer and the SCO OpenServer Development System 3.0
1185 and provided technical advice for the lsof port.
1187 Hugh Dickins, Bela Lubkin, Craig B. Olofson, and Nathan Peterson
1188 provided version 5.0 and gave technical advice for porting lsof to
1189 it. Bela provided the 5.0.4 changes. D. Chris Daniels provided
1190 a 5.0.4 test system, Lee Penn provided one for 5.0.5, and John
1193 The <netdb.h> header file was accidentally omitted from some SCO
1194 OpenServer Development System releases. The Configure script will
1195 sense its absence and substitute an equivalent from the BSD
1196 distribution. The BSD <netdb.h> and the <sys/cdefs.h> header file
1197 it includes are located in the dialects/os/include sub-directory
1200 To compile lsof from its distribution sources you must have the
1201 TCP/IP and NSF headers in /usr/include. While those are optional
1202 OpenServer packages, I have access to no system that doesn't have
1203 them, so I'm unable to build lsof for such a configuration. However,
1204 it should be possible to modify the lsof Configure script and
1205 sources so lsof would compile and work without those optional
1208 If you have an OpenServer system configured without the TCP/IP and
1209 NFS packages, and want to tackle the job of building lsof for it,
1210 contact me via e-mail at <abe@purdue.edu>. I'll identify the
1211 Configure script, header file, and source file changes you will
1212 need to make. (Caution: this is not a simple task, or I would have
1215 The optional osrgcc and scogcc Configure abbreviations construct
1216 Makefiles for compiling lsof with gcc.
1218 The UnixWare 7.1.4 sources are used for OpenServer Release 6.0.0.
1219 Hence there is a separate Configure abbreviation for it, "osr6".
1220 Richard of SCO provided a test system and technical assistance.
1223 SCO|Caldera UnixWare
1226 D. Chris Daniels, John Hughes, Ken Laing, Andrew Merril, Lee Penn, and
1227 Matthew Thurmaier provided test systems. Bela Lubkin provided
1228 technical assistance. Larry Rosenman provided 7.1.[34] test systems.
1231 Solaris 2.x, 7, 8, 9 and 10
1232 ===========================
1234 SEE THE CAUTIONS SECTION OF THIS DOCUMENT.
1236 The latest Solaris revision of lsof 4 might work under Solaris
1237 2.[1-4] and 2.5[.1] and 7 but hasn't been tested there. I have no
1238 test systems for those Solaris versions.
1240 Lsof will compile with gcc and the Sun C compiler under Solaris.
1241 If you want to use the Sun compiler, use the solariscc Configure
1242 abbreviation. If you use a gcc version less than 2.8 on Solaris,
1243 make sure the gcc-specific includes have been updated for your
1244 version of Solaris -- i.e., run the gcc fixincludes script.
1246 Solaris 7, 8, 9 and 10 support for 64 bit kernels depends on a Sun
1247 WorkShop or Forte C compiler version that supports the "-xarch=v9"
1248 flag -- usually 5.0 or greater. Gcc versions 2.95 and above *may*
1249 be configured and built for 64 bit support, but it takes some extra
1250 work, the resulting compiler may be fragile, and the gcc developers
1251 discourage it. I've built 64 bit capable gcc compilers for Solaris
1252 7, 8 and 9 from gcc versions 2.95 through 3.0.1 and produced working
1253 lsof executables with them. More information on 64 bit gcc for
1254 Solaris may be found in the 00FAQ file.
1256 Solaris 10 ZFS support is questionable, because Sun does not distribute
1257 the ZFS kernel structure definition header files. The lsof Configure
1258 script and source code use some risky work-arounds. ZFS file system
1259 support was made possible with help from Horst Scheuermann.
1261 Dave Curry and Steve Kirsch provided resources for Solaris 2.x
1262 ports. Casper Dik and Gerry Singleton consulted and provided
1263 valuable assistance.
1265 Henry Katz, Joseph Kowalski, Charles Stephens, Mike Sullivan, and
1266 Mike Tracy provided technical assistance.
1268 AFS support was added to Solaris lsof with help from Curt Freeland,
1269 Heidi Hornstein, Michael L. Lewis, Terry McCoy, Phillip Moore, and
1270 Sushila R. Subramanian.
1272 Casper Dik provided valuable assistance for the Solaris 8 support.
1274 Sun has graciously provided me access to BETA versions of Solaris
1275 2.5, 2.6, 7, 8, and 9.
1277 John Dzubera provided Solaris 7 and 8 test systems.
1279 Mike Miscevic provided Solaris 10 test systems.
1285 As of lsof revision 4.52 support for Ultrix is no longer available,
1286 because I no longer have an Ultrix test system.
1288 Terry Friedrichsen, Dwight McKay, and Jeffrey Mogul helped me with
1291 DECnet support was added to Ultrix lsof with the help of John
1292 Beacom, who kindly provided a test system. The Configure script
1293 decides that DECnet support is available if /usr/lib/libdnet.a and
1294 /usr/include/netdnet/dn.h exist and are readable.
1297 Veritas VxFS and VxVM
1298 =====================
1300 Lsof supports some versions of Veritas VxFS and VxVM on some UNIX
1301 dialects. Consult the lsof Configure script for the specific
1302 dialect, and consult the lsof dialect-specific source files for
1303 the UNIX dialect of interest. Veritas support will usually be
1304 found in a source file named dnode[1-9].c.
1306 Since Veritas rarely has a version number that can be extracted
1307 with shell commands, lsof doesn't use it. Instead, when lsof
1308 supports Veritas, the Configure script will form compile-time
1309 definitions starting with HASVXFS. Check the lsof 00PORTING
1310 documentation file for more information.
1312 Lsof Veritas support requires that the supporting Veritas header
1313 files be installed -- e.g., in /usr/include/sys/fs. (The location
1314 will depend in the dialect's header file conventions.)
1316 Some information on lsof support for Veritas extensions may be
1317 found in the lsof 00DIST file. (The ChangeLog file points to
1320 Chris Kordish and Andy Thomas have provided Solaris VxFS test
1324 ================================
1325 User-contributed Dialect Support
1326 ================================
1328 There are some user-contributed dialect versions of lsof; more
1329 information on them can be found at:
1331 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/contrib
1333 Check the 00INDEX file there for details.
1336 ============================
1337 Dialects No Longer Supported
1338 ============================
1340 Because I don't have access to test systems, these UNIX dialects
1341 are no longer supported by lsof:
1344 /dev/kmem-based Linux
1348 Pyramid Reliant UNIX
1355 Remnants of the support lsof once provided for these dialects may
1358 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/OLD/dialects
1365 The distributed Makefiles do not have actions that will install
1366 lsof. I've come to the conclusion there is no standard for installing
1367 lsof or its man page, so I no longer distribute make rules for
1368 installing them. You should adjust the Makefile for your local
1371 The Makefile does have an install rule that will cause lsof to
1372 compile by virtue of its dependency clause. Some Makefiles also
1373 have a dependency that causes the production of a man page that is
1374 ready to install. However, the actions of the install rule will
1375 not cause the lsof executable or its man page to be installed in
1376 any UNIX system-wide directory.
1378 Instead, after the compilation and optional man page production
1379 are completed, the install rule will produce a brief description
1380 of what actions you might add to the install rule. The description
1381 will suggest the possible modes, ownerships, permissions, and
1382 destinations your install rule might employ to install the lsof
1383 executable and man page.
1385 As you form your install rule, keep in mind that lsof usually needs
1386 some type of special permission to do its job. That may be permission
1387 to read memory devices such as /dev/kmem, /dev/mem, or /dev/swap,
1388 or it may be authorization to read entries in the /proc file system.
1390 Memory device access can usually be provided by setting the modes
1391 of the lsof executable so that it's effective group identifier when
1392 it runs is the same as the group that has permission to read the
1393 memory devices -- i.e., it is setgid-group. The privileged group
1394 is usually kmem, sys, or system.
1396 Don't overlook using ACLs -- e.g., on AIX or Solaris 8 -- to give
1397 lsof permission to access memory devices. ACLs, coupled to a
1398 separate group like kmem, can be safer than giving lsof setgid
1399 authorization to a commonly used system group.
1401 When lsof needs to read /proc file system entries, it must be
1402 installed with modes that make its effective user identifier root
1403 when it runs -- i.e., it must be setuid-root. If lsof must be
1404 installed setuid-root (only the AIX 5L, PSTAT-based HPUX, and
1405 /proc-based Linux, ports need such power.), then access to memory
1406 devices is automatic (or not needed in the case of /proc-based
1409 Your choice of permissions for lsof may also be affected by your
1410 desire to allow anyone to use it or your need to restrict its usage
1411 to specific individuals. You will have to be guided by local policy
1412 and convention in this case.
1414 The next two sections, Setgid Lsof Dialect Versions and Setuid-root
1415 Lsof Dialect Versions, list recommended install permissions.
1417 The system directory where you install the lsof executable is also
1418 open to choice. A traditional place for a tool like lsof is
1419 /usr/local/etc, but recent changes in directory structure organization
1420 suggest that somewhere in /opt may be more suitable.
1422 Bear one other factor in mind when choosing a location for the lsof
1423 executable -- it usually is a shared executable, requiring access
1424 to shared libraries. Thus, locations like /sbin or /usr/sbin are
1425 probably unsuitable.
1427 Once you've chosen a location for the executable you may find that
1428 the location for the man page follows -- e.g., if the executable
1429 goes in /usr/local/etc, then the man page goes in /usr/local/man.
1430 If the executable location doesn't imply a location for the man
1431 page, you'll have to let local custom guide you.
1434 Setuid-root Lsof Dialect Versions
1435 =================================
1437 These dialect versions should be installed with setuid-root
1438 permission -- i.e., the lsof binary should be owned by root and
1439 its setuid execution bit (04000) should be set.
1441 AIX 5L and above for full use of the -X option
1442 Apple Darwin 8.x for Power Macintosh systems
1443 PSTAT-based HP-UX 11.11 and 11.23
1444 /proc-based Linux (generally 2.1.72 and above)
1447 Setgid Lsof Dialect Versions
1448 ============================
1450 These dialect versions should be installed with setgid permission,
1451 owned by the group that can read kernel memory devices such as
1452 /dev/drum, /dev/kmem, /dev/ksyms, /dev/mem, /dev/swap. ACLs may
1453 be another mechanism (e.g., under AIX or Solaris 8) you can use to
1454 grant read permission to the kernel memory devices.
1456 AIX 4.1.[45], 4.2[.1], and 4.3[.123]
1457 Apple Darwin 7.x for Power Macintosh systems
1458 DEC OSF/1, Digital UNIX, Tru64 UNIX 2.0, 3.2, 4.0, and 5.[01]
1459 FreeBSD 2.1.6, 2.2[.x], 3.x, 4.x, 5.x and [67].x
1460 /dev/kmem-based 11.00
1461 NetBSD 1.[456], 2.x and 3.x
1463 OpenBSD 2.[89] and 3.[0-9]
1466 SCO OpenServer 5.0.[46]
1467 SCO UnixWare 7.0 and 7.1.[0134]
1468 Solaris 2.6, 8, 9 and 10
1469 Ultrix 4.2 (no longer available)
1471 ====================================
1472 Porting lsof 4 to a New UNIX Dialect
1473 ====================================
1475 If you're brave enough to consider this, look at the 00PORTING
1476 file. Please contact me before you start. I might be able to help
1477 you or even do the port myself.
1479 Don't overlook the contrib/ directory in pub/tools/unix/lsof on my
1480 ftp server, lsof.itap.purdue.edu. It contains user-contributed ports
1481 of lsof to dialects I don't distribute, because I can't test new
1482 revisions of lsof on them.
1485 =========================
1486 Quick Start to Using lsof
1487 =========================
1489 For information on how to get started quickly using lsof, consult
1490 the 00QUICKSTART file of the lsof distribution. It cuts past the
1491 formal density of the lsof man page to provide quick examples of
1492 using lsof to solve common open file display problems.
1495 ======================
1496 Cross-configuring Lsof
1497 ======================
1499 Using environment variables it is possible to Configure (and possibly
1500 build) lsof for one UNIX dialect on a different one -- e.g., you
1501 are running Configure on a Linux 2.3 system and you want to Configure
1502 and build lsof for Linux 2.4.
1504 See the 00XCONFIG file of the lsof distribution for a discussion
1508 ====================================================
1509 Environment Variables Affecting the Configure Script
1510 ====================================================
1512 Configure script actions can be modified by introducing values to
1513 the script via environment variables. In many cases the environment
1514 variable values take the place of test operations the Configure
1517 For more information on environment variables that can affect
1518 Configure, consult the 00XCONFIG file of the lsof distribution.
1519 See the General Environment Variables sections for descriptions of
1520 ones that affect all dialects. Consult the Dialect-Specific
1521 Environment Variables section for ones that might affect the dialect
1522 you are trying to configure.
1525 Vic Abell <abe@purdue.edu>