summaryrefslogtreecommitdiff
path: root/00README
blob: 5d0c388fdc7639aa06de95a0c203988a4e3b7e65 (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
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526

			Making and Installing lsof 4

********************************************************************
| The latest release of lsof is always available via anonymous ftp |
| from lsof.itap.purdue.edu.  Look in pub/tools/unix/lsof.         |
********************************************************************

				Contents

	Pre-built Lsof Binaries
	Making Lsof
	    Other Configure Script Options
	    Environment Variables
	    Security
	    Run-time Warnings
	    Device Access Warnings
	    NFS Blocks
	    Caches -- Name and Device
	    Raw Sockets
	    Other Compile-time Definitions
	    The AFSConfig Script
	    The Inventory Script
	    The Customize Script
	    Cautions
	    Warranty
	    License
	    Bug Reports
	    The 00FAQ File
	    The lsof-l Mailing List
	    Field Output Example Scripts
	    Field Output C Library
	Testing Lsof
	Dialect Notes
	    AFS
	    AIX
	    Apple Darwin
	    Auspex LFS (no longer maintained)
	    BSDI BSD/OS
	    DEC OSF/1, Digital UNIX, Tru64 UNIX
	    FreeBSD
	    HP-UX
	    IPv6
	    Linux
	    NetBSD
	    NEXTSTEP and OPENSTEP
	    OpenBSD
	    Pyramid DC/OSx and Reliant UNIX (no longer available)
	    Caldera OpenUNIX
	    SCO OpenServer
	    SCO|Caldera UnixWare
	    Solaris 2.x, 7, 8, 9 and 10
	    Ultrix (no longer available)
	    Veritas VxFS and VxVM
	User-contributed Dialect Support
	Dialects No Longer Supported
	Installing Lsof
	    Setuid-root Lsof Dialects
	    Setgid Lsof Dialects
	Porting lsof 4 to a New UNIX Dialect
	Quick Start to Using lsof
	Cross-configuring Lsof
	Environment Variables Affecting the Configure Script


=======================
Pre-built Lsof Binaries
=======================

Avoid using pre-built lsof binaries if you can; build your own
instead.

I do not support lsof binaries built and packaged by third parties nor
lsof binaries built from anything but the latest lsof revision.  (See
the Bug Reports section for more information on the details of lsof
support.)

One important reasone for those support restrictions is that when lsof
is built its Configure script tunes lsof to the features available on
the building system, often embodied in supporting header files and
libraries.  If the building system doesn't have support for a
particular feature, lsof won't be built to support the feature on any
system.

The Veritas VxFS file system is a good example of a feature that
requires build-time support.

UNIX dialect version differences --  Solaris 8 versus 9, AIX 4.3.3
vesus 5.2, etc. -- can also render a pre-built lsof binary useless
on a different version.  So can kernel bit size.

There are so many potential pitfalls to using an lsof binary
improperly that I strongly recommend lsof be used only where it is
built.


===========
Making Lsof
===========

	$ cd <lsof source directory>
	$ ./Configure <your dialect's abbreviation>
	$ make

(Consult the 00FAQ and 00XCONFIG files of the lsof distribution
for information about using make command invocations and environment
variables to override lsof default Makefile strings.)

This lsof distribution can be used with many UNIX dialects.  However,
it must be configured specifically for each dialect.  Configuration
is done in three ways: 1) by changing definitions in the machine.h
header file of the UNIX dialect of interest; 2) by defining
environment variable values prior to calling Configure (see the
00XCONFIG file, the Environment Variabls and Environment Variables
Affecting the Configure Script sections of this file); and 3) by
running the Configure shell script found in the top level of the
distribution directory.

You may not need to change any machine.h definitions, but you might
want to look at them anyway.  Pay particular attention to the
definitions that are discussed in the Security section of this
file.  Please read that section.

The Configure script calls three other scripts in the lsof
distribution: AFSConfig; Inventory; and Customize.  The AFSConfig
script is called for selected dialects (AIX, HP-UX, NEXTSTEP, and
Solaris) to locate AFS header files and determine the AFS version.
See The AFSConfig Script section of this file for more information.

The Inventory script checks the completeness of the lsof distribution.
Configure calls Inventory after it has accepted the dialect
abbreviation, but before it configures the top-level directory for
the dialect.  See The Inventory Script section of this file for
more information.

Configure calls the Customize script after it has configured the
top-level lsof directory for the declared dialect.  Customize helps
you modify some of the important compile-time definitions of
machine.h.  See the The Customize Script section.

You should also think about where you will install lsof and its
man page, and whom you will let execute lsof.  Please read the
Installing Lsof section of this file for information on installation
considerations.

Once you have inspected the machine.h file for the dialect for
which you want to build lsof, and made any changes you need, run
the Configure script, supplying it with the abbreviation for the
dialect.  (See the following table.)  Configure selects the
appropriate options for the dialect and runs the Mksrc shell script
in the dialect sub-directory to construct the appropriate source
files in the top-level distribution directory.

Configure may also run the MkKernOpts script in the dialect
sub-directory to propagate kernel build options to the dialect
Makefile.  This is done for only a few dialects -- e.g., DC/OSx,
and Reliant UNIX.

Configure creates a dialect-specific Makefile.  You may want to
inspect or edit this Makefile to make it conform to local conventions.
If you want the Makefile to install lsof and its man page, you will
have to create an appropriate install rule.

Lsof may be configured using UNIX dialect abbreviations from the
following table.  Alternative abbreviations are indicated by a
separating `|'.   For example, for SCO OpenServer you can use either
the ``osr'' or the ``sco'' abbreviation:

	$ Configure osr
    or
	$ Configure sco

 Abbreviations		UNIX Dialect
 -------------		------------

    aix			IBM AIX 5.[23] and 5.3-ML1 using IBM's C Compiler
    aixgcc		IBM AIX 5.[12] and 5.3-ML1 using gcc
    darwin		Apple Darwin 7.x and 8.x for Power Macintosh systems
    decosf		DEC OSF/1, Digital UNIX, Tru64 UNIX 4.0 and 5.1
    digital_unix	Digital UNIX, DEC OSF/1, Tru64 UNIX 4.0 and 5.1
    du			Digital UNIX, DEC OSF/1, Tru64 UNIX 4.0 and 5.1
    freebsd		FreeBSD 4.x, 4.1x, 5.x and [67].x
    hpux		HP-UX 11.00, 11.11 and 11.23, using HP's C
			Compiler, both /dev/kmem-based and PSTAT-based
    hpuxgcc		HP-UX 11.00, 11.11 and 11.23, using gcc, both
			/dev/kmem-based and PSTAT-based
    linux		Linux 2.1.72 and above for x86-based systems
    netbsd		NetBSD 1.[456], 2.x and 3.x
    next		NEXTSTEP 3.[13]
    nextstep		NEXTSTEP 3.[13]
    ns			NEXTSTEP 3.[13]
    nxt			NEXTSTEP 3.[13]
    openbsd		OpenBSD 2.[89] and 3.[0-9]
    openstep		OPENSTEP 4.x
    os			OPENSTEP 4.x
    osr			SCO OpenServer Release 5.0.6, using the C compiler
			from the SCO developer's kit
    osrgcc		SCO OpenServer Release 5.0.6, using gcc
    osr6		SCO Openserver 6.0.0, using the SCO C compiler
    sco			SCO OpenServer Release 5.0.6, using the C compiler
			from the SCO developer's kit
    scogcc		SCO OpenServer Release 5.0.6, using gcc
    solaris		Solaris 2.x, 7, 8, 9 and 10 using gcc
    solariscc		Solaris 2.x, 7, 8, 9 and 10 using Sun's cc
    tru64		Tru64 UNIX, DEC OSF/1, Digital UNIX 4.0 and 5.1
    unixware		SCO|Caldera UnixWare 7.1.4
    uw			SCO|Caldera UnixWare 7.1.4

If you have an earlier version of a dialect not named in the above
list, lsof may still work on your system.  I have no way of testing
that myself.  Try configuring for the named dialect -- e.g., if
you're using Solaris 2.1, try configuring for Solaris 2.5.1.

After you have configured lsof for your UNIX dialect and have
selected options via the Customize script (See the The Customize
Script section.) , use the make command to build lsof -- e.g.,

	$ make


Other Configure Script Options
==============================

There are three other useful options to the Configure script besides
the dialect abbreviation:

	-clean          may be specified to remove all traces of
			a dialect configuration, including the
			Makefile, symbolic links, and library files.

	-h              may be specified to obtain a list of
	-help		Configure options, including dialect
			abbreviations.

	-n              may be specified to stop the Configure
			script from calling the Customize and
			Inventory scripts.

			Caution: -n also suppresses the AFSConfig
			step.



Environment Variables
=====================

Lsof configuration, building, and execution may be affected by
environment variable settings.  See the Definitions That Affect
Compilation section in the 00PORTING file, the General Environment
Variables section in the 00XCONFIG file, the Dialect-Specific
Environment Variables section in the 00XCONFIG file, and the
Environment Variables Affecting the Configure Script section of
this file for more information.

Note in the General Environment Variables section of the 00XCONFIG
file that there are five environment variables that can be used to
pre-define values in lsof's -v output: LSOF_BLDCMT, LSOF_HOST,
LSOF_LOGNAME, LSOF_SYSINFO, and LSOF_USER.


Security
========

If the symbol HASSECURITY is defined, a security mode is enabled,
and lsof will allow only the root user to list all open files.
Non-root users may list only open files whose processes have the
same user ID as the real user ID of the lsof process (the one that
its user logged on with).

However, if HASNOSOCKSECURITY is also defined, anyone may list
anyone else's open socket files, provided their listing is enabled
with the "-i" option.

Lsof is distributed with the security mode disabled -- HASSECURITY
is not defined.  (When HASSECURITY is not defined, the definition
of HASNOSOCKSECURITY has no meaning.)  You can enable the security
mode by defining HASSECURITY in the Makefile or in the machine.h
header file for the specific dialect you're using -- e.g.
dialects/aix/machine.h.

The Customize script, run by Configure when it has finished its
work, gives you the opportunity to define HASSECURITY and
HASNOSOCKSECURITY.  (See the The Customize Script section.)

The lsof -h output indicates the state HASSECURITY and HASNOSOCKSECURITY
had when lsof was built, reporting:

    "Only root can list all files;"
	if HASSECURITY was defined and HASNOSOCKSECURITY wasn't
	defined;

    "Only root can list all files, but anyone can list socket files."
	if HASSECURITY and HASNOSOCKSECURITY were both defined;

    "Anyone can list all files;"
	if HASSECURITY wasn't defined.  (The definition of
	HASNOSOCKSECURITY doesn't matter when HASSECURITY isn't
	defined.)

You should carefully consider the implications of using the default
security mode.  When lsof is compiled in the absence of the
HASSECURITY definition, anyone who can execute lsof may be able to
see the presence of all open files.  This may allow the lsof user
to observe open files -- e.g., log files used to track intrusions
-- whose presence you would rather not disclose.

As distributed, lsof writes a user-readable and user-writable device
cache file in the home directory of the real user ID executing
lsof.  There are other options for constructing the device cache file
path, and they each have security implications.

The 00DCACHE file in the lsof distribution discusses device cache
file path construction in great detail.   It tells how to disable
the various device cache file path options, or how to disable the
entire device cache file feature by removing the HASDCACHE definition
from the dialect's machine.h file.  There is also information on
the device cache file feature in the 00FAQ file.  (The 00DCACHE
and 00FAQ files are part of the lsof distribution package.)

The Customize script, run by Configure after it has finished its
work, gives you the opportunity to change the compile-time options
related to the device cache file.  (See The Customize Script
section.)

Since lsof may need setgid or setuid-root permission (See the Setgid
Lsof Dialects and Setuid-root Lsof Dialects sections.), its security
should always be viewed with skepticism.  Lest the setgid and
setuid-root permissions allow lsof to read kernel name list or
memory files, declared with the -k and -m options, that the lsof
user can't normally access, lsof uses access(2) to establish its
real user's authority to read such files when it can't surrender
its power before opening them.  This change was added at the
suggestion of Tim Ramsey.

Lsof surrenders setgid permission on most dialects when it has
gained access to the kernel's memory devices.  There are exceptions
to this rule, and some lsof implementations need to run setuid-root.
(The Setgid Lsof Dialects and Setuid-root Lsof Dialects sections
contains a list of lsof implementations and the permissions
recommended in the distribution's Makefiles.)

The surrendering of setgid permission is controlled by the WILLDROPGID
definition in the dialect machine.h header files.

In the end you must judge for yourself and your installation the
risks that lsof presents and restrict access to it according to
your circumstances and judgement.


Run-time Warnings
=================

Lsof can issue warning messages when it runs -- e.g., about the
state of the device cache file, about an inability to access an
NFS file system, etc.  Issuance of warnings are enabled by default
in the lsof distribution.

Issuance or warnings may be disabled by default by defining
WARNINGSTATE in the dialect's machine.h.  The Customize script may
also be used to change the default warning message issuance state.
(See The Customize Script section.)

The ``-w'' option description of the ``-h'' option (help) output
will indicate the default warning issuance state.  Whatever the
state may be, it can be reversed with ``-w''.


Device Access Warnings
======================

When lsof encounters a /dev (or /devices) directory, one of its
sub-directories, or one of their files that it cannot access with
opendir(3) or stat(2), it issues a warning message and continues.
Lsof will be more likely to issue such a warning when it has been
installed with setgid(<some group name>) permission; it won't have
trouble if it has been installed with setuid(root) permission or
is being run under the root login.

The lsof caller can inhibit or enable the warning with the -w
option, depending on the issuance state of run-time warnings.  (See
the Run-time Warnings section.)

The warning messages do not appear when lsof obtains device
information from a device cache file that it has built and believes
to be current or when warning message issuance is disabled by
default.  (See the "Caches -- Name and Device" section for more
information on the device cache file.)

The lsof builder can inhibit the warning by disabling the definition
of WARNDEVACCESS in the dialect's machine.h or disable all warnings
by defining WARNINGSTATE.  WARNDEVACCESS is defined by default for
most dialects.  However, some dialects have some device directory
elements that are private -- e.g., HP-UX -- and it is more convenient
for the lsof user if warning messages about them are inhibited.

Output from lsof's -h option indicates the status of WARNDEVACCESS.
If it was defined when lsof was compiled, this message will appear:

    /dev warnings = enabled

If WARNDEVACCESS was not defined when lsof was compiled, this
message will appear instead:

    /dev warnings = disabled

The Customize script, run by Configure after it has finished its
work, gives you the opportunity to change the WARNDEVACCESS
definition.  (See The Customize Script section.)


NFS Blocks
==========

Lsof is susceptible to NFS blocks when it tries to lstat() mounted
file systems and when it does further processing -- lstat() and
readlink() -- on its optional file and file system arguments.

Lsof tries to avoid being stopped completely by NFS blocks by doing
the lstat() and readlink() functions in a child process, which
returns the function response via a pipe.  The lsof parent limits
the wait for data to arrive in the pipe with a SIGALRM, and, if
the alarm trips, terminates the child process with a SIGINT and a
SIGKILL.

This is as reliable and portable a method for breaking NFS deadlocks
as I have found, although it still fails under some combinations
of NFS version, UNIX dialect, and NFS file system mount options.
It generally succeeds when the "intr" or "soft" mount options are
used; it generally fails when the "hard" mount option is used.

When lsof cannot kill the child process, a second timeout causes
it to stop waiting for the killed child to complete.  While the
second timeout allows lsof to complete, it may leave behind a hung
child process.  Unless warnings are inhibited by default or with
the -w option, lsof reports the possible hung child.

NFS block handling was updated with suggestions made by Andreas
Stolcke.  Andreas suggested using the alternate device numbers that
appear in the mount tables of some dialects when it is not possible
to stat(2) the mount points.

The -b option was added to direct lsof to avoid the stat(2) and
readlink(2) calls that might block on NFS mount points and always
use the alternate device numbers.  If warning message issuance is
enabled and you don't want warning messages about what lsof is
doing, use the -w option, too.

The -O option directs lsof to avoid doing the potentially blocking
operations in child processes.  Instead, when -O is specified, lsof
does them directly.  While this consumes far less system overhead,
it can cause lsof to hang, so I advise you to use -O sparingly.


Caches -- Name and Device
==========================

Robert Ehrlich suggested that lsof obtain path name components for
open files from the kernel's name cache.  Where possible, lsof
dialect implementations do that.  The -C option inhibits kernel
name cache examination.

Since AFS apparently does not use the kernel's name cache, where
lsof supports AFS it is unable to identify AFS files with path name
components.

Robert also suggested that lsof cache the information it obtains
via stat(2) for nodes in /dev (or /devices) to reduce subsequent
running time.  Lsof does that, too.

In the default distribution the device cache file is stored in
.lsof_hostname, mode 0600, in the home directory of the login of
the user ID that executes lsof.  The suffix, hostname, is the first
component of the host's name returned by gethostname(2).  If lsof
is executed by a user ID whose home directory is NFS-mounted from
several hosts, the user ID's home directory may collect several
device cache files, one for each host from which it was executed.

Lsof senses accidental or malicious damage to the device cache file
with extensive integrity checks, including the use of a 16 bit CRC.
It also tries to sense changes in /dev (or /devices) that indicate
the device cache file is out of date.

There are other options for forming the device cache file path.
Methods the lsof builder can use to control and employ them are
documented in the separate 00DCACHE file of the lsof distribution.


Raw Sockets
===========

On many UNIX systems raw sockets use a separate network control
block structure.  Display of files for applications using raw
sockets -- ping, using ICMP, for example -- need special support
for displaying their information.  This support is so dialect-specific
and information to provide it so difficult to find that not all
dialect revisions of lsof handle raw sockets completely.


Other Compile-time Definitions
==============================

The machine.h and dlsof.h header files for each dialect contains
definitions that affect the compilation of lsof.  Check the
Definitions That Affect Compilation section of the 00PORTING file
of the lsof distribution for their descriptions.  (Also see The
Customize Script section.)


The AFSConfig Script
====================

Lsof supports AFS on some combinations of UNIX dialect and AFS
version.  See the AFS section of this document for a list of
supported combinations.

When configuring for dialects where AFS is supported, the Configure
script calls the AFSConfig script to determine the location of AFS
header files and the AFS version.  Configure will not call AFSConfig,
even for the selected dialects, unless the file /usr/vice/etc/ThisCell
exists.

The AFS header file location is recorded in the AFSHeaders file;
version, AFSVersion.  Once these values have been recorded, Configure
can be told to skip the calling of AFSConfig by specifying its
(Configure's) -n option.


The Inventory Script
====================

The lsof distribution contains a script, called Inventory, that
checks the distribution for completeness.  It uses the file 00MANIFEST
in the distribution as a reference point.

After the Configure script has accepted the dialect abbreviation,
it normally calls the Inventory script to make sure the distribution
is complete.

After Inventory has run, it creates the file ".ck00MAN" in the
top-level directory to record for itself the fact that the inventory
has been check.  Should Inventory be called again, it senses this
file and asks the caller if another check is in order, or if the
check should be skipped.

The -n option may be supplied to Configure to make it bypass the
calling of the Inventory script.  (The option also causes Configure
to avoid calling the Customize script.)

The lsof power user may want to define (touch) the file ".neverInv".
Configure avoids calling the Inventory script when ".neverInv"
exists.


The Customize Script
====================

Normally when the Configure script has finished its work, it calls
another shell script in the lsof distribution called Customize.
(You can tell Configure to bypass Customize with its -n option.)

Customize leads you through the specification of these important
compile-time definitions for the dialect's machine.h header file:

	HASDCACHE		device cache file control
	    HASENVDC		device cache file environment
				variable name
	    HASPERSDC		personal device cache file path
				format
	    HASPERSDCPATH	name of environment variable that
				provides an additional component
				of the personal device cache file
				path
	    HASSYSDC		system-wide device cache file path
	HASKERNIDCK		the build-time to run-time kernel
				identity check
	HASSECURITY		the security option
	HASNOSOCKSECURITY	the open socket listing option whe
				HASSECURITY is defined
	WARNDEVACCESS		/dev (or /devices) warning message
				control
	WARNINGSTATE		warning message issuance state

The Customize script accompanies its prompting for entry of new
values for these definitions with brief descriptions of each of
them.  More information on these definitions may be found in this
file or in the 00DCACHE and 00FAQ files of the lsof distribution.

You don't need to run Customize after Configure.  You can run it
later or you can edit machine.h directly.

The -n option may be supplied to Configure to make it bypass the
calling of the Customize script.  (The option also causes Configure
to avoid calling the Inventory script.)

The lsof power user may want to define (touch) the file ".neverCust".
Configure avoids calling the Customize script when ".neverCust"
exists.

Customize CAUTION: the Customize script works best when it is
applied to a newly configured lsof source base -- i.e., the machine.h
header file has not been previously modified by the Customize
script.  If you have previously configured lsof, and want to rerun
the Customize script, I recommend you clean out the previous
configuration and create a new one:

	$ Configure -clean
	$ Configure <dialect_abbreviation>
	...
	Customize in response to the Customize script prompts.


Cautions
========

Lsof is a tool that is closely tied to the UNIX operating system
version.  It uses header files that describe kernel structures and
reads kernel structures that typically change from OS version to
OS version, and even within a version as vendor patches are applied.

DON'T TRY TO USE AN LSOF BINARY, COMPILED FOR ONE UNIX OS VERSION,
ON ANOTHER.  VENDOR PATCHES INFLUENCE THE VERSION IDENTITY.

On some UNIX dialects lsof versions may be even more restricted by
architecture type.

The bottom line is use lsof where you built it.  If you intend to
use a common lsof binary on multiple systems, make sure all systems
run exactly the same OS version and have exactly the same patches.


Warranty
========

Lsof is provided as-is without any warranty of any kind, either
expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose.
The entire risk as to the quality and performance of lsof is with
you.  Should lsof prove defective, you assume the cost of all
necessary servicing, repair, or correction.


License
=======

Lsof has no license.  Its use and distribution are subject to these
terms and conditions, found in each lsof source file.  (The copyright
year in or format of the notice may vary slightly.)

    /*
     * Copyright 2002 Purdue Research Foundation, West Lafayette,
     * Indiana 47907.  All rights reserved.
     *
     * Written by Victor A. Abell
     *
     * This software is not subject to any license of the American
     * Telephone and Telegraph Company or the Regents of the
     * University of California.
     *
     * Permission is granted to anyone to use this software for
     * any purpose on any computer system, and to alter it and
     * redistribute it freely, subject to the following
     * restrictions:
     *
     * 1. Neither the authors nor Purdue University are responsible
     *    for any consequences of the use of this software.
     *
     * 2. The origin of this software must not be misrepresented,
     *    either by explicit claim or by omission.  Credit to the
     *    authors and Purdue University must appear in documentation
     *    and sources.
     *
     * 3. Altered versions must be plainly marked as such, and must
     *    not be misrepresented as being the original software.
     *
     * 4. This notice may not be removed or altered.
     */


Bug Reports
===========

Now that the obligatory disclaimer is out of the way, let me hasten to
add that I accept lsof bug reports and try hard to respond to them.  I
will also consider and discuss requests for new features, ports to new
dialects, or ports to new OS versions.

PLEASE DON'T SEND BUG REPORTS ABOUT LSOF TO THE UNIX DIALECT OR DIALECT
OPTION VENDOR.

At worst such bug reports will confuse the vendor; at best, the vendor
will forward the bug report to me.

PLEASE DON'T SEND BUG REPORTS ABOUT LSOF BINARIES BUILT OR DISTRIBUTED
BY SOMEONE ELSE, BECAUSE I CAN'T SUPPORT THEM.

Before you send me a bug report, please do these things:

    *  Make sure you try the latest lsof revision.

       +  Download the latest revision from:

	    ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof

       +  Verify the signatures of what you have downloaded;

       +  While connected to lsof.itap.purdue.edu, check for patches:

	    ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/patches

       +  If patches exist, install them in the latest revision
	  you just downloaded.  Then build the latest revision and
	  see if it fixes your bug.

    *  If you're having trouble compiling lsof with gcc, try the
       UNIX dialect vendor's compiler.  I don't have access to gcc on
       all test systems, so my support for it is hit-and-miss, and so
       is my ability to respond to gcc compilation problem reports.

    *  Check the lsof frequently asked questions file, 00FAQ,
       to see if there's a question and answer relevant to your
       problem.

    *  Make sure you're running the lsof you think you are by
       checking the path to it with which(1).  When in doubt, use an
       absolute path to lsof.  Make sure that lsof binary has
       sufficient permissions to do what you ask, including internal
       permissions given it (e.g., restrictions on what files lsof may
       report for whom) during its build.

When you send a bug report, make sure you include output from your
running of lsof's Configure script.  If you were able to compile a
running lsof, please also include:

    *  Output from which(1) that shows the absolute path to the
       lsof binary in question;

    *  Output from running lsof with its -h and -v options at
       lsof's absolute path;

    *  Output from "ls -l" directed to lsof's absolute path.

If you weren't able to compile a running lsof, please send me: the
compiler error output; identification of the lsof revision you're using
(contents of the lsof version.c file); identification of your system
(full uname output or output from whatever other tool identifies the
system); and compiler identification (e.g., gcc -v output).

Either set of output will help me understand how lsof was configured
and what UNIX dialect and lsof revision is involved.

Please send all bug reports, requests, etc. to me via e-mail at
<abe@purdue.edu>.  Make sure "lsof" appears in the "Subject:" line so
my e-mail filter won't classify your letter as Spam.


The 00FAQ File
==============

The lsof distribution contains an extensive frequently asked
questions file on lsof features and problems.  I recommend you
consult it before sending me e-mail.  Use your favorite editor or
pager to search 00FAQ -- e.g., supplying as a search argument some
fixed text from an lsof error message.


The lsof-l Mailing List
=======================

Information about lsof, including notices about the availability
of new revisions, may be found in mailings of the lsof-l listserv.
For more information about it, including instructions on how to
subscribe, read the 00LSOF-L file of the lsof distribution.


Field Output Example Scripts
============================

Example AWK and Perl 4 or 5 scripts for post-processing lsof field
output are locate in the scripts sub-directory of the lsof distribution.
The scripts sub-directory contains a 00README file with information
about the scripts.


Field Output C Library
======================

The lsof test suite (See "Testing Lsof."), checks basic lsof
operations using field output.  The test suite has its own library
of C functions for common test program operations, including
processing of field output.  The library or selections of its
functions could be adapted for use by C programs that want to
process lsof field output.  See the library in the file LTlib.c
in the tests/ sub-directory


Testing Lsof
============

Lsof has an automated test suite in the tests/ sub-directory that
can be used to test some basic lsof features -- once lsof has been
configured and made.  Tests are arranged in three groups: basic
tests that should run on all dialects; standard tests that should
run on all dialects; and optional tests that may not run on all
dialects or may need special resources to run.  See 00TEST for more
information.)

CAUTION!!!  Before you attempt to use the test suite make sure that
the lsof you want to test can access the necessary kernel resources
-- e.g., /dev/mem, /dev/kmem, /proc, etc.  Usually you want to test
the lsof you just built, so this is an important check.  (See
00TEST.)

To run the basic and standard tests, using the lsof in the parent
directory of tests/, do this:

	$ cd tests
	$ make test
    or	$ make std
    or	$ make standard

The basic and standard tests may be run as silently as possible,
using the lsof in the parent directory of tests/, with:

	$ cd tests
	$ make auto

This is the "automatic" test mode, designed for use by scripts that
build lsof.  The caller is expected to test the make exit code to
determine if the tests succeeded.  The caller should divert standard
output and standard error to /dev/null to suppress make's error
exit message.

The optional tests may be run, using the lsof in the parent directory
of tests/, with:

	$ cd tests
	$ make opt
    or	$ make optional

It's possible to excute individual tests, too.  See the 00TEST file
of this distribution for more informaiton on the tests, what they
do, and how to run and possibly customize each test.

It's possible to run the tests, using an lsof other than the one
in the parent directory of /tests, too.  See 00TEST for information
about using the LT_LSOF_PATH environment variable to do that.


=============
Dialect Notes
=============


AFS
===

Lsof recognizes AFS files on the following combinations of UNIX
dialect and AFS versions:

	AIX 4.1.4 (AFS 3.4a)
	Linux 1.2.13 (AFS 3.3)
	NEXTSTEP 3.2 (AFS 3.3) (untested on recent lsof revisions)
	Solaris 2.6 (AFS 3.4a)
	Ultrix 4.2 RISC (AFS 3.2b) (no longer available)

Lsof has not been tested under other combinations -- e.g. HP-UX
10.10 and AFS 3.4a -- and probably won't even compile there.  Often
when a UNIX dialect version or AFS version changes, the new header
files come into conflict, causing compiler objections.


AIX
===

Specify the aix Configure abbreviation for AIX 4.1.[45], 4.2[.1],
4.3[.123], 5L, and 5.[123].

Specify aixgcc on AIX above 4.1 to use the gcc compiler.  (Gcc can't be
used to compile lsof on AIX 4.1 and below because of kernel structure
alignment differences between it and xlc.)  Gcc results sometimes
depend on the version of the gcc compiler that is used.

Compilation of lsof with gcc on AIX 4.3[.123], 5L, and 5.[123] has been
sparsely tested with varying degrees of success: it has been reported
to succeed on AIX 4.3.3 and 32 bit Power AIX 5.1; to fail on ia64 AIX
5.1 and 64 bit Power AIX 5.1; and to succeed on 32 and 64 bit Power AIX
5.2.  Lsof compilation with gcc hasn't been tested on AIX 5.3.

At revision 4.61 and above lsof is configured and built to match the
bit size of the kernel of Power architecture AIX 5.1 systems.  Lsof
binaries built for 32 and 64 bit kernels are not interchangeable.  See
00FAQ for more information.

The Configure script uses /usr/bin/oslevel to determine the AIX version
for AIX less than 5 and ``uname -rv'' for AIX 5 and higher.  If
/usr/bin/oslevel isn't executable on AIX less than 5, the Configure
script issues a warning message and uses ``uname -rv'' to determine the
AIX version.

When Configure must use ``uname -rv'' on AIX less than 5 to determine
the AIX version, the result will lack a correct third component --
e.g., the `4' of ``4.1.4''.  If your AIX less than 5 system lacks lacks
an executable oslevel, I suggest you edit the Configure-produced
Makefile and complete the _AIXV definition in the CFGF string.

By default lsof avoids using the kernel's readx() function, causing
it to be unable to report information on some text and library file
references.  The ``-X'' option allows the lsof user to ask for the
information readx() supplies.

Lsof avoids readx() to avoid the possibility of triggering a kernel
problem, known as the Stale Segment ID kernel bug.  Kevin Ruderman
reported this bug to me.  The bug shows up when the kernel's
dir_search() function hangs, hanging the application process that
called it so completely that the application process can neither
be killed nor stopped.  The hang is the consequence of another
process (perhaps lsof) making legitimate use of the kernel's readx()
function to access the kernel memory that dir_search() is examining.
IBM has indicated they have no plans to fix the bug.

A fuller discussion of this bug may be found in the 00FAQ file of
the lsof distribution.  There you will find a description of the
Stale Segment ID bug, the APAR on it, and a discussion of the
sequence of events that exposes it.

I added the ``-X'' function so you can tell lsof to use readx(),
but if you use ``-X'', you should be alert to its possibly serious
side effects.  Although readx() is normally disabled, its state is
controlled with the HASXOPT, HASXOPT_ROOT, and HASXOPT_VALUE
definitions in dialects/aix/machine.h, and you can change its
default state by changing those definitions.  You can also change
HASXOPT_ROOT via the Customize script.

You can also compile lsof with readx() use permanently enabled or
disabled -- see the comments about the definitions in the
dialects/aix/machine.h header file.  You may want to permanently
disable lsof's use of readx() if you plan to make lsof publicly
executable.  You can also restrict -X to processes whose real UID
is root by defining HASXOPT_ROOT.

I have never seen lsof cause the Stale Segment ID bug to occur and
haven't had a report that it has, but I believe there is a possibility
it could.

AFS support for AIX was added with help help from Bob Cook and Jan
Tax who provided test systems.

Henry Grebler and David J. Wilson helped with lsof for AIX 4.2.

Bill Pemberton provided an AIX 4.3 test system.  Andrew Kephart
and Tom Weaver provided AIX 4.3 technical assistance.   Niklas
Edmundsson did 4.3.1 testing.  Doug Crabill provided an AIX 4.3.2
test system.  Jeff W. Stewart provided an AIX 4.3.3 test system.

The SMT file type for AIX 4.1.[45], 4.2[.1], and 4.3[.12] is my
fabrication.  See the 00FAQ file more information on it.

Loc Le and Nasser Momtaheni of IBM provided test systems for AIX 5L and
5.1.  Lsof for AIX 5L and 5.1 needs setuid-root permission to process
the -X option on systems whose architecture type is ia64.

Dale Talcott of Purdue provided AIX 5.1 and 5.2 test systems.  Dale and
John Jackson of Purdue provided an AIX 5.3 test system.


Apple Darwin
============

The Apple Darwin port was provided by Allan Nathanson for version
1.2.  Allan also arranged for access to a test system for maintenance
and regression testing.  Dale Talcott provided a test system, too.

Allan supplied patches for updates to 1.4, 5.x, 6.x, 7.x and 8.x.


BSDI BSD/OS
===========

As of lsof revision 4.77 support for BSDI BSD/OS has been
discontinued.  Lsof revision 4.76 with BSDI BSD/OS support may be found
on lsof.itap.purdue.edu in pub/tools/unix/lsof/src.


DEC OSF/1, Digital UNIX, Tru64 UNIX
===================================

Robert Benites, Dean Brock, Angel Li, Dwight McKay, Berkley Shands,
Ron Young and Steve Wilson have kindly provided test systems.
Jeffrey Mogul has provided technical assistance.  Dave Morrison
and Lawrence MacIntyre did Digital UNIX V3.2 testing.

Lsof supports the ADVFS/MSFS layered file system product.  Lsof
can locate all the open files of an ADVFS/MSFS file system when
its path is specified, provided the file system is listed in
/etc/fstab with an ``advfs'' type.  (This /etc/fstab caveat applies
only to Digital UNIX 2.0.)  At Digital UNIX 4.0 and Tru64 UNIX,
using code provided by David Brock, lsof 4.20 and above can locate
ADVFS file paths.

Testing of lsof on DEC OSF/1 and Digital UNIX 4.0 ended with lsof
revision 4.74.  Hence, the lsof documentation has dropped the claim
that it works there.  For a distribution of lsof 4.74 that was tested
on DEC OSF/1 and Digital UNIX 4.0, check pub/tools/unix/lsof/OLD/src
on the lsof ftp home, lsof.itap.purdue.edu.

Lsof revisions past 4.74 have only been tested on Tru64 UNIX 5.1.


FreeBSD
=======

Bill Bormann of Purdue University provided access to several FreeBSD
test systems.  Ade Barkah, John Clear, Ralph Forsythe, Michael
Haro, Kurt Jaeger, and William McVey have also provided FreeBSD
test systems.

The FreeBSD distribution header files are augmented by header files
in the dialects/freebsd/include directory.

David O'Brien maintains the lsof FreeBSD port package.


HP-UX
=====

Lsof has two HP-UX bases: /dev/kmem for HP-UX 11.0 and earlier;
and PSTAT for HP-UX 11.11 and later.  The lsof Configure script
will pick the appropriate base.

To use the CCITT x.25 socket support for HP-UX, you must have the
x.25 header files in /etc/conf/x25

Pasi Kaara helped with the HP-UX port, especially with its CCITT
x.25 socket support.

Richard Allen provided HP-UX 10.x and 11.x test systems, as did
Mark Bixby, and Elias Halldor Agustsson.   Marc Winkler helped test
the 10.20 port.  Richard J. Rauenzahn provided a 64 bit HP-UX 11
test system and an HP-UX 11.11 development system.

AFS support for HP-UX was added thanks to help from Chaskiel Moses
Grundman, who provided a test system.

The /dev/kmem-based HP-UX 11.00 support is extremely fragile.  It
depends on privately developed kernel structure definitions.  (See
.../dialects/hpux/hpux11 for the header files making the definitions.)
Those header files and their definitions will not be updated by
HP-UX 11.00 patches, making it likely that any patch changing a
kernel structure critical to lsof will break lsof in some way.

It's possible to build a 64 bit lsof for 64 bit HP-UX 11.00 with
gcc, but you must have a gcc compiler capable of producing 64 bit
executables.  See the 00FAQ file for more information.

The PSTAT-based lsof for HP-UX 11.11 and later is much more solid.
I am indebted to the vision of HP for providing an lsof kernel API
through the PSTAT implementation.  Specifically I appreciate the
help of HP staff members Carl Davidson, Louis Huemiller, Rich
Rauenzahn, and Sailu Yallapragada that made PSTAT-based HP-UX lsof
possible.


IPv6
====

Lsof has IPv6 support that has been tested for these UNIX dialects:
AIX 4.3.x; Apple Darwin 5.[12] and 6.0; the INRIA and KAME FreeBSD IPv6
implementations; PSTAT-based HP-UX; /proc-based Linux; the INRIA and
KAME NetBSD implementations; and Solaris 8 and 9.  Lsof has IPv6
support that hasn't been tested for: OpenBSD (KAME); OpenUNIX 8; Tru64
Unix 5.[01]; and UnixWare 7.1.[34].

Please let me know if your UNIX dialect has IPv6 support and I'll
see if it can be supported by lsof.


Linux
=====

Tim Korb, Steve Logue, Joseph J. Nuspl Jr., and Jonathan Sergent
have provided Linux test systems.

Michael Shields helped add and test automatic handling of ELF/COFF
form names in /System.map, Marty Leisner and Keith Parks have helped
test many lsof revisions.  Marty has provided valuable suggestions,
Linux hints, and code, too.

The 00FAQ file gives some Linux tips, including information on
coping with system map file problems.

To determine the state of the Linux 2.1.x C library lseek() function,
the lsof Configure script runs a test program that must have
permission to read /dev/kmem.  The test determines if the lseek()
function properly handles kernel offsets, which appear to be negative
because their high order bit is set.  If the lseek() test reveals
a faulty lseek(), Configure activates the use of a private lseek()
function for kernel offset positioning.  See the Linux problems
section of the 00FAQ file of the lsof distribution for more
information.


NetBSD
======

Greg Earle  and Paul Kranenburg have assisted with the NetBSD ports.
Paul has provided test systems.  Ray Phillips provided a NetBSA
Alpha test system.  Andrew Brown also provided a test system.

The NetBSD dialect version of lsof is compiled using the dialect
sources it shares with OpenBSD in the n+obsd dialect sub-directory.


NEXTSTEP and OPENSTEP
=====================

Virtual memory header files that allow lsof to display text references
were derived from the contents of /usr/include/vm of NEXTSTEP 2.0.
NeXT did not ship the virtual memory header files with other NEXTSTEP
or OPENSTEP versions.

You may use the RC_FLAGS environment variable to declare compiler
options outside the Makefile.  A common use of this variable is to
define the architecture types to be included in a "fat" executable.
See the comments in dialects/next/Makefile for an example.


OpenBSD
=======

David Mazieres has provided OpenBSD test systems.  The OpenBSD
dialect version of lsof is compiled using the dialect sources it
shares with NetBSD in the n+obsd dialect sub-directory.

Kenneth Stailey has provided OpenBSD testing and advice.

John Dzubera (Zube) reports, "lsof 4.33 compiles and runs on OpenBSD
2.3 for the pmax architecture (decstation 3100)."

I have not tested lsof on OpenBSD 3.8, but David Mazieres reports
revision 4.76 worked on OpenBSD 3.8.


Pyramid DC/OSx and Reliant UNIX
===============================

As of lsof revision 4.52 support for all Pyramid dialects has been
discontinued.  Lsof revision 4.51 with Pyramid support may be
obtained upon request.  Send the request to abe@purdue.edu.

These two UNIX dialects are very similar and share dialect-specific
source files from the pyramid sub-directory.

The Reliant Unix Pyramid C compiler issues warning messages that
I haven't found a convenient way to suppress.  You can ignore
warning messages about casts and conversions that lose bits.  The
message "warning: undefining __STDC__" is intentionally caused by
the lsof MkKernOpts configuration script to suppress warning messages
about cast and conversion problems in standard system header files,
such as <stdio.h> and <string.h>.

Bruce Beare and Kevin Smith provided test systems.


Caldera OpenUNIX
================

Larry Rosenman provided an OpenUNIX 8 test system.  Matthew Thurmaier
provided technical assistance, along with these people from Caldera:
Jack Craig, Robert Lipe, and Bela Lubkin.

Robert Lipe supplied changes to lsof for OpenUNIX 8.0.1.  Those
changes were also incorporated in UnixWare 7.1.3 when it became
the release name for OpenUNIX 8.0.1.

Support for lsof on OpenUNIX ended at lsof revision 4.74.  The last
lsof revision, 4.74, tested on OpenUNIX, may be found at the lsof
"home" ftp site, lsof.itap.purdue.edu, in pub/tools/unix/lsof/OLD/src.


SCO OpenServer
==============

Dion Johnson, Bela Lubkin, and Nathan Peterson of SCO gave me copies
of SCO OpenServer and the SCO OpenServer Development System 3.0
and provided technical advice for the lsof port.

Hugh Dickins, Bela Lubkin, Craig B. Olofson, and Nathan Peterson
provided version 5.0 and gave technical advice for porting lsof to
it.  Bela provided the 5.0.4 changes.  D. Chris Daniels provided
a 5.0.4 test system, Lee Penn provided one for 5.0.5, and John
Dubois for 5.0.6.

The <netdb.h> header file was accidentally omitted from some SCO
OpenServer Development System releases.  The Configure script will
sense its absence and substitute an equivalent from the BSD
distribution.  The BSD <netdb.h> and the <sys/cdefs.h> header file
it includes are located in the dialects/os/include sub-directory
tree.

To compile lsof from its distribution sources you must have the
TCP/IP and NSF headers in /usr/include.  While those are optional
OpenServer packages, I have access to no system that doesn't have
them, so I'm unable to build lsof for such a configuration.  However,
it should be possible to modify the lsof Configure script and
sources so lsof would compile and work without those optional
packages.

If you have an OpenServer system configured without the TCP/IP and
NFS packages, and want to tackle the job of building lsof for it,
contact me via e-mail at <abe@purdue.edu>.  I'll identify the
Configure script, header file, and source file changes you will
need to make.  (Caution: this is not a simple task, or I would have
already done it.)

The optional osrgcc and scogcc Configure abbreviations construct
Makefiles for compiling lsof with gcc.

The UnixWare 7.1.4 sources are used for OpenServer Release 6.0.0.
Hence there is a separate Configure abbreviation for it, "osr6".
Richard of SCO provided a test system and technical assistance.


SCO|Caldera UnixWare
============

D. Chris Daniels, John Hughes, Ken Laing, Andrew Merril, Lee Penn, and
Matthew Thurmaier provided test systems.  Bela Lubkin provided
technical assistance.  Larry Rosenman provided 7.1.[34] test systems.


Solaris 2.x, 7, 8, 9 and 10
===========================

SEE THE CAUTIONS SECTION OF THIS DOCUMENT.

The latest Solaris revision of lsof 4 might work under Solaris
2.[1-4] and 2.5[.1] and 7 but hasn't been tested there.  I have no
test systems for those Solaris versions.

Lsof will compile with gcc and the Sun C compiler under Solaris.
If you want to use the Sun compiler, use the solariscc Configure
abbreviation.  If you use a gcc version less than 2.8 on Solaris,
make sure the gcc-specific includes have been updated for your
version of Solaris -- i.e., run the gcc fixincludes script.

Solaris 7, 8, 9 and 10 support for 64 bit kernels depends on a Sun
WorkShop or Forte C compiler version that supports the "-xarch=v9"
flag -- usually 5.0 or greater.  Gcc versions 2.95 and above *may*
be configured and built for 64 bit support, but it takes some extra
work, the resulting compiler may be fragile, and the gcc developers
discourage it.  I've built 64 bit capable gcc compilers for Solaris
7, 8 and 9 from gcc versions 2.95 through 3.0.1 and produced working
lsof executables with them.  More information on 64 bit gcc for
Solaris may be found in the 00FAQ file.

Solaris 10 ZFS support is questionable, because Sun does not distribute
the ZFS kernel structure definition header files.  The lsof Configure
script and source code use some risky work-arounds.  ZFS file system
support was made possible with help from Horst Scheuermann.

Dave Curry and Steve Kirsch provided resources for Solaris 2.x
ports.  Casper Dik and Gerry Singleton consulted and provided
valuable assistance.

Henry Katz, Joseph Kowalski, Charles Stephens, Mike Sullivan, and
Mike Tracy provided technical assistance.

AFS support was added to Solaris lsof with help from Curt Freeland,
Heidi Hornstein, Michael L. Lewis, Terry McCoy, Phillip Moore, and
Sushila R. Subramanian.

Casper Dik provided valuable assistance for the Solaris 8 support.

Sun has graciously provided me access to BETA versions of Solaris
2.5, 2.6, 7, 8, and 9.

John Dzubera provided Solaris 7 and 8 test systems.

Mike Miscevic provided  Solaris 10 test systems.


Ultrix
======

As of lsof revision 4.52 support for Ultrix is no longer available,
because I no longer have an Ultrix test system.

Terry Friedrichsen, Dwight McKay, and Jeffrey Mogul helped me with
this port.

DECnet support was added to Ultrix lsof with the help of John
Beacom, who kindly provided a test system.  The Configure script
decides that DECnet support is available if /usr/lib/libdnet.a and
/usr/include/netdnet/dn.h exist and are readable.


Veritas VxFS and VxVM
=====================

Lsof supports some versions of Veritas VxFS and VxVM on some UNIX
dialects.  Consult the lsof Configure script for the specific
dialect, and consult the lsof dialect-specific source files for
the UNIX dialect of interest.  Veritas support will usually be
found in a source file named dnode[1-9].c.

Since Veritas rarely has a version number that can be extracted
with shell commands, lsof doesn't use it.  Instead, when lsof
supports Veritas, the Configure script will form compile-time
definitions starting with HASVXFS.   Check the lsof 00PORTING
documentation file for more information.

Lsof Veritas support requires that the supporting Veritas header
files be installed -- e.g., in /usr/include/sys/fs.  (The location
will depend in the dialect's header file conventions.)

Some information on lsof support for Veritas extensions may be
found in the lsof 00DIST file.  (The ChangeLog file points to
00DIST.)

Chris Kordish and Andy Thomas have provided Solaris VxFS test
systems.


================================
User-contributed Dialect Support
================================

There are some user-contributed dialect versions of lsof; more
information on them can be found at:

	ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/contrib

Check the 00INDEX file there for details.


============================
Dialects No Longer Supported
============================

Because I don't have access to test systems, these UNIX dialects
are no longer supported by lsof:

	CDC EP/IX
	/dev/kmem-based Linux
	MIPS RISC/os
	Motorola V/88
	Pyramid DC/OSx
	Pyramid Reliant UNIX
	Sequent DYNIX
	SGI IRIX
	SunOS 4.x
	Ultrix
	UnixWare below 7.0

Remnants of the support lsof once provided for these dialects may
be found in:

	ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/OLD/dialects


===============
Installing Lsof
===============

The distributed Makefiles do not have actions that will install
lsof.  I've come to the conclusion there is no standard for installing
lsof or its man page, so I no longer distribute make rules for
installing them.  You should adjust the Makefile for your local
preferences.

The Makefile does have an install rule that will cause lsof to
compile by virtue of its dependency clause.  Some Makefiles also
have a dependency that causes the production of a man page that is
ready to install.  However, the actions of the install rule will
not cause the lsof executable or its man page to be installed in
any UNIX system-wide directory.

Instead, after the compilation and optional man page production
are completed, the install rule will produce a brief description
of what actions you might add to the install rule.  The description
will suggest the possible modes, ownerships, permissions, and
destinations your install rule might employ to install the lsof
executable and man page.

As you form your install rule, keep in mind that lsof usually needs
some type of special permission to do its job.  That may be permission
to read memory devices such as /dev/kmem, /dev/mem, or /dev/swap,
or it may be authorization to read entries in the /proc file system.

Memory device access can usually be provided by setting the modes
of the lsof executable so that it's effective group identifier when
it runs is the same as the group that has permission to read the
memory devices -- i.e., it is setgid-group.  The privileged group
is usually kmem, sys, or system.

Don't overlook using ACLs -- e.g., on AIX or Solaris 8 -- to give
lsof permission to access memory devices.  ACLs, coupled to a
separate group like kmem, can be safer than giving lsof setgid
authorization to a commonly used system group.

When lsof needs to read /proc file system entries, it must be
installed with modes that make its effective user identifier root
when it runs -- i.e., it must be setuid-root.  If lsof must be
installed setuid-root (only the AIX 5L, PSTAT-based HPUX, and
/proc-based Linux, ports need such power.), then access to memory
devices is automatic (or not needed in the case of /proc-based
Linux).

Your choice of permissions for lsof may also be affected by your
desire to allow anyone to use it or your need to restrict its usage
to specific individuals.  You will have to be guided by local policy
and convention in this case.

The next two sections, Setgid Lsof Dialect Versions and Setuid-root
Lsof Dialect Versions, list recommended install permissions.

The system directory where you install the lsof executable is also
open to choice.  A traditional place for a tool like lsof is
/usr/local/etc, but recent changes in directory structure organization
suggest that somewhere in /opt may be more suitable.

Bear one other factor in mind when choosing a location for the lsof
executable -- it usually is a shared executable, requiring access
to shared libraries.  Thus, locations like /sbin or /usr/sbin are
probably unsuitable.

Once you've chosen a location for the executable you may find that
the location for the man page follows -- e.g., if the executable
goes in /usr/local/etc, then the man page goes in /usr/local/man.
If the executable location doesn't imply a location for the man
page, you'll have to let local custom guide you.


Setuid-root Lsof Dialect Versions
=================================

These dialect versions should be installed with setuid-root
permission -- i.e., the lsof binary should be owned by root and
its setuid execution bit (04000) should be set.

	AIX 5L and above for full use of the -X option
	Apple Darwin 8.x for Power Macintosh systems
	PSTAT-based HP-UX 11.11 and 11.23
	/proc-based Linux (generally 2.1.72 and above)


Setgid Lsof Dialect Versions
============================

These dialect versions should be installed with setgid permission,
owned by the group that can read kernel memory devices such as
/dev/drum, /dev/kmem, /dev/ksyms, /dev/mem, /dev/swap.  ACLs may
be another mechanism (e.g., under AIX or Solaris 8) you can use to
grant read permission to the kernel memory devices.

	AIX 4.1.[45], 4.2[.1], and 4.3[.123]
	Apple Darwin 7.x for Power Macintosh systems
	DEC OSF/1, Digital UNIX, Tru64 UNIX 2.0, 3.2, 4.0, and 5.[01]
	FreeBSD 2.1.6, 2.2[.x], 3.x, 4.x, 5.x and [67].x
	/dev/kmem-based 11.00
	NetBSD 1.[456], 2.x and 3.x
	NEXTSTEP 3.[13]
	OpenBSD 2.[89] and 3.[0-9]
	OPENSTEP 4.x
	Caldera OpenUNIX 8
	SCO OpenServer 5.0.[46]
	SCO UnixWare 7.0 and 7.1.[0134]
	Solaris 2.6, 8, 9 and 10
	Ultrix 4.2 (no longer available)

====================================
Porting lsof 4 to a New UNIX Dialect
====================================

If you're brave enough to consider this, look at the 00PORTING
file.  Please contact me before you start.  I might be able to help
you or even do the port myself.

Don't overlook the contrib/ directory in pub/tools/unix/lsof on my
ftp server, lsof.itap.purdue.edu.  It contains user-contributed ports
of lsof to dialects I don't distribute, because I can't test new
revisions of lsof on them.


=========================
Quick Start to Using lsof
=========================

For information on how to get started quickly using lsof, consult
the 00QUICKSTART file of the lsof distribution.  It cuts past the
formal density of the lsof man page to provide quick examples of
using lsof to solve common open file display problems.


======================
Cross-configuring Lsof
======================

Using environment variables it is possible to Configure (and possibly
build) lsof for one UNIX dialect on a different one -- e.g., you
are running Configure on a Linux 2.3 system and you want to Configure
and build lsof for Linux 2.4.

See the 00XCONFIG file of the lsof distribution for a discussion
of how to do this.


====================================================
Environment Variables Affecting the Configure Script
====================================================

Configure script actions can be modified by introducing values to
the script via environment variables.  In many cases the environment
variable values take the place of test operations the Configure
script makes.

For more information on environment variables that can affect
Configure, consult the 00XCONFIG file of the lsof distribution.
See the General Environment Variables sections for descriptions of
ones that affect all dialects.  Consult the Dialect-Specific
Environment Variables section for ones that might affect the dialect
you are trying to configure.


Vic Abell <abe@purdue.edu>
January 2, 2013