Making and Installing lsof 3 ******************************************************************** | The latest release of lsof is always available via anonymous ftp | | from vic.cc.purdue.edu. Look in pub/tools/unix/lsof. | ******************************************************************** Contents Making Lsof Other Configure Script Options Security Device Directory 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 Bug Reports Field Output Example Scripts Dialect Notes AIX 3.2.[45], 4.1, and 4.1.[1234] BSDI BSD/OS 2.0, 2.0.1, and 2.1-BETA EP/IX FreeBSD HP-UX 8.x, 9.x, and 10 IRIX 4.0.5H, 5.1.1, 5.2, 5.3, 6.0, 6.0.1, 6.1, and 6.2-BETA Linux through 1.3.56 NetBSD 1.0 and 1.1 NEXTSTEP 2.1 and 3.[0123] Novell UnixWare 1.1, 1.1.1, and 1.1.2 OSF/1 2.0, 3.[02], and 4.0-BETA for the DEC Alpha Pyramid DC/OSx 1.1 for ES, Nile and S Series RISC/os 4.52 SCO OpenDesktop or OpenServer 1.1, 3.0, and 5.0 Sequent PTX 2.1.[156], 4.0.[23], and 4.1.[02] Solaris 2.[12345] SunOS 4.1.[1234] SunOS 4.1.x gcc Warning Ultrix 2.2, 4.2, 4.3, 4.4, and 4.5 Installing Lsof Porting lsof 3 to a New Unix Dialect Quick Start to Using lsof =========== Making Lsof =========== This lsof distribution can be used with many Unix dialects. However, it must be configured specifically for each dialect. Configuration is done in two ways: 1) by changing definitions in the machine.h header file of the Unix dialect of interest; and 2) 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 should look at them first anyway. Pay particular attention to the definitions that are discussed in the Security section of this file. Please read that section now. The Configure script calls three other scripts in the lsof distribution: AFSConfig; Inventory; and Customize. The AFSConfig script is called for selected dialects (HP-UX, Solaris, and SunOS at lsof revision 3.61) to locate AFS header files. 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 subdirectory to construct the appropriate source files in the top-level distribution directory. Configure also creates a 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 for the following Unix dialects, using the named abbreviations -- e.g., $ Configure solaris Dialect* Abbreviation Notes Unix Dialect ------------ ------ ------------ aix Yes IBM AIX 3.2.[45], 4.1, and 4.1.[1234] bsdi Yes BSDI BSD/OS 2.0, 2.0.1, and 2.1-BETA decosf Yes DEC OSF/1 2.0, 3.[02], and 4.0-BETA epix211 Yes EP/IX 2.1.1 for the CDC 4680 freebsd Yes FreeBSD 1.1.5.1, 2.0, 2.0.5, and 2.1 hpux Yes HP-UX 8.x, 9.x, and 10 irix Yes SGI IRIX 4.0.5H, 5.2, 5.3, 6.0, 6.0.1, 6.1, and 6.2-BETA netbsd Yes NetBSD 1.0 and 1.1 linux Yes Linux through 1.3.56 next3 Yes NEXTSTEP 2.1 and 3.[0123], all architectures ptx Yes Sequent PTX 2.1.[156], 4.0.[23], and 4.1.[02] riscos Yes RISC/os 4.52 for MIPS R2000-based systems sco Yes SCO OpenDesktop or OpenServer, 1.1, 3.0, and 5.0 solaris Yes Solaris 2.[12345], using gcc solariscc Yes Solaris 2.[12345], using Sun's cc sunos413 Yes SunOS 4.1.[1234], using gcc sunos413cc Yes SunOS 4.1.[1234], using Sun's cc ultrix22 Yes Purdue version of Ultrix 2.2 ultrix Yes Ultrix 4.2, 4.3, 4.4, and 4.5 for DEC RISC and VAX (* -- Look in the Dialect Notes section for more information on the lsof revision for this dialect.) If you have an earlier version of a Unix dialect named in this list, lsof may 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.3. 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, copied source files, and assembled source 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. 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). Lsof is distributed with the security mode disabled -- HASSECURITY is not defined. 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. (See the The Customize Script section.) 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 can 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. All pre-compiled binaries on vic.cc.purdue.edu or its mirrors were constructed without the HASSECURITY definition. 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 section 4.2 of 00FAQ. (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 usually needs setgid permission to read /dev/mem or /dev/kmem, and needs setuid-root permission to read /proc file system entries, 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, when it can't surrender its power before opening them, lsof uses access(2) to establish its real user's authority to read such files. This change was added in revision 3.07 at the suggestion of Tim Ramsey . Lsof surrenders setgid permission on most ports when it has gained access to the kernel's memory devices. There are exceptions to this rule, and some lsof implementations must run setuid-root. Appendix B of 00DCACHE contains a list of the 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. Device Directory Access Warnings ================================ When lsof encounters a /dev (or /devices) directory or one of its subdirectories that it cannot access with opendir(3), it issues a warning message and continues. The lsof caller can inhibit the warning with the -w option. The lsof builder can inhibit the warning by disabling the definition of WARNDEVACCESS in the dialect's machine.h. WARNDEVACCESS is defined by default for most dialects. However, some dialects have some device subdirectories 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: Warnings are enabled for inaccessible device directories. If WARNDEVACCESS was not defined when lsof was compiled, this message will appear instead: Warnings are disabled for inaccessible device directories 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 with the -w option, lsof reports the possible hung child. The NFS block handling was updated at revisions 3.17 and 3.18 from 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. Lsof 3.17 does this. The -b option was added at lsof 3.18 to direct it to avoid the stat(2) and readlink(2) calls that might block on NFS mount points and always use the alternate device numbers. Consequently, if you're running lsof 3.18 or later, you can avoid kernel blocks altogether by using the -b option. If you don't want warning messages about what lsof is doing, use the -w option, too. The -O option was added at revision 3.36. It 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 revisions 3.19 and later do this. 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 revisions 3.19 and later do this. 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 by comparing the device cache file's mtime to the mtime and ctime of the device directory. There are other options for forming the device cache file path. Methods the lsof builder can use to control and employ them is 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 ==================== When configuring for selected dialects -- AIX, HP-UX, NEXTSTEP, Solaris, and SunOS as of lsof revision 3.61 -- the Configure script calls the AFSConfig script to determine the location of AFS header files and the version of AFS in use. 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 HASSECURITY the security option WARNDEVACCESS /dev (or /devices) warning message control 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. 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. DON'T TRY TO USE AN LSOF BINARY, COMPILED FOR ONE UNIX OS VERSION, ON ANOTHER. On some Unix dialects, notably SunOS and Solaris, lsof versions may be even more restricted by architecture type. An lsof binary, compiled for SunOS 4.1.3 on a sun4c machine, for example, won't work on a sun4m machine. Although I have no evidence that they exist, the potential for similar restrictions exists in Solaris versions of lsof. AN LSOF BINARY, COMPILED FOR ONE SOLARIS ARCHITECTURE, ISN'T GUARANTEED TO WORK ON A DIFFERENT SOLARIS ARCHITECTURE. 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. 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 A BUG REPORT ABOUT LSOF TO THE UNIX DIALECT VENDOR. At worst such a bug report will confuse the vendor; at best, the vendor will forward the bug report to me. Please send all bug reports, requests, etc. to me via email at . Field Output Example Scripts ============================ Example AWK and Perl 4 or 5 scripts for post-processing lsof field output are locate in the scripts subdirectory of the lsof distribution. The scripts subdirectory contains a 00README file with information about the scripts. ============= Dialect Notes ============= AIX 3.2.[45], 4.1, and 4.1.[1234] ================================= Specify the aix Configure abbreviation for AIX 3.2.[45], 4.1, and 4.1.[1234]. The Configure script uses /usr/bin/oslevel to determine the AIX version. If /usr/bin/oslevel isn't executable, the Configure script issues a warning message and assumes the version is 3.2.0. If you have an AIX version earlier than 3.2.0, you will have to edit the Makefile, produced by Configure, and change the value of the _AIXV definition in the CFGF string. As of revision 3.29 lsof by default 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 was added to allow 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 (e.g., 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 in 3.2.x or 4.1[.x] but may fix it in 4.2. A fuller discussion of this bug may be found in the 00FAQ file of this distribution. Sections 3.4.2 and 3.4.2.1 describe the Stale Segment ID bug, the APAR on it, and 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. Mark Peek provided and tested the changes for IBM's AIX 4.1. AFS suppport for AIX was added at lsof revision 3.61, thanks to help from Bob Cook and Jan Tax who provided test systems. BSDI BSD/OS 2.0, 2.0.1, and 2.1-BETA ==================================== Terry Kennedy provided a 2.1-BETA test system so that support for BSDI BSD/OS could be revived at revision 3.57. (BSDI BSD/OS support was dropped at revision 3.21 when a test system was no longer available.) Terry did the 2.0.1 testing. Since 2.0 and 2.0.1 do not differ signficantly, Terry believes that lsof 3.57 will work there, too. THE BSDI /proc file system support was copied from NetBSD and has not been tested. EP/IX ===== The EP/IX port would not have been possible without the help of Doug Eldred of CDC. There is no /proc file system support in EP/IX 2.1.1, even though it's a SYSV R4 derivative. As now configured, lsof must compile in the svr3 environment, but /proc file system support needs functions and header files from the svr4 environment. I have not succeeded in mixing the two environments. FreeBSD ======= Bill Bormann of the Purdue University Computing Center provided access to a FreeBSD 1.1.5.1 test system. Kurt Jaeger helped with the FreeBSD 2.0 update. Ade Barkah and William McVey provided FreeBSD 2.0 test systems. Ade provided the FreeBSD 2.0.5 test system. The FreeBSD distribution header files are augmented by header files in the dialects/freebsd/include directory tree. The tree includes separate sub-trees for FreeBSD 1.1.5.1 (dialects/freebsd/include/1) and 2.0 (dialects/freebsd/include/2). The two sub-trees contain header files that may not always be present in a FreeBSD system, or that need special modifications. The modifications consist of #if/#endif brackets, using the definition LSOF, to eliminate or alter troublesome header file items. The LSOF definition is made in the CDEFS string of the Makefile. Configuring lsof 3 for FreeBSD, using lsof's Configure script, may require specification of the name of the file in / that contains kernel name list (symbol to address) information. The Configure script assumes that the file is named /386bsd for FreeBSD 1.1.5.1; and gets the FreeBSD 2.0 name via sysctl(8). If the FreeBSD 2.0 sysctl doesn't yield a kernel name, lsof uses a default of /kernel. After defining the default kernel file name, lsof tests it to make sure it's a plain, executable file. If it is not, Configure will ``ls -CF'' the contents of / and ask that the Configure user specify the name of the kernel name list file. Whatever is specified must be a plain, executable file. John Clear provided access to a FreeBSD 2.1 test system. HP-UX 8.x, 9.x, and 10 ====================== Lsof has been tested under some versions of HP-UX 8.x, 9.x, and 10 on some HP hardware platforms. 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 a test system and helped with the HP-UX 10 port. AFS support for HP-UX was added at lsof revision 3.61, thanks to help from Chaskiel Moses Grundman , who provided a test system. IRIX 4.0.5H, 5.1.1, 5.2, 5.3, 6.0, 6.0.1, 6.1, and 6.2-BETA =========================================================== Adam Hammer of Purdue's Computer Science Department, Dwight McKay of Purdue's Biology Department, and Dave Olson of Silicon Graphics kindly assisted with the IRIX ports. Przemek Klosowski provided IRIX 6.0 and 6.1 test systems. Eberhard Mater helped with 6.0.1 testing. Angel Li provided a 6.2-BETA test system. I currently don't have access to IRIX 4.0.5, 5.1.1, 5.2, or 6.0, so recent revisions of lsof haven't been tested on them. Dave Olson supplied the IRIX 5.3 changes. Dave says IRIX 5.3 lsof doesn't work with the new XFS file system, because of kernel data structure definitions. The CFLAGS string, the clean rule, the depend rule, and the disabled sinclude make directive have traces of a dependency technique that uses the -MDupdate flag of the IRIX cc compiler. Unfortunately I have encountered two IRIX dialects -- a 4.0.5H system, and a 5.2 one -- where the use of -MDupdate hung the compiler and the OS. Therefore, I have disabled the use of -MDupdate, but have left enough traces that the brave can re-enable it. If you are brave and want to use compiler dependency generation, re-enable it by defining the CFGD string for the compiler option (e.g., CFGD=-MDupdate), and the CFGDN string for the name of the dependency file (e.g., CFGDN=-Makedepend.irix) in the Configure script or in the Makefile it constructs. Remove the leading comment character (`#') from the Makefile's sinclude directive. IRIX 5.x and 6.x below 6.2-BETA ship without some important system header files. They are found in the irix5hdr and irix6[0][1]hdr subdirectories. The last lsof revision I could test under 4.0.5H was 3.19. The last lsof revision I could test under 5.2 was 3.18. Linux ===== With the help of Tim Korb , who provided access to a Linux PC in the Purdue Computer Science Department, I first ported lsof to Linux version 1.0.9. Subsequently I adapted that port to Yggdrasil Plug-and-Play Linux, Fall '94, version 1.1.47. The revision 3.20 changes appear to be necessary for Linux 1.1.75 and above, although I have no confirmation of that. If you learn differently, please let me know. At revision 3.32 Michael Shields helped add and test automatic handling of ELF/COFF form names in /System.map, and Joseph J. Nuspl Jr. gave me access to his Linux system for testing. Michael's testing and mine on Joe's system were done against Linux version 1.2.10. Subsequently I have tested lsof through revision 3.39 under Linux 1.2.11. At revision 3.35 Marty Leisner provided code to validate the Linux /System.map or /zSystem.map file against values obtained from /proc/ksyms. Roman Gollent provided help in updating lsof 3.38 for Linux 1.3.0. However, the Linux kernel name cache support at revision 3.49 has not been tested in anything but a 1.2.13 system, so it may not compile or work at 1.3.0 and above. Keith Parks supplied changes to lsof revision 3.52 that update it to Linux versions 1.3.22 and above. Keith tested lsof 3.52 on Linux 1.3.42 and 1.3.43; lsof 3.57 on Linux 1.3.56. The 00FAQ file gives some Linux tips. NetBSD 1.0 and 1.1 ================== Greg Earle and Paul Kranenburg assisted me with NetBSD 1.0 and 1.0A. Greg provided modifications to the NetBSD code that was once in lsof, and helped test the revised code; Paul generously provided Intel and SPARC-based test systems. The NetBSD 0.9 support that was in lsof revisions 3.0 through 3.20, but tested last in 3.0, has been removed. NEXTSTEP 2.1 and 3.[0123] ========================= 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 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. Stuart Staniford-Chen reports that lsof 3 builds and works under NEXTSTEP 3.0. Andreas Stolcke reports that lsof 3.09 builds and works under NEXTSTEP 2.1, if ``-DKERNEL_FEATURES'' is added to the compiler flags in the Makefile. Allan Nathanson supplied the update in lsof 3.23 for NEXTSTEP 3.3 (m68k, i486, hppa, and SPARC architectures). See the note about AFS in the Solaris section. Novell UnixWare 1.1, 1.1.1, and 1.1.2 ===================================== Novell UnixWare is no longer supported. Remnants of the UnixWare support may be found on vic.cc.purdue.edu in the subdirectories: pub/tools/unix/lsof/OLD/binaries and pub/tools/unix/lsof/OLD/dialects OSF/1 2.0, 3.[02], and 4.0-BETA for the DEC Alpha ================================================= Lsof 3 has been tested under OSF/1 2.0, 3.0, 3.2, and 4.0-BETA for the DEC Alpha. Lsof 3 also supports the ADVFS/MSFS layered file system product. It has been tested on a 1.3a system, kindly provided by Achim Bohnet and Bernt Christandl , and 3.0 and 3.2 systems kindly provided by Ron Young , (It has not been tested under OSF/1 2.0.) 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. (The /etc/fstab caveat applies only to OSF/1 2.0.) Dave Morrison and Lawrence MacIntyre did OSF/1 V3.2 testing Angel Li provided a 4.0-BETA test system. Configuring lsof 3 for DEC OSF/1, using lsof's Configure script, requires specification of the subdirectory of /sys or /usr/sys that contains configuration header files. (The script prompts for the entry of the subdirectory name.) Usually the name is an upper case version of the first host name component -- e.g., TOMIS from tomis.bio.purdue.edu. In addition to those already mentioned, these people helped with OSF/1 porting efforts: Alex Kreis, Anthony Baxter, Jim Brown, Axel Clauberg, Claus Kalle, Dwight McKay, Jeffrey Mogul, and James Woodward. Pyramid DC/OSx ============== Pyramid DC/OSx is no longer supported. Remnants of the DC/OSx support may be found on vic.cc.purdue.edu in the subdirectories: pub/tools/unix/lsof/OLD/binaries and pub/tools/unix/lsof/OLD/dialects RISC/os 4.52 ============ The RISC/os 4.52 R2030 test system was provided by Zdenko Tomasic . SCO OpenDesktop or OpenServer 1.1, 3.0, and 5.0 =============================================== Dion Johnson , Bela Lubkin , and Nathan Peterson of SCO provided me copies of SCO OpenDesktop, version 3.0, and the SCO OpenDesktop Development System, version 3.0, and gave me 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 3.26 to it. Lsof has been tested on SCO OpenDesktop or OpenServer releases 1.1, 3.0, and 5.0. It should Configure without complaint, using the sco abbreviation, for release 2.0; and for SCO Unix release 3.2v2.0 through 3.2v5.0.0 with SCO TCP/IP and SCO NFS, but it has not been tested on them. It will Configure, but complain, for releases 3.2.0 and 3.2.1. At revision 3.52 lsof was updated to test for the presence of SCO NFS header files and deactivate its NFS support code. No such option exists for TCP/IP, however, so you must have the TCP/IP header files installed to be able to compile any lsof revision. The header file was accidentally omitted from some SCO Development System releases. The Configure script will sense its absence and substitute an equivalent from the BSD distribution. The BSD and the header file it includes are located in the dialects/sco/include subdirectory tree. Sequent DYNIX ============= Sequent DYNIX is no longer supported. Remnants of the DYNIX support may be found on vic.cc.purdue.edu in the subdirectories: pub/tools/unix/lsof/OLD/binaries and pub/tools/unix/lsof/OLD/dialects Sequent PTX 2.1.[156], 4.0.[23], and 4.1.[02] ============================================= This distribution will build an lsof that I have tested on PTX 2.1.6, 4.0.[23], and 4.1.[02] systems. Peter Jordan , Gerrit Huizenga , Kevin Smallwood , and Mike Spitzer provided access to the test systems and gave me technical advice. Kevin Smallwood tested lsof under PTX 2.1.1. Thomas A. Endo and David Putz tested under PTX 2.1.5. Joel White tested under PTX 2.1.6. Bob Foertsch tested under PTX 4. Lsof may not compile under all versions of PTX because of header file complications resulting from the absence of a particular layered product. I have accommodated only the CD-ROM and NFS layered products in the lsof sources of revision 3.28. If you have problems compiling lsof because your C compiler complains about missing header files, please email a description of your problems to me. Solaris 2.[12345] ================= SEE THE CAUTIONS SECTION OF THIS DOCUMENT. The Solaris 2.3 revision of lsof 3 will probably work under Solaris 2.[12], but hasn't been tested there. 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. Dave Curry and Steve Kirsch provided resources for the port. Casper Dik and Gerry Singleton consulted and provided valuable assistance. Casper Dik provided and tested the Solaris 2.4 changes, including changes to the Configure script that allow it to sense and adjust to the Solaris version. If you use gcc on Solaris, make sure the gcc-specific includes have been updated for 2.4. Support for Solaris 2.5 was made possible with the help of Henry Katz , Joseph Kowalski , and Mike Tracy . AFS support was added to lsof at revision 3.59 for NEXTSTEP, Solaris, and SunOS, thanks to help from many people: * Curt Freeland and Terry McCoy provided a Solaris 2.5 test system. * Chaskiel Moses Grundman provided NEXTSTEP and SunOS test systems and valuable AFS consulting. * Heidi Hornstein provided a Solaris 2.4 test system; her colleague, Sushila R. Subramanian helped me understand AFS. * Michael L. Lewis made the initial request; his colleague, Phillip Moore , helped me find AFS test systems. AFS was tested at lsof revision 3.59 under NEXTSTEP 3.2, Solaris 2.[45], and SunOS 4.1.4. SunOS 4.1.[1234] ================ SEE THE CAUTIONS SECTION OF THIS DOCUMENT. The distribution will build a usable lsof for SunOS 4.1.3. It also will build distributions that usually work under SunOS 4.1.1 and 4.1.2. (Steinar Haug reports that it works for SunOS 4.1.4, too.) To use lsof with SunOS versions below 4.1.3, configure for sunos413 or sunos413cc. To use lsof with SunOS 4.1.4, Configure for sunos413 (or sunos413cc). You have two compiler choices -- gcc or cc. Select the abbreviation that fits your system, sunos413 for gcc, or suns413cc for Sun cc. This hack is required because the Sun cc doesn't grok the const keyword. It is also important to understand that a SunOS 4.1.x executable may only work for the architecture on which it is compiled. For example, compiling lsof on a S690MP server produces a lsof that will only run on the server; that lsof won't run on the server's IPC clients. To obtain a lsof that will run on the IPC clients, one must compile lsof on an IPC. This awkward condition is a result of differences in the user structure (in ) between Sun architectures. Some standard Sun executables -- e.g., /bin/ps -- have the same problem. Sun has "solved" the problem by symbolically linking them to architecture-specific executables in /usr/kvm. Thus, /bin/ps becomes a symbolic link to /usr/kvm/ps. Following this pattern, lsof is usually installed in /usr/kvm under SunOS. Sometimes people will make a symbolic link from a more common place, e.g., /usr/local/etc/lsof to /usr/kvm/lsof, to make it easier to find lsof. You may not want to install lsof in /usr/kvm with a symbolic link from somewhere else. In that case you might want to try a strategy suggested by Steinar Haug. First, install the architecture-specific revisions of lsof in the place of your choice, each with a suffix matching the architecture value produced by the -m option of the uname command -- e.g., lsof.sun4, lsof.sun4c, lsof.sun4m. Then, install the following shell script as lsof. #! /bin/sh prog=$0.`uname -m` exec $prog ${1+"$@"} AFS support was added for SunOS to lsof 3.59, thanks to help from Chaskiel Moses Grundman . Chaskiel provided a test system and valuable AFS consulting. Only SunOS 4.1.4 AFS was tested at lsof 3.59. See the note about AFS in the Solaris section. SunOS 4.1.x gcc Warning ======================= There is a subtle gcc installation problem that may prevent you from building a working lsof on your SunOS 4.1.x system. (It will prevent you from building a working ps, too, if you have sources.) The problem deals with the header files that gcc "fixes" so they will be ANSI compliant. There's a script in the gcc installation process, called fixincludes, that makes selected header files ANSI compliant by copying them from their Sun locations to a gcc library location. Some structures in these header files change length, depending on the Sun architecture. That length change affects the position of important elements from the user structure -- command name among them -- that lsof uses. If header files are fixed on one architecture and copied to another -- e.g., fixed on a sun4m and copied to a sun4c -- the destination architecture will have a gcc that works for many programs, but may fail for programs that reference the user structure. The common manifestation of incorrect gcc header files is that lsof compiles properly, but doesn't report anything when it is run, no matter what option is used. If this happens to you, examine the ancestry of your gcc compiler carefully. Check the 00FAQ file for some suggested work-arounds. Ultrix 2.2, 4.2, 4.3, 4.4, and 4.5 ================================== Terry Friedrichsen , Dwight McKay , and Jeffrey Mogul helped me with this port. The system to which the 2.2 port was directed has been extensively updated with 4.3BSD{Tahoe,Reno} network features, so it may not match a standard 2.2 system, if there is any such system still in use. A separate Configure abbreviation, ultrix22, is necessary for it. All other Ultrix versions may be configured with the ultrix abbreviation. DECnet support was added to lsof at revision 3.05. John Beacom kindly provided the 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. Chris Timmons reports that lsof 3.12 compiles and works under Ultrix 4.4. Gregory Neil Shapiro reports that lsof 3.58 compiles and works under Ultrix 4.5. =============== 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 actions 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. If lsof needs to read /proc file system entries, then it must be installed with modes that make its effective user identifier root when it runs -- i.e., it must be setuid-root. If you have to install lsof setuid-root, then access to memory devices follows. 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 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. See the discussion of the SunOS 4.1.x /usr/kvm strategy for another perspective on the siting of the lsof executable. 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 usually 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. ==================================== Porting lsof 3 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, vic.cc.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. Vic Abell Purdue University Computing Center (PUCC) March 8, 1996