Edit File: 00README
Making and Installing lsof 4 ******************************************************************** | The latest release of lsof is always available via anonymous ftp | | from lsof.itap.purdue.edu. Look in pub/tools/unix/lsof. | ******************************************************************** Contents Pre-built Lsof Binaries Making Lsof Other Configure Script Options Environment Variables Security Run-time Warnings Device Access Warnings NFS Blocks Caches -- Name and Device Raw Sockets Other Compile-time Definitions The AFSConfig Script The Inventory Script The Customize Script Cautions Warranty License Bug Reports The 00FAQ File The lsof-l Mailing List Field Output Example Scripts Field Output C Library Testing Lsof Dialect Notes AFS AIX Apple Darwin Auspex LFS (no longer maintained) BSDI BSD/OS DEC OSF/1, Digital UNIX, Tru64 UNIX FreeBSD HP-UX IPv6 Linux NetBSD NEXTSTEP and OPENSTEP OpenBSD Pyramid DC/OSx and Reliant UNIX (no longer available) Caldera OpenUNIX SCO OpenServer SCO|Caldera UnixWare Solaris 2.x, 7, 8, 9 and 10 Ultrix (no longer available) Veritas VxFS and VxVM User-contributed Dialect Support Dialects No Longer Supported Installing Lsof Setuid-root Lsof Dialects Setgid Lsof Dialects Porting lsof 4 to a New UNIX Dialect Quick Start to Using lsof Cross-configuring Lsof Environment Variables Affecting the Configure Script ======================= Pre-built Lsof Binaries ======================= Avoid using pre-built lsof binaries if you can; build your own instead. I do not support lsof binaries built and packaged by third parties nor lsof binaries built from anything but the latest lsof revision. (See the Bug Reports section for more information on the details of lsof support.) One important reasone for those support restrictions is that when lsof is built its Configure script tunes lsof to the features available on the building system, often embodied in supporting header files and libraries. If the building system doesn't have support for a particular feature, lsof won't be built to support the feature on any system. The Veritas VxFS file system is a good example of a feature that requires build-time support. UNIX dialect version differences -- Solaris 8 versus 9, AIX 4.3.3 vesus 5.2, etc. -- can also render a pre-built lsof binary useless on a different version. So can kernel bit size. There are so many potential pitfalls to using an lsof binary improperly that I strongly recommend lsof be used only where it is built. =========== Making Lsof =========== $ cd <lsof source directory> $ ./Configure <your dialect's abbreviation> $ make (Consult the 00FAQ and 00XCONFIG files of the lsof distribution for information about using make command invocations and environment variables to override lsof default Makefile strings.) This lsof distribution can be used with many UNIX dialects. However, it must be configured specifically for each dialect. Configuration is done in three ways: 1) by changing definitions in the machine.h header file of the UNIX dialect of interest; 2) by defining environment variable values prior to calling Configure (see the 00XCONFIG file, the Environment Variabls and Environment Variables Affecting the Configure Script sections of this file); and 3) by running the Configure shell script found in the top level of the distribution directory. You may not need to change any machine.h definitions, but you might want to look at them anyway. Pay particular attention to the definitions that are discussed in the Security section of this file. Please read that section. The Configure script calls three other scripts in the lsof distribution: AFSConfig; Inventory; and Customize. The AFSConfig script is called for selected dialects (AIX, HP-UX, NEXTSTEP, and Solaris) to locate AFS header files and determine the AFS version. See The AFSConfig Script section of this file for more information. The Inventory script checks the completeness of the lsof distribution. Configure calls Inventory after it has accepted the dialect abbreviation, but before it configures the top-level directory for the dialect. See The Inventory Script section of this file for more information. Configure calls the Customize script after it has configured the top-level lsof directory for the declared dialect. Customize helps you modify some of the important compile-time definitions of machine.h. See the The Customize Script section. You should also think about where you will install lsof and its man page, and whom you will let execute lsof. Please read the Installing Lsof section of this file for information on installation considerations. Once you have inspected the machine.h file for the dialect for which you want to build lsof, and made any changes you need, run the Configure script, supplying it with the abbreviation for the dialect. (See the following table.) Configure selects the appropriate options for the dialect and runs the Mksrc shell script in the dialect sub-directory to construct the appropriate source files in the top-level distribution directory. Configure may also run the MkKernOpts script in the dialect sub-directory to propagate kernel build options to the dialect Makefile. This is done for only a few dialects -- e.g., DC/OSx, and Reliant UNIX. Configure creates a dialect-specific Makefile. You may want to inspect or edit this Makefile to make it conform to local conventions. If you want the Makefile to install lsof and its man page, you will have to create an appropriate install rule. Lsof may be configured using UNIX dialect abbreviations from the following table. Alternative abbreviations are indicated by a separating `|'. For example, for SCO OpenServer you can use either the ``osr'' or the ``sco'' abbreviation: $ Configure osr or $ Configure sco Abbreviations UNIX Dialect ------------- ------------ aix IBM AIX 5.[23] and 5.3-ML1 using IBM's C Compiler aixgcc IBM AIX 5.[12] and 5.3-ML1 using gcc darwin Apple Darwin 7.x and 8.x for Power Macintosh systems decosf DEC OSF/1, Digital UNIX, Tru64 UNIX 4.0 and 5.1 digital_unix Digital UNIX, DEC OSF/1, Tru64 UNIX 4.0 and 5.1 du Digital UNIX, DEC OSF/1, Tru64 UNIX 4.0 and 5.1 freebsd FreeBSD 4.x, 4.1x, 5.x and [67].x hpux HP-UX 11.00, 11.11 and 11.23, using HP's C Compiler, both /dev/kmem-based and PSTAT-based hpuxgcc HP-UX 11.00, 11.11 and 11.23, using gcc, both /dev/kmem-based and PSTAT-based linux Linux 2.1.72 and above for x86-based systems netbsd NetBSD 1.[456], 2.x and 3.x next NEXTSTEP 3.[13] nextstep NEXTSTEP 3.[13] ns NEXTSTEP 3.[13] nxt NEXTSTEP 3.[13] openbsd OpenBSD 2.[89] and 3.[0-9] openstep OPENSTEP 4.x os OPENSTEP 4.x osr SCO OpenServer Release 5.0.6, using the C compiler from the SCO developer's kit osrgcc SCO OpenServer Release 5.0.6, using gcc osr6 SCO Openserver 6.0.0, using the SCO C compiler sco SCO OpenServer Release 5.0.6, using the C compiler from the SCO developer's kit scogcc SCO OpenServer Release 5.0.6, using gcc solaris Solaris 2.x, 7, 8, 9 and 10 using gcc solariscc Solaris 2.x, 7, 8, 9 and 10 using Sun's cc tru64 Tru64 UNIX, DEC OSF/1, Digital UNIX 4.0 and 5.1 unixware SCO|Caldera UnixWare 7.1.4 uw SCO|Caldera UnixWare 7.1.4 If you have an earlier version of a dialect not named in the above list, lsof may still work on your system. I have no way of testing that myself. Try configuring for the named dialect -- e.g., if you're using Solaris 2.1, try configuring for Solaris 2.5.1. After you have configured lsof for your UNIX dialect and have selected options via the Customize script (See the The Customize Script section.) , use the make command to build lsof -- e.g., $ make Other Configure Script Options ============================== There are three other useful options to the Configure script besides the dialect abbreviation: -clean may be specified to remove all traces of a dialect configuration, including the Makefile, symbolic links, and library files. -h may be specified to obtain a list of -help Configure options, including dialect abbreviations. -n may be specified to stop the Configure script from calling the Customize and Inventory scripts. Caution: -n also suppresses the AFSConfig step. Environment Variables ===================== Lsof configuration, building, and execution may be affected by environment variable settings. See the Definitions That Affect Compilation section in the 00PORTING file, the General Environment Variables section in the 00XCONFIG file, the Dialect-Specific Environment Variables section in the 00XCONFIG file, and the Environment Variables Affecting the Configure Script section of this file for more information. Note in the General Environment Variables section of the 00XCONFIG file that there are five environment variables that can be used to pre-define values in lsof's -v output: LSOF_BLDCMT, LSOF_HOST, LSOF_LOGNAME, LSOF_SYSINFO, and LSOF_USER. Security ======== If the symbol HASSECURITY is defined, a security mode is enabled, and lsof will allow only the root user to list all open files. Non-root users may list only open files whose processes have the same user ID as the real user ID of the lsof process (the one that its user logged on with). However, if HASNOSOCKSECURITY is also defined, anyone may list anyone else's open socket files, provided their listing is enabled with the "-i" option. Lsof is distributed with the security mode disabled -- HASSECURITY is not defined. (When HASSECURITY is not defined, the definition of HASNOSOCKSECURITY has no meaning.) You can enable the security mode by defining HASSECURITY in the Makefile or in the machine.h header file for the specific dialect you're using -- e.g. dialects/aix/machine.h. The Customize script, run by Configure when it has finished its work, gives you the opportunity to define HASSECURITY and HASNOSOCKSECURITY. (See the The Customize Script section.) The lsof -h output indicates the state HASSECURITY and HASNOSOCKSECURITY had when lsof was built, reporting: "Only root can list all files;" if HASSECURITY was defined and HASNOSOCKSECURITY wasn't defined; "Only root can list all files, but anyone can list socket files." if HASSECURITY and HASNOSOCKSECURITY were both defined; "Anyone can list all files;" if HASSECURITY wasn't defined. (The definition of HASNOSOCKSECURITY doesn't matter when HASSECURITY isn't defined.) You should carefully consider the implications of using the default security mode. When lsof is compiled in the absence of the HASSECURITY definition, anyone who can execute lsof may be able to see the presence of all open files. This may allow the lsof user to observe open files -- e.g., log files used to track intrusions -- whose presence you would rather not disclose. As distributed, lsof writes a user-readable and user-writable device cache file in the home directory of the real user ID executing lsof. There are other options for constructing the device cache file path, and they each have security implications. The 00DCACHE file in the lsof distribution discusses device cache file path construction in great detail. It tells how to disable the various device cache file path options, or how to disable the entire device cache file feature by removing the HASDCACHE definition from the dialect's machine.h file. There is also information on the device cache file feature in the 00FAQ file. (The 00DCACHE and 00FAQ files are part of the lsof distribution package.) The Customize script, run by Configure after it has finished its work, gives you the opportunity to change the compile-time options related to the device cache file. (See The Customize Script section.) Since lsof may need setgid or setuid-root permission (See the Setgid Lsof Dialects and Setuid-root Lsof Dialects sections.), its security should always be viewed with skepticism. Lest the setgid and setuid-root permissions allow lsof to read kernel name list or memory files, declared with the -k and -m options, that the lsof user can't normally access, lsof uses access(2) to establish its real user's authority to read such files when it can't surrender its power before opening them. This change was added at the suggestion of Tim Ramsey. Lsof surrenders setgid permission on most dialects when it has gained access to the kernel's memory devices. There are exceptions to this rule, and some lsof implementations need to run setuid-root. (The Setgid Lsof Dialects and Setuid-root Lsof Dialects sections contains a list of lsof implementations and the permissions recommended in the distribution's Makefiles.) The surrendering of setgid permission is controlled by the WILLDROPGID definition in the dialect machine.h header files. In the end you must judge for yourself and your installation the risks that lsof presents and restrict access to it according to your circumstances and judgement. Run-time Warnings ================= Lsof can issue warning messages when it runs -- e.g., about the state of the device cache file, about an inability to access an NFS file system, etc. Issuance of warnings are enabled by default in the lsof distribution. Issuance or warnings may be disabled by default by defining WARNINGSTATE in the dialect's machine.h. The Customize script may also be used to change the default warning message issuance state. (See The Customize Script section.) The ``-w'' option description of the ``-h'' option (help) output will indicate the default warning issuance state. Whatever the state may be, it can be reversed with ``-w''. Device Access Warnings ====================== When lsof encounters a /dev (or /devices) directory, one of its sub-directories, or one of their files that it cannot access with opendir(3) or stat(2), it issues a warning message and continues. Lsof will be more likely to issue such a warning when it has been installed with setgid(<some group name>) permission; it won't have trouble if it has been installed with setuid(root) permission or is being run under the root login. The lsof caller can inhibit or enable the warning with the -w option, depending on the issuance state of run-time warnings. (See the Run-time Warnings section.) The warning messages do not appear when lsof obtains device information from a device cache file that it has built and believes to be current or when warning message issuance is disabled by default. (See the "Caches -- Name and Device" section for more information on the device cache file.) The lsof builder can inhibit the warning by disabling the definition of WARNDEVACCESS in the dialect's machine.h or disable all warnings by defining WARNINGSTATE. WARNDEVACCESS is defined by default for most dialects. However, some dialects have some device directory elements that are private -- e.g., HP-UX -- and it is more convenient for the lsof user if warning messages about them are inhibited. Output from lsof's -h option indicates the status of WARNDEVACCESS. If it was defined when lsof was compiled, this message will appear: /dev warnings = enabled If WARNDEVACCESS was not defined when lsof was compiled, this message will appear instead: /dev warnings = disabled The Customize script, run by Configure after it has finished its work, gives you the opportunity to change the WARNDEVACCESS definition. (See The Customize Script section.) NFS Blocks ========== Lsof is susceptible to NFS blocks when it tries to lstat() mounted file systems and when it does further processing -- lstat() and readlink() -- on its optional file and file system arguments. Lsof tries to avoid being stopped completely by NFS blocks by doing the lstat() and readlink() functions in a child process, which returns the function response via a pipe. The lsof parent limits the wait for data to arrive in the pipe with a SIGALRM, and, if the alarm trips, terminates the child process with a SIGINT and a SIGKILL. This is as reliable and portable a method for breaking NFS deadlocks as I have found, although it still fails under some combinations of NFS version, UNIX dialect, and NFS file system mount options. It generally succeeds when the "intr" or "soft" mount options are used; it generally fails when the "hard" mount option is used. When lsof cannot kill the child process, a second timeout causes it to stop waiting for the killed child to complete. While the second timeout allows lsof to complete, it may leave behind a hung child process. Unless warnings are inhibited by default or with the -w option, lsof reports the possible hung child. NFS block handling was updated with suggestions made by Andreas Stolcke. Andreas suggested using the alternate device numbers that appear in the mount tables of some dialects when it is not possible to stat(2) the mount points. The -b option was added to direct lsof to avoid the stat(2) and readlink(2) calls that might block on NFS mount points and always use the alternate device numbers. If warning message issuance is enabled and you don't want warning messages about what lsof is doing, use the -w option, too. The -O option directs lsof to avoid doing the potentially blocking operations in child processes. Instead, when -O is specified, lsof does them directly. While this consumes far less system overhead, it can cause lsof to hang, so I advise you to use -O sparingly. Caches -- Name and Device ========================== Robert Ehrlich suggested that lsof obtain path name components for open files from the kernel's name cache. Where possible, lsof dialect implementations do that. The -C option inhibits kernel name cache examination. Since AFS apparently does not use the kernel's name cache, where lsof supports AFS it is unable to identify AFS files with path name components. Robert also suggested that lsof cache the information it obtains via stat(2) for nodes in /dev (or /devices) to reduce subsequent running time. Lsof does that, too. In the default distribution the device cache file is stored in .lsof_hostname, mode 0600, in the home directory of the login of the user ID that executes lsof. The suffix, hostname, is the first component of the host's name returned by gethostname(2). If lsof is executed by a user ID whose home directory is NFS-mounted from several hosts, the user ID's home directory may collect several device cache files, one for each host from which it was executed. Lsof senses accidental or malicious damage to the device cache file with extensive integrity checks, including the use of a 16 bit CRC. It also tries to sense changes in /dev (or /devices) that indicate the device cache file is out of date. There are other options for forming the device cache file path. Methods the lsof builder can use to control and employ them are documented in the separate 00DCACHE file of the lsof distribution. Raw Sockets =========== On many UNIX systems raw sockets use a separate network control block structure. Display of files for applications using raw sockets -- ping, using ICMP, for example -- need special support for displaying their information. This support is so dialect-specific and information to provide it so difficult to find that not all dialect revisions of lsof handle raw sockets completely. Other Compile-time Definitions ============================== The machine.h and dlsof.h header files for each dialect contains definitions that affect the compilation of lsof. Check the Definitions That Affect Compilation section of the 00PORTING file of the lsof distribution for their descriptions. (Also see The Customize Script section.) The AFSConfig Script ==================== Lsof supports AFS on some combinations of UNIX dialect and AFS version. See the AFS section of this document for a list of supported combinations. When configuring for dialects where AFS is supported, the Configure script calls the AFSConfig script to determine the location of AFS header files and the AFS version. Configure will not call AFSConfig, even for the selected dialects, unless the file /usr/vice/etc/ThisCell exists. The AFS header file location is recorded in the AFSHeaders file; version, AFSVersion. Once these values have been recorded, Configure can be told to skip the calling of AFSConfig by specifying its (Configure's) -n option. The Inventory Script ==================== The lsof distribution contains a script, called Inventory, that checks the distribution for completeness. It uses the file 00MANIFEST in the distribution as a reference point. After the Configure script has accepted the dialect abbreviation, it normally calls the Inventory script to make sure the distribution is complete. After Inventory has run, it creates the file ".ck00MAN" in the top-level directory to record for itself the fact that the inventory has been check. Should Inventory be called again, it senses this file and asks the caller if another check is in order, or if the check should be skipped. The -n option may be supplied to Configure to make it bypass the calling of the Inventory script. (The option also causes Configure to avoid calling the Customize script.) The lsof power user may want to define (touch) the file ".neverInv". Configure avoids calling the Inventory script when ".neverInv" exists. The Customize Script ==================== Normally when the Configure script has finished its work, it calls another shell script in the lsof distribution called Customize. (You can tell Configure to bypass Customize with its -n option.) Customize leads you through the specification of these important compile-time definitions for the dialect's machine.h header file: HASDCACHE device cache file control HASENVDC device cache file environment variable name HASPERSDC personal device cache file path format HASPERSDCPATH name of environment variable that provides an additional component of the personal device cache file path HASSYSDC system-wide device cache file path HASKERNIDCK the build-time to run-time kernel identity check HASSECURITY the security option HASNOSOCKSECURITY the open socket listing option whe HASSECURITY is defined WARNDEVACCESS /dev (or /devices) warning message control WARNINGSTATE warning message issuance state The Customize script accompanies its prompting for entry of new values for these definitions with brief descriptions of each of them. More information on these definitions may be found in this file or in the 00DCACHE and 00FAQ files of the lsof distribution. You don't need to run Customize after Configure. You can run it later or you can edit machine.h directly. The -n option may be supplied to Configure to make it bypass the calling of the Customize script. (The option also causes Configure to avoid calling the Inventory script.) The lsof power user may want to define (touch) the file ".neverCust". Configure avoids calling the Customize script when ".neverCust" exists. Customize CAUTION: the Customize script works best when it is applied to a newly configured lsof source base -- i.e., the machine.h header file has not been previously modified by the Customize script. If you have previously configured lsof, and want to rerun the Customize script, I recommend you clean out the previous configuration and create a new one: $ Configure -clean $ Configure <dialect_abbreviation> ... Customize in response to the Customize script prompts. Cautions ======== Lsof is a tool that is closely tied to the UNIX operating system version. It uses header files that describe kernel structures and reads kernel structures that typically change from OS version to OS version, and even within a version as vendor patches are applied. DON'T TRY TO USE AN LSOF BINARY, COMPILED FOR ONE UNIX OS VERSION, ON ANOTHER. VENDOR PATCHES INFLUENCE THE VERSION IDENTITY. On some UNIX dialects lsof versions may be even more restricted by architecture type. The bottom line is use lsof where you built it. If you intend to use a common lsof binary on multiple systems, make sure all systems run exactly the same OS version and have exactly the same patches. Warranty ======== Lsof is provided as-is without any warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of lsof is with you. Should lsof prove defective, you assume the cost of all necessary servicing, repair, or correction. License ======= Lsof has no license. Its use and distribution are subject to these terms and conditions, found in each lsof source file. (The copyright year in or format of the notice may vary slightly.) /* * Copyright 2002 Purdue Research Foundation, West Lafayette, * Indiana 47907. All rights reserved. * * Written by Victor A. Abell * * This software is not subject to any license of the American * Telephone and Telegraph Company or the Regents of the * University of California. * * Permission is granted to anyone to use this software for * any purpose on any computer system, and to alter it and * redistribute it freely, subject to the following * restrictions: * * 1. Neither the authors nor Purdue University are responsible * for any consequences of the use of this software. * * 2. The origin of this software must not be misrepresented, * either by explicit claim or by omission. Credit to the * authors and Purdue University must appear in documentation * and sources. * * 3. Altered versions must be plainly marked as such, and must * not be misrepresented as being the original software. * * 4. This notice may not be removed or altered. */ Bug Reports =========== Now that the obligatory disclaimer is out of the way, let me hasten to add that I accept lsof bug reports and try hard to respond to them. I will also consider and discuss requests for new features, ports to new dialects, or ports to new OS versions. PLEASE DON'T SEND BUG REPORTS ABOUT LSOF TO THE UNIX DIALECT OR DIALECT OPTION VENDOR. At worst such bug reports will confuse the vendor; at best, the vendor will forward the bug report to me. PLEASE DON'T SEND BUG REPORTS ABOUT LSOF BINARIES BUILT OR DISTRIBUTED BY SOMEONE ELSE, BECAUSE I CAN'T SUPPORT THEM. Before you send me a bug report, please do these things: * Make sure you try the latest lsof revision. + Download the latest revision from: ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof + Verify the signatures of what you have downloaded; + While connected to lsof.itap.purdue.edu, check for patches: ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/patches + If patches exist, install them in the latest revision you just downloaded. Then build the latest revision and see if it fixes your bug. * If you're having trouble compiling lsof with gcc, try the UNIX dialect vendor's compiler. I don't have access to gcc on all test systems, so my support for it is hit-and-miss, and so is my ability to respond to gcc compilation problem reports. * Check the lsof frequently asked questions file, 00FAQ, to see if there's a question and answer relevant to your problem. * Make sure you're running the lsof you think you are by checking the path to it with which(1). When in doubt, use an absolute path to lsof. Make sure that lsof binary has sufficient permissions to do what you ask, including internal permissions given it (e.g., restrictions on what files lsof may report for whom) during its build. When you send a bug report, make sure you include output from your running of lsof's Configure script. If you were able to compile a running lsof, please also include: * Output from which(1) that shows the absolute path to the lsof binary in question; * Output from running lsof with its -h and -v options at lsof's absolute path; * Output from "ls -l" directed to lsof's absolute path. If you weren't able to compile a running lsof, please send me: the compiler error output; identification of the lsof revision you're using (contents of the lsof version.c file); identification of your system (full uname output or output from whatever other tool identifies the system); and compiler identification (e.g., gcc -v output). Either set of output will help me understand how lsof was configured and what UNIX dialect and lsof revision is involved. Please send all bug reports, requests, etc. to me via e-mail at <abe@purdue.edu>. Make sure "lsof" appears in the "Subject:" line so my e-mail filter won't classify your letter as Spam. The 00FAQ File ============== The lsof distribution contains an extensive frequently asked questions file on lsof features and problems. I recommend you consult it before sending me e-mail. Use your favorite editor or pager to search 00FAQ -- e.g., supplying as a search argument some fixed text from an lsof error message. The lsof-l Mailing List ======================= Information about lsof, including notices about the availability of new revisions, may be found in mailings of the lsof-l listserv. For more information about it, including instructions on how to subscribe, read the 00LSOF-L file of the lsof distribution. Field Output Example Scripts ============================ Example AWK and Perl 4 or 5 scripts for post-processing lsof field output are locate in the scripts sub-directory of the lsof distribution. The scripts sub-directory contains a 00README file with information about the scripts. Field Output C Library ====================== The lsof test suite (See "Testing Lsof."), checks basic lsof operations using field output. The test suite has its own library of C functions for common test program operations, including processing of field output. The library or selections of its functions could be adapted for use by C programs that want to process lsof field output. See the library in the file LTlib.c in the tests/ sub-directory Testing Lsof ============ Lsof has an automated test suite in the tests/ sub-directory that can be used to test some basic lsof features -- once lsof has been configured and made. Tests are arranged in three groups: basic tests that should run on all dialects; standard tests that should run on all dialects; and optional tests that may not run on all dialects or may need special resources to run. See 00TEST for more information.) CAUTION!!! Before you attempt to use the test suite make sure that the lsof you want to test can access the necessary kernel resources -- e.g., /dev/mem, /dev/kmem, /proc, etc. Usually you want to test the lsof you just built, so this is an important check. (See 00TEST.) To run the basic and standard tests, using the lsof in the parent directory of tests/, do this: $ cd tests $ make test or $ make std or $ make standard The basic and standard tests may be run as silently as possible, using the lsof in the parent directory of tests/, with: $ cd tests $ make auto This is the "automatic" test mode, designed for use by scripts that build lsof. The caller is expected to test the make exit code to determine if the tests succeeded. The caller should divert standard output and standard error to /dev/null to suppress make's error exit message. The optional tests may be run, using the lsof in the parent directory of tests/, with: $ cd tests $ make opt or $ make optional It's possible to excute individual tests, too. See the 00TEST file of this distribution for more informaiton on the tests, what they do, and how to run and possibly customize each test. It's possible to run the tests, using an lsof other than the one in the parent directory of /tests, too. See 00TEST for information about using the LT_LSOF_PATH environment variable to do that. ============= Dialect Notes ============= AFS === Lsof recognizes AFS files on the following combinations of UNIX dialect and AFS versions: AIX 4.1.4 (AFS 3.4a) Linux 1.2.13 (AFS 3.3) NEXTSTEP 3.2 (AFS 3.3) (untested on recent lsof revisions) Solaris 2.6 (AFS 3.4a) Ultrix 4.2 RISC (AFS 3.2b) (no longer available) Lsof has not been tested under other combinations -- e.g. HP-UX 10.10 and AFS 3.4a -- and probably won't even compile there. Often when a UNIX dialect version or AFS version changes, the new header files come into conflict, causing compiler objections. AIX === Specify the aix Configure abbreviation for AIX 4.1.[45], 4.2[.1], 4.3[.123], 5L, and 5.[123]. Specify aixgcc on AIX above 4.1 to use the gcc compiler. (Gcc can't be used to compile lsof on AIX 4.1 and below because of kernel structure alignment differences between it and xlc.) Gcc results sometimes depend on the version of the gcc compiler that is used. Compilation of lsof with gcc on AIX 4.3[.123], 5L, and 5.[123] has been sparsely tested with varying degrees of success: it has been reported to succeed on AIX 4.3.3 and 32 bit Power AIX 5.1; to fail on ia64 AIX 5.1 and 64 bit Power AIX 5.1; and to succeed on 32 and 64 bit Power AIX 5.2. Lsof compilation with gcc hasn't been tested on AIX 5.3. At revision 4.61 and above lsof is configured and built to match the bit size of the kernel of Power architecture AIX 5.1 systems. Lsof binaries built for 32 and 64 bit kernels are not interchangeable. See 00FAQ for more information. The Configure script uses /usr/bin/oslevel to determine the AIX version for AIX less than 5 and ``uname -rv'' for AIX 5 and higher. If /usr/bin/oslevel isn't executable on AIX less than 5, the Configure script issues a warning message and uses ``uname -rv'' to determine the AIX version. When Configure must use ``uname -rv'' on AIX less than 5 to determine the AIX version, the result will lack a correct third component -- e.g., the `4' of ``4.1.4''. If your AIX less than 5 system lacks lacks an executable oslevel, I suggest you edit the Configure-produced Makefile and complete the _AIXV definition in the CFGF string. By default lsof avoids using the kernel's readx() function, causing it to be unable to report information on some text and library file references. The ``-X'' option allows the lsof user to ask for the information readx() supplies. Lsof avoids readx() to avoid the possibility of triggering a kernel problem, known as the Stale Segment ID kernel bug. Kevin Ruderman reported this bug to me. The bug shows up when the kernel's dir_search() function hangs, hanging the application process that called it so completely that the application process can neither be killed nor stopped. The hang is the consequence of another process (perhaps lsof) making legitimate use of the kernel's readx() function to access the kernel memory that dir_search() is examining. IBM has indicated they have no plans to fix the bug. A fuller discussion of this bug may be found in the 00FAQ file of the lsof distribution. There you will find a description of the Stale Segment ID bug, the APAR on it, and a discussion of the sequence of events that exposes it. I added the ``-X'' function so you can tell lsof to use readx(), but if you use ``-X'', you should be alert to its possibly serious side effects. Although readx() is normally disabled, its state is controlled with the HASXOPT, HASXOPT_ROOT, and HASXOPT_VALUE definitions in dialects/aix/machine.h, and you can change its default state by changing those definitions. You can also change HASXOPT_ROOT via the Customize script. You can also compile lsof with readx() use permanently enabled or disabled -- see the comments about the definitions in the dialects/aix/machine.h header file. You may want to permanently disable lsof's use of readx() if you plan to make lsof publicly executable. You can also restrict -X to processes whose real UID is root by defining HASXOPT_ROOT. I have never seen lsof cause the Stale Segment ID bug to occur and haven't had a report that it has, but I believe there is a possibility it could. AFS support for AIX was added with help help from Bob Cook and Jan Tax who provided test systems. Henry Grebler and David J. Wilson helped with lsof for AIX 4.2. Bill Pemberton provided an AIX 4.3 test system. Andrew Kephart and Tom Weaver provided AIX 4.3 technical assistance. Niklas Edmundsson did 4.3.1 testing. Doug Crabill provided an AIX 4.3.2 test system. Jeff W. Stewart provided an AIX 4.3.3 test system. The SMT file type for AIX 4.1.[45], 4.2[.1], and 4.3[.12] is my fabrication. See the 00FAQ file more information on it. Loc Le and Nasser Momtaheni of IBM provided test systems for AIX 5L and 5.1. Lsof for AIX 5L and 5.1 needs setuid-root permission to process the -X option on systems whose architecture type is ia64. Dale Talcott of Purdue provided AIX 5.1 and 5.2 test systems. Dale and John Jackson of Purdue provided an AIX 5.3 test system. Apple Darwin ============ The Apple Darwin port was provided by Allan Nathanson for version 1.2. Allan also arranged for access to a test system for maintenance and regression testing. Dale Talcott provided a test system, too. Allan supplied patches for updates to 1.4, 5.x, 6.x, 7.x and 8.x. BSDI BSD/OS =========== As of lsof revision 4.77 support for BSDI BSD/OS has been discontinued. Lsof revision 4.76 with BSDI BSD/OS support may be found on lsof.itap.purdue.edu in pub/tools/unix/lsof/src. DEC OSF/1, Digital UNIX, Tru64 UNIX =================================== Robert Benites, Dean Brock, Angel Li, Dwight McKay, Berkley Shands, Ron Young and Steve Wilson have kindly provided test systems. Jeffrey Mogul has provided technical assistance. Dave Morrison and Lawrence MacIntyre did Digital UNIX V3.2 testing. Lsof supports the ADVFS/MSFS layered file system product. Lsof can locate all the open files of an ADVFS/MSFS file system when its path is specified, provided the file system is listed in /etc/fstab with an ``advfs'' type. (This /etc/fstab caveat applies only to Digital UNIX 2.0.) At Digital UNIX 4.0 and Tru64 UNIX, using code provided by David Brock, lsof 4.20 and above can locate ADVFS file paths. Testing of lsof on DEC OSF/1 and Digital UNIX 4.0 ended with lsof revision 4.74. Hence, the lsof documentation has dropped the claim that it works there. For a distribution of lsof 4.74 that was tested on DEC OSF/1 and Digital UNIX 4.0, check pub/tools/unix/lsof/OLD/src on the lsof ftp home, lsof.itap.purdue.edu. Lsof revisions past 4.74 have only been tested on Tru64 UNIX 5.1. FreeBSD ======= Bill Bormann of Purdue University provided access to several FreeBSD test systems. Ade Barkah, John Clear, Ralph Forsythe, Michael Haro, Kurt Jaeger, and William McVey have also provided FreeBSD test systems. The FreeBSD distribution header files are augmented by header files in the dialects/freebsd/include directory. David O'Brien maintains the lsof FreeBSD port package. HP-UX ===== Lsof has two HP-UX bases: /dev/kmem for HP-UX 11.0 and earlier; and PSTAT for HP-UX 11.11 and later. The lsof Configure script will pick the appropriate base. To use the CCITT x.25 socket support for HP-UX, you must have the x.25 header files in /etc/conf/x25 Pasi Kaara helped with the HP-UX port, especially with its CCITT x.25 socket support. Richard Allen provided HP-UX 10.x and 11.x test systems, as did Mark Bixby, and Elias Halldor Agustsson. Marc Winkler helped test the 10.20 port. Richard J. Rauenzahn provided a 64 bit HP-UX 11 test system and an HP-UX 11.11 development system. AFS support for HP-UX was added thanks to help from Chaskiel Moses Grundman, who provided a test system. The /dev/kmem-based HP-UX 11.00 support is extremely fragile. It depends on privately developed kernel structure definitions. (See .../dialects/hpux/hpux11 for the header files making the definitions.) Those header files and their definitions will not be updated by HP-UX 11.00 patches, making it likely that any patch changing a kernel structure critical to lsof will break lsof in some way. It's possible to build a 64 bit lsof for 64 bit HP-UX 11.00 with gcc, but you must have a gcc compiler capable of producing 64 bit executables. See the 00FAQ file for more information. The PSTAT-based lsof for HP-UX 11.11 and later is much more solid. I am indebted to the vision of HP for providing an lsof kernel API through the PSTAT implementation. Specifically I appreciate the help of HP staff members Carl Davidson, Louis Huemiller, Rich Rauenzahn, and Sailu Yallapragada that made PSTAT-based HP-UX lsof possible. IPv6 ==== Lsof has IPv6 support that has been tested for these UNIX dialects: AIX 4.3.x; Apple Darwin 5.[12] and 6.0; the INRIA and KAME FreeBSD IPv6 implementations; PSTAT-based HP-UX; /proc-based Linux; the INRIA and KAME NetBSD implementations; and Solaris 8 and 9. Lsof has IPv6 support that hasn't been tested for: OpenBSD (KAME); OpenUNIX 8; Tru64 Unix 5.[01]; and UnixWare 7.1.[34]. Please let me know if your UNIX dialect has IPv6 support and I'll see if it can be supported by lsof. Linux ===== Tim Korb, Steve Logue, Joseph J. Nuspl Jr., and Jonathan Sergent have provided Linux test systems. Michael Shields helped add and test automatic handling of ELF/COFF form names in /System.map, Marty Leisner and Keith Parks have helped test many lsof revisions. Marty has provided valuable suggestions, Linux hints, and code, too. The 00FAQ file gives some Linux tips, including information on coping with system map file problems. To determine the state of the Linux 2.1.x C library lseek() function, the lsof Configure script runs a test program that must have permission to read /dev/kmem. The test determines if the lseek() function properly handles kernel offsets, which appear to be negative because their high order bit is set. If the lseek() test reveals a faulty lseek(), Configure activates the use of a private lseek() function for kernel offset positioning. See the Linux problems section of the 00FAQ file of the lsof distribution for more information. NetBSD ====== Greg Earle and Paul Kranenburg have assisted with the NetBSD ports. Paul has provided test systems. Ray Phillips provided a NetBSA Alpha test system. Andrew Brown also provided a test system. The NetBSD dialect version of lsof is compiled using the dialect sources it shares with OpenBSD in the n+obsd dialect sub-directory. NEXTSTEP and OPENSTEP ===================== Virtual memory header files that allow lsof to display text references were derived from the contents of /usr/include/vm of NEXTSTEP 2.0. NeXT did not ship the virtual memory header files with other NEXTSTEP or OPENSTEP versions. You may use the RC_FLAGS environment variable to declare compiler options outside the Makefile. A common use of this variable is to define the architecture types to be included in a "fat" executable. See the comments in dialects/next/Makefile for an example. OpenBSD ======= David Mazieres has provided OpenBSD test systems. The OpenBSD dialect version of lsof is compiled using the dialect sources it shares with NetBSD in the n+obsd dialect sub-directory. Kenneth Stailey has provided OpenBSD testing and advice. John Dzubera (Zube) reports, "lsof 4.33 compiles and runs on OpenBSD 2.3 for the pmax architecture (decstation 3100)." I have not tested lsof on OpenBSD 3.8, but David Mazieres reports revision 4.76 worked on OpenBSD 3.8. Pyramid DC/OSx and Reliant UNIX =============================== As of lsof revision 4.52 support for all Pyramid dialects has been discontinued. Lsof revision 4.51 with Pyramid support may be obtained upon request. Send the request to abe@purdue.edu. These two UNIX dialects are very similar and share dialect-specific source files from the pyramid sub-directory. The Reliant Unix Pyramid C compiler issues warning messages that I haven't found a convenient way to suppress. You can ignore warning messages about casts and conversions that lose bits. The message "warning: undefining __STDC__" is intentionally caused by the lsof MkKernOpts configuration script to suppress warning messages about cast and conversion problems in standard system header files, such as <stdio.h> and <string.h>. Bruce Beare and Kevin Smith provided test systems. Caldera OpenUNIX ================ Larry Rosenman provided an OpenUNIX 8 test system. Matthew Thurmaier provided technical assistance, along with these people from Caldera: Jack Craig, Robert Lipe, and Bela Lubkin. Robert Lipe supplied changes to lsof for OpenUNIX 8.0.1. Those changes were also incorporated in UnixWare 7.1.3 when it became the release name for OpenUNIX 8.0.1. Support for lsof on OpenUNIX ended at lsof revision 4.74. The last lsof revision, 4.74, tested on OpenUNIX, may be found at the lsof "home" ftp site, lsof.itap.purdue.edu, in pub/tools/unix/lsof/OLD/src. SCO OpenServer ============== Dion Johnson, Bela Lubkin, and Nathan Peterson of SCO gave me copies of SCO OpenServer and the SCO OpenServer Development System 3.0 and provided technical advice for the lsof port. Hugh Dickins, Bela Lubkin, Craig B. Olofson, and Nathan Peterson provided version 5.0 and gave technical advice for porting lsof to it. Bela provided the 5.0.4 changes. D. Chris Daniels provided a 5.0.4 test system, Lee Penn provided one for 5.0.5, and John Dubois for 5.0.6. The <netdb.h> header file was accidentally omitted from some SCO OpenServer Development System releases. The Configure script will sense its absence and substitute an equivalent from the BSD distribution. The BSD <netdb.h> and the <sys/cdefs.h> header file it includes are located in the dialects/os/include sub-directory tree. To compile lsof from its distribution sources you must have the TCP/IP and NSF headers in /usr/include. While those are optional OpenServer packages, I have access to no system that doesn't have them, so I'm unable to build lsof for such a configuration. However, it should be possible to modify the lsof Configure script and sources so lsof would compile and work without those optional packages. If you have an OpenServer system configured without the TCP/IP and NFS packages, and want to tackle the job of building lsof for it, contact me via e-mail at <abe@purdue.edu>. I'll identify the Configure script, header file, and source file changes you will need to make. (Caution: this is not a simple task, or I would have already done it.) The optional osrgcc and scogcc Configure abbreviations construct Makefiles for compiling lsof with gcc. The UnixWare 7.1.4 sources are used for OpenServer Release 6.0.0. Hence there is a separate Configure abbreviation for it, "osr6". Richard of SCO provided a test system and technical assistance. SCO|Caldera UnixWare ============ D. Chris Daniels, John Hughes, Ken Laing, Andrew Merril, Lee Penn, and Matthew Thurmaier provided test systems. Bela Lubkin provided technical assistance. Larry Rosenman provided 7.1.[34] test systems. Solaris 2.x, 7, 8, 9 and 10 =========================== SEE THE CAUTIONS SECTION OF THIS DOCUMENT. The latest Solaris revision of lsof 4 might work under Solaris 2.[1-4] and 2.5[.1] and 7 but hasn't been tested there. I have no test systems for those Solaris versions. Lsof will compile with gcc and the Sun C compiler under Solaris. If you want to use the Sun compiler, use the solariscc Configure abbreviation. If you use a gcc version less than 2.8 on Solaris, make sure the gcc-specific includes have been updated for your version of Solaris -- i.e., run the gcc fixincludes script. Solaris 7, 8, 9 and 10 support for 64 bit kernels depends on a Sun WorkShop or Forte C compiler version that supports the "-xarch=v9" flag -- usually 5.0 or greater. Gcc versions 2.95 and above *may* be configured and built for 64 bit support, but it takes some extra work, the resulting compiler may be fragile, and the gcc developers discourage it. I've built 64 bit capable gcc compilers for Solaris 7, 8 and 9 from gcc versions 2.95 through 3.0.1 and produced working lsof executables with them. More information on 64 bit gcc for Solaris may be found in the 00FAQ file. Solaris 10 ZFS support is questionable, because Sun does not distribute the ZFS kernel structure definition header files. The lsof Configure script and source code use some risky work-arounds. ZFS file system support was made possible with help from Horst Scheuermann. Dave Curry and Steve Kirsch provided resources for Solaris 2.x ports. Casper Dik and Gerry Singleton consulted and provided valuable assistance. Henry Katz, Joseph Kowalski, Charles Stephens, Mike Sullivan, and Mike Tracy provided technical assistance. AFS support was added to Solaris lsof with help from Curt Freeland, Heidi Hornstein, Michael L. Lewis, Terry McCoy, Phillip Moore, and Sushila R. Subramanian. Casper Dik provided valuable assistance for the Solaris 8 support. Sun has graciously provided me access to BETA versions of Solaris 2.5, 2.6, 7, 8, and 9. John Dzubera provided Solaris 7 and 8 test systems. Mike Miscevic provided Solaris 10 test systems. Ultrix ====== As of lsof revision 4.52 support for Ultrix is no longer available, because I no longer have an Ultrix test system. Terry Friedrichsen, Dwight McKay, and Jeffrey Mogul helped me with this port. DECnet support was added to Ultrix lsof with the help of John Beacom, who kindly provided a test system. The Configure script decides that DECnet support is available if /usr/lib/libdnet.a and /usr/include/netdnet/dn.h exist and are readable. Veritas VxFS and VxVM ===================== Lsof supports some versions of Veritas VxFS and VxVM on some UNIX dialects. Consult the lsof Configure script for the specific dialect, and consult the lsof dialect-specific source files for the UNIX dialect of interest. Veritas support will usually be found in a source file named dnode[1-9].c. Since Veritas rarely has a version number that can be extracted with shell commands, lsof doesn't use it. Instead, when lsof supports Veritas, the Configure script will form compile-time definitions starting with HASVXFS. Check the lsof 00PORTING documentation file for more information. Lsof Veritas support requires that the supporting Veritas header files be installed -- e.g., in /usr/include/sys/fs. (The location will depend in the dialect's header file conventions.) Some information on lsof support for Veritas extensions may be found in the lsof 00DIST file. (The ChangeLog file points to 00DIST.) Chris Kordish and Andy Thomas have provided Solaris VxFS test systems. ================================ User-contributed Dialect Support ================================ There are some user-contributed dialect versions of lsof; more information on them can be found at: ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/contrib Check the 00INDEX file there for details. ============================ Dialects No Longer Supported ============================ Because I don't have access to test systems, these UNIX dialects are no longer supported by lsof: CDC EP/IX /dev/kmem-based Linux MIPS RISC/os Motorola V/88 Pyramid DC/OSx Pyramid Reliant UNIX Sequent DYNIX SGI IRIX SunOS 4.x Ultrix UnixWare below 7.0 Remnants of the support lsof once provided for these dialects may be found in: ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/OLD/dialects =============== Installing Lsof =============== The distributed Makefiles do not have actions that will install lsof. I've come to the conclusion there is no standard for installing lsof or its man page, so I no longer distribute make rules for installing them. You should adjust the Makefile for your local preferences. The Makefile does have an install rule that will cause lsof to compile by virtue of its dependency clause. Some Makefiles also have a dependency that causes the production of a man page that is ready to install. However, the actions of the install rule will not cause the lsof executable or its man page to be installed in any UNIX system-wide directory. Instead, after the compilation and optional man page production are completed, the install rule will produce a brief description of what actions you might add to the install rule. The description will suggest the possible modes, ownerships, permissions, and destinations your install rule might employ to install the lsof executable and man page. As you form your install rule, keep in mind that lsof usually needs some type of special permission to do its job. That may be permission to read memory devices such as /dev/kmem, /dev/mem, or /dev/swap, or it may be authorization to read entries in the /proc file system. Memory device access can usually be provided by setting the modes of the lsof executable so that it's effective group identifier when it runs is the same as the group that has permission to read the memory devices -- i.e., it is setgid-group. The privileged group is usually kmem, sys, or system. Don't overlook using ACLs -- e.g., on AIX or Solaris 8 -- to give lsof permission to access memory devices. ACLs, coupled to a separate group like kmem, can be safer than giving lsof setgid authorization to a commonly used system group. When lsof needs to read /proc file system entries, it must be installed with modes that make its effective user identifier root when it runs -- i.e., it must be setuid-root. If lsof must be installed setuid-root (only the AIX 5L, PSTAT-based HPUX, and /proc-based Linux, ports need such power.), then access to memory devices is automatic (or not needed in the case of /proc-based Linux). Your choice of permissions for lsof may also be affected by your desire to allow anyone to use it or your need to restrict its usage to specific individuals. You will have to be guided by local policy and convention in this case. The next two sections, Setgid Lsof Dialect Versions and Setuid-root Lsof Dialect Versions, list recommended install permissions. The system directory where you install the lsof executable is also open to choice. A traditional place for a tool like lsof is /usr/local/etc, but recent changes in directory structure organization suggest that somewhere in /opt may be more suitable. Bear one other factor in mind when choosing a location for the lsof executable -- it usually is a shared executable, requiring access to shared libraries. Thus, locations like /sbin or /usr/sbin are probably unsuitable. Once you've chosen a location for the executable you may find that the location for the man page follows -- e.g., if the executable goes in /usr/local/etc, then the man page goes in /usr/local/man. If the executable location doesn't imply a location for the man page, you'll have to let local custom guide you. Setuid-root Lsof Dialect Versions ================================= These dialect versions should be installed with setuid-root permission -- i.e., the lsof binary should be owned by root and its setuid execution bit (04000) should be set. AIX 5L and above for full use of the -X option Apple Darwin 8.x for Power Macintosh systems PSTAT-based HP-UX 11.11 and 11.23 /proc-based Linux (generally 2.1.72 and above) Setgid Lsof Dialect Versions ============================ These dialect versions should be installed with setgid permission, owned by the group that can read kernel memory devices such as /dev/drum, /dev/kmem, /dev/ksyms, /dev/mem, /dev/swap. ACLs may be another mechanism (e.g., under AIX or Solaris 8) you can use to grant read permission to the kernel memory devices. AIX 4.1.[45], 4.2[.1], and 4.3[.123] Apple Darwin 7.x for Power Macintosh systems DEC OSF/1, Digital UNIX, Tru64 UNIX 2.0, 3.2, 4.0, and 5.[01] FreeBSD 2.1.6, 2.2[.x], 3.x, 4.x, 5.x and [67].x /dev/kmem-based 11.00 NetBSD 1.[456], 2.x and 3.x NEXTSTEP 3.[13] OpenBSD 2.[89] and 3.[0-9] OPENSTEP 4.x Caldera OpenUNIX 8 SCO OpenServer 5.0.[46] SCO UnixWare 7.0 and 7.1.[0134] Solaris 2.6, 8, 9 and 10 Ultrix 4.2 (no longer available) ==================================== Porting lsof 4 to a New UNIX Dialect ==================================== If you're brave enough to consider this, look at the 00PORTING file. Please contact me before you start. I might be able to help you or even do the port myself. Don't overlook the contrib/ directory in pub/tools/unix/lsof on my ftp server, lsof.itap.purdue.edu. It contains user-contributed ports of lsof to dialects I don't distribute, because I can't test new revisions of lsof on them. ========================= Quick Start to Using lsof ========================= For information on how to get started quickly using lsof, consult the 00QUICKSTART file of the lsof distribution. It cuts past the formal density of the lsof man page to provide quick examples of using lsof to solve common open file display problems. ====================== Cross-configuring Lsof ====================== Using environment variables it is possible to Configure (and possibly build) lsof for one UNIX dialect on a different one -- e.g., you are running Configure on a Linux 2.3 system and you want to Configure and build lsof for Linux 2.4. See the 00XCONFIG file of the lsof distribution for a discussion of how to do this. ==================================================== Environment Variables Affecting the Configure Script ==================================================== Configure script actions can be modified by introducing values to the script via environment variables. In many cases the environment variable values take the place of test operations the Configure script makes. For more information on environment variables that can affect Configure, consult the 00XCONFIG file of the lsof distribution. See the General Environment Variables sections for descriptions of ones that affect all dialects. Consult the Dialect-Specific Environment Variables section for ones that might affect the dialect you are trying to configure. Vic Abell <abe@purdue.edu> January 2, 2013