00TEST

   1
   2                         The Lsof Test Suite
   3
   4                             Contents
   5
   6                 A.  Introduction
   7                     1.  Test Suite Goals
   8                     2.  Not a FAQ
   9                     3.  Where have the tests been tested?
  10                 B.  Test Methodology
  11                     1.  Test Limitations
  12                     2.  Test Data Base and Scripts
  13                     3.  The Makefile
  14                         3.1 The CkTestDB Script
  15                     4.  The Lsof Executable and LT_LSOF_PATH
  16                     5.  Automated Testing
  17                 C.  Configure Script Participation
  18                     1.  config.cc
  19                     2.  config.cflags
  20                         2.1  config.cflags Contents
  21                     3.  config.ldflags
  22                     4.  config.xobj
  23                 D.  Cleaning -- Quick or Spotless
  24                 E.  Test Libraries
  25                     1.  LTlib.c
  26                 F.  The Individual Tests
  27                     1.  LTbasic, a Basic Lsof Test
  28                     2.  LTbigf, Test Sizes and Offsets for Large
  29                         (> 32 bit) Files
  30                     3.  LTdnlc, Test the Kernel's Dynamic Name Lookup
  31                         Cache
  32                     4.  LTlock, Lock Tests
  33                     5.  LTnfs, NFS Test
  34                     6.  LTnlink, Link Count Test
  35                     7.  LTsock, Test IPv4 Sockets
  36                     8.  LTszoff, Test Sizes and Offsets for Small
  37                         (< 32 bit) Files
  38                     9.  LTunix, Test UNIX Domain Sockets
  39                 Appendix A, Test Files
  40                 Appendix B, Test Validations
  41                 Appendix C, Test Failures
  42
  43
  44 A. Introduction
  45 ===============
  46
  47 Lsof has an automated test suite whose components are located in
  48 the tests/ sub-directory of the lsof top-level directory.  Configuring,
  49 building and testing lsof can be done with these shell commands:
  50
  51     $ Configure -n <dialect-abbreviation>
  52     $ make
  53     $ cd tests
  54     $ make
  55
  56 That's all there is to it!
  57
  58 But read on for more dirty details.
  59
  60 A.1. Test Suite Goals
  61 =====================
  62
  63 The lsof test suite attempts to test basic lsof features.  It does
  64 not promise to test every lsof feature for every supported dialect.
  65 (That's a nearly impossible goal.)
  66
  67 As a result, the test suite cannot promise that every lsof feature
  68 works as documented.  At best the test suite gives some assurance
  69 that basic, standard and some optional lsof features work.
  70
  71 A.2. Not a FAQ
  72 ==============
  73
  74 One caution: this is not a frequently asked questions (FAQ) file
  75 for the lsof test suite.  FAQs on the lsof test suite will be found
  76 in the one and only lsof FAQ in file 00FAQ of the lsof distribution,
  77 or on-line at:
  78
  79     ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/FAQ
  80
  81 A.3. Where have the tests been tested?
  82 ======================================
  83
  84 OK, I just said this isn't an FAQ and here comes a question and
  85 answer that looks like an FAQ.  Consider it a very frequently asked
  86 question and indulge me -- let me answer it here.
  87
  88 The lsof test suite hasn't been tested everywhere it might be
  89 possible to build lsof successfully.  That "everywhere" includes
  90 dialect versions -- e.g., Solaris < 2.6 -- to which I no longer
  91 have access.  On some dialect versions to which I have access, some
  92 tests won't run because the test system lacks support.
  93
  94 In "Appendix B, Test Validations" I've tried to list where I compiled
  95 and tested the test suite and information on any tests I was unable
  96 to run.  In "Appendix C, Test Failures" I list where the test suite
  97 fails and why it failed.
  98
  99 A.4 Where are the tests?
 100 ========================
 101
 102 This is another FAQ whose answer is that the tests are in the tests/
 103 sub-directory of the main lsof source directory.
 104
 105
 106 B. Test Methodology
 107 ===================
 108
 109 The test suite is made up of individual C programs.  Test setup is
 110 performed by the lsof Configure script itself, which writes a set
 111 of dialect configuration files in the tests/ subdirectory.  (See
 112 "C. Configure Script Participation.")
 113
 114 Each program or script performs a specialized tests.  Those tests
 115 are described below in "F. The Individual Tests".
 116
 117 Each test measures lsof functionality by putting a specific lsof
 118 command execution at the end of an in-bound (to the test) pipe.
 119 The caller asks lsof to write its results to the pipe in field
 120 output form.  (See the -F option in the lsof man page.)
 121
 122 Using an in-bound lsof pipe allows the tests to measure a great
 123 deal of lsof functionality, including as an interesting side effect,
 124 the performance of field output.  Consequently, there's no special
 125 field output test.
 126
 127 B.1. Test Limitations
 128 =====================
 129
 130 One limitation of the tests is that they don't measure lsof formatted
 131 output -- i.e., the output normally see when lsof is run.  There
 132 are just too many variants of lsof output produced across the range
 133 of dialects where lsof runs, so field output is a more consistent
 134 way to process lsof output.
 135
 136 But using field output does mean that the test suite doesn't check
 137 for lsof formatting problems, except in the field output itself.
 138
 139 B.2. Test Data Base and Scripts
 140 ===============================
 141
 142 The TestDB file contains a simple data base that describes where
 143 the tests have been validated.  Entries are formed from a combination
 144 of the lines in the config.cflags file produced by the lsof Configure
 145 script.  The entries can be considered "lsof dialect footprints,"
 146 hereafter simply called "dialect footprints" or just "footprints."
 147
 148 Two shell scripts support TestDB.  The first, Add2TestDB, will add
 149 a footprint to TestDB.  I don't recommend you use this script.
 150 Mostly it's for my use when I find that the test suite has been
 151 validated on a new dialect.
 152
 153 It's also possible to add a footprint to TestDB by simply editing
 154 TestDB and pasting into it a copy of the footprint reported by a
 155 failed Makefile rule.  I don't generally recommend this be done,
 156 either.
 157
 158 There are Makefile rules that use (and avoid) the CkTestDB script.
 159 (See "B.3 The Makefile".)
 160
 161 The default (i.e., "all") Makefile rule uses the CkTestDB script
 162 to look for the footprint in TestDB. If no footprint is found, the
 163 script issues a warning, displays the unfound footprint, and asks
 164 if running the test suite should continue.
 165
 166 The "auto" Makefile rule also uses CkTestDB, but with a special
 167 call that causes CkTestDB to look in TestDB for the footprint,
 168 report it when it can't be found, and then fail.  That CkTestDB
 169 failure causes the "auto" rule to fail, too.
 170
 171 The "silent" Makefile rule doesn't use CkTestDB to look in TestDB
 172 for the footprint.  It runs the standard and basic tests as silently
 173 as possible, then returns a failure or success exit code that
 174 signals the result of the running of the tests.  (Use the "silent"
 175 rule carefully, because it will skip proving the tests have previously
 176 run on the dialect.)
 177
 178 B.3. The Makefile
 179 =======================
 180
 181 The Makefile runs the tests in the test suite.  It has these rules.
 182
 183     all         runs the basic test and the standard tests,
 184                 interacting with the caller should the footprint
 185                 not be found in TestDB.
 186
 187                 (This is the default rule.)
 188
 189     auto        runs the basic test and the standard tests on a
 190                 previously validated system as silently as possible.
 191
 192                 The footprint must be found in TestDB for this rule
 193                 to succeed.  (See the "silent" rule for one that
 194                 avoids checking TestDB.)
 195
 196                 This rule is designed for lsof build scripts that
 197                 want a quick noiseless test to make sure what they
 198                 built works as it previously did.
 199
 200                 This rule calls CkTestDB in a way that inhibits
 201                 its normal go-ahead request. (See "B.2.1 The CkTestDB
 202                 Script".)  If CkTestDB finds the footprint and all
 203                 tests succeed, this rule returns a zero exit code
 204                 (success).  If the footprint isn't found or if any
 205                 test fails, a non-zero exit code (failure) is
 206                 returned.
 207
 208     ckDB        calls the CkTestDB script to look for a footprint.
 209                 If none is found, the way CkTestDB was called (See
 210                 "B.3.1 The CkTestDB Script".) causes it to return
 211                 a non-zero exit code (failure) to this rule, and
 212                 the rule then returns a non-zero exit code (failure)
 213                 itself.
 214
 215                 This rule is used by the "auto" rule.  If this rule
 216                 succeeds (zero exit code), the "auto" rule then
 217                 uses the "silent" rule.
 218
 219     clean       removes test and compiler output.  (See the "D.
 220                 Cleaning -- Quick or Spotless" section.)
 221
 222     opt         runs the optional tests.
 223     optional
 224
 225     silent      runs the lsof basic and standard tests as silently
 226                 as possible (as the "auto" rule does), but without
 227                 using CkTestDB to look for a footprint.  If all
 228                 tests succeed, the rule returns a zero exit code
 229                 (success).  If any test fails, the rule returns a
 230                 non-zero exit code (failure).
 231
 232                 Use the "silent" rule carefully, because it will
 233                 skip proving the tests have previously run on the
 234                 dialect.
 235
 236     spotless    does what the clean rule does and also removes the
 237                 config.* files created by ../Configure.  (See the
 238                 "D. Cleaning -- Quick or Spotless" section.)
 239
 240     std         runs the basic test and the standard tests.
 241     standard
 242
 243 The Makefile cleaning rules are further described in "D.  Cleaning
 244 -- Quick or Spotless."
 245
 246 B.3.1 The CkTestDB Script
 247 =========================
 248
 249 Some Makefile rules (e.g., "all" and "auto") use the CkTestDB script
 250 to make sure the tests have been run previously on the dialect.
 251 CkTestDB does that by looking for the dialect's footprint in TestDB.
 252
 253 If no footprint is found, and if standard input is a TTY, CkTestDB
 254 asks for a go-ahead signal.  If standard input isn't a TTY, CkTestDB
 255 aborts the test run.  (See "B.2. Test Data Base and Scripts".)
 256
 257 The Makefile "silent" rule does not call CkTestDB.  use the "silent"
 258 rule carefully, because it will skip proving the tests have previously
 259 run on the dialect.
 260
 261 B.4. The Lsof Executable and LT_LSOF_PATH
 262 =========================================
 263
 264 Normally the programs in the test suite use the lsof executable in
 265 their parent directory, ../lsof.  Usually that lsof has just been
 266 built and testing it is the next logical step.
 267
 268 Be careful that ../lsof has sufficient permission to access the
 269 necessary kernel resources -- e.g., /dev/kmem, /dev/mem, /proc,
 270 etc.  If it doesn't the tests will fail.  (The tests do check to
 271 see if they can open /dev/mem and /dev/kmem for read access if
 272 LT_KMEM is defined in config.cflags and if the path to the lsof
 273 executable is ../lsof.)
 274
 275 Here are two possible ways you can make sure the lsof being tested
 276 has sufficient permission: 1) use chmod and chgrp to enable its
 277 running and put its path in LT_LSOF_PATH, thus disabling the check
 278 in the tests for kernel memory access; or 2) run the tests (and
 279 hence the lsof being tested) under a login that has sufficient
 280 permission -- e.g., is in a group that can read /dev/kmem.
 281
 282 You can direct the tests to use a different lsof executable by
 283 specifying its path in the LT_LSOF_PATH environment variable.  To
 284 test an lsof executable already installed in /usr/local/etc --
 285 provided that lsof is at revision 4.63 or higher -- do this:
 286
 287     $ LT_LSOF_PATH=/usr/local/etc/lsof
 288     $ export LT_LSOF_PATH
 289     $ cd .../lsof_<version>/tests
 290     $ make
 291
 292 When you specify an alternate executable path via LT_LSOF_PATH,
 293 that also prevents the tests from checking to see if they have
 294 kernel memory access.
 295
 296 B.5 Automated Testing
 297 =====================
 298
 299 Normally the lsof test suite is wordy and may require interaction.
 300 When you want to avoid those interferences, use the Makefile "auto"
 301 or "silent" rules.  (See the description of the "auto" and "silent"
 302 rules in "B.3 The Makefile".)
 303
 304 The footprint must be present in TestDB in order to use the "auto"
 305 rule.  If it is not, the "auto" rule will fail and report the
 306 missing footprint.  Footprints in TestDB proclaim that the tests
 307 have previously succeeded on the dialect.
 308
 309 The footprint need not be present in TestDB in order to use the
 310 "silent" rule.  Use the "silent" rule carefully, because it will
 311 skip proving the tests have previously run on the dialect.
 312
 313
 314 C. Configure Script Participation
 315 =================================
 316
 317 An important step in setting up the test suite is performed by the
 318 Configure script in the lsof home directory (the parent to tests/.)
 319
 320 Configure writes four files in tests/ that describe how the tests
 321 are to be compiled, configured and loaded.  The files also describe
 322 options that Configure selected that are important to the test
 323 suite.
 324
 325 C.1. config.cc
 326 ==============
 327
 328 This file, config.cc, contains the name of or the path to the C
 329 compiler used to compile lsof.  The Makefile uses this file in
 330 place of the standard make(1) CC string with a shell in-place
 331 execution statement -- i.e., `cat config.cc`.
 332
 333 If the LSOF_CC environment variable is supplied to the lsof Configure
 334 script, its value will appear in the config.cc file.
 335
 336 C.2. config.cflags
 337 ==================
 338
 339 This file, config.cflags, contains C compiler flags that Makefile
 340 uses to compile the C programs in the test suite.  As with the
 341 compiler file, config.cc, the make rules incorporate the contents
 342 of this file into C compiler options with `cat config.cflags`.
 343
 344 This file is also used by the Add2TestDB and CkTestDB shell scripts
 345 to build and match footprints.  (See "B.2. Test Data Base and
 346 Scripts.")
 347
 348 C.2.1 config.cflags Contents
 349 ============================
 350
 351 The config.cflags file may contain the following C compiler flags.
 352
 353
 354     -DLT_AIXA               is present if lsof was built for AIX.
 355                             It contains the AIX architecture flag.
 356                             (See the lsof Configure script or
 357                             dialects/aix/dlsof.h for more information
 358                             on the AIX architecture flag.)
 359
 360     -DLT_BIGF               is present if lsof was built for a dialect
 361                             that has large file (sizes and offsets >
 362                             32 bits).
 363
 364     -DLT_CC                 is present if the lsof compiler is cc.
 365
 366     -DLT_DIAL_<abbr>        always ends in (the <abbr> part) the
 367                             "canonical" -- i.e., usually the most
 368                             common abbreviation by which the dialect
 369                             is known.
 370
 371                             Example: -DLT_DIAL_solaris
 372
 373     -DLT_GCC                is present if the lsof compiler is gcc.
 374
 375     -DLT_K64                is present if lsof has been built for a
 376                             64 bit kernel
 377
 378     -DLT_KMEM               is present if lsof has been built to
 379                             use /dev/kmem to obtain kernel values.
 380
 381     -DLT_VERS=<vn>          contains the version number for the
 382                             dialect, as used in lsof pre-processor
 383                             tests.
 384
 385                             Example for Solaris 10: -DLT_VERS=100000
 386
 387     -DLT_VPATH              is present if the dialect has the v_path
 388                             member in the vnode structure (e.g., some
 389                             versions of Solaris 10).
 390
 391 The config.cflags file may also contain dialect-specific compiler
 392 flags needed to activate a specific feature on the dialect.  For
 393 example, for HP-UX config.cflags might contain:
 394
 395     -D_LARGEFILE64_SOURCE   This compiler flag enables the use of
 396                             large-file system library functions
 397                             --e.g., open64().
 398
 399                             The lsof Configure script stanzas for
 400                             the dialects select these options.
 401
 402
 403 C.3. config.ldflags
 404 ===================
 405
 406 This file, config.ldflags, contains the dialect loader flags --
 407 i.e., the equivalent to make(1) LFLAGS -- for loading the test
 408 programs.
 409
 410 Example for Solaris: -lsocket           this adds the socket library
 411                                         to the loading of the lsof
 412                                         test programs.
 413
 414 Example for UnixWare: -lsocket -lnsl    this adds the socket and
 415                                         name server libraries to
 416                                         the loading of the lsof
 417                                         test programs.
 418
 419
 420 C.4. config.xobj
 421 ================
 422
 423 This file, config.xobj, contains the paths to any extra object
 424 files (.o's) that must be loaded when the test suite C programs
 425 are loaded.  Like config.cc and config.cflags, it's incorporated
 426 into the loader statements of the Makefile's rules with `cat
 427 config.xobj`.
 428
 429 Examples for DEC OSF/1 and NEXTSTEP:
 430
 431     ../lib/snpf.o       this loads the private lsof object file
 432                         that contains an snprintf() function.  (The
 433                         DEC OSF/1 4.0 and NEXTSTEP 3.1 C libraries
 434                         don't have snprintf().)
 435
 436
 437 D. Cleaning -- Quick or Spotless
 438 ================================
 439
 440 There are two Makefile rules that clean the tests/ subdirectory --
 441 "clean" and "spotless".  They cause different degrees of cleaning.
 442
 443     clean       a "quick" clean that removes compiled object files,
 444                 executables and test files.  It does NOT remove
 445                 the configuration files that ../Configure and the
 446                 config.perl rule wrote.
 447
 448     spotless    cleans out everything clean does -- plus the
 449                 configuration files that ../Configure and the
 450                 config.perl rule wrote.
 451
 452                 This is the rule used when `./Configure -clean` is
 453                 specified.  If this rule is used, `../Configure -n
 454                 <abbr>` and `../make`) must be run again before
 455                 the test suite can be used.
 456
 457
 458 E. Test Library
 459 ===============
 460
 461 The lsof test suite provides a C library.
 462
 463 E.1. LTlib.c
 464 ============
 465
 466 This is a C library of common functions used by tests.  Configured
 467 at compile time by the contents of config.cflags, it uses the single
 468 header file LsofTest.h.  LsofTest.h tailors its definitions to the
 469 dialect at compile time, using the LT_DIAL_* definitions in
 470 config.cflags.
 471
 472 Two particularly useful functions in the library are: ExecLsof(),
 473 which will execute an lsof child process; and RdFromLsof(), which
 474 will read from the in-bound lsof pipe, and decode the fields into
 475 structures that are easy for C programs to process.
 476
 477 This library is a good model for processing field output in a C
 478 program from an in-bound lsof pipe.
 479
 480 The source for the library, LTlib.c, contains more documentation.
 481
 482
 483 F. The Individual Tests
 484 =======================
 485
 486 The individual tests are listed in this section.  The listings
 487 explain what the tests do, a few errors they might report, and how
 488 to use options and environment variables to customize the tests.
 489
 490 The test descriptions are listed in this section in alphabetical
 491 order, not in the order they are run by Makefile.
 492
 493 The Makefile runs the tests in three groups, basic tests, standard
 494 tests, and optional tests.  The default make "all" rule runs the
 495 basic and standard tests.  (The "standard", "std", and "test"
 496 Makefile rules are synonyms to "all".) If the standard tests succeed,
 497 Makefile suggests running the optional tests with the "opt" (or
 498 "optional") rule.
 499
 500 The Makefile "auto" and "silent" rules run only the basic and
 501 standard tests.  They do not run or suggest you run the optional
 502 tests.
 503
 504     The basic test:
 505         LTbasic
 506
 507     Standard tests:
 508         LTnlink
 509         LTsock
 510         LTszoff
 511         LTunix
 512
 513     Optional tests:
 514         LTbigf
 515         LTdnlc
 516         LTlock
 517         LTnfs
 518
 519 The basic and standard tests should all succeed on all dialects,
 520 although LTnlink may warn that it can't perform its unlink test on
 521 an NFS file system.
 522
 523 The optional tests may run, they may be disabled for specific
 524 dialects, or they may fail because of special resource needs --
 525 e.g., LTbigf will run only on UNIX dialects where it knows how to
 526 handle files whose lengths exceed 32 bits, and LTnfs needs access
 527 to an NFS file system mounted from a remote NFS server.
 528
 529 Tests that need special resources usually provide a hint about the
 530 resources when they fail.  Information about special resource needs
 531 may also be found in the following sections about the individual
 532 tests.
 533
 534 G.1. LTbasic, a Basic Lsof Test
 535 ===============================
 536
 537 This is the basic lsof test.  If it doesn't run, it's not likely
 538 any other tests will run, either.  Hence, if it fails, no Makefile
 539 rule runs any other tests.
 540
 541 This test uses lsof to locate files in the lsof process, including
 542 current working directory, the lsof executable, and the /dev/kmem
 543 open file.
 544
 545 Finding the lsof executable may not be possible on AIX if lsof was
 546 compiled without support for its -X option.
 547
 548 Finding /dev/kmem use by lsof is only possible on dialects where
 549 lsof uses /dev/kmem.  The -DLT_KMEM define indicates that.
 550
 551 Run this test:
 552
 553     $ ./LTbasic
 554
 555 Environment variables: LT_LSOF_PATH defines the path to the lsof
 556                        executable.  (The default is ../lsof.)
 557
 558 G.2. LTbigf, Test Sizes and Offsets for Large (> 32 bit) Files
 559 ==============================================================
 560
 561 This is a test in the optional test group.
 562
 563 This test is effective only when ../Configure has put -DLT_BIGF in
 564 config.cflags.  Without that definition this test simply reports
 565 that the dialect doesn't support large files.  That report is
 566 accompanied by a successful test exit code, so that the runner of
 567 the test (e.g., the Makefile) won't believe the test failed.
 568
 569 When a dialect does support large files, the test attempts to create
 570 a file that looks very large -- e.g., has a length as reported by
 571 ls(1) of 0x140000000 bytes.  However, the file really has only a
 572 small amount of data in it, the rest of the file consists of a
 573 large standard UNIX file system "hole."
 574
 575 By default the test file is named config.LTbigf<PID>, where PID is
 576 the Process ID of the LTbigf process.
 577
 578 When that file is not on a file system enabled for large files, or
 579 when the process that runs LTbigf can't create a big file, LTbigf
 580 will report an error.  The error will be accompanied by hints that
 581 the -p option may need to be used to define a path where the test
 582 can write a large file, or the process ulimit file block size may
 583 need to be raised -- e.g., to "unlimited."
 584
 585 LTbigf can't test file offset reporting on Linux kernels below
 586 2.6.22, because the /proc file systems of those kernels don't make
 587 file offsets available to lsof.
 588
 589 Run this test:
 590
 591     $ ./LTbigf [-p <path>]
 592
 593 Environment variables: LT_LSOF_PATH defines the path to the lsof
 594                        executable.  (The default is ../lsof.)
 595
 596 G.3. LTdnlc, Test the Kernel's Dynamic Name Lookup Cache
 597 ========================================================
 598
 599 This is a test in the optional test group.
 600
 601 This test asks lsof to locate the current working directory of its
 602 own process and report the path it has assembled from the components
 603 it found in the kernel's Dynamic Name Lookup Cache (DNLC) or via
 604 other dialect-specific methods.  (E.g., Linux, HP-UX 11.11, and
 605 some Tru64 UNIX versions have private name lookup methods.)
 606
 607 The test checks what lsof reports as the current working directory
 608 path for any missing components and counts the number of full paths
 609 returned.  (Symbolic link complications prevent testing for exact
 610 path matches.)  The test is repeated.  If full paths are returned
 611 at least half the time, the test considers itself successful.
 612
 613 This test can't be run on AIX, because lsof can't access the DNLC
 614 there.  It can't be run on Apple Darwin versions below 8.0, either,
 615 because insufficiently reliable DNLC information is available there.
 616 This test may fail on other dialects when the file system -- e.g., NFS.
 617 /tmp, loopback -- doesn't fully participate in the dialect's DNLC.
 618
 619 Run this test:
 620
 621     $ ./LTdnlc
 622
 623 Environment variables: LT_LSOF_PATH defines the path to the lsof
 624                        executable.  (The default is ../lsof.)
 625
 626 G.4. LTlock, Lock Tests
 627 =======================
 628
 629 This is a test in the optional test group.
 630
 631 This test uses flock() and fcntl() to set and clear file locks,
 632 and measures lsof's ability to report them.  The choice of system
 633 lock call is based on the dialect.  (There are LT_DIAL_* pre-processor
 634 tests in LTlock.c.)
 635
 636 This test can't be run on an NFS client file system, because NFS
 637 lock information is kept on the server.  Lsof on the client can't
 638 see that server kernel data.
 639
 640 By default the test attempts to create a file named config.LTlock<PID>,
 641 where PID is the Process ID of the locking test process.  It uses
 642 lsof to determine if the file is on a client NFS file system.  If
 643 it is, the test aborts, hinting that the -p option can be used to
 644 specify a non-client-NFS test file path.
 645
 646 This test can't be run on Darwin, because insufficient file system
 647 lock information is available to lsof there.
 648
 649 Run this test:
 650
 651     $ ./LTlock [-p <path>]
 652
 653 Environment variables: LT_LSOF_PATH defines the path to the lsof
 654                        executable.  (The default is ../lsof.)
 655
 656 G.6. LTnfs, NFS Test
 657 ====================
 658
 659 This is a test in the optional test group.
 660
 661 This test verifies that lsof can locate files mounted on a client
 662 NFS system from an NFS server.
 663
 664 By default it creates a test file, config.LTnfs<PID>, where PID is
 665 the Process ID of the test process.  The test then uses lsof to
 666 find the file on an NFS file system.
 667
 668 If lsof can't find the file the test warns that the test file might
 669 not be on an NFS file system and hints that the -p option may be
 670 used to specify the path of an NFS file, provided the test can have
 671 read access to it there.  The test warning also states that the
 672 file at the path specified with -p must be a regular file, not a
 673 directory.
 674
 675 This test can't be run on Darwin versions below 8.0, because
 676 insufficient NFS file information is available to lsof there.
 677
 678 Run this test:
 679
 680     $ ./LTnfs [-p <path>]
 681
 682 Environment variables: LT_LSOF_PATH defines the path to the lsof
 683                        executable.  (The default is ../lsof.)
 684
 685 G.7. LTnlink, Link Count Test
 686 =============================
 687
 688 This is a test in the standard test group.
 689
 690 The test checks lsof's reporting of link count (nlink in UNIX
 691 argot.)
 692
 693 It creates a test file in the current working directory named
 694 config.LTnlink<PID>, where  PID is the Process ID of the test
 695 process.  It then uses stat(2) and lsof to measure the link count
 696 of the file.
 697
 698 If LTnlink creates the test file in the current working directory
 699 and it is on an NFS file system, LTnlink won't be able to perform
 700 one section of its test.  In that section the test file is unlinked
 701 so its link count will be zero and lsof is asked to find it among
 702 the set of files whose link counts are zero.
 703
 704 When an NFS file is unlinked its link count isn't reduced until
 705 the last open instance is closed on either the NFS clients or the
 706 NFS.  That's a consequence of NFS statelessness and leads to the
 707 occasional presence of files with names of the form .nfsxxxx.
 708
 709 Should LTnlink find its test file on an NFS file system, it disables
 710 the unlink section of its tests and issues a warning.  It also
 711 issues a hint that the test file path can be named via the -p option
 712 to give a test file location that isn't on an NFS file system.
 713
 714 This test can't be run on Darwin, because insufficient file system link
 715 count information is available to lsof there.
 716
 717 Because some UNIX dialects delay the reporting of a link count
 718 update after a file has been unlinked, LTnlink may not get its
 719 expected response from lsof for a while after the test file has
 720 been unlinked.  In that cause LTnlink may delay for up to a minute,
 721 calling lsof once every two seconds and displaying a "waiting for
 722 link count update: ..." message.
 723
 724 Some file systems -- e.g., ZFS on Solaris 11 -- don't allow LTnlink to
 725 unlink its test file, because LTnlink has the file open.  LTnlink
 726 explains that failure and suggests that it be run with path of the "-p
 727 path" option set to a file on /tmp.  See 00FAQ for more information.
 728
 729 Run this test:
 730
 731     $ ./LTnlink [-p <path>]
 732
 733 Environment variables: LT_LSOF_PATH defines the path to the lsof
 734                        executable.  (The default is ../lsof.)
 735
 736 G.7. LTsock, Test IPv4 Sockets
 737 ==============================
 738
 739 This is a test in the standard test group.
 740
 741 This test uses lsof to locate open IPv4 socket files that the test
 742 has created itself.  The test opens a server socket, then forks a
 743 child process to connect to that socket.  After both are running,
 744 the test uses lsof to find the open socket files at their known
 745 host and port addresses.
 746
 747 Run this test:
 748
 749     $ ./LTsock
 750
 751 Environment variables: LT_LSOF_PATH defines the path to the lsof
 752                        executable.  (The default is ../lsof.)
 753
 754 G.8. LTszoff, Test Sizes and Offsets for Small (< 32 bit) Files
 755 ===============================================================
 756
 757 This is a test in the standard test group.
 758
 759 This test checks lsof's reporting of file size and offset for small
 760 (< 32 bits) files.
 761
 762 It creates a test file in the current working directory named
 763 config.LTszoff<PID>.  PID is the Process ID of the test process.
 764
 765 LTszoff can't test file offset reporting on Linux kernels below
 766 2.6.22, because the /proc file systems of those kernels don't make
 767 file offsets available to lsof.
 768
 769 Run this test:
 770
 771     $ ./LTszoff [-p <path>]
 772
 773 Environment variables: LT_LSOF_PATH defines the path to the lsof
 774                        executable.  (The default is ../lsof.)
 775
 776 G.9.  LTunix, Test UNIX Domain Sockets
 777 ======================================
 778
 779 This is a test in the standard test group.
 780
 781 This test checks lsof's reporting of UNIX domain sockets.
 782
 783 The test creates a pair of UNIX domain sockets and uses bind(2) to
 784 associate the file system names config.LT0U<PID> (client) and
 785 config.LT1U<PID> (server) with them.  (PID is the test process ID.)
 786 The test then uses lsof to find the two open UNIX domain socket
 787 files.
 788
 789 Run this test:
 790
 791     $ ./LTunix
 792
 793 Environment variables: LT_LSOF_PATH defines the path to the lsof
 794                        executable.  (The default is ../lsof.)
 795
 796
 797 Appendix A, Test Files
 798 ======================
 799
 800 These files may be created by suite tests.
 801
 802                         Created
 803     ./tests Name        by Test     Use
 804     ============        =======     ===
 805
 806     config.LTbifg**     LTbigf      to test lsof's large file size
 807                                     and offset reporting
 808
 809     config.LTlock*      LTlock      for locking tests
 810
 811     config.LTnfs*       LTnfs       for NFS tests
 812
 813     config.LTnlink*     LTnlink     for link count tests
 814
 815     config.LTszoff*     LTszoff     for small file size and and
 816                                     offset reporting
 817
 818     config.LT[01]U*     LTunix      two UNIX domain sockets, used
 819                                     to determine if lsof can report
 820                                     their open instances properly
 821
 822
 823 Appendix B, Test Validations
 824 ============================
 825
 826 This appendix lists the UNIX dialects and their versions where I
 827 have validated the test suite.  The list indicates the particular
 828 tests I was unable to run, mostly LTnfs because the test systems
 829 I used had no NFS file systems mounted.
 830
 831 The information in the following table is encoded in a test data
 832 base file, TestDB, as footprints, using the tests compiler options
 833 written to config.cflags by the lsof Configure script.  See "B.2.
 834 Test Data Base and Scripts" for more information on the test data
 835 base, footprints, and the scripts that support them.
 836
 837     UNIX
 838     Dialect       Dialect Description           Untested Tests
 839     =======       ===================           ==============
 840     AIX           4.3.3, Power, cc
 841                   5.1, Power-32, cc
 842                   5.1, Power-32, gcc
 843                   5.1, Power-64, cc
 844                   5.2, Power-32, cc
 845                   5.2, Power-32, gcc
 846                   5.2, Power-64, cc
 847                   5.2, Power-64, gcc
 848                   5.3, Power-64, cc
 849     Darwin        1.4, 5.5, 6.x, 7.x gcc        Darwin lsof doesn't
 850                                                 have adequate support
 851                                                 to allow the LTbigf,
 852                                                 Ltdnlc, LTlock, LTnfs,
 853                                                 and LTnlink tests to
 854                                                 run.
 855                   8.0, gcc                      Darwin lsof doesn't
 856                                                 have adequate support
 857                                                 to allow the LTbigf,
 858                                                 LTlock and LTnlink
 859                                                 tests to run.
 860                   9.0, gcc                      Darwin lsof doesn't
 861                                                 have adequate support
 862                                                 to allow the LTlock
 863                                                 test to run.
 864                   10.0, gcc                     Darwin lsof doesn't
 865                                                 have adequate support
 866                                                 to allow the LTlock test
 867                                                 to run.
 868                   11.0, gcc                     Darwin lsof doesn't
 869                                                 have adequate support
 870                                                 to allow the LTlock test
 871                                                 to run.
 872     FreeBSD       4.5, i386, gcc
 873                   4.6, i386, gcc
 874                   4.7, i386, gcc
 875                   4.8, i386, gcc
 876                   4.9, i386, gcc
 877                   4.10, i386 gcc
 878                   5.0, Alpha, gcc
 879                   5.0, Sparc, gcc
 880                   5.0, i386, gcc
 881                   5.1, Alpha, gcc
 882                   5.1, Amd64, gcc
 883                   5.1, Sparc, gcc
 884                   5.1, i386, gcc
 885                   5.2, i386, gcc
 886                   5.2, Alpha, gcc
 887                   5.2, Amd64, gcc
 888                   5.2, Sparc, gcc
 889                   5.3, Alpha, gcc
 890                   5.4, Alpha, gcc
 891                   5.5, Alpha, gcc
 892                   6.0, Alpha, gcc
 893                   6.0, Amd64, gcc
 894                   6.0, Sparc, gcc
 895                   6.1, i386, gcc
 896                   6.4, i386, gcc
 897                   7.0 Alpha, gcc
 898                   7.0 Amd64, gcc
 899                   7.1 Amd64, gcc
 900                   7.2 Amd64, gcc
 901                   7.3 Amd64, gcc
 902                   7.4 Amd64, gcc
 903                   8.0 Amd64, gcc
 904                   8.2 Amd64, gcc
 905                   8.3 Amd64, gcc
 906                   9.0 Amd64, gcc
 907                  10.0 Amd64, gcc
 908     DEC OSF/1     4.0, cc
 909     HP-UX         10.20, cc                     LTbigf
 910                   10.20, gcc (1)                LTbigf
 911                   11.00-32, ANSI-C              LTbigf, LTnfs
 912                   11.00-64, ANSI-C
 913                   11.11, ANSI-C
 914                   11.23, ANSI-C
 915     Linux         2.4.12-686                    LTbigf, no offset tests
 916                                                 LTszoff, no offset tests
 917                   2.4.18-686                    LTbigf, no offset tests
 918                                                 LTszoff, no offset tests
 919                   2.4.21-686                    LTbigf, no offset tests
 920                                                 LTszoff, no offset tests
 921                   2.4.23-686                    LTbigf, no offset tests
 922                                                 LTszoff, no offset tests
 923                   2.4.24-686                    LTbigf, no offset tests
 924                                                 LTszoff, no offset tests
 925                   2.4.25-686                    LTbigf, no offset tests
 926                                                 LTszoff, no offset tests
 927                   2.4.26-686                    LTbigf, no offset tests
 928                                                 LTszoff, no offset tests
 929                   2.4.27-686                    LTbigf, no offset tests
 930                                                 LTszoff, no offset tests
 931                   2.4.28-686                    LTbigf, no offset tests
 932                                                 LTszoff, no offset tests
 933                   2.4.29-686                    LTbigf, no offset tests
 934                                                 LTszoff, no offset tests
 935                   2.4.30-686                    LTbigf, no offset tests
 936                                                 LTszoff, no offset tests
 937                   2.6.1-rc2                     LTbigf, no offset tests
 938                                                 LTszoff, no offset tests
 939                   2.6.18-686                    LTbigf, no offset tests
 940                                                 LTszoff, no offset tests
 941                   2.6.22-686                    (Note: this Linux kernel
 942                                                  supplies file offsets to
 943                                                  lsof.)
 944                   2.6.32-686                    (Note: this Linux kernel
 945                                                  supplies file offsets to
 946                                                  lsof.)
 947                   2.6.38-686
 948     NEXTSTEP      3.1, gcc                      LTnfs
 949     NetBSD        1.4.1, Alpha, gcc             LTnfs
 950                   1.5x, x86, gcc                LTnfs
 951                   1.6x, Alpha, gcc              LTnfs
 952                   1.6x, x86, gcc                LTnfs
 953                   2.0x, alpha, gcc              LTnfs
 954                   2.0x, sparc64, gcc            LTnfs
 955                   2.0x, x86, gcc                LTnfs
 956                   2.99.9, x86, gcc              LTnfs
 957                   2.99.10, x86, gcc             LTnfs
 958                   2.99.11, x86, gcc             LTnfs
 959                   2.99.12, x86, gcc             LTnfs
 960                   3.99., x86, gcc               LTnfs
 961     OpenBSD       3.0, gcc
 962                   3.1, gcc
 963                   3.2, gcc
 964                   3.3, gcc
 965                   3.4, gcc
 966                   3.5, gcc
 967                   3.6, gcc
 968                   3.7, gcc
 969                   3.9, gcc
 970     OPENSTEP      4.2, gcc                      LTnfs
 971     OSR           5.04, cc                      LTnfs
 972                   5.06, cc                      LTnfs
 973     Solaris       2.6, cc                       LTnfs
 974                   2.6, gcc                      LTnfs
 975                   7-32, cc
 976                   7-32, gcc                     LTnfs
 977                   8-32, cc
 978                   8-32, gcc
 979                   8-64, cc
 980                   8-64, gcc
 981                   9-64, Beta-Refresh, cc
 982                   9-64, Beta-Refresh, gcc
 983                   9-64, FCS, cc
 984                   9-64, FCS, gcc
 985                   10-32, i86pc, gcc
 986                   10-32, i86pc, cc
 987                   10-64, Sparc, cc
 988                   10-64, Sparc, gcc
 989                   11-64, Amd64, cc
 990     Tru64 UNIX    5.0, cc
 991     Tru64 UNIX    5.0, cc
 992                   5.1, cc
 993     UnixWare      7.1.1, NSC, cc                LTnfs
 994                   7.1.3, cc
 995                   7.1.4, cc
 996
 997 If you are able to run the test suite on dialect versions other
 998 than the ones listed above, please send e-mail to <abe@purdue.edu>,
 999 indicating the dialect version where you were able to run the test
1000 suite.  Please send me the footprint formed by CkTestDB, or run
1001 the Add2TestDB script and send me the footprint it reports.
1002
1003 If you encounter problems compiling the tests or running them on
1004 a dialect version listed above, please send e-mail to <abe@purdue.edu>,
1005 naming the dialect version and providing the output from the lsof
1006 Configure script and make operation.
1007
1008 1) John Dzubera did the HP-UX 10.20 gcc testing and provided its
1009    footprint.
1010
1011
1012 Appendix C, Test Failures
1013 =========================
1014
1015 I was unable to make the test suite run on the following dialects.
1016
1017     UNIX Dialect
1018     and Description      Failure
1019     ===============      =======
1020     HP-UX 11-64, gcc     64 bit gcc 3.0 didn't compile the LTsock
1021                          test correctly on my 64 bit HP-UX 11 test
1022                          system.
1023
1024
1025 Vic Abell <abe@purdue.edu>
1026 April 10, 2012