summaryrefslogtreecommitdiff
path: root/perl.man.4
blob: 5d3b8c91bd7f63bea1bcc6d19c9d70f75003f8fc (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
''' Beginning of part 4
''' $Header: perl.man.4,v 3.0.1.2 89/11/11 04:46:40 lwall Locked $
'''
''' $Log:	perl.man.4,v $
''' Revision 3.0.1.2  89/11/11  04:46:40  lwall
''' patch2: made some line breaks depend on troff vs. nroff
''' patch2: clarified operation of ^ and $ when $* is false
''' 
''' Revision 3.0.1.1  89/10/26  23:18:43  lwall
''' patch1: documented the desirability of unnecessary parentheses
''' 
''' Revision 3.0  89/10/18  15:21:55  lwall
''' 3.0 baseline
''' 
.Sh "Precedence"
.I Perl
operators have the following associativity and precedence:
.nf

nonassoc\h'|1i'print printf exec system sort reverse
\h'1.5i'chmod chown kill unlink utime die return
left\h'|1i',
right\h'|1i'= += \-= *= etc.
right\h'|1i'?:
nonassoc\h'|1i'.\|.
left\h'|1i'||
left\h'|1i'&&
left\h'|1i'| ^
left\h'|1i'&
nonassoc\h'|1i'== != eq ne
nonassoc\h'|1i'< > <= >= lt gt le ge
nonassoc\h'|1i'chdir exit eval reset sleep rand umask
nonassoc\h'|1i'\-r \-w \-x etc.
left\h'|1i'<< >>
left\h'|1i'+ \- .
left\h'|1i'* / % x
left\h'|1i'=~ !~ 
right\h'|1i'! ~ and unary minus
right\h'|1i'**
nonassoc\h'|1i'++ \-\|\-
left\h'|1i'\*(L'(\*(R'

.fi
As mentioned earlier, if any list operator (print, etc.) or
any unary operator (chdir, etc.)
is followed by a left parenthesis as the next token on the same line,
the operator and arguments within parentheses are taken to
be of highest precedence, just like a normal function call.
Examples:
.nf

	chdir $foo || die;	# (chdir $foo) || die
	chdir($foo) || die;	# (chdir $foo) || die
	chdir ($foo) || die;	# (chdir $foo) || die
	chdir +($foo) || die;	# (chdir $foo) || die

but, because * is higher precedence than ||:

	chdir $foo * 20;	# chdir ($foo * 20)
	chdir($foo) * 20;	# (chdir $foo) * 20
	chdir ($foo) * 20;	# (chdir $foo) * 20
	chdir +($foo) * 20;	# chdir ($foo * 20)

	rand 10 * 20;		# rand (10 * 20)
	rand(10) * 20;		# (rand 10) * 20
	rand (10) * 20;		# (rand 10) * 20
	rand +(10) * 20;	# rand (10 * 20)

.fi
In the absence of parentheses,
the precedence of list operators such as print, sort or chmod is
either very high or very low depending on whether you look at the left
side of operator or the right side of it.
For example, in
.nf

	@ary = (1, 3, sort 4, 2);
	print @ary;		# prints 1324

.fi
the commas on the right of the sort are evaluated before the sort, but
the commas on the left are evaluated after.
In other words, list operators tend to gobble up all the arguments that
follow them, and then act like a simple term with regard to the preceding
expression.
Note that you have to be careful with parens:
.nf

.ne 3
	# These evaluate exit before doing the print:
	print($foo, exit);	# Obviously not what you want.
	print $foo, exit;	# Nor is this.

.ne 4
	# These do the print before evaluating exit:
	(print $foo), exit;	# This is what you want.
	print($foo), exit;	# Or this.
	print ($foo), exit;	# Or even this.

Also note that

	print ($foo & 255) + 1, "\en";

.fi
probably doesn't do what you expect at first glance.
.Sh "Subroutines"
A subroutine may be declared as follows:
.nf

    sub NAME BLOCK

.fi
.PP
Any arguments passed to the routine come in as array @_,
that is ($_[0], $_[1], .\|.\|.).
The array @_ is a local array, but its values are references to the
actual scalar parameters.
The return value of the subroutine is the value of the last expression
evaluated, and can be either an array value or a scalar value.
Alternately, a return statement may be used to specify the returned value and
exit the subroutine.
To create local variables see the
.I local
operator.
.PP
A subroutine is called using the
.I do
operator or the & operator.
.nf

.ne 12
Example:

	sub MAX {
		local($max) = pop(@_);
		foreach $foo (@_) {
			$max = $foo \|if \|$max < $foo;
		}
		$max;
	}

	.\|.\|.
	$bestday = &MAX($mon,$tue,$wed,$thu,$fri);

.ne 21
Example:

	# get a line, combining continuation lines
	#  that start with whitespace
	sub get_line {
		$thisline = $lookahead;
		line: while ($lookahead = <STDIN>) {
			if ($lookahead \|=~ \|/\|^[ \^\e\|t]\|/\|) {
				$thisline \|.= \|$lookahead;
			}
			else {
				last line;
			}
		}
		$thisline;
	}

	$lookahead = <STDIN>;	# get first line
	while ($_ = do get_line(\|)) {
		.\|.\|.
	}

.fi
.nf
.ne 6
Use array assignment to a local list to name your formal arguments:

	sub maybeset {
		local($key, $value) = @_;
		$foo{$key} = $value unless $foo{$key};
	}

.fi
This also has the effect of turning call-by-reference into call-by-value,
since the assignment copies the values.
.Sp
Subroutines may be called recursively.
If a subroutine is called using the & form, the argument list is optional.
If omitted, no @_ array is set up for the subroutine; the @_ array at the
time of the call is visible to subroutine instead.
.nf

	do foo(1,2,3);		# pass three arguments
	&foo(1,2,3);		# the same

	do foo();		# pass a null list
	&foo();			# the same
	&foo;			# pass no arguments--more efficient

.fi
.Sh "Passing By Reference"
Sometimes you don't want to pass the value of an array to a subroutine but
rather the name of it, so that the subroutine can modify the global copy
of it rather than working with a local copy.
In perl you can refer to all the objects of a particular name by prefixing
the name with a star: *foo.
When evaluated, it produces a scalar value that represents all the objects
of that name.
When assigned to within a local() operation, it causes the name mentioned
to refer to whatever * value was assigned to it.
Example:
.nf

	sub doubleary {
	    local(*someary) = @_;
	    foreach $elem (@someary) {
		$elem *= 2;
	    }
	}
	do doubleary(*foo);
	do doubleary(*bar);

.fi
Assignment to *name is currently recommended only inside a local().
You can actually assign to *name anywhere, but the previous referent of
*name may be stranded forever.
This may or may not bother you.
.Sp
Note that scalars are already passed by reference, so you can modify scalar
arguments without using this mechanism by referring explicitly to the $_[nnn]
in question.
You can modify all the elements of an array by passing all the elements
as scalars, but you have to use the * mechanism to push, pop or change the
size of an array.
The * mechanism will probably be more efficient in any case.
.Sp
Since a *name value contains unprintable binary data, if it is used as
an argument in a print, or as a %s argument in a printf or sprintf, it
then has the value '*name', just so it prints out pretty.
.Sh "Regular Expressions"
The patterns used in pattern matching are regular expressions such as
those supplied in the Version 8 regexp routines.
(In fact, the routines are derived from Henry Spencer's freely redistributable
reimplementation of the V8 routines.)
In addition, \ew matches an alphanumeric character (including \*(L"_\*(R") and \eW a nonalphanumeric.
Word boundaries may be matched by \eb, and non-boundaries by \eB.
A whitespace character is matched by \es, non-whitespace by \eS.
A numeric character is matched by \ed, non-numeric by \eD.
You may use \ew, \es and \ed within character classes.
Also, \en, \er, \ef, \et and \eNNN have their normal interpretations.
Within character classes \eb represents backspace rather than a word boundary.
Alternatives may be separated by |.
The bracketing construct \|(\ .\|.\|.\ \|) may also be used, in which case \e<digit>
matches the digit'th substring, where digit can range from 1 to 9.
(Outside of the pattern, always use $ instead of \e in front of the digit.
The scope of $<digit> (and $\`, $& and $\')
extends to the end of the enclosing BLOCK or eval string, or to
the next pattern match with subexpressions.
The \e<digit> notation sometimes works outside the current pattern, but should
not be relied upon.)
$+ returns whatever the last bracket match matched.
$& returns the entire matched string.
($0 normally returns the same thing, but don't depend on it.)
$\` returns everything before the matched string.
$\' returns everything after the matched string.
Examples:
.nf
    
	s/\|^\|([^ \|]*\|) \|*([^ \|]*\|)\|/\|$2 $1\|/;	# swap first two words

.ne 5
	if (/\|Time: \|(.\|.\|):\|(.\|.\|):\|(.\|.\|)\|/\|) {
		$hours = $1;
		$minutes = $2;
		$seconds = $3;
	}

.fi
By default, the ^ character is only guaranteed to match at the beginning
of the string,
the $ character only at the end (or before the newline at the end)
and
.I perl
does certain optimizations with the assumption that the string contains
only one line.
The behavior of ^ and $ on embedded newlines will be inconsistent.
You may, however, wish to treat a string as a multi-line buffer, such that
the ^ will match after any newline within the string, and $ will match
before any newline.
At the cost of a little more overhead, you can do this by setting the variable
$* to 1.
Setting it back to 0 makes
.I perl
revert to its old behavior.
.PP
To facilitate multi-line substitutions, the . character never matches a newline
(even when $* is 0).
In particular, the following leaves a newline on the $_ string:
.nf

	$_ = <STDIN>;
	s/.*(some_string).*/$1/;

If the newline is unwanted, try one of

	s/.*(some_string).*\en/$1/;
	s/.*(some_string)[^\e000]*/$1/;
	s/.*(some_string)(.|\en)*/$1/;
	chop; s/.*(some_string).*/$1/;
	/(some_string)/ && ($_ = $1);

.fi
Any item of a regular expression may be followed with digits in curly brackets
of the form {n,m}, where n gives the minimum number of times to match the item
and m gives the maximum.
The form {n} is equivalent to {n,n} and matches exactly n times.
The form {n,} matches n or more times.
(If a curly bracket occurs in any other context, it is treated as a regular
character.)
The * modifier is equivalent to {0,}, the + modifier to {1,} and the ? modifier
to {0,1}.
There is no limit to the size of n or m, but large numbers will chew up
more memory.
.Sp
You will note that all backslashed metacharacters in
.I perl
are alphanumeric,
such as \eb, \ew, \en.
Unlike some other regular expression languages, there are no backslashed
symbols that aren't alphanumeric.
So anything that looks like \e\e, \e(, \e), \e<, \e>, \e{, or \e} is always
interpreted as a literal character, not a metacharacter.
This makes it simple to quote a string that you want to use for a pattern
but that you are afraid might contain metacharacters.
Simply quote all the non-alphanumeric characters:
.nf

	$pattern =~ s/(\eW)/\e\e$1/g;

.fi
.Sh "Formats"
Output record formats for use with the
.I write
operator may declared as follows:
.nf

.ne 3
    format NAME =
    FORMLIST
    .

.fi
If name is omitted, format \*(L"STDOUT\*(R" is defined.
FORMLIST consists of a sequence of lines, each of which may be of one of three
types:
.Ip 1. 4
A comment.
.Ip 2. 4
A \*(L"picture\*(R" line giving the format for one output line.
.Ip 3. 4
An argument line supplying values to plug into a picture line.
.PP
Picture lines are printed exactly as they look, except for certain fields
that substitute values into the line.
Each picture field starts with either @ or ^.
The @ field (not to be confused with the array marker @) is the normal
case; ^ fields are used
to do rudimentary multi-line text block filling.
The length of the field is supplied by padding out the field
with multiple <, >, or | characters to specify, respectively, left justification,
right justification, or centering.
If any of the values supplied for these fields contains a newline, only
the text up to the newline is printed.
The special field @* can be used for printing multi-line values.
It should appear by itself on a line.
.PP
The values are specified on the following line, in the same order as
the picture fields.
The values should be separated by commas.
.PP
Picture fields that begin with ^ rather than @ are treated specially.
The value supplied must be a scalar variable name which contains a text
string.
.I Perl
puts as much text as it can into the field, and then chops off the front
of the string so that the next time the variable is referenced,
more of the text can be printed.
Normally you would use a sequence of fields in a vertical stack to print
out a block of text.
If you like, you can end the final field with .\|.\|., which will appear in the
output if the text was too long to appear in its entirety.
You can change which characters are legal to break on by changing the
variable $: to a list of the desired characters.
.PP
Since use of ^ fields can produce variable length records if the text to be
formatted is short, you can suppress blank lines by putting the tilde (~)
character anywhere in the line.
(Normally you should put it in the front if possible, for visibility.)
The tilde will be translated to a space upon output.
If you put a second tilde contiguous to the first, the line will be repeated
until all the fields on the line are exhausted.
(If you use a field of the @ variety, the expression you supply had better
not give the same value every time forever!)
.PP
Examples:
.nf
.lg 0
.cs R 25
.ft C

.ne 10
# a report on the /etc/passwd file
format top =
\&                        Passwd File
Name                Login    Office   Uid   Gid Home
------------------------------------------------------------------
\&.
format STDOUT =
@<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
$name,              $login,  $office,$uid,$gid, $home
\&.

.ne 29
# a report from a bug report form
format top =
\&                        Bug Reports
@<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
$system,                      $%,         $date
------------------------------------------------------------------
\&.
format STDOUT =
Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&         $subject
Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&       $index,                       $description
Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&          $priority,        $date,   $description
From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&      $from,                         $description
Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&             $programmer,            $description
\&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&                                     $description
\&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&                                     $description
\&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&                                     $description
\&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
\&                                     $description
\&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
\&                                     $description
\&.

.ft R
.cs R
.lg
.fi
It is possible to intermix prints with writes on the same output channel,
but you'll have to handle $\- (lines left on the page) yourself.
.PP
If you are printing lots of fields that are usually blank, you should consider
using the reset operator between records.
Not only is it more efficient, but it can prevent the bug of adding another
field and forgetting to zero it.
.Sh "Interprocess Communication"
The IPC facilities of perl are built on the Berkeley socket mechanism.
If you don't have sockets, you can ignore this section.
The calls have the same names as the corresponding system calls,
but the arguments tend to differ, for two reasons.
First, perl file handles work differently than C file descriptors.
Second, perl already knows the length of its strings, so you don't need
to pass that information.
Here is a sample client (untested):
.nf

	($them,$port) = @ARGV;
	$port = 2345 unless $port;
	$them = 'localhost' unless $them;

	$SIG{'INT'} = 'dokill';
	sub dokill { kill 9,$child if $child; }

	do 'sys/socket.h' || die "Can't do sys/socket.h: $@";

	$sockaddr = 'S n a4 x8';
	chop($hostname = `hostname`);

	($name, $aliases, $proto) = getprotobyname('tcp');
	($name, $aliases, $port) = getservbyname($port, 'tcp')
		unless $port =~ /^\ed+$/;;
.ie t \{\
	($name, $aliases, $type, $len, $thisaddr) = gethostbyname($hostname);
'br\}
.el \{\
	($name, $aliases, $type, $len, $thisaddr) =
					gethostbyname($hostname);
'br\}
	($name, $aliases, $type, $len, $thataddr) = gethostbyname($them);

	$this = pack($sockaddr, &AF_INET, 0, $thisaddr);
	$that = pack($sockaddr, &AF_INET, $port, $thataddr);

	socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
	bind(S, $this) || die "bind: $!";
	connect(S, $that) || die "connect: $!";

	select(S); $| = 1; select(stdout);

	if ($child = fork) {
		while (<>) {
			print S;
		}
		sleep 3;
		do dokill();
	}
	else {
		while (<S>) {
			print;
		}
	}

.fi
And here's a server:
.nf

	($port) = @ARGV;
	$port = 2345 unless $port;

	do 'sys/socket.h' || die "Can't do sys/socket.h: $@";

	$sockaddr = 'S n a4 x8';

	($name, $aliases, $proto) = getprotobyname('tcp');
	($name, $aliases, $port) = getservbyname($port, 'tcp')
		unless $port =~ /^\ed+$/;;

	$this = pack($sockaddr, &AF_INET, $port, "\e0\e0\e0\e0");

	select(NS); $| = 1; select(stdout);

	socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
	bind(S, $this) || die "bind: $!";
	listen(S, 5) || die "connect: $!";

	select(S); $| = 1; select(stdout);

	for (;;) {
		print "Listening again\en";
		($addr = accept(NS,S)) || die $!;
		print "accept ok\en";

		($af,$port,$inetaddr) = unpack($sockaddr,$addr);
		@inetaddr = unpack('C4',$inetaddr);
		print "$af $port @inetaddr\en";

		while (<NS>) {
			print;
			print NS;
		}
	}

.fi
.Sh "Predefined Names"
The following names have special meaning to
.IR perl .
I could have used alphabetic symbols for some of these, but I didn't want
to take the chance that someone would say reset \*(L"a\-zA\-Z\*(R" and wipe them all
out.
You'll just have to suffer along with these silly symbols.
Most of them have reasonable mnemonics, or analogues in one of the shells.
.Ip $_ 8
The default input and pattern-searching space.
The following pairs are equivalent:
.nf

.ne 2
	while (<>) {\|.\|.\|.	# only equivalent in while!
	while ($_ = <>) {\|.\|.\|.

.ne 2
	/\|^Subject:/
	$_ \|=~ \|/\|^Subject:/

.ne 2
	y/a\-z/A\-Z/
	$_ =~ y/a\-z/A\-Z/

.ne 2
	chop
	chop($_)

.fi 
(Mnemonic: underline is understood in certain operations.)
.Ip $. 8
The current input line number of the last filehandle that was read.
Readonly.
Remember that only an explicit close on the filehandle resets the line number.
Since <> never does an explicit close, line numbers increase across ARGV files
(but see examples under eof).
(Mnemonic: many programs use . to mean the current line number.)
.Ip $/ 8
The input record separator, newline by default.
Works like
.IR awk 's
RS variable, including treating blank lines as delimiters
if set to the null string.
If set to a value longer than one character, only the first character is used.
(Mnemonic: / is used to delimit line boundaries when quoting poetry.)
.Ip $, 8
The output field separator for the print operator.
Ordinarily the print operator simply prints out the comma separated fields
you specify.
In order to get behavior more like
.IR awk ,
set this variable as you would set
.IR awk 's
OFS variable to specify what is printed between fields.
(Mnemonic: what is printed when there is a , in your print statement.)
.Ip $"" 8
This is like $, except that it applies to array values interpolated into
a double-quoted string (or similar interpreted string).
Default is a space.
(Mnemonic: obvious, I think.)
.Ip $\e 8
The output record separator for the print operator.
Ordinarily the print operator simply prints out the comma separated fields
you specify, with no trailing newline or record separator assumed.
In order to get behavior more like
.IR awk ,
set this variable as you would set
.IR awk 's
ORS variable to specify what is printed at the end of the print.
(Mnemonic: you set $\e instead of adding \en at the end of the print.
Also, it's just like /, but it's what you get \*(L"back\*(R" from
.IR perl .)
.Ip $# 8
The output format for printed numbers.
This variable is a half-hearted attempt to emulate
.IR awk 's
OFMT variable.
There are times, however, when
.I awk
and
.I perl
have differing notions of what
is in fact numeric.
Also, the initial value is %.20g rather than %.6g, so you need to set $#
explicitly to get
.IR awk 's
value.
(Mnemonic: # is the number sign.)
.Ip $% 8
The current page number of the currently selected output channel.
(Mnemonic: % is page number in nroff.)
.Ip $= 8
The current page length (printable lines) of the currently selected output
channel.
Default is 60.
(Mnemonic: = has horizontal lines.)
.Ip $\- 8
The number of lines left on the page of the currently selected output channel.
(Mnemonic: lines_on_page \- lines_printed.)
.Ip $~ 8
The name of the current report format for the currently selected output
channel.
(Mnemonic: brother to $^.)
.Ip $^ 8
The name of the current top-of-page format for the currently selected output
channel.
(Mnemonic: points to top of page.)
.Ip $| 8
If set to nonzero, forces a flush after every write or print on the currently
selected output channel.
Default is 0.
Note that
.I STDOUT
will typically be line buffered if output is to the
terminal and block buffered otherwise.
Setting this variable is useful primarily when you are outputting to a pipe,
such as when you are running a
.I perl
script under rsh and want to see the
output as it's happening.
(Mnemonic: when you want your pipes to be piping hot.)
.Ip $$ 8
The process number of the
.I perl
running this script.
(Mnemonic: same as shells.)
.Ip $? 8
The status returned by the last pipe close, backtick (\`\`) command or
.I system
operator.
Note that this is the status word returned by the wait() system
call, so the exit value of the subprocess is actually ($? >> 8).
$? & 255 gives which signal, if any, the process died from, and whether
there was a core dump.
(Mnemonic: similar to sh and ksh.)
.Ip $& 8 4
The string matched by the last pattern match (not counting any matches hidden
within a BLOCK or eval enclosed by the current BLOCK).
(Mnemonic: like & in some editors.)
.Ip $\` 8 4
The string preceding whatever was matched by the last pattern match
(not counting any matches hidden within a BLOCK or eval enclosed by the current
BLOCK).
(Mnemonic: \` often precedes a quoted string.)
.Ip $\' 8 4
The string following whatever was matched by the last pattern match
(not counting any matches hidden within a BLOCK or eval enclosed by the current
BLOCK).
(Mnemonic: \' often follows a quoted string.)
Example:
.nf

.ne 3
	$_ = \'abcdefghi\';
	/def/;
	print "$\`:$&:$\'\en";  	# prints abc:def:ghi

.fi
.Ip $+ 8 4
The last bracket matched by the last search pattern.
This is useful if you don't know which of a set of alternative patterns
matched.
For example:
.nf

    /Version: \|(.*\|)|Revision: \|(.*\|)\|/ \|&& \|($rev = $+);

.fi
(Mnemonic: be positive and forward looking.)
.Ip $* 8 2
Set to 1 to do multiline matching within a string, 0 to tell
.I perl
that it can assume that strings contain a single line, for the purpose
of optimizing pattern matches.
Pattern matches on strings containing multiple newlines can produce confusing
results when $* is 0.
Default is 0.
(Mnemonic: * matches multiple things.)
.Ip $0 8
Contains the name of the file containing the
.I perl
script being executed.
The value should be copied elsewhere before any pattern matching happens, which
clobbers $0.
(Mnemonic: same as sh and ksh.)
.Ip $<digit> 8
Contains the subpattern from the corresponding set of parentheses in the last
pattern matched, not counting patterns matched in nested blocks that have
been exited already.
(Mnemonic: like \edigit.)
.Ip $[ 8 2
The index of the first element in an array, and of the first character in
a substring.
Default is 0, but you could set it to 1 to make
.I perl
behave more like
.I awk
(or Fortran)
when subscripting and when evaluating the index() and substr() functions.
(Mnemonic: [ begins subscripts.)
.Ip $] 8 2
The string printed out when you say \*(L"perl -v\*(R".
It can be used to determine at the beginning of a script whether the perl
interpreter executing the script is in the right range of versions.
Example:
.nf

.ne 5
	# see if getc is available
        ($version,$patchlevel) =
		 $] =~ /(\ed+\e.\ed+).*\enPatch level: (\ed+)/;
        print STDERR "(No filename completion available.)\en"
		 if $version * 1000 + $patchlevel < 2016;

.fi
(Mnemonic: Is this version of perl in the right bracket?)
.Ip $; 8 2
The subscript separator for multi-dimensional array emulation.
If you refer to an associative array element as
.nf
	$foo{$a,$b,$c}

it really means

	$foo{join($;, $a, $b, $c)}

But don't put

	@foo{$a,$b,$c}		# a slice--note the @

which means

	($foo{$a},$foo{$b},$foo{$c})

.fi
Default is "\e034", the same as SUBSEP in
.IR awk .
Note that if your keys contain binary data there might not be any safe
value for $;.
(Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
Yeah, I know, it's pretty lame, but $, is already taken for something more
important.)
.Ip $! 8 2
If used in a numeric context, yields the current value of errno, with all the
usual caveats.
If used in a string context, yields the corresponding system error string.
You can assign to $! in order to set errno
if, for instance, you want $! to return the string for error n, or you want
to set the exit value for the die operator.
(Mnemonic: What just went bang?)
.Ip $@ 8 2
The error message from the last eval command.
If null, the last eval parsed and executed correctly.
(Mnemonic: Where was the syntax error \*(L"at\*(R"?)
.Ip $< 8 2
The real uid of this process.
(Mnemonic: it's the uid you came FROM, if you're running setuid.)
.Ip $> 8 2
The effective uid of this process.
Example:
.nf

.ne 2
	$< = $>;	# set real uid to the effective uid
	($<,$>) = ($>,$<);	# swap real and effective uid

.fi
(Mnemonic: it's the uid you went TO, if you're running setuid.)
Note: $< and $> can only be swapped on machines supporting setreuid().
.Ip $( 8 2
The real gid of this process.
If you are on a machine that supports membership in multiple groups
simultaneously, gives a space separated list of groups you are in.
The first number is the one returned by getgid(), and the subsequent ones
by getgroups(), one of which may be the same as the first number.
(Mnemonic: parentheses are used to GROUP things.
The real gid is the group you LEFT, if you're running setgid.)
.Ip $) 8 2
The effective gid of this process.
If you are on a machine that supports membership in multiple groups
simultaneously, gives a space separated list of groups you are in.
The first number is the one returned by getegid(), and the subsequent ones
by getgroups(), one of which may be the same as the first number.
(Mnemonic: parentheses are used to GROUP things.
The effective gid is the group that's RIGHT for you, if you're running setgid.)
.Sp
Note: $<, $>, $( and $) can only be set on machines that support the
corresponding set[re][ug]id() routine.
$( and $) can only be swapped on machines supporting setregid().
.Ip $: 8 2
The current set of characters after which a string may be broken to
fill continuation fields (starting with ^) in a format.
Default is "\ \en-", to break on whitespace or hyphens.
(Mnemonic: a \*(L"colon\*(R" in poetry is a part of a line.)
.Ip @ARGV 8 3
The array ARGV contains the command line arguments intended for the script.
Note that $#ARGV is the generally number of arguments minus one, since
$ARGV[0] is the first argument, NOT the command name.
See $0 for the command name.
.Ip @INC 8 3
The array INC contains the list of places to look for
.I perl
scripts to be
evaluated by the \*(L"do EXPR\*(R" command.
It initially consists of the arguments to any
.B \-I
command line switches, followed
by the default
.I perl
library, probably \*(L"/usr/local/lib/perl\*(R".
.Ip $ENV{expr} 8 2
The associative array ENV contains your current environment.
Setting a value in ENV changes the environment for child processes.
.Ip $SIG{expr} 8 2
The associative array SIG is used to set signal handlers for various signals.
Example:
.nf

.ne 12
	sub handler {	# 1st argument is signal name
		local($sig) = @_;
		print "Caught a SIG$sig\-\|\-shutting down\en";
		close(LOG);
		exit(0);
	}

	$SIG{\'INT\'} = \'handler\';
	$SIG{\'QUIT\'} = \'handler\';
	.\|.\|.
	$SIG{\'INT\'} = \'DEFAULT\';	# restore default action
	$SIG{\'QUIT\'} = \'IGNORE\';	# ignore SIGQUIT

.fi
The SIG array only contains values for the signals actually set within
the perl script.
.Sh "Packages"
Perl provides a mechanism for alternate namespaces to protect packages from
stomping on each others variables.
By default, a perl script starts compiling into the package known as \*(L"main\*(R".
By use of the
.I package
declaration, you can switch namespaces.
The scope of the package declaration is from the declaration itself to the end
of the enclosing block (the same scope as the local() operator).
Typically it would be the first declaration in a file to be included by
the \*(L"do FILE\*(R" operator.
You can switch into a package in more than one place; it merely influences
which symbol table is used by the compiler for the rest of that block.
You can refer to variables in other packages by prefixing the name with
the package name and a single quote.
If the package name is null, the \*(L"main\*(R" package as assumed.
Eval'ed strings are compiled in the package in which the eval was compiled
in.
(Assignments to $SIG{}, however, assume the signal handler specified is in the
main package.
Qualify the signal handler name if you wish to have a signal handler in
a package.)
For an example, examine perldb.pl in the perl library.
It initially switches to the DB package so that the debugger doesn't interfere
with variables in the script you are trying to debug.
At various points, however, it temporarily switches back to the main package
to evaluate various expressions in the context of the main package.
.PP
The symbol table for a package happens to be stored in the associative array
of that name prepended with an underscore.
The value in each entry of the associative array is
what you are referring to when you use the *name notation.
In fact, the following have the same effect (in package main, anyway),
though the first is more
efficient because it does the symbol table lookups at compile time:
.nf

.ne 2
	local(*foo) = *bar;
	local($_main{'foo'}) = $_main{'bar'};

.fi
You can use this to print out all the variables in a package, for instance.
Here is dumpvar.pl from the perl library:
.nf
.ne 11
	package dumpvar;

	sub main'dumpvar {
	\&    ($package) = @_;
	\&    local(*stab) = eval("*_$package");
	\&    while (($key,$val) = each(%stab)) {
	\&        {
	\&            local(*entry) = $val;
	\&            if (defined $entry) {
	\&                print "\e$$key = '$entry'\en";
	\&            }
.ne 7
	\&            if (defined @entry) {
	\&                print "\e@$key = (\en";
	\&                foreach $num ($[ .. $#entry) {
	\&                    print "  $num\et'",$entry[$num],"'\en";
	\&                }
	\&                print ")\en";
	\&            }
.ne 10
	\&            if ($key ne "_$package" && defined %entry) {
	\&                print "\e%$key = (\en";
	\&                foreach $key (sort keys(%entry)) {
	\&                    print "  $key\et'",$entry{$key},"'\en";
	\&                }
	\&                print ")\en";
	\&            }
	\&        }
	\&    }
	}

.fi
Note that, even though the subroutine is compiled in package dumpvar, the
name of the subroutine is qualified so that it's name is inserted into package
\*(L"main\*(R".
.Sh "Style"
Each programmer will, of course, have his or her own preferences in regards
to formatting, but there are some general guidelines that will make your
programs easier to read.
.Ip 1. 4 4
Just because you CAN do something a particular way doesn't mean that
you SHOULD do it that way.
.I Perl
is designed to give you several ways to do anything, so consider picking
the most readable one.
For instance

	open(FOO,$foo) || die "Can't open $foo: $!";

is better than

	die "Can't open $foo: $!" unless open(FOO,$foo);

because the second way hides the main point of the statement in a
modifier.
On the other hand

	print "Starting analysis\en" if $verbose;

is better than

	$verbose && print "Starting analysis\en";

since the main point isn't whether the user typed -v or not.
.Sp
Similarly, just because an operator lets you assume default arguments
doesn't mean that you have to make use of the defaults.
The defaults are there for lazy systems programmers writing one-shot
programs.
If you want your program to be readable, consider supplying the argument.
.Sp
Along the same lines, just because you
.I can
omit parentheses in many places doesn't mean that you ought to:
.nf

	return print reverse sort num values array;
	return print(reverse(sort num (values(%array))));

.fi
When in doubt, parenthesize.
At the very least it will let some poor schmuck bounce on the % key in vi.
.Ip 2. 4 4
Don't go through silly contortions to exit a loop at the top or the
bottom, when
.I perl
provides the "last" operator so you can exit in the middle.
Just outdent it a little to make it more visible:
.nf

.ne 7
    line:
	for (;;) {
	    statements;
	last line if $foo;
	    next line if /^#/;
	    statements;
	}

.fi
.Ip 3. 4 4
Don't be afraid to use loop labels\*(--they're there to enhance readability as
well as to allow multi-level loop breaks.
See last example.
.Ip 6. 4 4
For portability, when using features that may not be implemented on every
machine, test the construct in an eval to see if it fails.
If you know what version or patchlevel a particular feature was implemented,
you can test $] to see if it will be there.
.Ip 4. 4 4
Choose mnemonic identifiers.
.Ip 5. 4 4
Be consistent.
.Sh "Debugging"
If you invoke
.I perl
with a
.B \-d
switch, your script will be run under a debugging monitor.
It will halt before the first executable statement and ask you for a
command, such as:
.Ip "h" 12 4
Prints out a help message.
.Ip "s" 12 4
Single step.
Executes until it reaches the beginning of another statement.
.Ip "c" 12 4
Continue.
Executes until the next breakpoint is reached.
.Ip "<CR>" 12 4
Repeat last s or c.
.Ip "n" 12 4
Single step around subroutine call.
.Ip "l min+incr" 12 4
List incr+1 lines starting at min.
If min is omitted, starts where last listing left off.
If incr is omitted, previous value of incr is used.
.Ip "l min-max" 12 4
List lines in the indicated range.
.Ip "l line" 12 4
List just the indicated line.
.Ip "l" 12 4
List incr+1 more lines after last printed line.
.Ip "l subname" 12 4
List subroutine.
If it's a long subroutine it just lists the beginning.
Use \*(L"l\*(R" to list more.
.Ip "L" 12 4
List lines that have breakpoints or actions.
.Ip "t" 12 4
Toggle trace mode on or off.
.Ip "b line" 12 4
Set a breakpoint.
If line is omitted, sets a breakpoint on the current line
line that is about to be executed.
Breakpoints may only be set on lines that begin an executable statement.
.Ip "b subname" 12 4
Set breakpoint at first executable line of subroutine.
.Ip "S" 12 4
Lists the names of all subroutines.
.Ip "d line" 12 4
Delete breakpoint.
If line is omitted, deletes the breakpoint on the current line
line that is about to be executed.
.Ip "D" 12 4
Delete all breakpoints.
.Ip "A" 12 4
Delete all line actions.
.Ip "V package" 12 4
List all variables in package.
Default is main package.
.Ip "a line command" 12 4
Set an action for line.
A multi-line command may be entered by backslashing the newlines.
.Ip "< command" 12 4
Set an action to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.
.Ip "> command" 12 4
Set an action to happen after the prompt when you've just given a command
to return to executing the script.
A multi-line command may be entered by backslashing the newlines.
.Ip "! number" 12 4
Redo a debugging command.
If number is omitted, redoes the previous command.
.Ip "! -number" 12 4
Redo the command that was that many commands ago.
.Ip "H -number" 12 4
Display last n commands.
Only commands longer than one character are listed.
If number is omitted, lists them all.
.Ip "q or ^D" 12 4
Quit.
.Ip "command" 12 4
Execute command as a perl statement.
A missing semicolon will be supplied.
.Ip "p expr" 12 4
Same as \*(L"print DB'OUT expr\*(R".
The DB'OUT filehandle is opened to /dev/tty, regardless of where STDOUT
may be redirected to.
.PP
If you want to modify the debugger, copy perldb.pl from the perl library
to your current directory and modify it as necessary.
You can do some customization by setting up a .perldb file which contains
initialization code.
For instance, you could make aliases like these:
.nf

    $DBalias{'len'} = 's/^len(.*)/p length(\e$1)/';
    $DBalias{'stop'} = 's/^stop (at|in)/b/';
    $DBalias{'.'} =
      's/^./p "\e$DBsub(\e$DBline):\et\e$DBline[\e$DBline]"/';

.fi
.Sh "Setuid Scripts"
.I Perl
is designed to make it easy to write secure setuid and setgid scripts.
Unlike shells, which are based on multiple substitution passes on each line
of the script,
.I perl
uses a more conventional evaluation scheme with fewer hidden \*(L"gotchas\*(R".
Additionally, since the language has more built-in functionality, it
has to rely less upon external (and possibly untrustworthy) programs to
accomplish its purposes.
.PP
In an unpatched 4.2 or 4.3bsd kernel, setuid scripts are intrinsically
insecure, but this kernel feature can be disabled.
If it is,
.I perl
can emulate the setuid and setgid mechanism when it notices the otherwise
useless setuid/gid bits on perl scripts.
If the kernel feature isn't disabled,
.I perl
will complain loudly that your setuid script is insecure.
You'll need to either disable the kernel setuid script feature, or put
a C wrapper around the script.
.PP
When perl is executing a setuid script, it takes special precautions to
prevent you from falling into any obvious traps.
(In some ways, a perl script is more secure than the corresponding
C program.)
Any command line argument, environment variable, or input is marked as
\*(L"tainted\*(R", and may not be used, directly or indirectly, in any
command that invokes a subshell, or in any command that modifies files,
directories or processes.
Any variable that is set within an expression that has previously referenced
a tainted value also becomes tainted (even if it is logically impossible
for the tainted value to influence the variable).
For example:
.nf

.ne 5
	$foo = shift;			# $foo is tainted
	$bar = $foo,\'bar\';		# $bar is also tainted
	$xxx = <>;			# Tainted
	$path = $ENV{\'PATH\'};	# Tainted, but see below
	$abc = \'abc\';			# Not tainted

.ne 4
	system "echo $foo";		# Insecure
	system "echo", $foo;	# Secure (doesn't use sh)
	system "echo $bar";		# Insecure
	system "echo $abc";		# Insecure until PATH set

.ne 5
	$ENV{\'PATH\'} = \'/bin:/usr/bin\';
	$ENV{\'IFS\'} = \'\' if $ENV{\'IFS\'} ne \'\';

	$path = $ENV{\'PATH\'};	# Not tainted
	system "echo $abc";		# Is secure now!

.ne 5
	open(FOO,"$foo");		# OK
	open(FOO,">$foo"); 		# Not OK

	open(FOO,"echo $foo|");	# Not OK, but...
	open(FOO,"-|") || exec \'echo\', $foo;	# OK

	$zzz = `echo $foo`;		# Insecure, zzz tainted

	unlink $abc,$foo;		# Insecure
	umask $foo;			# Insecure

.ne 3
	exec "echo $foo";		# Insecure
	exec "echo", $foo;		# Secure (doesn't use sh)
	exec "sh", \'-c\', $foo;	# Considered secure, alas

.fi
The taintedness is associated with each scalar value, so some elements
of an array can be tainted, and others not.
.PP
If you try to do something insecure, you will get a fatal error saying 
something like \*(L"Insecure dependency\*(R" or \*(L"Insecure PATH\*(R".
Note that you can still write an insecure system call or exec,
but only by explicitly doing something like the last example above.
You can also bypass the tainting mechanism by referencing
subpatterns\*(--\c
.I perl
presumes that if you reference a substring using $1, $2, etc, you knew
what you were doing when you wrote the pattern:
.nf

	$ARGV[0] =~ /^\-P(\ew+)$/;
	$printer = $1;		# Not tainted

.fi
This is fairly secure since \ew+ doesn't match shell metacharacters.
Use of .+ would have been insecure, but
.I perl
doesn't check for that, so you must be careful with your patterns.
This is the ONLY mechanism for untainting user supplied filenames if you
want to do file operations on them (unless you make $> equal to $<).
.PP
It's also possible to get into trouble with other operations that don't care
whether they use tainted values.
Make judicious use of the file tests in dealing with any user-supplied
filenames.
When possible, do opens and such after setting $> = $<.
.I Perl
doesn't prevent you from opening tainted filenames for reading, so be
careful what you print out.
The tainting mechanism is intended to prevent stupid mistakes, not to remove
the need for thought.
.SH ENVIRONMENT
.I Perl
uses PATH in executing subprocesses, and in finding the script if \-S
is used.
HOME or LOGDIR are used if chdir has no argument.
.PP
Apart from these,
.I perl
uses no environment variables, except to make them available
to the script being executed, and to child processes.
However, scripts running setuid would do well to execute the following lines
before doing anything else, just to keep people honest:
.nf

.ne 3
    $ENV{\'PATH\'} = \'/bin:/usr/bin\';    # or whatever you need
    $ENV{\'SHELL\'} = \'/bin/sh\' if $ENV{\'SHELL\'} ne \'\';
    $ENV{\'IFS\'} = \'\' if $ENV{\'IFS\'} ne \'\';

.fi
.SH AUTHOR
Larry Wall <lwall@jpl-devvax.Jpl.Nasa.Gov>
.SH FILES
/tmp/perl\-eXXXXXX	temporary file for
.B \-e
commands.
.SH SEE ALSO
a2p	awk to perl translator
.br
s2p	sed to perl translator
.SH DIAGNOSTICS
Compilation errors will tell you the line number of the error, with an
indication of the next token or token type that was to be examined.
(In the case of a script passed to
.I perl
via
.B \-e
switches, each
.B \-e
is counted as one line.)
.PP
Setuid scripts have additional constraints that can produce error messages
such as \*(L"Insecure dependency\*(R".
See the section on setuid scripts.
.SH TRAPS
Accustomed
.IR awk
users should take special note of the following:
.Ip * 4 2
Semicolons are required after all simple statements in
.IR perl .
Newline
is not a statement delimiter.
.Ip * 4 2
Curly brackets are required on ifs and whiles.
.Ip * 4 2
Variables begin with $ or @ in
.IR perl .
.Ip * 4 2
Arrays index from 0 unless you set $[.
Likewise string positions in substr() and index().
.Ip * 4 2
You have to decide whether your array has numeric or string indices.
.Ip * 4 2
Associative array values do not spring into existence upon mere reference.
.Ip * 4 2
You have to decide whether you want to use string or numeric comparisons.
.Ip * 4 2
Reading an input line does not split it for you.  You get to split it yourself
to an array.
And the
.I split
operator has different arguments.
.Ip * 4 2
The current input line is normally in $_, not $0.
It generally does not have the newline stripped.
($0 is initially the name of the program executed, then the last matched
string.)
.Ip * 4 2
$<digit> does not refer to fields\*(--it refers to substrings matched by the last
match pattern.
.Ip * 4 2
The
.I print
statement does not add field and record separators unless you set
$, and $\e.
.Ip * 4 2
You must open your files before you print to them.
.Ip * 4 2
The range operator is \*(L".\|.\*(R", not comma.
(The comma operator works as in C.)
.Ip * 4 2
The match operator is \*(L"=~\*(R", not \*(L"~\*(R".
(\*(L"~\*(R" is the one's complement operator, as in C.)
.Ip * 4 2
The exponentiation operator is \*(L"**\*(R", not \*(L"^\*(R".
(\*(L"^\*(R" is the XOR operator, as in C.)
.Ip * 4 2
The concatenation operator is \*(L".\*(R", not the null string.
(Using the null string would render \*(L"/pat/ /pat/\*(R" unparsable,
since the third slash would be interpreted as a division operator\*(--the
tokener is in fact slightly context sensitive for operators like /, ?, and <.
And in fact, . itself can be the beginning of a number.)
.Ip * 4 2
.IR Next ,
.I exit
and
.I continue
work differently.
.Ip * 4 2
The following variables work differently
.nf

	  Awk	\h'|2.5i'Perl
	  ARGC	\h'|2.5i'$#ARGV
	  ARGV[0]	\h'|2.5i'$0
	  FILENAME\h'|2.5i'$ARGV
	  FNR	\h'|2.5i'$. \- something
	  FS	\h'|2.5i'(whatever you like)
	  NF	\h'|2.5i'$#Fld, or some such
	  NR	\h'|2.5i'$.
	  OFMT	\h'|2.5i'$#
	  OFS	\h'|2.5i'$,
	  ORS	\h'|2.5i'$\e
	  RLENGTH	\h'|2.5i'length($&)
	  RS	\h'|2.5i'$\/
	  RSTART	\h'|2.5i'length($\`)
	  SUBSEP	\h'|2.5i'$;

.fi
.Ip * 4 2
When in doubt, run the
.I awk
construct through a2p and see what it gives you.
.PP
Cerebral C programmers should take note of the following:
.Ip * 4 2
Curly brackets are required on ifs and whiles.
.Ip * 4 2
You should use \*(L"elsif\*(R" rather than \*(L"else if\*(R"
.Ip * 4 2
.I Break
and
.I continue
become
.I last
and
.IR next ,
respectively.
.Ip * 4 2
There's no switch statement.
.Ip * 4 2
Variables begin with $ or @ in
.IR perl .
.Ip * 4 2
Printf does not implement *.
.Ip * 4 2
Comments begin with #, not /*.
.Ip * 4 2
You can't take the address of anything.
.Ip * 4 2
ARGV must be capitalized.
.Ip * 4 2
The \*(L"system\*(R" calls link, unlink, rename, etc. return nonzero for success, not 0.
.Ip * 4 2
Signal handlers deal with signal names, not numbers.
.Ip * 4 2
You can't subscript array values, only arrays (no $x = (1,2,3)[2];).
.PP
Seasoned
.I sed
programmers should take note of the following:
.Ip * 4 2
Backreferences in substitutions use $ rather than \e.
.Ip * 4 2
The pattern matching metacharacters (, ), and | do not have backslashes in front.
.Ip * 4 2
The range operator is .\|. rather than comma.
.PP
Sharp shell programmers should take note of the following:
.Ip * 4 2
The backtick operator does variable interpretation without regard to the
presence of single quotes in the command.
.Ip * 4 2
The backtick operator does no translation of the return value, unlike csh.
.Ip * 4 2
Shells (especially csh) do several levels of substitution on each command line.
.I Perl
does substitution only in certain constructs such as double quotes,
backticks, angle brackets and search patterns.
.Ip * 4 2
Shells interpret scripts a little bit at a time.
.I Perl
compiles the whole program before executing it.
.Ip * 4 2
The arguments are available via @ARGV, not $1, $2, etc.
.Ip * 4 2
The environment is not automatically made available as variables.
.SH BUGS
.PP
.I Perl
is at the mercy of your machine's definitions of various operations
such as type casting, atof() and sprintf().
.PP
If your stdio requires an seek or eof between reads and writes on a particular
stream, so does
.IR perl .
.PP
While none of the built-in data types have any arbitrary size limits (apart
from memory size), there are still a few arbitrary limits:
a given identifier may not be longer than 255 characters;
sprintf is limited on many machines to 128 characters per field (unless the format
specifier is exactly %s);
and no component of your PATH may be longer than 255 if you use \-S.
.PP
.I Perl
actually stands for Pathologically Eclectic Rubbish Lister, but don't tell
anyone I said that.
.rn }` ''