| |
| 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 and |
| LTnlink tests 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 |
| 9/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> |
| September 27, 2011 |