summaryrefslogtreecommitdiff
path: root/00TEST
blob: 624d0a417190b419884ff6800ca385b9e2a39a0a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
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