summaryrefslogtreecommitdiff
path: root/00TEST
diff options
context:
space:
mode:
authorPatrick McCarty <patrick.mccarty@linux.intel.com>2013-02-08 13:26:27 -0800
committerPatrick McCarty <patrick.mccarty@linux.intel.com>2013-02-08 13:26:27 -0800
commit9bb81f8a90ecc8b70c955bff72ec59dd3d9e5ae7 (patch)
tree881eebfa461e4f8aa6b6f44b96ac0decd3bc887a /00TEST
downloadlsof-9bb81f8a90ecc8b70c955bff72ec59dd3d9e5ae7.tar.gz
lsof-9bb81f8a90ecc8b70c955bff72ec59dd3d9e5ae7.tar.bz2
lsof-9bb81f8a90ecc8b70c955bff72ec59dd3d9e5ae7.zip
Imported Upstream version 4.87upstream/4.87
Diffstat (limited to '00TEST')
-rw-r--r--00TEST1026
1 files changed, 1026 insertions, 0 deletions
diff --git a/00TEST b/00TEST
new file mode 100644
index 0000000..624d0a4
--- /dev/null
+++ b/00TEST
@@ -0,0 +1,1026 @@
+
+ The Lsof Test Suite
+
+ Contents
+
+ A. Introduction
+ 1. Test Suite Goals
+ 2. Not a FAQ
+ 3. Where have the tests been tested?
+ B. Test Methodology
+ 1. Test Limitations
+ 2. Test Data Base and Scripts
+ 3. The Makefile
+ 3.1 The CkTestDB Script
+ 4. The Lsof Executable and LT_LSOF_PATH
+ 5. Automated Testing
+ C. Configure Script Participation
+ 1. config.cc
+ 2. config.cflags
+ 2.1 config.cflags Contents
+ 3. config.ldflags
+ 4. config.xobj
+ D. Cleaning -- Quick or Spotless
+ E. Test Libraries
+ 1. LTlib.c
+ F. The Individual Tests
+ 1. LTbasic, a Basic Lsof Test
+ 2. LTbigf, Test Sizes and Offsets for Large
+ (> 32 bit) Files
+ 3. LTdnlc, Test the Kernel's Dynamic Name Lookup
+ Cache
+ 4. LTlock, Lock Tests
+ 5. LTnfs, NFS Test
+ 6. LTnlink, Link Count Test
+ 7. LTsock, Test IPv4 Sockets
+ 8. LTszoff, Test Sizes and Offsets for Small
+ (< 32 bit) Files
+ 9. LTunix, Test UNIX Domain Sockets
+ Appendix A, Test Files
+ Appendix B, Test Validations
+ Appendix C, Test Failures
+
+
+A. Introduction
+===============
+
+Lsof has an automated test suite whose components are located in
+the tests/ sub-directory of the lsof top-level directory. Configuring,
+building and testing lsof can be done with these shell commands:
+
+ $ Configure -n <dialect-abbreviation>
+ $ make
+ $ cd tests
+ $ make
+
+That's all there is to it!
+
+But read on for more dirty details.
+
+A.1. Test Suite Goals
+=====================
+
+The lsof test suite attempts to test basic lsof features. It does
+not promise to test every lsof feature for every supported dialect.
+(That's a nearly impossible goal.)
+
+As a result, the test suite cannot promise that every lsof feature
+works as documented. At best the test suite gives some assurance
+that basic, standard and some optional lsof features work.
+
+A.2. Not a FAQ
+==============
+
+One caution: this is not a frequently asked questions (FAQ) file
+for the lsof test suite. FAQs on the lsof test suite will be found
+in the one and only lsof FAQ in file 00FAQ of the lsof distribution,
+or on-line at:
+
+ ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/FAQ
+
+A.3. Where have the tests been tested?
+======================================
+
+OK, I just said this isn't an FAQ and here comes a question and
+answer that looks like an FAQ. Consider it a very frequently asked
+question and indulge me -- let me answer it here.
+
+The lsof test suite hasn't been tested everywhere it might be
+possible to build lsof successfully. That "everywhere" includes
+dialect versions -- e.g., Solaris < 2.6 -- to which I no longer
+have access. On some dialect versions to which I have access, some
+tests won't run because the test system lacks support.
+
+In "Appendix B, Test Validations" I've tried to list where I compiled
+and tested the test suite and information on any tests I was unable
+to run. In "Appendix C, Test Failures" I list where the test suite
+fails and why it failed.
+
+A.4 Where are the tests?
+========================
+
+This is another FAQ whose answer is that the tests are in the tests/
+sub-directory of the main lsof source directory.
+
+
+B. Test Methodology
+===================
+
+The test suite is made up of individual C programs. Test setup is
+performed by the lsof Configure script itself, which writes a set
+of dialect configuration files in the tests/ subdirectory. (See
+"C. Configure Script Participation.")
+
+Each program or script performs a specialized tests. Those tests
+are described below in "F. The Individual Tests".
+
+Each test measures lsof functionality by putting a specific lsof
+command execution at the end of an in-bound (to the test) pipe.
+The caller asks lsof to write its results to the pipe in field
+output form. (See the -F option in the lsof man page.)
+
+Using an in-bound lsof pipe allows the tests to measure a great
+deal of lsof functionality, including as an interesting side effect,
+the performance of field output. Consequently, there's no special
+field output test.
+
+B.1. Test Limitations
+=====================
+
+One limitation of the tests is that they don't measure lsof formatted
+output -- i.e., the output normally see when lsof is run. There
+are just too many variants of lsof output produced across the range
+of dialects where lsof runs, so field output is a more consistent
+way to process lsof output.
+
+But using field output does mean that the test suite doesn't check
+for lsof formatting problems, except in the field output itself.
+
+B.2. Test Data Base and Scripts
+===============================
+
+The TestDB file contains a simple data base that describes where
+the tests have been validated. Entries are formed from a combination
+of the lines in the config.cflags file produced by the lsof Configure
+script. The entries can be considered "lsof dialect footprints,"
+hereafter simply called "dialect footprints" or just "footprints."
+
+Two shell scripts support TestDB. The first, Add2TestDB, will add
+a footprint to TestDB. I don't recommend you use this script.
+Mostly it's for my use when I find that the test suite has been
+validated on a new dialect.
+
+It's also possible to add a footprint to TestDB by simply editing
+TestDB and pasting into it a copy of the footprint reported by a
+failed Makefile rule. I don't generally recommend this be done,
+either.
+
+There are Makefile rules that use (and avoid) the CkTestDB script.
+(See "B.3 The Makefile".)
+
+The default (i.e., "all") Makefile rule uses the CkTestDB script
+to look for the footprint in TestDB. If no footprint is found, the
+script issues a warning, displays the unfound footprint, and asks
+if running the test suite should continue.
+
+The "auto" Makefile rule also uses CkTestDB, but with a special
+call that causes CkTestDB to look in TestDB for the footprint,
+report it when it can't be found, and then fail. That CkTestDB
+failure causes the "auto" rule to fail, too.
+
+The "silent" Makefile rule doesn't use CkTestDB to look in TestDB
+for the footprint. It runs the standard and basic tests as silently
+as possible, then returns a failure or success exit code that
+signals the result of the running of the tests. (Use the "silent"
+rule carefully, because it will skip proving the tests have previously
+run on the dialect.)
+
+B.3. The Makefile
+=======================
+
+The Makefile runs the tests in the test suite. It has these rules.
+
+ all runs the basic test and the standard tests,
+ interacting with the caller should the footprint
+ not be found in TestDB.
+
+ (This is the default rule.)
+
+ auto runs the basic test and the standard tests on a
+ previously validated system as silently as possible.
+
+ The footprint must be found in TestDB for this rule
+ to succeed. (See the "silent" rule for one that
+ avoids checking TestDB.)
+
+ This rule is designed for lsof build scripts that
+ want a quick noiseless test to make sure what they
+ built works as it previously did.
+
+ This rule calls CkTestDB in a way that inhibits
+ its normal go-ahead request. (See "B.2.1 The CkTestDB
+ Script".) If CkTestDB finds the footprint and all
+ tests succeed, this rule returns a zero exit code
+ (success). If the footprint isn't found or if any
+ test fails, a non-zero exit code (failure) is
+ returned.
+
+ ckDB calls the CkTestDB script to look for a footprint.
+ If none is found, the way CkTestDB was called (See
+ "B.3.1 The CkTestDB Script".) causes it to return
+ a non-zero exit code (failure) to this rule, and
+ the rule then returns a non-zero exit code (failure)
+ itself.
+
+ This rule is used by the "auto" rule. If this rule
+ succeeds (zero exit code), the "auto" rule then
+ uses the "silent" rule.
+
+ clean removes test and compiler output. (See the "D.
+ Cleaning -- Quick or Spotless" section.)
+
+ opt runs the optional tests.
+ optional
+
+ silent runs the lsof basic and standard tests as silently
+ as possible (as the "auto" rule does), but without
+ using CkTestDB to look for a footprint. If all
+ tests succeed, the rule returns a zero exit code
+ (success). If any test fails, the rule returns a
+ non-zero exit code (failure).
+
+ Use the "silent" rule carefully, because it will
+ skip proving the tests have previously run on the
+ dialect.
+
+ spotless does what the clean rule does and also removes the
+ config.* files created by ../Configure. (See the
+ "D. Cleaning -- Quick or Spotless" section.)
+
+ std runs the basic test and the standard tests.
+ standard
+
+The Makefile cleaning rules are further described in "D. Cleaning
+-- Quick or Spotless."
+
+B.3.1 The CkTestDB Script
+=========================
+
+Some Makefile rules (e.g., "all" and "auto") use the CkTestDB script
+to make sure the tests have been run previously on the dialect.
+CkTestDB does that by looking for the dialect's footprint in TestDB.
+
+If no footprint is found, and if standard input is a TTY, CkTestDB
+asks for a go-ahead signal. If standard input isn't a TTY, CkTestDB
+aborts the test run. (See "B.2. Test Data Base and Scripts".)
+
+The Makefile "silent" rule does not call CkTestDB. use the "silent"
+rule carefully, because it will skip proving the tests have previously
+run on the dialect.
+
+B.4. The Lsof Executable and LT_LSOF_PATH
+=========================================
+
+Normally the programs in the test suite use the lsof executable in
+their parent directory, ../lsof. Usually that lsof has just been
+built and testing it is the next logical step.
+
+Be careful that ../lsof has sufficient permission to access the
+necessary kernel resources -- e.g., /dev/kmem, /dev/mem, /proc,
+etc. If it doesn't the tests will fail. (The tests do check to
+see if they can open /dev/mem and /dev/kmem for read access if
+LT_KMEM is defined in config.cflags and if the path to the lsof
+executable is ../lsof.)
+
+Here are two possible ways you can make sure the lsof being tested
+has sufficient permission: 1) use chmod and chgrp to enable its
+running and put its path in LT_LSOF_PATH, thus disabling the check
+in the tests for kernel memory access; or 2) run the tests (and
+hence the lsof being tested) under a login that has sufficient
+permission -- e.g., is in a group that can read /dev/kmem.
+
+You can direct the tests to use a different lsof executable by
+specifying its path in the LT_LSOF_PATH environment variable. To
+test an lsof executable already installed in /usr/local/etc --
+provided that lsof is at revision 4.63 or higher -- do this:
+
+ $ LT_LSOF_PATH=/usr/local/etc/lsof
+ $ export LT_LSOF_PATH
+ $ cd .../lsof_<version>/tests
+ $ make
+
+When you specify an alternate executable path via LT_LSOF_PATH,
+that also prevents the tests from checking to see if they have
+kernel memory access.
+
+B.5 Automated Testing
+=====================
+
+Normally the lsof test suite is wordy and may require interaction.
+When you want to avoid those interferences, use the Makefile "auto"
+or "silent" rules. (See the description of the "auto" and "silent"
+rules in "B.3 The Makefile".)
+
+The footprint must be present in TestDB in order to use the "auto"
+rule. If it is not, the "auto" rule will fail and report the
+missing footprint. Footprints in TestDB proclaim that the tests
+have previously succeeded on the dialect.
+
+The footprint need not be present in TestDB in order to use the
+"silent" rule. Use the "silent" rule carefully, because it will
+skip proving the tests have previously run on the dialect.
+
+
+C. Configure Script Participation
+=================================
+
+An important step in setting up the test suite is performed by the
+Configure script in the lsof home directory (the parent to tests/.)
+
+Configure writes four files in tests/ that describe how the tests
+are to be compiled, configured and loaded. The files also describe
+options that Configure selected that are important to the test
+suite.
+
+C.1. config.cc
+==============
+
+This file, config.cc, contains the name of or the path to the C
+compiler used to compile lsof. The Makefile uses this file in
+place of the standard make(1) CC string with a shell in-place
+execution statement -- i.e., `cat config.cc`.
+
+If the LSOF_CC environment variable is supplied to the lsof Configure
+script, its value will appear in the config.cc file.
+
+C.2. config.cflags
+==================
+
+This file, config.cflags, contains C compiler flags that Makefile
+uses to compile the C programs in the test suite. As with the
+compiler file, config.cc, the make rules incorporate the contents
+of this file into C compiler options with `cat config.cflags`.
+
+This file is also used by the Add2TestDB and CkTestDB shell scripts
+to build and match footprints. (See "B.2. Test Data Base and
+Scripts.")
+
+C.2.1 config.cflags Contents
+============================
+
+The config.cflags file may contain the following C compiler flags.
+
+
+ -DLT_AIXA is present if lsof was built for AIX.
+ It contains the AIX architecture flag.
+ (See the lsof Configure script or
+ dialects/aix/dlsof.h for more information
+ on the AIX architecture flag.)
+
+ -DLT_BIGF is present if lsof was built for a dialect
+ that has large file (sizes and offsets >
+ 32 bits).
+
+ -DLT_CC is present if the lsof compiler is cc.
+
+ -DLT_DIAL_<abbr> always ends in (the <abbr> part) the
+ "canonical" -- i.e., usually the most
+ common abbreviation by which the dialect
+ is known.
+
+ Example: -DLT_DIAL_solaris
+
+ -DLT_GCC is present if the lsof compiler is gcc.
+
+ -DLT_K64 is present if lsof has been built for a
+ 64 bit kernel
+
+ -DLT_KMEM is present if lsof has been built to
+ use /dev/kmem to obtain kernel values.
+
+ -DLT_VERS=<vn> contains the version number for the
+ dialect, as used in lsof pre-processor
+ tests.
+
+ Example for Solaris 10: -DLT_VERS=100000
+
+ -DLT_VPATH is present if the dialect has the v_path
+ member in the vnode structure (e.g., some
+ versions of Solaris 10).
+
+The config.cflags file may also contain dialect-specific compiler
+flags needed to activate a specific feature on the dialect. For
+example, for HP-UX config.cflags might contain:
+
+ -D_LARGEFILE64_SOURCE This compiler flag enables the use of
+ large-file system library functions
+ --e.g., open64().
+
+ The lsof Configure script stanzas for
+ the dialects select these options.
+
+
+C.3. config.ldflags
+===================
+
+This file, config.ldflags, contains the dialect loader flags --
+i.e., the equivalent to make(1) LFLAGS -- for loading the test
+programs.
+
+Example for Solaris: -lsocket this adds the socket library
+ to the loading of the lsof
+ test programs.
+
+Example for UnixWare: -lsocket -lnsl this adds the socket and
+ name server libraries to
+ the loading of the lsof
+ test programs.
+
+
+C.4. config.xobj
+================
+
+This file, config.xobj, contains the paths to any extra object
+files (.o's) that must be loaded when the test suite C programs
+are loaded. Like config.cc and config.cflags, it's incorporated
+into the loader statements of the Makefile's rules with `cat
+config.xobj`.
+
+Examples for DEC OSF/1 and NEXTSTEP:
+
+ ../lib/snpf.o this loads the private lsof object file
+ that contains an snprintf() function. (The
+ DEC OSF/1 4.0 and NEXTSTEP 3.1 C libraries
+ don't have snprintf().)
+
+
+D. Cleaning -- Quick or Spotless
+================================
+
+There are two Makefile rules that clean the tests/ subdirectory --
+"clean" and "spotless". They cause different degrees of cleaning.
+
+ clean a "quick" clean that removes compiled object files,
+ executables and test files. It does NOT remove
+ the configuration files that ../Configure and the
+ config.perl rule wrote.
+
+ spotless cleans out everything clean does -- plus the
+ configuration files that ../Configure and the
+ config.perl rule wrote.
+
+ This is the rule used when `./Configure -clean` is
+ specified. If this rule is used, `../Configure -n
+ <abbr>` and `../make`) must be run again before
+ the test suite can be used.
+
+
+E. Test Library
+===============
+
+The lsof test suite provides a C library.
+
+E.1. LTlib.c
+============
+
+This is a C library of common functions used by tests. Configured
+at compile time by the contents of config.cflags, it uses the single
+header file LsofTest.h. LsofTest.h tailors its definitions to the
+dialect at compile time, using the LT_DIAL_* definitions in
+config.cflags.
+
+Two particularly useful functions in the library are: ExecLsof(),
+which will execute an lsof child process; and RdFromLsof(), which
+will read from the in-bound lsof pipe, and decode the fields into
+structures that are easy for C programs to process.
+
+This library is a good model for processing field output in a C
+program from an in-bound lsof pipe.
+
+The source for the library, LTlib.c, contains more documentation.
+
+
+F. The Individual Tests
+=======================
+
+The individual tests are listed in this section. The listings
+explain what the tests do, a few errors they might report, and how
+to use options and environment variables to customize the tests.
+
+The test descriptions are listed in this section in alphabetical
+order, not in the order they are run by Makefile.
+
+The Makefile runs the tests in three groups, basic tests, standard
+tests, and optional tests. The default make "all" rule runs the
+basic and standard tests. (The "standard", "std", and "test"
+Makefile rules are synonyms to "all".) If the standard tests succeed,
+Makefile suggests running the optional tests with the "opt" (or
+"optional") rule.
+
+The Makefile "auto" and "silent" rules run only the basic and
+standard tests. They do not run or suggest you run the optional
+tests.
+
+ The basic test:
+ LTbasic
+
+ Standard tests:
+ LTnlink
+ LTsock
+ LTszoff
+ LTunix
+
+ Optional tests:
+ LTbigf
+ LTdnlc
+ LTlock
+ LTnfs
+
+The basic and standard tests should all succeed on all dialects,
+although LTnlink may warn that it can't perform its unlink test on
+an NFS file system.
+
+The optional tests may run, they may be disabled for specific
+dialects, or they may fail because of special resource needs --
+e.g., LTbigf will run only on UNIX dialects where it knows how to
+handle files whose lengths exceed 32 bits, and LTnfs needs access
+to an NFS file system mounted from a remote NFS server.
+
+Tests that need special resources usually provide a hint about the
+resources when they fail. Information about special resource needs
+may also be found in the following sections about the individual
+tests.
+
+G.1. LTbasic, a Basic Lsof Test
+===============================
+
+This is the basic lsof test. If it doesn't run, it's not likely
+any other tests will run, either. Hence, if it fails, no Makefile
+rule runs any other tests.
+
+This test uses lsof to locate files in the lsof process, including
+current working directory, the lsof executable, and the /dev/kmem
+open file.
+
+Finding the lsof executable may not be possible on AIX if lsof was
+compiled without support for its -X option.
+
+Finding /dev/kmem use by lsof is only possible on dialects where
+lsof uses /dev/kmem. The -DLT_KMEM define indicates that.
+
+Run this test:
+
+ $ ./LTbasic
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.2. LTbigf, Test Sizes and Offsets for Large (> 32 bit) Files
+==============================================================
+
+This is a test in the optional test group.
+
+This test is effective only when ../Configure has put -DLT_BIGF in
+config.cflags. Without that definition this test simply reports
+that the dialect doesn't support large files. That report is
+accompanied by a successful test exit code, so that the runner of
+the test (e.g., the Makefile) won't believe the test failed.
+
+When a dialect does support large files, the test attempts to create
+a file that looks very large -- e.g., has a length as reported by
+ls(1) of 0x140000000 bytes. However, the file really has only a
+small amount of data in it, the rest of the file consists of a
+large standard UNIX file system "hole."
+
+By default the test file is named config.LTbigf<PID>, where PID is
+the Process ID of the LTbigf process.
+
+When that file is not on a file system enabled for large files, or
+when the process that runs LTbigf can't create a big file, LTbigf
+will report an error. The error will be accompanied by hints that
+the -p option may need to be used to define a path where the test
+can write a large file, or the process ulimit file block size may
+need to be raised -- e.g., to "unlimited."
+
+LTbigf can't test file offset reporting on Linux kernels below
+2.6.22, because the /proc file systems of those kernels don't make
+file offsets available to lsof.
+
+Run this test:
+
+ $ ./LTbigf [-p <path>]
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.3. LTdnlc, Test the Kernel's Dynamic Name Lookup Cache
+========================================================
+
+This is a test in the optional test group.
+
+This test asks lsof to locate the current working directory of its
+own process and report the path it has assembled from the components
+it found in the kernel's Dynamic Name Lookup Cache (DNLC) or via
+other dialect-specific methods. (E.g., Linux, HP-UX 11.11, and
+some Tru64 UNIX versions have private name lookup methods.)
+
+The test checks what lsof reports as the current working directory
+path for any missing components and counts the number of full paths
+returned. (Symbolic link complications prevent testing for exact
+path matches.) The test is repeated. If full paths are returned
+at least half the time, the test considers itself successful.
+
+This test can't be run on AIX, because lsof can't access the DNLC
+there. It can't be run on Apple Darwin versions below 8.0, either,
+because insufficiently reliable DNLC information is available there.
+This test may fail on other dialects when the file system -- e.g., NFS.
+/tmp, loopback -- doesn't fully participate in the dialect's DNLC.
+
+Run this test:
+
+ $ ./LTdnlc
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.4. LTlock, Lock Tests
+=======================
+
+This is a test in the optional test group.
+
+This test uses flock() and fcntl() to set and clear file locks,
+and measures lsof's ability to report them. The choice of system
+lock call is based on the dialect. (There are LT_DIAL_* pre-processor
+tests in LTlock.c.)
+
+This test can't be run on an NFS client file system, because NFS
+lock information is kept on the server. Lsof on the client can't
+see that server kernel data.
+
+By default the test attempts to create a file named config.LTlock<PID>,
+where PID is the Process ID of the locking test process. It uses
+lsof to determine if the file is on a client NFS file system. If
+it is, the test aborts, hinting that the -p option can be used to
+specify a non-client-NFS test file path.
+
+This test can't be run on Darwin, because insufficient file system
+lock information is available to lsof there.
+
+Run this test:
+
+ $ ./LTlock [-p <path>]
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.6. LTnfs, NFS Test
+====================
+
+This is a test in the optional test group.
+
+This test verifies that lsof can locate files mounted on a client
+NFS system from an NFS server.
+
+By default it creates a test file, config.LTnfs<PID>, where PID is
+the Process ID of the test process. The test then uses lsof to
+find the file on an NFS file system.
+
+If lsof can't find the file the test warns that the test file might
+not be on an NFS file system and hints that the -p option may be
+used to specify the path of an NFS file, provided the test can have
+read access to it there. The test warning also states that the
+file at the path specified with -p must be a regular file, not a
+directory.
+
+This test can't be run on Darwin versions below 8.0, because
+insufficient NFS file information is available to lsof there.
+
+Run this test:
+
+ $ ./LTnfs [-p <path>]
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.7. LTnlink, Link Count Test
+=============================
+
+This is a test in the standard test group.
+
+The test checks lsof's reporting of link count (nlink in UNIX
+argot.)
+
+It creates a test file in the current working directory named
+config.LTnlink<PID>, where PID is the Process ID of the test
+process. It then uses stat(2) and lsof to measure the link count
+of the file.
+
+If LTnlink creates the test file in the current working directory
+and it is on an NFS file system, LTnlink won't be able to perform
+one section of its test. In that section the test file is unlinked
+so its link count will be zero and lsof is asked to find it among
+the set of files whose link counts are zero.
+
+When an NFS file is unlinked its link count isn't reduced until
+the last open instance is closed on either the NFS clients or the
+NFS. That's a consequence of NFS statelessness and leads to the
+occasional presence of files with names of the form .nfsxxxx.
+
+Should LTnlink find its test file on an NFS file system, it disables
+the unlink section of its tests and issues a warning. It also
+issues a hint that the test file path can be named via the -p option
+to give a test file location that isn't on an NFS file system.
+
+This test can't be run on Darwin, because insufficient file system link
+count information is available to lsof there.
+
+Because some UNIX dialects delay the reporting of a link count
+update after a file has been unlinked, LTnlink may not get its
+expected response from lsof for a while after the test file has
+been unlinked. In that cause LTnlink may delay for up to a minute,
+calling lsof once every two seconds and displaying a "waiting for
+link count update: ..." message.
+
+Some file systems -- e.g., ZFS on Solaris 11 -- don't allow LTnlink to
+unlink its test file, because LTnlink has the file open. LTnlink
+explains that failure and suggests that it be run with path of the "-p
+path" option set to a file on /tmp. See 00FAQ for more information.
+
+Run this test:
+
+ $ ./LTnlink [-p <path>]
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.7. LTsock, Test IPv4 Sockets
+==============================
+
+This is a test in the standard test group.
+
+This test uses lsof to locate open IPv4 socket files that the test
+has created itself. The test opens a server socket, then forks a
+child process to connect to that socket. After both are running,
+the test uses lsof to find the open socket files at their known
+host and port addresses.
+
+Run this test:
+
+ $ ./LTsock
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.8. LTszoff, Test Sizes and Offsets for Small (< 32 bit) Files
+===============================================================
+
+This is a test in the standard test group.
+
+This test checks lsof's reporting of file size and offset for small
+(< 32 bits) files.
+
+It creates a test file in the current working directory named
+config.LTszoff<PID>. PID is the Process ID of the test process.
+
+LTszoff can't test file offset reporting on Linux kernels below
+2.6.22, because the /proc file systems of those kernels don't make
+file offsets available to lsof.
+
+Run this test:
+
+ $ ./LTszoff [-p <path>]
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+G.9. LTunix, Test UNIX Domain Sockets
+======================================
+
+This is a test in the standard test group.
+
+This test checks lsof's reporting of UNIX domain sockets.
+
+The test creates a pair of UNIX domain sockets and uses bind(2) to
+associate the file system names config.LT0U<PID> (client) and
+config.LT1U<PID> (server) with them. (PID is the test process ID.)
+The test then uses lsof to find the two open UNIX domain socket
+files.
+
+Run this test:
+
+ $ ./LTunix
+
+Environment variables: LT_LSOF_PATH defines the path to the lsof
+ executable. (The default is ../lsof.)
+
+
+Appendix A, Test Files
+======================
+
+These files may be created by suite tests.
+
+ Created
+ ./tests Name by Test Use
+ ============ ======= ===
+
+ config.LTbifg** LTbigf to test lsof's large file size
+ and offset reporting
+
+ config.LTlock* LTlock for locking tests
+
+ config.LTnfs* LTnfs for NFS tests
+
+ config.LTnlink* LTnlink for link count tests
+
+ config.LTszoff* LTszoff for small file size and and
+ offset reporting
+
+ config.LT[01]U* LTunix two UNIX domain sockets, used
+ to determine if lsof can report
+ their open instances properly
+
+
+Appendix B, Test Validations
+============================
+
+This appendix lists the UNIX dialects and their versions where I
+have validated the test suite. The list indicates the particular
+tests I was unable to run, mostly LTnfs because the test systems
+I used had no NFS file systems mounted.
+
+The information in the following table is encoded in a test data
+base file, TestDB, as footprints, using the tests compiler options
+written to config.cflags by the lsof Configure script. See "B.2.
+Test Data Base and Scripts" for more information on the test data
+base, footprints, and the scripts that support them.
+
+ UNIX
+ Dialect Dialect Description Untested Tests
+ ======= =================== ==============
+ AIX 4.3.3, Power, cc
+ 5.1, Power-32, cc
+ 5.1, Power-32, gcc
+ 5.1, Power-64, cc
+ 5.2, Power-32, cc
+ 5.2, Power-32, gcc
+ 5.2, Power-64, cc
+ 5.2, Power-64, gcc
+ 5.3, Power-64, cc
+ Darwin 1.4, 5.5, 6.x, 7.x gcc Darwin lsof doesn't
+ have adequate support
+ to allow the LTbigf,
+ Ltdnlc, LTlock, LTnfs,
+ and LTnlink tests to
+ run.
+ 8.0, gcc Darwin lsof doesn't
+ have adequate support
+ to allow the LTbigf,
+ LTlock and LTnlink
+ tests to run.
+ 9.0, gcc Darwin lsof doesn't
+ have adequate support
+ to allow the LTlock
+ test to run.
+ 10.0, gcc Darwin lsof doesn't
+ have adequate support
+ to allow the LTlock test
+ to run.
+ 11.0, gcc Darwin lsof doesn't
+ have adequate support
+ to allow the LTlock test
+ to run.
+ FreeBSD 4.5, i386, gcc
+ 4.6, i386, gcc
+ 4.7, i386, gcc
+ 4.8, i386, gcc
+ 4.9, i386, gcc
+ 4.10, i386 gcc
+ 5.0, Alpha, gcc
+ 5.0, Sparc, gcc
+ 5.0, i386, gcc
+ 5.1, Alpha, gcc
+ 5.1, Amd64, gcc
+ 5.1, Sparc, gcc
+ 5.1, i386, gcc
+ 5.2, i386, gcc
+ 5.2, Alpha, gcc
+ 5.2, Amd64, gcc
+ 5.2, Sparc, gcc
+ 5.3, Alpha, gcc
+ 5.4, Alpha, gcc
+ 5.5, Alpha, gcc
+ 6.0, Alpha, gcc
+ 6.0, Amd64, gcc
+ 6.0, Sparc, gcc
+ 6.1, i386, gcc
+ 6.4, i386, gcc
+ 7.0 Alpha, gcc
+ 7.0 Amd64, gcc
+ 7.1 Amd64, gcc
+ 7.2 Amd64, gcc
+ 7.3 Amd64, gcc
+ 7.4 Amd64, gcc
+ 8.0 Amd64, gcc
+ 8.2 Amd64, gcc
+ 8.3 Amd64, gcc
+ 9.0 Amd64, gcc
+ 10.0 Amd64, gcc
+ DEC OSF/1 4.0, cc
+ HP-UX 10.20, cc LTbigf
+ 10.20, gcc (1) LTbigf
+ 11.00-32, ANSI-C LTbigf, LTnfs
+ 11.00-64, ANSI-C
+ 11.11, ANSI-C
+ 11.23, ANSI-C
+ Linux 2.4.12-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.18-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.21-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.23-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.24-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.25-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.26-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.27-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.28-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.29-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.4.30-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.6.1-rc2 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.6.18-686 LTbigf, no offset tests
+ LTszoff, no offset tests
+ 2.6.22-686 (Note: this Linux kernel
+ supplies file offsets to
+ lsof.)
+ 2.6.32-686 (Note: this Linux kernel
+ supplies file offsets to
+ lsof.)
+ 2.6.38-686
+ NEXTSTEP 3.1, gcc LTnfs
+ NetBSD 1.4.1, Alpha, gcc LTnfs
+ 1.5x, x86, gcc LTnfs
+ 1.6x, Alpha, gcc LTnfs
+ 1.6x, x86, gcc LTnfs
+ 2.0x, alpha, gcc LTnfs
+ 2.0x, sparc64, gcc LTnfs
+ 2.0x, x86, gcc LTnfs
+ 2.99.9, x86, gcc LTnfs
+ 2.99.10, x86, gcc LTnfs
+ 2.99.11, x86, gcc LTnfs
+ 2.99.12, x86, gcc LTnfs
+ 3.99., x86, gcc LTnfs
+ OpenBSD 3.0, gcc
+ 3.1, gcc
+ 3.2, gcc
+ 3.3, gcc
+ 3.4, gcc
+ 3.5, gcc
+ 3.6, gcc
+ 3.7, gcc
+ 3.9, gcc
+ OPENSTEP 4.2, gcc LTnfs
+ OSR 5.04, cc LTnfs
+ 5.06, cc LTnfs
+ Solaris 2.6, cc LTnfs
+ 2.6, gcc LTnfs
+ 7-32, cc
+ 7-32, gcc LTnfs
+ 8-32, cc
+ 8-32, gcc
+ 8-64, cc
+ 8-64, gcc
+ 9-64, Beta-Refresh, cc
+ 9-64, Beta-Refresh, gcc
+ 9-64, FCS, cc
+ 9-64, FCS, gcc
+ 10-32, i86pc, gcc
+ 10-32, i86pc, cc
+ 10-64, Sparc, cc
+ 10-64, Sparc, gcc
+ 11-64, Amd64, cc
+ Tru64 UNIX 5.0, cc
+ Tru64 UNIX 5.0, cc
+ 5.1, cc
+ UnixWare 7.1.1, NSC, cc LTnfs
+ 7.1.3, cc
+ 7.1.4, cc
+
+If you are able to run the test suite on dialect versions other
+than the ones listed above, please send e-mail to <abe@purdue.edu>,
+indicating the dialect version where you were able to run the test
+suite. Please send me the footprint formed by CkTestDB, or run
+the Add2TestDB script and send me the footprint it reports.
+
+If you encounter problems compiling the tests or running them on
+a dialect version listed above, please send e-mail to <abe@purdue.edu>,
+naming the dialect version and providing the output from the lsof
+Configure script and make operation.
+
+1) John Dzubera did the HP-UX 10.20 gcc testing and provided its
+ footprint.
+
+
+Appendix C, Test Failures
+=========================
+
+I was unable to make the test suite run on the following dialects.
+
+ UNIX Dialect
+ and Description Failure
+ =============== =======
+ HP-UX 11-64, gcc 64 bit gcc 3.0 didn't compile the LTsock
+ test correctly on my 64 bit HP-UX 11 test
+ system.
+
+
+Vic Abell <abe@purdue.edu>
+April 10, 2012