summaryrefslogtreecommitdiff
path: root/perl.man.3
blob: d4574ebd69e1d2ae43bf8de80c7817c8968ff153 (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
''' Beginning of part 3
''' $Header: perl_man.3,v 3.0.1.12 91/01/11 18:18:15 lwall Locked $
'''
''' $Log:	perl.man.3,v $
''' Revision 3.0.1.12  91/01/11  18:18:15  lwall
''' patch42: added binary and hex pack/unpack options
''' 
''' Revision 3.0.1.11  90/11/10  01:48:21  lwall
''' patch38: random cleanup
''' patch38: documented tr///cds
''' 
''' Revision 3.0.1.10  90/10/20  02:15:17  lwall
''' patch37: patch37: fixed various typos in man page
''' 
''' Revision 3.0.1.9  90/10/16  10:02:43  lwall
''' patch29: you can now read into the middle string
''' patch29: index and substr now have optional 3rd args
''' patch29: added scalar reverse
''' patch29: added scalar
''' patch29: added SysV IPC
''' patch29: added waitpid
''' patch29: added sysread and syswrite
''' 
''' Revision 3.0.1.8  90/08/09  04:39:04  lwall
''' patch19: added require operator
''' patch19: added truncate operator
''' patch19: unpack can do checksumming
''' 
''' Revision 3.0.1.7  90/08/03  11:15:42  lwall
''' patch19: Intermediate diffs for Randal
''' 
''' Revision 3.0.1.6  90/03/27  16:17:56  lwall
''' patch16: MSDOS support
''' 
''' Revision 3.0.1.5  90/03/12  16:52:21  lwall
''' patch13: documented that print $filehandle &foo is ambiguous
''' patch13: added splice operator: @oldelems = splice(@array,$offset,$len,LIST)
''' 
''' Revision 3.0.1.4  90/02/28  18:00:09  lwall
''' patch9: added pipe function
''' patch9: documented how to handle arbitrary weird characters in filenames
''' patch9: documented the unflushed buffers problem on piped opens
''' patch9: documented how to force top of page
''' 
''' Revision 3.0.1.3  89/12/21  20:10:12  lwall
''' patch7: documented that s`pat`repl` does command substitution on replacement
''' patch7: documented that $timeleft from select() is likely not implemented
''' 
''' Revision 3.0.1.2  89/11/17  15:31:05  lwall
''' patch5: fixed some manual typos and indent problems
''' patch5: added warning about print making an array context
''' 
''' Revision 3.0.1.1  89/11/11  04:45:06  lwall
''' patch2: made some line breaks depend on troff vs. nroff
''' 
''' Revision 3.0  89/10/18  15:21:46  lwall
''' 3.0 baseline
''' 
.Ip "next LABEL" 8 8
.Ip "next" 8
The
.I next
command is like the
.I continue
statement in C; it starts the next iteration of the loop:
.nf

.ne 4
	line: while (<STDIN>) {
		next line if /\|^#/;	# discard comments
		.\|.\|.
	}

.fi
Note that if there were a
.I continue
block on the above, it would get executed even on discarded lines.
If the LABEL is omitted, the command refers to the innermost enclosing loop.
.Ip "oct(EXPR)" 8 4
.Ip "oct EXPR" 8
Returns the decimal value of EXPR interpreted as an octal string.
(If EXPR happens to start off with 0x, interprets it as a hex string instead.)
The following will handle decimal, octal and hex in the standard notation:
.nf

	$val = oct($val) if $val =~ /^0/;

.fi
If EXPR is omitted, uses $_.
.Ip "open(FILEHANDLE,EXPR)" 8 8
.Ip "open(FILEHANDLE)" 8
.Ip "open FILEHANDLE" 8
Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.
If FILEHANDLE is an expression, its value is used as the name of the
real filehandle wanted.
If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE
contains the filename.
If the filename begins with \*(L"<\*(R" or nothing, the file is opened for
input.
If the filename begins with \*(L">\*(R", the file is opened for output.
If the filename begins with \*(L">>\*(R", the file is opened for appending.
(You can put a \'+\' in front of the \'>\' or \'<\' to indicate that you
want both read and write access to the file.)
If the filename begins with \*(L"|\*(R", the filename is interpreted
as a command to which output is to be piped, and if the filename ends
with a \*(L"|\*(R", the filename is interpreted as command which pipes
input to us.
(You may not have a command that pipes both in and out.)
Opening \'\-\' opens
.I STDIN
and opening \'>\-\' opens
.IR STDOUT .
Open returns non-zero upon success, the undefined value otherwise.
If the open involved a pipe, the return value happens to be the pid
of the subprocess.
Examples:
.nf
    
.ne 3
	$article = 100;
	open article || die "Can't find article $article: $!\en";
	while (<article>) {\|.\|.\|.

.ie t \{\
	open(LOG, \'>>/usr/spool/news/twitlog\'\|);	# (log is reserved)
'br\}
.el \{\
	open(LOG, \'>>/usr/spool/news/twitlog\'\|);
					# (log is reserved)
'br\}

.ie t \{\
	open(article, "caesar <$article |"\|);		# decrypt article
'br\}
.el \{\
	open(article, "caesar <$article |"\|);
					# decrypt article
'br\}

.ie t \{\
	open(extract, "|sort >/tmp/Tmp$$"\|);		# $$ is our process#
'br\}
.el \{\
	open(extract, "|sort >/tmp/Tmp$$"\|);
					# $$ is our process#
'br\}

.ne 7
	# process argument list of files along with any includes

	foreach $file (@ARGV) {
		do process($file, \'fh00\');	# no pun intended
	}

	sub process {
		local($filename, $input) = @_;
		$input++;		# this is a string increment
		unless (open($input, $filename)) {
			print STDERR "Can't open $filename: $!\en";
			return;
		}
.ie t \{\
		while (<$input>) {		# note the use of indirection
'br\}
.el \{\
		while (<$input>) {		# note use of indirection
'br\}
			if (/^#include "(.*)"/) {
				do process($1, $input);
				next;
			}
			.\|.\|.		# whatever
		}
	}

.fi
You may also, in the Bourne shell tradition, specify an EXPR beginning
with \*(L">&\*(R", in which case the rest of the string
is interpreted as the name of a filehandle
(or file descriptor, if numeric) which is to be duped and opened.
You may use & after >, >>, <, +>, +>> and +<.
The mode you specify should match the mode of the original filehandle.
Here is a script that saves, redirects, and restores
.I STDOUT
and
.IR STDERR :
.nf

.ne 21
	#!/usr/bin/perl
	open(SAVEOUT, ">&STDOUT");
	open(SAVEERR, ">&STDERR");

	open(STDOUT, ">foo.out") || die "Can't redirect stdout";
	open(STDERR, ">&STDOUT") || die "Can't dup stdout";

	select(STDERR); $| = 1;		# make unbuffered
	select(STDOUT); $| = 1;		# make unbuffered

	print STDOUT "stdout 1\en";	# this works for
	print STDERR "stderr 1\en"; 	# subprocesses too

	close(STDOUT);
	close(STDERR);

	open(STDOUT, ">&SAVEOUT");
	open(STDERR, ">&SAVEERR");

	print STDOUT "stdout 2\en";
	print STDERR "stderr 2\en";

.fi
If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R",
then there is an implicit fork done, and the return value of open
is the pid of the child within the parent process, and 0 within the child
process.
(Use defined($pid) to determine if the open was successful.)
The filehandle behaves normally for the parent, but i/o to that
filehandle is piped from/to the
.IR STDOUT / STDIN
of the child process.
In the child process the filehandle isn't opened\*(--i/o happens from/to
the new
.I STDOUT
or
.IR STDIN .
Typically this is used like the normal piped open when you want to exercise
more control over just how the pipe command gets executed, such as when
you are running setuid, and don't want to have to scan shell commands
for metacharacters.
The following pairs are more or less equivalent:
.nf

.ne 5
	open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'");
	open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\';

	open(FOO, "cat \-n '$file'|");
	open(FOO, "\-|") || exec \'cat\', \'\-n\', $file;

.fi
Explicitly closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in $?.
Note: on any operation which may do a fork,
unflushed buffers remain unflushed in both
processes, which means you may need to set $| to
avoid duplicate output.
.Sp
The filename that is passed to open will have leading and trailing
whitespace deleted.
In order to open a file with arbitrary weird characters in it, it's necessary
to protect any leading and trailing whitespace thusly:
.nf

.ne 2
        $file =~ s#^(\es)#./$1#;
        open(FOO, "< $file\e0");

.fi
.Ip "opendir(DIRHANDLE,EXPR)" 8 3
Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(),
rewinddir() and closedir().
Returns true if successful.
DIRHANDLEs have their own namespace separate from FILEHANDLEs.
.Ip "ord(EXPR)" 8 4
.Ip "ord EXPR" 8
Returns the numeric ascii value of the first character of EXPR.
If EXPR is omitted, uses $_.
''' Comments on f & d by gnb@melba.bby.oz.au	22/11/89
.Ip "pack(TEMPLATE,LIST)" 8 4
Takes an array or list of values and packs it into a binary structure,
returning the string containing the structure.
The TEMPLATE is a sequence of characters that give the order and type
of values, as follows:
.nf

	A	An ascii string, will be space padded.
	a	An ascii string, will be null padded.
	c	A signed char value.
	C	An unsigned char value.
	s	A signed short value.
	S	An unsigned short value.
	i	A signed integer value.
	I	An unsigned integer value.
	l	A signed long value.
	L	An unsigned long value.
	n	A short in \*(L"network\*(R" order.
	N	A long in \*(L"network\*(R" order.
	f	A single-precision float in the native format.
	d	A double-precision float in the native format.
	p	A pointer to a string.
	x	A null byte.
	X	Back up a byte.
	@	Null fill to absolute position.
	u	A uuencoded string.
	b	A bit string (ascending bit order, like vec()).
	B	A bit string (descending bit order).
	h	A hex string (low nybble first).
	H	A hex string (high nybble first).

.fi
Each letter may optionally be followed by a number which gives a repeat
count.
With all types except "a", "A", "b", "B", "h" and "H",
the pack function will gobble up that many values
from the LIST.
A * for the repeat count means to use however many items are left.
The "a" and "A" types gobble just one value, but pack it as a string of length
count,
padding with nulls or spaces as necessary.
(When unpacking, "A" strips trailing spaces and nulls, but "a" does not.)
Likewise, the "b" and "B" fields pack a string that many bits long.
The "h" and "H" fields pack a string that many nybbles long.
Real numbers (floats and doubles) are in the native machine format
only; due to the multiplicity of floating formats around, and the lack
of a standard \*(L"network\*(R" representation, no facility for
interchange has been made.
This means that packed floating point data
written on one machine may not be readable on another - even if both
use IEEE floating point arithmetic (as the endian-ness of the memory
representation is not part of the IEEE spec).
Note that perl uses
doubles internally for all numeric calculation, and converting from
double -> float -> double will lose precision (i.e. unpack("f",
pack("f", $foo)) will not in general equal $foo).
.br
Examples:
.nf

	$foo = pack("cccc",65,66,67,68);
	# foo eq "ABCD"
	$foo = pack("c4",65,66,67,68);
	# same thing

	$foo = pack("ccxxcc",65,66,67,68);
	# foo eq "AB\e0\e0CD"

	$foo = pack("s2",1,2);
	# "\e1\e0\e2\e0" on little-endian
	# "\e0\e1\e0\e2" on big-endian

	$foo = pack("a4","abcd","x","y","z");
	# "abcd"

	$foo = pack("aaaa","abcd","x","y","z");
	# "axyz"

	$foo = pack("a14","abcdefg");
	# "abcdefg\e0\e0\e0\e0\e0\e0\e0"

	$foo = pack("i9pl", gmtime);
	# a real struct tm (on my system anyway)

	sub bintodec {
	    unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
	}
.fi
The same template may generally also be used in the unpack function.
.Ip "pipe(READHANDLE,WRITEHANDLE)" 8 3
Opens a pair of connected pipes like the corresponding system call.
Note that if you set up a loop of piped processes, deadlock can occur
unless you are very careful.
In addition, note that perl's pipes use stdio buffering, so you may need
to set $| to flush your WRITEHANDLE after each command, depending on
the application.
[Requires version 3.0 patchlevel 9.]
.Ip "pop(ARRAY)" 8
.Ip "pop ARRAY" 8 6
Pops and returns the last value of the array, shortening the array by 1.
Has the same effect as
.nf

	$tmp = $ARRAY[$#ARRAY\-\|\-];

.fi
If there are no elements in the array, returns the undefined value.
.Ip "print(FILEHANDLE LIST)" 8 10
.Ip "print(LIST)" 8
.Ip "print FILEHANDLE LIST" 8
.Ip "print LIST" 8
.Ip "print" 8
Prints a string or a comma-separated list of strings.
Returns non-zero if successful.
FILEHANDLE may be a scalar variable name, in which case the variable contains
the name of the filehandle, thus introducing one level of indirection.
(NOTE: If FILEHANDLE is a variable and the next token is a term, it may be
misinterpreted as an operator unless you interpose a + or put parens around
the arguments.)
If FILEHANDLE is omitted, prints by default to standard output (or to the
last selected output channel\*(--see select()).
If LIST is also omitted, prints $_ to
.IR STDOUT .
To set the default output channel to something other than
.I STDOUT
use the select operation.
Note that, because print takes a LIST, anything in the LIST is evaluated
in an array context, and any subroutine that you call will have one or more
of its expressions evaluated in an array context.
Also be careful not to follow the print keyword with a left parenthesis
unless you want the corresponding right parenthesis to terminate the
arguments to the print\*(--interpose a + or put parens around all the arguments.
.Ip "printf(FILEHANDLE LIST)" 8 10
.Ip "printf(LIST)" 8
.Ip "printf FILEHANDLE LIST" 8
.Ip "printf LIST" 8
Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R".
.Ip "push(ARRAY,LIST)" 8 7
Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST
onto the end of ARRAY.
The length of ARRAY increases by the length of LIST.
Has the same effect as
.nf

    for $value (LIST) {
	    $ARRAY[++$#ARRAY] = $value;
    }

.fi
but is more efficient.
.Ip "q/STRING/" 8 5
.Ip "qq/STRING/" 8
These are not really functions, but simply syntactic sugar to let you
avoid putting too many backslashes into quoted strings.
The q operator is a generalized single quote, and the qq operator a
generalized double quote.
Any non-alphanumeric delimiter can be used in place of /, including newline.
If the delimiter is an opening bracket or parenthesis, the final delimiter
will be the corresponding closing bracket or parenthesis.
(Embedded occurrences of the closing bracket need to be backslashed as usual.)
Examples:
.nf

.ne 5
	$foo = q!I said, "You said, \'She said it.\'"!;
	$bar = q(\'This is it.\');
	$_ .= qq
*** The previous line contains the naughty word "$&".\en
		if /(ibm|apple|awk)/;      # :-)

.fi
.Ip "rand(EXPR)" 8 8
.Ip "rand EXPR" 8
.Ip "rand" 8
Returns a random fractional number between 0 and the value of EXPR.
(EXPR should be positive.)
If EXPR is omitted, returns a value between 0 and 1.
See also srand().
.Ip "read(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
.Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5
Attempts to read LENGTH bytes of data into variable SCALAR from the specified
FILEHANDLE.
Returns the number of bytes actually read, or undef if there was an error.
SCALAR will be grown or shrunk to the length actually read.
An OFFSET may be specified to place the read data at some other place
than the beginning of the string.
This call is actually implemented in terms of stdio's fread call.  To get
a true read system call, see sysread.
.Ip "readdir(DIRHANDLE)" 8 3
.Ip "readdir DIRHANDLE" 8
Returns the next directory entry for a directory opened by opendir().
If used in an array context, returns all the rest of the entries in the
directory.
If there are no more entries, returns an undefined value in a scalar context
or a null list in an array context.
.Ip "readlink(EXPR)" 8 6
.Ip "readlink EXPR" 8
Returns the value of a symbolic link, if symbolic links are implemented.
If not, gives a fatal error.
If there is some system error, returns the undefined value and sets $! (errno).
If EXPR is omitted, uses $_.
.Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4
Receives a message on a socket.
Attempts to receive LENGTH bytes of data into variable SCALAR from the specified
SOCKET filehandle.
Returns the address of the sender, or the undefined value if there's an error.
SCALAR will be grown or shrunk to the length actually read.
Takes the same flags as the system call of the same name.
.Ip "redo LABEL" 8 8
.Ip "redo" 8
The
.I redo
command restarts the loop block without evaluating the conditional again.
The
.I continue
block, if any, is not executed.
If the LABEL is omitted, the command refers to the innermost enclosing loop.
This command is normally used by programs that want to lie to themselves
about what was just input:
.nf

.ne 16
	# a simpleminded Pascal comment stripper
	# (warning: assumes no { or } in strings)
	line: while (<STDIN>) {
		while (s|\|({.*}.*\|){.*}|$1 \||) {}
		s|{.*}| \||;
		if (s|{.*| \||) {
			$front = $_;
			while (<STDIN>) {
				if (\|/\|}/\|) {	# end of comment?
					s|^|$front{|;
					redo line;
				}
			}
		}
		print;
	}

.fi
.Ip "rename(OLDNAME,NEWNAME)" 8 2
Changes the name of a file.
Returns 1 for success, 0 otherwise.
Will not work across filesystem boundaries.
.Ip "require(EXPR)" 8 6
.Ip "require EXPR" 8
.Ip "require" 8
Includes the library file specified by EXPR, or by $_ if EXPR is not supplied.
Has semantics similar to the following subroutine:
.nf

	sub require {
	    local($filename) = @_;
	    return 1 if $INC{$filename};
	    local($realfilename,$result);
	    ITER: {
		foreach $prefix (@INC) {
		    $realfilename = "$prefix/$filename";
		    if (-f $realfilename) {
			$result = do $realfilename;
			last ITER;
		    }
		}
		die "Can't find $filename in \e@INC";
	    }
	    die $@ if $@;
	    die "$filename did not return true value" unless $result;
	    $INC{$filename} = $realfilename;
	    $result;
	}

.fi
Note that the file will not be included twice under the same specified name.
.Ip "reset(EXPR)" 8 6
.Ip "reset EXPR" 8
.Ip "reset" 8
Generally used in a
.I continue
block at the end of a loop to clear variables and reset ?? searches
so that they work again.
The expression is interpreted as a list of single characters (hyphens allowed
for ranges).
All variables and arrays beginning with one of those letters are reset to
their pristine state.
If the expression is omitted, one-match searches (?pattern?) are reset to
match again.
Only resets variables or searches in the current package.
Always returns 1.
Examples:
.nf

.ne 3
    reset \'X\';	\h'|2i'# reset all X variables
    reset \'a\-z\';\h'|2i'# reset lower case variables
    reset;	\h'|2i'# just reset ?? searches

.fi
Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV
arrays.
.Sp
The use of reset on dbm associative arrays does not change the dbm file.
(It does, however, flush any entries cached by perl, which may be useful if
you are sharing the dbm file.
Then again, maybe not.)
.Ip "return LIST" 8 3
Returns from a subroutine with the value specified.
(Note that a subroutine can automatically return
the value of the last expression evaluated.
That's the preferred method\*(--use of an explicit
.I return
is a bit slower.)
.Ip "reverse(LIST)" 8 4
.Ip "reverse LIST" 8
In an array context, returns an array value consisting of the elements
of LIST in the opposite order.
In a scalar context, returns a string value consisting of the bytes of
the first element of LIST in the opposite order.
.Ip "rewinddir(DIRHANDLE)" 8 5
.Ip "rewinddir DIRHANDLE" 8
Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE.
.Ip "rindex(STR,SUBSTR,POSITION)" 8 6
.Ip "rindex(STR,SUBSTR)" 8 4
Works just like index except that it
returns the position of the LAST occurrence of SUBSTR in STR.
If POSITION is specified, returns the last occurrence at or before that
position.
.Ip "rmdir(FILENAME)" 8 4
.Ip "rmdir FILENAME" 8
Deletes the directory specified by FILENAME if it is empty.
If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
If FILENAME is omitted, uses $_.
.Ip "s/PATTERN/REPLACEMENT/gieo" 8 3
Searches a string for a pattern, and if found, replaces that pattern with the
replacement text and returns the number of substitutions made.
Otherwise it returns false (0).
The \*(L"g\*(R" is optional, and if present, indicates that all occurrences
of the pattern are to be replaced.
The \*(L"i\*(R" is also optional, and if present, indicates that matching
is to be done in a case-insensitive manner.
The \*(L"e\*(R" is likewise optional, and if present, indicates that
the replacement string is to be evaluated as an expression rather than just
as a double-quoted string.
Any non-alphanumeric delimiter may replace the slashes;
if single quotes are used, no
interpretation is done on the replacement string (the e modifier overrides
this, however); if backquotes are used, the replacement string is a command
to execute whose output will be used as the actual replacement text.
If no string is specified via the =~ or !~ operator,
the $_ string is searched and modified.
(The string specified with =~ must be a scalar variable, an array element,
or an assignment to one of those, i.e. an lvalue.)
If the pattern contains a $ that looks like a variable rather than an
end-of-string test, the variable will be interpolated into the pattern at
run-time.
If you only want the pattern compiled once the first time the variable is
interpolated, add an \*(L"o\*(R" at the end.
See also the section on regular expressions.
Examples:
.nf

    s/\|\e\|bgreen\e\|b/mauve/g;		# don't change wintergreen

    $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;

    s/Login: $foo/Login: $bar/; # run-time pattern

    ($foo = $bar) =~ s/bar/foo/;

    $_ = \'abc123xyz\';
    s/\ed+/$&*2/e;		# yields \*(L'abc246xyz\*(R'
    s/\ed+/sprintf("%5d",$&)/e;	# yields \*(L'abc  246xyz\*(R'
    s/\ew/$& x 2/eg;		# yields \*(L'aabbcc  224466xxyyzz\*(R'

    s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/;	# reverse 1st two fields

.fi
(Note the use of $ instead of \|\e\| in the last example.  See section
on regular expressions.)
.Ip "scalar(EXPR)" 8 3
Forces EXPR to be interpreted in a scalar context and returns the value
of EXPR.
.Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
Randomly positions the file pointer for FILEHANDLE, just like the fseek()
call of stdio.
FILEHANDLE may be an expression whose value gives the name of the filehandle.
Returns 1 upon success, 0 otherwise.
.Ip "seekdir(DIRHANDLE,POS)" 8 3
Sets the current position for the readdir() routine on DIRHANDLE.
POS must be a value returned by telldir().
Has the same caveats about possible directory compaction as the corresponding
system library routine.
.Ip "select(FILEHANDLE)" 8 3
.Ip "select" 8 3
Returns the currently selected filehandle.
Sets the current default filehandle for output, if FILEHANDLE is supplied.
This has two effects: first, a
.I write
or a
.I print
without a filehandle will default to this FILEHANDLE.
Second, references to variables related to output will refer to this output
channel.
For example, if you have to set the top of form format for more than
one output channel, you might do the following:
.nf

.ne 4
	select(REPORT1);
	$^ = \'report1_top\';
	select(REPORT2);
	$^ = \'report2_top\';

.fi
FILEHANDLE may be an expression whose value gives the name of the actual filehandle.
Thus:
.nf

	$oldfh = select(STDERR); $| = 1; select($oldfh);

.fi
.Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3
This calls the select system call with the bitmasks specified, which can
be constructed using fileno() and vec(), along these lines:
.nf

	$rin = $win = $ein = '';
	vec($rin,fileno(STDIN),1) = 1;
	vec($win,fileno(STDOUT),1) = 1;
	$ein = $rin | $win;

.fi
If you want to select on many filehandles you might wish to write a subroutine:
.nf

	sub fhbits {
	    local(@fhlist) = split(' ',$_[0]);
	    local($bits);
	    for (@fhlist) {
		vec($bits,fileno($_),1) = 1;
	    }
	    $bits;
	}
	$rin = &fhbits('STDIN TTY SOCK');

.fi
The usual idiom is:
.nf

	($nfound,$timeleft) =
	  select($rout=$rin, $wout=$win, $eout=$ein, $timeout);

or to block until something becomes ready:

.ie t \{\
	$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
'br\}
.el \{\
	$nfound = select($rout=$rin, $wout=$win,
				$eout=$ein, undef);
'br\}

.fi
Any of the bitmasks can also be undef.
The timeout, if specified, is in seconds, which may be fractional.
NOTE: not all implementations are capable of returning the $timeleft.
If not, they always return $timeleft equal to the supplied $timeout.
.Ip "semctl(ID,SEMNUM,CMD,ARG)" 8 4
Calls the System V IPC function semctl.  If CMD is &IPC_STAT or
&GETALL, then ARG must be a variable which will hold the returned
semid_ds structure or semaphore value array.  Returns like ioctl: the
undefined value for error, "0 but true" for zero, or the actual return
value otherwise.
.Ip "semget(KEY,NSEMS,SIZE,FLAGS)" 8 4
Calls the System V IPC function semget.  Returns the semaphore id, or
the undefined value if there is an error.
.Ip "semop(KEY,OPSTRING)" 8 4
Calls the System V IPC function semop to perform semaphore operations
such as signaling and waiting.  OPSTRING must be a packed array of
semop structures.  Each semop structure can be generated with
\&'pack("sss", $semnum, $semop, $semflag)'.  The number of semaphore
operations is implied by the length of OPSTRING.  Returns true if
successful, or false if there is an error.  As an example, the
following code waits on semaphore $semnum of semaphore id $semid:
.nf

	$semop = pack("sss", $semnum, -1, 0);
	die "Semaphore trouble: $!\en" unless semop($semid, $semop);

.fi
To signal the semaphore, replace "-1" with "1".
.Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4
.Ip "send(SOCKET,MSG,FLAGS)" 8
Sends a message on a socket.
Takes the same flags as the system call of the same name.
On unconnected sockets you must specify a destination to send TO.
Returns the number of characters sent, or the undefined value if
there is an error.
.Ip "setpgrp(PID,PGRP)" 8 4
Sets the current process group for the specified PID, 0 for the current
process.
Will produce a fatal error if used on a machine that doesn't implement
setpgrp(2).
.Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4
Sets the current priority for a process, a process group, or a user.
(See setpriority(2).)
Will produce a fatal error if used on a machine that doesn't implement
setpriority(2).
.Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3
Sets the socket option requested.
Returns undefined if there is an error.
OPTVAL may be specified as undef if you don't want to pass an argument.
.Ip "shift(ARRAY)" 8 6
.Ip "shift ARRAY" 8
.Ip "shift" 8
Shifts the first value of the array off and returns it,
shortening the array by 1 and moving everything down.
If there are no elements in the array, returns the undefined value.
If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_
array in subroutines.
(This is determined lexically.)
See also unshift(), push() and pop().
Shift() and unshift() do the same thing to the left end of an array that push()
and pop() do to the right end.
.Ip "shmctl(ID,CMD,ARG)" 8 4
Calls the System V IPC function shmctl.  If CMD is &IPC_STAT, then ARG
must be a variable which will hold the returned shmid_ds structure.
Returns like ioctl: the undefined value for error, "0 but true" for
zero, or the actual return value otherwise.
.Ip "shmget(KEY,SIZE,FLAGS)" 8 4
Calls the System V IPC function shmget.  Returns the shared memory
segment id, or the undefined value if there is an error.
.Ip "shmread(ID,VAR,POS,SIZE)" 8 4
.Ip "shmwrite(ID,STRING,POS,SIZE)" 8
Reads or writes the System V shared memory segment ID starting at
position POS for size SIZE by attaching to it, copying in/out, and
detaching from it.  When reading, VAR must be a variable which
will hold the data read.  When writing, if STRING is too long,
only SIZE bytes are used; if STRING is too short, nulls are
written to fill out SIZE bytes.  Return true if successful, or
false if there is an error.
.Ip "shutdown(SOCKET,HOW)" 8 3
Shuts down a socket connection in the manner indicated by HOW, which has
the same interpretation as in the system call of the same name.
.Ip "sin(EXPR)" 8 4
.Ip "sin EXPR" 8
Returns the sine of EXPR (expressed in radians).
If EXPR is omitted, returns sine of $_.
.Ip "sleep(EXPR)" 8 6
.Ip "sleep EXPR" 8
.Ip "sleep" 8
Causes the script to sleep for EXPR seconds, or forever if no EXPR.
May be interrupted by sending the process a SIGALARM.
Returns the number of seconds actually slept.
.Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3
Opens a socket of the specified kind and attaches it to filehandle SOCKET.
DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
of the same name.
You may need to run h2ph on sys/socket.h to get the proper values handy
in a perl library file.
Return true if successful.
See the example in the section on Interprocess Communication.
.Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3
Creates an unnamed pair of sockets in the specified domain, of the specified
type.
DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
of the same name.
If unimplemented, yields a fatal error.
Return true if successful.
.Ip "sort(SUBROUTINE LIST)" 8 9
.Ip "sort(LIST)" 8
.Ip "sort SUBROUTINE LIST" 8
.Ip "sort LIST" 8
Sorts the LIST and returns the sorted array value.
Nonexistent values of arrays are stripped out.
If SUBROUTINE is omitted, sorts in standard string comparison order.
If SUBROUTINE is specified, gives the name of a subroutine that returns
an integer less than, equal to, or greater than 0,
depending on how the elements of the array are to be ordered.
In the interests of efficiency the normal calling code for subroutines
is bypassed, with the following effects: the subroutine may not be a recursive
subroutine, and the two elements to be compared are passed into the subroutine
not via @_ but as $a and $b (see example below).
They are passed by reference so don't modify $a and $b.
SUBROUTINE may be a scalar variable name, in which case the value provides
the name of the subroutine to use.
Examples:
.nf

.ne 4
	sub byage {
	    $age{$a} - $age{$b};	# presuming integers
	}
	@sortedclass = sort byage @class;

.ne 9
	sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; }
	@harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\');
	@george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\');
	print sort @harry;
		# prints AbelCaincatdogx
	print sort reverse @harry;
		# prints xdogcatCainAbel
	print sort @george, \'to\', @harry;
		# prints AbelAxedCainPunishedcatchaseddoggonetoxyz

.fi
.Ip "splice(ARRAY,OFFSET,LENGTH,LIST)" 8 8
.Ip "splice(ARRAY,OFFSET,LENGTH)" 8
.Ip "splice(ARRAY,OFFSET)" 8
Removes the elements designated by OFFSET and LENGTH from an array, and
replaces them with the elements of LIST, if any.
Returns the elements removed from the array.
The array grows or shrinks as necessary.
If LENGTH is omitted, removes everything from OFFSET onward.
The following equivalencies hold (assuming $[ == 0):
.nf

	push(@a,$x,$y)\h'|3.5i'splice(@a,$#a+1,0,$x,$y)
	pop(@a)\h'|3.5i'splice(@a,-1)
	shift(@a)\h'|3.5i'splice(@a,0,1)
	unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y)
	$a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y);

Example, assuming array lengths are passed before arrays:
	
	sub aeq {	# compare two array values
		local(@a) = splice(@_,0,shift);
		local(@b) = splice(@_,0,shift);
		return 0 unless @a == @b;	# same len?
		while (@a) {
		    return 0 if pop(@a) ne pop(@b);
		}
		return 1;
	}
	if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }

.fi
.Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
.Ip "split(/PATTERN/,EXPR)" 8 8
.Ip "split(/PATTERN/)" 8
.Ip "split" 8
Splits a string into an array of strings, and returns it.
(If not in an array context, returns the number of fields found and splits
into the @_ array.
(In an array context, you can force the split into @_
by using ?? as the pattern delimiters, but it still returns the array value.))
If EXPR is omitted, splits the $_ string.
If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
Anything matching PATTERN is taken to be a delimiter separating the fields.
(Note that the delimiter may be longer than one character.)
If LIMIT is specified, splits into no more than that many fields (though it
may split into fewer).
If LIMIT is unspecified, trailing null fields are stripped (which
potential users of pop() would do well to remember).
A pattern matching the null string (not to be confused with a null pattern //,
which is just one member of the set of patterns matching a null string)
will split the value of EXPR into separate characters at each point it
matches that way.
For example:
.nf

	print join(\':\', split(/ */, \'hi there\'));

.fi
produces the output \*(L'h:i:t:h:e:r:e\*(R'.
.Sp
The LIMIT parameter can be used to partially split a line
.nf

	($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);

.fi
(When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one
larger than the number of variables in the list, to avoid unnecessary work.
For the list above LIMIT would have been 4 by default.
In time critical applications it behooves you not to split into
more fields than you really need.)
.Sp
If the PATTERN contains parentheses, additional array elements are created
from each matching substring in the delimiter.
.Sp
	split(/([,-])/,"1-10,20");
.Sp
produces the array value
.Sp
	(1,'-',10,',',20)
.Sp
The pattern /PATTERN/ may be replaced with an expression to specify patterns
that vary at runtime.
(To do runtime compilation only once, use /$variable/o.)
As a special case, specifying a space (\'\ \') will split on white space
just as split with no arguments does, but leading white space does NOT
produce a null first field.
Thus, split(\'\ \') can be used to emulate
.IR awk 's
default behavior, whereas
split(/\ /) will give you as many null initial fields as there are
leading spaces.
.Sp
Example:
.nf

.ne 5
	open(passwd, \'/etc/passwd\');
	while (<passwd>) {
.ie t \{\
		($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
'br\}
.el \{\
		($login, $passwd, $uid, $gid, $gcos, $home, $shell)
			= split(\|/\|:\|/\|);
'br\}
		.\|.\|.
	}

.fi
(Note that $shell above will still have a newline on it.  See chop().)
See also
.IR join .
.Ip "sprintf(FORMAT,LIST)" 8 4
Returns a string formatted by the usual printf conventions.
The * character is not supported.
.Ip "sqrt(EXPR)" 8 4
.Ip "sqrt EXPR" 8
Return the square root of EXPR.
If EXPR is omitted, returns square root of $_.
.Ip "srand(EXPR)" 8 4
.Ip "srand EXPR" 8
Sets the random number seed for the
.I rand
operator.
If EXPR is omitted, does srand(time).
.Ip "stat(FILEHANDLE)" 8 8
.Ip "stat FILEHANDLE" 8
.Ip "stat(EXPR)" 8
.Ip "stat SCALARVARIABLE" 8
Returns a 13-element array giving the statistics for a file, either the file
opened via FILEHANDLE, or named by EXPR.
Typically used as follows:
.nf

.ne 3
    ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
       $atime,$mtime,$ctime,$blksize,$blocks)
           = stat($filename);

.fi
If stat is passed the special filehandle consisting of an underline,
no stat is done, but the current contents of the stat structure from
the last stat or filetest are returned.
Example:
.nf

.ne 3
	if (-x $file && (($d) = stat(_)) && $d < 0) {
		print "$file is executable NFS file\en";
	}

.fi
.Ip "study(SCALAR)" 8 6
.Ip "study SCALAR" 8
.Ip "study"
Takes extra time to study SCALAR ($_ if unspecified) in anticipation of
doing many pattern matches on the string before it is next modified.
This may or may not save time, depending on the nature and number of patterns
you are searching on, and on the distribution of character frequencies in
the string to be searched\*(--you probably want to compare runtimes with and
without it to see which runs faster.
Those loops which scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most.
You may have only one study active at a time\*(--if you study a different
scalar the first is \*(L"unstudied\*(R".
(The way study works is this: a linked list of every character in the string
to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters
are.
From each search string, the rarest character is selected, based on some
static frequency tables constructed from some C programs and English text.
Only those places that contain this \*(L"rarest\*(R" character are examined.)
.Sp
For example, here is a loop which inserts index producing entries before any line
containing a certain pattern:
.nf

.ne 8
	while (<>) {
		study;
		print ".IX foo\en" if /\ebfoo\eb/;
		print ".IX bar\en" if /\ebbar\eb/;
		print ".IX blurfl\en" if /\ebblurfl\eb/;
		.\|.\|.
		print;
	}

.fi
In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R'
will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'.
In general, this is a big win except in pathological cases.
The only question is whether it saves you more time than it took to build
the linked list in the first place.
.Sp
Note that if you have to look for strings that you don't know till runtime,
you can build an entire loop as a string and eval that to avoid recompiling
all your patterns all the time.
Together with setting $/ to input entire files as one record, this can
be very fast, often faster than specialized programs like fgrep.
The following scans a list of files (@files)
for a list of words (@words), and prints out the names of those files that
contain a match:
.nf

.ne 12
	$search = \'while (<>) { study;\';
	foreach $word (@words) {
	    $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en";
	}
	$search .= "}";
	@ARGV = @files;
	$/ = "\e177";		# something that doesn't occur
	eval $search;		# this screams
	$/ = "\en";		# put back to normal input delim
	foreach $file (sort keys(%seen)) {
	    print $file, "\en";
	}

.fi
.Ip "substr(EXPR,OFFSET,LEN)" 8 2
.Ip "substr(EXPR,OFFSET)" 8 2
Extracts a substring out of EXPR and returns it.
First character is at offset 0, or whatever you've set $[ to.
If OFFSET is negative, starts that far from the end of the string.
If LEN is omitted, returns everything to the end of the string.
You can use the substr() function as an lvalue, in which case EXPR must
be an lvalue.
If you assign something shorter than LEN, the string will shrink, and
if you assign something longer than LEN, the string will grow to accommodate it.
To keep the string the same length you may need to pad or chop your value using
sprintf().
.Ip "symlink(OLDFILE,NEWFILE)" 8 2
Creates a new filename symbolically linked to the old filename.
Returns 1 for success, 0 otherwise.
On systems that don't support symbolic links, produces a fatal error at
run time.
To check for that, use eval:
.nf

	$symlink_exists = (eval \'symlink("","");\', $@ eq \'\');

.fi
.Ip "syscall(LIST)" 8 6
.Ip "syscall LIST" 8
Calls the system call specified as the first element of the list, passing
the remaining elements as arguments to the system call.
If unimplemented, produces a fatal error.
The arguments are interpreted as follows: if a given argument is numeric,
the argument is passed as an int.
If not, the pointer to the string value is passed.
You are responsible to make sure a string is pre-extended long enough
to receive any result that might be written into a string.
If your integer arguments are not literals and have never been interpreted
in a numeric context, you may need to add 0 to them to force them to look
like numbers.
.nf

	require 'syscall.ph';		# may need to run h2ph
	syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9);

.fi
.Ip "sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
.Ip "sysread(FILEHANDLE,SCALAR,LENGTH)" 8 5
Attempts to read LENGTH bytes of data into variable SCALAR from the specified
FILEHANDLE, using the system call read(2).
It bypasses stdio, so mixing this with other kinds of reads may cause
confusion.
Returns the number of bytes actually read, or undef if there was an error.
SCALAR will be grown or shrunk to the length actually read.
An OFFSET may be specified to place the read data at some other place
than the beginning of the string.
.Ip "system(LIST)" 8 6
.Ip "system LIST" 8
Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork
is done first, and the parent process waits for the child process to complete.
Note that argument processing varies depending on the number of arguments.
The return value is the exit status of the program as returned by the wait()
call.
To get the actual exit value divide by 256.
See also
.IR exec .
.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH)" 8 5
Attempts to write LENGTH bytes of data from variable SCALAR to the specified
FILEHANDLE, using the system call write(2).
It bypasses stdio, so mixing this with prints may cause
confusion.
Returns the number of bytes actually written, or undef if there was an error.
An OFFSET may be specified to place the read data at some other place
than the beginning of the string.
.Ip "tell(FILEHANDLE)" 8 6
.Ip "tell FILEHANDLE" 8 6
.Ip "tell" 8
Returns the current file position for FILEHANDLE.
FILEHANDLE may be an expression whose value gives the name of the actual
filehandle.
If FILEHANDLE is omitted, assumes the file last read.
.Ip "telldir(DIRHANDLE)" 8 5
.Ip "telldir DIRHANDLE" 8
Returns the current position of the readdir() routines on DIRHANDLE.
Value may be given to seekdir() to access a particular location in
a directory.
Has the same caveats about possible directory compaction as the corresponding
system library routine.
.Ip "time" 8 4
Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970.
Suitable for feeding to gmtime() and localtime().
.Ip "times" 8 4
Returns a four-element array giving the user and system times, in seconds, for this
process and the children of this process.
.Sp
    ($user,$system,$cuser,$csystem) = times;
.Sp
.Ip "tr/SEARCHLIST/REPLACEMENTLIST/cds" 8 5
.Ip "y/SEARCHLIST/REPLACEMENTLIST/cds" 8
Translates all occurrences of the characters found in the search list with
the corresponding character in the replacement list.
It returns the number of characters replaced or deleted.
If no string is specified via the =~ or !~ operator,
the $_ string is translated.
(The string specified with =~ must be a scalar variable, an array element,
or an assignment to one of those, i.e. an lvalue.)
For
.I sed
devotees,
.I y
is provided as a synonym for
.IR tr .
.Sp
If the c modifier is specified, the SEARCHLIST character set is complemented.
If the d modifier is specified, any characters specified by SEARCHLIST that
are not found in REPLACEMENTLIST are deleted.
(Note that this is slightly more flexible than the behavior of some
.I tr
programs, which delete anything they find in the SEARCHLIST, period.)
If the s modifier is specified, sequences of characters that were translated
to the same character are squashed down to 1 instance of the character.
.Sp
If the d modifier was used, the REPLACEMENTLIST is always interpreted exactly
as specified.
Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST,
the final character is replicated till it is long enough.
If the REPLACEMENTLIST is null, the SEARCHLIST is replicated.
This latter is useful for counting characters in a class, or for squashing
character sequences in a class.
.Sp
Examples:
.nf

    $ARGV[1] \|=~ \|y/A\-Z/a\-z/;	\h'|3i'# canonicalize to lower case

    $cnt = tr/*/*/;		\h'|3i'# count the stars in $_

    $cnt = tr/0\-9//;		\h'|3i'# count the digits in $_

    tr/a\-zA\-Z//s;	\h'|3i'# bookkeeper \-> bokeper

    ($HOST = $host) =~ tr/a\-z/A\-Z/;

    y/a\-zA\-Z/ /cs;	\h'|3i'# change non-alphas to single space

    tr/\e200\-\e377/\e0\-\e177/;\h'|3i'# delete 8th bit

.fi
.Ip "truncate(FILEHANDLE,LENGTH)" 8 4
.Ip "truncate(EXPR,LENGTH)" 8
Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified
length.
Produces a fatal error if truncate isn't implemented on your system.
.Ip "umask(EXPR)" 8 4
.Ip "umask EXPR" 8
.Ip "umask" 8
Sets the umask for the process and returns the old one.
If EXPR is omitted, merely returns current umask.
.Ip "undef(EXPR)" 8 6
.Ip "undef EXPR" 8
.Ip "undef" 8
Undefines the value of EXPR, which must be an lvalue.
Use only on a scalar value, an entire array, or a subroutine name (using &).
(Undef will probably not do what you expect on most predefined variables or
dbm array values.)
Always returns the undefined value.
You can omit the EXPR, in which case nothing is undefined, but you still
get an undefined value that you could, for instance, return from a subroutine.
Examples:
.nf

.ne 6
	undef $foo;
	undef $bar{'blurfl'};
	undef @ary;
	undef %assoc;
	undef &mysub;
	return (wantarray ? () : undef) if $they_blew_it;

.fi
.Ip "unlink(LIST)" 8 4
.Ip "unlink LIST" 8
Deletes a list of files.
Returns the number of files successfully deleted.
.nf

.ne 2
	$cnt = unlink \'a\', \'b\', \'c\';
	unlink @goners;
	unlink <*.bak>;

.fi
Note: unlink will not delete directories unless you are superuser and the
.B \-U
flag is supplied to
.IR perl .
Even if these conditions are met, be warned that unlinking a directory
can inflict damage on your filesystem.
Use rmdir instead.
.Ip "unpack(TEMPLATE,EXPR)" 8 4
Unpack does the reverse of pack: it takes a string representing
a structure and expands it out into an array value, returning the array
value.
(In a scalar context, it merely returns the first value produced.)
The TEMPLATE has the same format as in the pack function.
Here's a subroutine that does substring:
.nf

.ne 4
	sub substr {
		local($what,$where,$howmuch) = @_;
		unpack("x$where a$howmuch", $what);
	}

.ne 3
and then there's

	sub ord { unpack("c",$_[0]); }

.fi
In addition, you may prefix a field with a %<number> to indicate that
you want a <number>-bit checksum of the items instead of the items themselves.
Default is a 16-bit checksum.
For example, the following computes the same number as the System V sum program:
.nf

.ne 4
	while (<>) {
	    $checksum += unpack("%16C*", $_);
	}
	$checksum %= 65536;

.fi
.Ip "unshift(ARRAY,LIST)" 8 4
Does the opposite of a
.IR shift .
Or the opposite of a
.IR push ,
depending on how you look at it.
Prepends list to the front of the array, and returns the number of elements
in the new array.
.nf

	unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/;

.fi
.Ip "utime(LIST)" 8 2
.Ip "utime LIST" 8 2
Changes the access and modification times on each file of a list of files.
The first two elements of the list must be the NUMERICAL access and
modification times, in that order.
Returns the number of files successfully changed.
The inode modification time of each file is set to the current time.
Example of a \*(L"touch\*(R" command:
.nf

.ne 3
	#!/usr/bin/perl
	$now = time;
	utime $now, $now, @ARGV;

.fi
.Ip "values(ASSOC_ARRAY)" 8 6
.Ip "values ASSOC_ARRAY" 8
Returns a normal array consisting of all the values of the named associative
array.
The values are returned in an apparently random order, but it is the same order
as either the keys() or each() function would produce on the same array.
See also keys() and each().
.Ip "vec(EXPR,OFFSET,BITS)" 8 2
Treats a string as a vector of unsigned integers, and returns the value
of the bitfield specified.
May also be assigned to.
BITS must be a power of two from 1 to 32.
.Sp
Vectors created with vec() can also be manipulated with the logical operators
|, & and ^,
which will assume a bit vector operation is desired when both operands are
strings.
This interpretation is not enabled unless there is at least one vec() in
your program, to protect older programs.
.Sp
To transform a bit vector into a string or array of 0's and 1's, use these:
.nf

	$bits = unpack("b*", $vector);
	@bits = split(//, unpack("b*", $vector));

.fi
If you know the exact length in bits, it can be used in place of the *.
.Ip "wait" 8 6
Waits for a child process to terminate and returns the pid of the deceased
process, or -1 if there are no child processes.
The status is returned in $?.
.Ip "waitpid(PID,FLAGS)" 8 6
Waits for a particular child process to terminate and returns the pid of the deceased
process, or -1 if there is no such child process.
The status is returned in $?.
If you say
.nf

	require "sys/wait.h";
	.\|.\|.
	waitpid(-1,&WNOHANG);

.fi
then you can do a non-blocking wait for any process.  Non-blocking wait
is only available on machines supporting either the
.I waitpid (2)
or
.I wait4 (2)
system calls.
However, waiting for a particular pid with FLAGS of 0 is implemented
everywhere.  (Perl emulates the system call by remembering the status
values of processes that have exited but have not been harvested by the
Perl script yet.)
.Ip "wantarray" 8 4
Returns true if the context of the currently executing subroutine
is looking for an array value.
Returns false if the context is looking for a scalar.
.nf

	return wantarray ? () : undef;

.fi
.Ip "warn(LIST)" 8 4
.Ip "warn LIST" 8
Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
.Ip "write(FILEHANDLE)" 8 6
.Ip "write(EXPR)" 8
.Ip "write" 8
Writes a formatted record (possibly multi-line) to the specified file,
using the format associated with that file.
By default the format for a file is the one having the same name is the
filehandle, but the format for the current output channel (see
.IR select )
may be set explicitly
by assigning the name of the format to the $~ variable.
.Sp
Top of form processing is handled automatically:
if there is insufficient room on the current page for the formatted 
record, the page is advanced by writing a form feed,
a special top-of-page format is used
to format the new page header, and then the record is written.
By default the top-of-page format is \*(L"top\*(R", but it
may be set to the
format of your choice by assigning the name to the $^ variable.
The number of lines remaining on the current page is in variable $-, which
can be set to 0 to force a new page.
.Sp
If FILEHANDLE is unspecified, output goes to the current default output channel,
which starts out as
.I STDOUT
but may be changed by the
.I select
operator.
If the FILEHANDLE is an EXPR, then the expression is evaluated and the
resulting string is used to look up the name of the FILEHANDLE at run time.
For more on formats, see the section on formats later on.
.Sp
Note that write is NOT the opposite of read.