diff options
Diffstat (limited to '00README')
-rw-r--r-- | 00README | 1526 |
1 files changed, 1526 insertions, 0 deletions
diff --git a/00README b/00README new file mode 100644 index 0000000..5d0c388 --- /dev/null +++ b/00README @@ -0,0 +1,1526 @@ + + 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 |