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