This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 4.0.00: (no release announcement available)
[perl5.git] / perl.man
CommitLineData
fe14fcc3
LW
1.rn '' }`
2''' $Header: perl.man,v 4.0 91/03/20 01:38:08 lwall Locked $
3'''
4''' $Log: perl.man,v $
5''' Revision 4.0 91/03/20 01:38:08 lwall
6''' 4.0 baseline.
7'''
8'''
9.de Sh
10.br
11.ne 5
12.PP
13\fB\\$1\fR
14.PP
15..
16.de Sp
17.if t .sp .5v
18.if n .sp
19..
20.de Ip
21.br
22.ie \\n(.$>=3 .ne \\$3
23.el .ne 3
24.IP "\\$1" \\$2
25..
26'''
27''' Set up \*(-- to give an unbreakable dash;
28''' string Tr holds user defined translation string.
29''' Bell System Logo is used as a dummy character.
30'''
31.tr \(*W-|\(bv\*(Tr
32.ie n \{\
33.ds -- \(*W-
34.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
35.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
36.ds L" ""
37.ds R" ""
38.ds L' '
39.ds R' '
40'br\}
41.el\{\
42.ds -- \(em\|
43.tr \*(Tr
44.ds L" ``
45.ds R" ''
46.ds L' `
47.ds R' '
48'br\}
49.TH PERL 1 "\*(RP"
50.UC
51.SH NAME
52perl \- Practical Extraction and Report Language
53.SH SYNOPSIS
54.B perl
55[options] filename args
56.SH DESCRIPTION
57.I Perl
58is an interpreted language optimized for scanning arbitrary text files,
59extracting information from those text files, and printing reports based
60on that information.
61It's also a good language for many system management tasks.
62The language is intended to be practical (easy to use, efficient, complete)
63rather than beautiful (tiny, elegant, minimal).
64It combines (in the author's opinion, anyway) some of the best features of C,
65\fIsed\fR, \fIawk\fR, and \fIsh\fR,
66so people familiar with those languages should have little difficulty with it.
67(Language historians will also note some vestiges of \fIcsh\fR, Pascal, and
68even BASIC-PLUS.)
69Expression syntax corresponds quite closely to C expression syntax.
70Unlike most Unix utilities,
71.I perl
72does not arbitrarily limit the size of your data\*(--if you've got
73the memory,
74.I perl
75can slurp in your whole file as a single string.
76Recursion is of unlimited depth.
77And the hash tables used by associative arrays grow as necessary to prevent
78degraded performance.
79.I Perl
80uses sophisticated pattern matching techniques to scan large amounts of
81data very quickly.
82Although optimized for scanning text,
83.I perl
84can also deal with binary data, and can make dbm files look like associative
85arrays (where dbm is available).
86Setuid
87.I perl
88scripts are safer than C programs
89through a dataflow tracing mechanism which prevents many stupid security holes.
90If you have a problem that would ordinarily use \fIsed\fR
91or \fIawk\fR or \fIsh\fR, but it
92exceeds their capabilities or must run a little faster,
93and you don't want to write the silly thing in C, then
94.I perl
95may be for you.
96There are also translators to turn your
97.I sed
98and
99.I awk
100scripts into
101.I perl
102scripts.
103OK, enough hype.
104.PP
105Upon startup,
106.I perl
107looks for your script in one of the following places:
108.Ip 1. 4 2
109Specified line by line via
110.B \-e
111switches on the command line.
112.Ip 2. 4 2
113Contained in the file specified by the first filename on the command line.
114(Note that systems supporting the #! notation invoke interpreters this way.)
115.Ip 3. 4 2
116Passed in implicitly via standard input.
117This only works if there are no filename arguments\*(--to pass
118arguments to a
119.I stdin
120script you must explicitly specify a \- for the script name.
121.PP
122After locating your script,
123.I perl
124compiles it to an internal form.
125If the script is syntactically correct, it is executed.
126.Sh "Options"
127Note: on first reading this section may not make much sense to you. It's here
128at the front for easy reference.
129.PP
130A single-character option may be combined with the following option, if any.
131This is particularly useful when invoking a script using the #! construct which
132only allows one argument. Example:
133.nf
134
135.ne 2
136 #!/usr/bin/perl \-spi.bak # same as \-s \-p \-i.bak
137 .\|.\|.
138
139.fi
140Options include:
141.TP 5
142.BI \-0 digits
143specifies the record separator ($/) as an octal number.
144If there are no digits, the null character is the separator.
145Other switches may precede or follow the digits.
146For example, if you have a version of
147.I find
148which can print filenames terminated by the null character, you can say this:
149.nf
150
151 find . \-name '*.bak' \-print0 | perl \-n0e unlink
152
153.fi
154The special value 00 will cause Perl to slurp files in paragraph mode.
155The value 0777 will cause Perl to slurp files whole since there is no
156legal character with that value.
157.TP 5
158.B \-a
159turns on autosplit mode when used with a
160.B \-n
161or
162.BR \-p .
163An implicit split command to the @F array
164is done as the first thing inside the implicit while loop produced by
165the
166.B \-n
167or
168.BR \-p .
169.nf
170
171 perl \-ane \'print pop(@F), "\en";\'
172
173is equivalent to
174
175 while (<>) {
176 @F = split(\' \');
177 print pop(@F), "\en";
178 }
179
180.fi
181.TP 5
182.B \-c
183causes
184.I perl
185to check the syntax of the script and then exit without executing it.
186.TP 5
187.BI \-d
188runs the script under the perl debugger.
189See the section on Debugging.
190.TP 5
191.BI \-D number
192sets debugging flags.
193To watch how it executes your script, use
194.BR \-D14 .
195(This only works if debugging is compiled into your
196.IR perl .)
197Another nice value is \-D1024, which lists your compiled syntax tree.
198And \-D512 displays compiled regular expressions.
199.TP 5
200.BI \-e " commandline"
201may be used to enter one line of script.
202Multiple
203.B \-e
204commands may be given to build up a multi-line script.
205If
206.B \-e
207is given,
208.I perl
209will not look for a script filename in the argument list.
210.TP 5
211.BI \-i extension
212specifies that files processed by the <> construct are to be edited
213in-place.
214It does this by renaming the input file, opening the output file by the
215same name, and selecting that output file as the default for print statements.
216The extension, if supplied, is added to the name of the
217old file to make a backup copy.
218If no extension is supplied, no backup is made.
219Saying \*(L"perl \-p \-i.bak \-e "s/foo/bar/;" .\|.\|. \*(R" is the same as using
220the script:
221.nf
222
223.ne 2
224 #!/usr/bin/perl \-pi.bak
225 s/foo/bar/;
226
227which is equivalent to
228
229.ne 14
230 #!/usr/bin/perl
231 while (<>) {
232 if ($ARGV ne $oldargv) {
233 rename($ARGV, $ARGV . \'.bak\');
234 open(ARGVOUT, ">$ARGV");
235 select(ARGVOUT);
236 $oldargv = $ARGV;
237 }
238 s/foo/bar/;
239 }
240 continue {
241 print; # this prints to original filename
242 }
243 select(STDOUT);
244
245.fi
246except that the
247.B \-i
248form doesn't need to compare $ARGV to $oldargv to know when
249the filename has changed.
250It does, however, use ARGVOUT for the selected filehandle.
251Note that
252.I STDOUT
253is restored as the default output filehandle after the loop.
254.Sp
255You can use eof to locate the end of each input file, in case you want
256to append to each file, or reset line numbering (see example under eof).
257.TP 5
258.BI \-I directory
259may be used in conjunction with
260.B \-P
261to tell the C preprocessor where to look for include files.
262By default /usr/include and /usr/lib/perl are searched.
263.TP 5
264.BI \-l octnum
265enables automatic line-ending processing. It has two effects:
266first, it automatically chops the line terminator when used with
267.B \-n
268or
269.B \-p ,
270and second, it assigns $\e to have the value of
271.I octnum
272so that any print statements will have that line terminator added back on. If
273.I octnum
274is omitted, sets $\e to the current value of $/.
275For instance, to trim lines to 80 columns:
276.nf
277
278 perl -lpe \'substr($_, 80) = ""\'
279
280.fi
281Note that the assignment $\e = $/ is done when the switch is processed,
282so the input record separator can be different than the output record
283separator if the
284.B \-l
285switch is followed by a
286.B \-0
287switch:
288.nf
289
290 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
291
292.fi
293This sets $\e to newline and then sets $/ to the null character.
294.TP 5
295.B \-n
296causes
297.I perl
298to assume the following loop around your script, which makes it iterate
299over filename arguments somewhat like \*(L"sed \-n\*(R" or \fIawk\fR:
300.nf
301
302.ne 3
303 while (<>) {
304 .\|.\|. # your script goes here
305 }
306
307.fi
308Note that the lines are not printed by default.
309See
310.B \-p
311to have lines printed.
312Here is an efficient way to delete all files older than a week:
313.nf
314
315 find . \-mtime +7 \-print | perl \-nle \'unlink;\'
316
317.fi
318This is faster than using the \-exec switch of find because you don't have to
319start a process on every filename found.
320.TP 5
321.B \-p
322causes
323.I perl
324to assume the following loop around your script, which makes it iterate
325over filename arguments somewhat like \fIsed\fR:
326.nf
327
328.ne 5
329 while (<>) {
330 .\|.\|. # your script goes here
331 } continue {
332 print;
333 }
334
335.fi
336Note that the lines are printed automatically.
337To suppress printing use the
338.B \-n
339switch.
340A
341.B \-p
342overrides a
343.B \-n
344switch.
345.TP 5
346.B \-P
347causes your script to be run through the C preprocessor before
348compilation by
349.IR perl .
350(Since both comments and cpp directives begin with the # character,
351you should avoid starting comments with any words recognized
352by the C preprocessor such as \*(L"if\*(R", \*(L"else\*(R" or \*(L"define\*(R".)
353.TP 5
354.B \-s
355enables some rudimentary switch parsing for switches on the command line
356after the script name but before any filename arguments (or before a \-\|\-).
357Any switch found there is removed from @ARGV and sets the corresponding variable in the
358.I perl
359script.
360The following script prints \*(L"true\*(R" if and only if the script is
361invoked with a \-xyz switch.
362.nf
363
364.ne 2
365 #!/usr/bin/perl \-s
366 if ($xyz) { print "true\en"; }
367
368.fi
369.TP 5
370.B \-S
371makes
372.I perl
373use the PATH environment variable to search for the script
374(unless the name of the script starts with a slash).
375Typically this is used to emulate #! startup on machines that don't
376support #!, in the following manner:
377.nf
378
379 #!/usr/bin/perl
380 eval "exec /usr/bin/perl \-S $0 $*"
381 if $running_under_some_shell;
382
383.fi
384The system ignores the first line and feeds the script to /bin/sh,
385which proceeds to try to execute the
386.I perl
387script as a shell script.
388The shell executes the second line as a normal shell command, and thus
389starts up the
390.I perl
391interpreter.
392On some systems $0 doesn't always contain the full pathname,
393so the
394.B \-S
395tells
396.I perl
397to search for the script if necessary.
398After
399.I perl
400locates the script, it parses the lines and ignores them because
401the variable $running_under_some_shell is never true.
402A better construct than $* would be ${1+"$@"}, which handles embedded spaces
403and such in the filenames, but doesn't work if the script is being interpreted
404by csh.
405In order to start up sh rather than csh, some systems may have to replace the
406#! line with a line containing just
407a colon, which will be politely ignored by perl.
408Other systems can't control that, and need a totally devious construct that
409will work under any of csh, sh or perl, such as the following:
410.nf
411
412.ne 3
413 eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
414 & eval 'exec /usr/bin/perl -S $0 $argv:q'
415 if 0;
416
417.fi
418.TP 5
419.B \-u
420causes
421.I perl
422to dump core after compiling your script.
423You can then take this core dump and turn it into an executable file
424by using the undump program (not supplied).
425This speeds startup at the expense of some disk space (which you can
426minimize by stripping the executable).
427(Still, a "hello world" executable comes out to about 200K on my machine.)
428If you are going to run your executable as a set-id program then you
429should probably compile it using taintperl rather than normal perl.
430If you want to execute a portion of your script before dumping, use the
431dump operator instead.
432Note: availability of undump is platform specific and may not be available
433for a specific port of perl.
434.TP 5
435.B \-U
436allows
437.I perl
438to do unsafe operations.
439Currently the only \*(L"unsafe\*(R" operation is the unlinking of directories while
440running as superuser.
441.TP 5
442.B \-v
443prints the version and patchlevel of your
444.I perl
445executable.
446.TP 5
447.B \-w
448prints warnings about identifiers that are mentioned only once, and scalar
449variables that are used before being set.
450Also warns about redefined subroutines, and references to undefined
451filehandles or filehandles opened readonly that you are attempting to
452write on.
453Also warns you if you use == on values that don't look like numbers, and if
454your subroutines recurse more than 100 deep.
455.TP 5
456.BI \-x directory
457tells
458.I perl
459that the script is embedded in a message.
460Leading garbage will be discarded until the first line that starts
461with #! and contains the string "perl".
462Any meaningful switches on that line will be applied (but only one
463group of switches, as with normal #! processing).
464If a directory name is specified, Perl will switch to that directory
465before running the script.
466The
467.B \-x
468switch only controls the the disposal of leading garbage.
469The script must be terminated with __END__ if there is trailing garbage
470to be ignored (the script can process any or all of the trailing garbage
471via the DATA filehandle if desired).
472.Sh "Data Types and Objects"
473.PP
474.I Perl
475has three data types: scalars, arrays of scalars, and
476associative arrays of scalars.
477Normal arrays are indexed by number, and associative arrays by string.
478.PP
479The interpretation of operations and values in perl sometimes
480depends on the requirements
481of the context around the operation or value.
482There are three major contexts: string, numeric and array.
483Certain operations return array values
484in contexts wanting an array, and scalar values otherwise.
485(If this is true of an operation it will be mentioned in the documentation
486for that operation.)
487Operations which return scalars don't care whether the context is looking
488for a string or a number, but
489scalar variables and values are interpreted as strings or numbers
490as appropriate to the context.
491A scalar is interpreted as TRUE in the boolean sense if it is not the null
492string or 0.
493Booleans returned by operators are 1 for true and 0 or \'\' (the null
494string) for false.
495.PP
496There are actually two varieties of null string: defined and undefined.
497Undefined null strings are returned when there is no real value for something,
498such as when there was an error, or at end of file, or when you refer
499to an uninitialized variable or element of an array.
500An undefined null string may become defined the first time you access it, but
501prior to that you can use the defined() operator to determine whether the
502value is defined or not.
503.PP
504References to scalar variables always begin with \*(L'$\*(R', even when referring
505to a scalar that is part of an array.
506Thus:
507.nf
508
509.ne 3
510 $days \h'|2i'# a simple scalar variable
511 $days[28] \h'|2i'# 29th element of array @days
512 $days{\'Feb\'}\h'|2i'# one value from an associative array
513 $#days \h'|2i'# last index of array @days
514
515but entire arrays or array slices are denoted by \*(L'@\*(R':
516
517 @days \h'|2i'# ($days[0], $days[1],\|.\|.\|. $days[n])
518 @days[3,4,5]\h'|2i'# same as @days[3.\|.5]
519 @days{'a','c'}\h'|2i'# same as ($days{'a'},$days{'c'})
520
521and entire associative arrays are denoted by \*(L'%\*(R':
522
523 %days \h'|2i'# (key1, val1, key2, val2 .\|.\|.)
524.fi
525.PP
526Any of these eight constructs may serve as an lvalue,
527that is, may be assigned to.
528(It also turns out that an assignment is itself an lvalue in
529certain contexts\*(--see examples under s, tr and chop.)
530Assignment to a scalar evaluates the righthand side in a scalar context,
531while assignment to an array or array slice evaluates the righthand side
532in an array context.
533.PP
534You may find the length of array @days by evaluating
535\*(L"$#days\*(R", as in
536.IR csh .
537(Actually, it's not the length of the array, it's the subscript of the last element, since there is (ordinarily) a 0th element.)
538Assigning to $#days changes the length of the array.
539Shortening an array by this method does not actually destroy any values.
540Lengthening an array that was previously shortened recovers the values that
541were in those elements.
542You can also gain some measure of efficiency by preextending an array that
543is going to get big.
544(You can also extend an array by assigning to an element that is off the
545end of the array.
546This differs from assigning to $#whatever in that intervening values
547are set to null rather than recovered.)
548You can truncate an array down to nothing by assigning the null list () to
549it.
550The following are exactly equivalent
551.nf
552
553 @whatever = ();
554 $#whatever = $[ \- 1;
555
556.fi
557.PP
558If you evaluate an array in a scalar context, it returns the length of
559the array.
560The following is always true:
561.nf
562
563 @whatever == $#whatever \- $[ + 1;
564
565.fi
566.PP
567Multi-dimensional arrays are not directly supported, but see the discussion
568of the $; variable later for a means of emulating multiple subscripts with
569an associative array.
570You could also write a subroutine to turn multiple subscripts into a single
571subscript.
572.PP
573Every data type has its own namespace.
574You can, without fear of conflict, use the same name for a scalar variable,
575an array, an associative array, a filehandle, a subroutine name, and/or
576a label.
577Since variable and array references always start with \*(L'$\*(R', \*(L'@\*(R',
578or \*(L'%\*(R', the \*(L"reserved\*(R" words aren't in fact reserved
579with respect to variable names.
580(They ARE reserved with respect to labels and filehandles, however, which
581don't have an initial special character.
582Hint: you could say open(LOG,\'logfile\') rather than open(log,\'logfile\').
583Using uppercase filehandles also improves readability and protects you
584from conflict with future reserved words.)
585Case IS significant\*(--\*(L"FOO\*(R", \*(L"Foo\*(R" and \*(L"foo\*(R" are all
586different names.
587Names which start with a letter may also contain digits and underscores.
588Names which do not start with a letter are limited to one character,
589e.g. \*(L"$%\*(R" or \*(L"$$\*(R".
590(Most of the one character names have a predefined significance to
591.IR perl .
592More later.)
593.PP
594Numeric literals are specified in any of the usual floating point or
595integer formats:
596.nf
597
598.ne 5
599 12345
600 12345.67
601 .23E-10
602 0xffff # hex
603 0377 # octal
604
605.fi
606String literals are delimited by either single or double quotes.
607They work much like shell quotes:
608double-quoted string literals are subject to backslash and variable
609substitution; single-quoted strings are not (except for \e\' and \e\e).
610The usual backslash rules apply for making characters such as newline, tab,
611etc., as well as some more exotic forms:
612.nf
613
614 \et tab
615 \en newline
616 \er return
617 \ef form feed
618 \eb backspace
619 \ea alarm (bell)
620 \ee escape
621 \e033 octal char
622 \ex1b hex char
623 \ec[ control char
624 \el lowercase next char
625 \eu uppercase next char
626 \eL lowercase till \eE
627 \eU uppercase till \eE
628 \eE end case modification
629
630.fi
631You can also embed newlines directly in your strings, i.e. they can end on
632a different line than they begin.
633This is nice, but if you forget your trailing quote, the error will not be
634reported until
635.I perl
636finds another line containing the quote character, which
637may be much further on in the script.
638Variable substitution inside strings is limited to scalar variables, normal
639array values, and array slices.
640(In other words, identifiers beginning with $ or @, followed by an optional
641bracketed expression as a subscript.)
642The following code segment prints out \*(L"The price is $100.\*(R"
643.nf
644
645.ne 2
646 $Price = \'$100\';\h'|3.5i'# not interpreted
647 print "The price is $Price.\e\|n";\h'|3.5i'# interpreted
648
649.fi
650Note that you can put curly brackets around the identifier to delimit it
651from following alphanumerics.
652Also note that a single quoted string must be separated from a preceding
653word by a space, since single quote is a valid character in an identifier
654(see Packages).
655.PP
656Two special literals are __LINE__ and __FILE__, which represent the current
657line number and filename at that point in your program.
658They may only be used as separate tokens; they will not be interpolated
659into strings.
660In addition, the token __END__ may be used to indicate the logical end of the
661script before the actual end of file.
662Any following text is ignored (but may be read via the DATA filehandle).
663The two control characters ^D and ^Z are synonyms for __END__.
664.PP
665A word that doesn't have any other interpretation in the grammar will be
666treated as if it had single quotes around it.
667For this purpose, a word consists only of alphanumeric characters and underline,
668and must start with an alphabetic character.
669As with filehandles and labels, a bare word that consists entirely of
670lowercase letters risks conflict with future reserved words, and if you
671use the
672.B \-w
673switch, Perl will warn you about any such words.
674.PP
675Array values are interpolated into double-quoted strings by joining all the
676elements of the array with the delimiter specified in the $" variable,
677space by default.
678(Since in versions of perl prior to 3.0 the @ character was not a metacharacter
679in double-quoted strings, the interpolation of @array, $array[EXPR],
680@array[LIST], $array{EXPR}, or @array{LIST} only happens if array is
681referenced elsewhere in the program or is predefined.)
682The following are equivalent:
683.nf
684
685.ne 4
686 $temp = join($",@ARGV);
687 system "echo $temp";
688
689 system "echo @ARGV";
690
691.fi
692Within search patterns (which also undergo double-quotish substitution)
693there is a bad ambiguity: Is /$foo[bar]/ to be
694interpreted as /${foo}[bar]/ (where [bar] is a character class for the
695regular expression) or as /${foo[bar]}/ (where [bar] is the subscript to
696array @foo)?
697If @foo doesn't otherwise exist, then it's obviously a character class.
698If @foo exists, perl takes a good guess about [bar], and is almost always right.
699If it does guess wrong, or if you're just plain paranoid,
700you can force the correct interpretation with curly brackets as above.
701.PP
702A line-oriented form of quoting is based on the shell here-is syntax.
703Following a << you specify a string to terminate the quoted material, and all lines
704following the current line down to the terminating string are the value
705of the item.
706The terminating string may be either an identifier (a word), or some
707quoted text.
708If quoted, the type of quotes you use determines the treatment of the text,
709just as in regular quoting.
710An unquoted identifier works like double quotes.
711There must be no space between the << and the identifier.
712(If you put a space it will be treated as a null identifier, which is
713valid, and matches the first blank line\*(--see Merry Christmas example below.)
714The terminating string must appear by itself (unquoted and with no surrounding
715whitespace) on the terminating line.
716.nf
717
718 print <<EOF; # same as above
719The price is $Price.
720EOF
721
722 print <<"EOF"; # same as above
723The price is $Price.
724EOF
725
726 print << x 10; # null identifier is delimiter
727Merry Christmas!
728
729 print <<`EOC`; # execute commands
730echo hi there
731echo lo there
732EOC
733
734 print <<foo, <<bar; # you can stack them
735I said foo.
736foo
737I said bar.
738bar
739
740.fi
741Array literals are denoted by separating individual values by commas, and
742enclosing the list in parentheses:
743.nf
744
745 (LIST)
746
747.fi
748In a context not requiring an array value, the value of the array literal
749is the value of the final element, as in the C comma operator.
750For example,
751.nf
752
753.ne 4
754 @foo = (\'cc\', \'\-E\', $bar);
755
756assigns the entire array value to array foo, but
757
758 $foo = (\'cc\', \'\-E\', $bar);
759
760.fi
761assigns the value of variable bar to variable foo.
762Note that the value of an actual array in a scalar context is the length
763of the array; the following assigns to $foo the value 3:
764.nf
765
766.ne 2
767 @foo = (\'cc\', \'\-E\', $bar);
768 $foo = @foo; # $foo gets 3
769
770.fi
771You may have an optional comma before the closing parenthesis of an
772array literal, so that you can say:
773.nf
774
775 @foo = (
776 1,
777 2,
778 3,
779 );
780
781.fi
782When a LIST is evaluated, each element of the list is evaluated in
783an array context, and the resulting array value is interpolated into LIST
784just as if each individual element were a member of LIST. Thus arrays
785lose their identity in a LIST\*(--the list
786
787 (@foo,@bar,&SomeSub)
788
789contains all the elements of @foo followed by all the elements of @bar,
790followed by all the elements returned by the subroutine named SomeSub.
791.PP
792A list value may also be subscripted like a normal array.
793Examples:
794.nf
795
796 $time = (stat($file))[8]; # stat returns array value
797 $digit = ('a','b','c','d','e','f')[$digit-10];
798 return (pop(@foo),pop(@foo))[0];
799
800.fi
801.PP
802Array lists may be assigned to if and only if each element of the list
803is an lvalue:
804.nf
805
806 ($a, $b, $c) = (1, 2, 3);
807
808 ($map{\'red\'}, $map{\'blue\'}, $map{\'green\'}) = (0x00f, 0x0f0, 0xf00);
809
810The final element may be an array or an associative array:
811
812 ($a, $b, @rest) = split;
813 local($a, $b, %rest) = @_;
814
815.fi
816You can actually put an array anywhere in the list, but the first array
817in the list will soak up all the values, and anything after it will get
818a null value.
819This may be useful in a local().
820.PP
821An associative array literal contains pairs of values to be interpreted
822as a key and a value:
823.nf
824
825.ne 2
826 # same as map assignment above
827 %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
828
829.fi
830Array assignment in a scalar context returns the number of elements
831produced by the expression on the right side of the assignment:
832.nf
833
834 $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2
835
836.fi
837.PP
838There are several other pseudo-literals that you should know about.
839If a string is enclosed by backticks (grave accents), it first undergoes
840variable substitution just like a double quoted string.
841It is then interpreted as a command, and the output of that command
842is the value of the pseudo-literal, like in a shell.
843In a scalar context, a single string consisting of all the output is
844returned.
845In an array context, an array of values is returned, one for each line
846of output.
847(You can set $/ to use a different line terminator.)
848The command is executed each time the pseudo-literal is evaluated.
849The status value of the command is returned in $? (see Predefined Names
850for the interpretation of $?).
851Unlike in \f2csh\f1, no translation is done on the return
852data\*(--newlines remain newlines.
853Unlike in any of the shells, single quotes do not hide variable names
854in the command from interpretation.
855To pass a $ through to the shell you need to hide it with a backslash.
856.PP
857Evaluating a filehandle in angle brackets yields the next line
858from that file (newline included, so it's never false until EOF, at
859which time an undefined value is returned).
860Ordinarily you must assign that value to a variable,
861but there is one situation where an automatic assignment happens.
862If (and only if) the input symbol is the only thing inside the conditional of a
863.I while
864loop, the value is
865automatically assigned to the variable \*(L"$_\*(R".
866(This may seem like an odd thing to you, but you'll use the construct
867in almost every
868.I perl
869script you write.)
870Anyway, the following lines are equivalent to each other:
871.nf
872
873.ne 5
874 while ($_ = <STDIN>) { print; }
875 while (<STDIN>) { print; }
876 for (\|;\|<STDIN>;\|) { print; }
877 print while $_ = <STDIN>;
878 print while <STDIN>;
879
880.fi
881The filehandles
882.IR STDIN ,
883.I STDOUT
884and
885.I STDERR
886are predefined.
887(The filehandles
888.IR stdin ,
889.I stdout
890and
891.I stderr
892will also work except in packages, where they would be interpreted as
893local identifiers rather than global.)
894Additional filehandles may be created with the
895.I open
896function.
897.PP
898If a <FILEHANDLE> is used in a context that is looking for an array, an array
899consisting of all the input lines is returned, one line per array element.
900It's easy to make a LARGE data space this way, so use with care.
901.PP
902The null filehandle <> is special and can be used to emulate the behavior of
903\fIsed\fR and \fIawk\fR.
904Input from <> comes either from standard input, or from each file listed on
905the command line.
906Here's how it works: the first time <> is evaluated, the ARGV array is checked,
907and if it is null, $ARGV[0] is set to \'-\', which when opened gives you standard
908input.
909The ARGV array is then processed as a list of filenames.
910The loop
911.nf
912
913.ne 3
914 while (<>) {
915 .\|.\|. # code for each line
916 }
917
918.ne 10
919is equivalent to
920
921 unshift(@ARGV, \'\-\') \|if \|$#ARGV < $[;
922 while ($ARGV = shift) {
923 open(ARGV, $ARGV);
924 while (<ARGV>) {
925 .\|.\|. # code for each line
926 }
927 }
928
929.fi
930except that it isn't as cumbersome to say.
931It really does shift array ARGV and put the current filename into
932variable ARGV.
933It also uses filehandle ARGV internally.
934You can modify @ARGV before the first <> as long as you leave the first
935filename at the beginning of the array.
936Line numbers ($.) continue as if the input was one big happy file.
937(But see example under eof for how to reset line numbers on each file.)
938.PP
939.ne 5
940If you want to set @ARGV to your own list of files, go right ahead.
941If you want to pass switches into your script, you can
942put a loop on the front like this:
943.nf
944
945.ne 10
946 while ($_ = $ARGV[0], /\|^\-/\|) {
947 shift;
948 last if /\|^\-\|\-$\|/\|;
949 /\|^\-D\|(.*\|)/ \|&& \|($debug = $1);
950 /\|^\-v\|/ \|&& \|$verbose++;
951 .\|.\|. # other switches
952 }
953 while (<>) {
954 .\|.\|. # code for each line
955 }
956
957.fi
958The <> symbol will return FALSE only once.
959If you call it again after this it will assume you are processing another
960@ARGV list, and if you haven't set @ARGV, will input from
961.IR STDIN .
962.PP
963If the string inside the angle brackets is a reference to a scalar variable
964(e.g. <$foo>),
965then that variable contains the name of the filehandle to input from.
966.PP
967If the string inside angle brackets is not a filehandle, it is interpreted
968as a filename pattern to be globbed, and either an array of filenames or the
969next filename in the list is returned, depending on context.
970One level of $ interpretation is done first, but you can't say <$foo>
971because that's an indirect filehandle as explained in the previous
972paragraph.
973You could insert curly brackets to force interpretation as a
974filename glob: <${foo}>.
975Example:
976.nf
977
978.ne 3
979 while (<*.c>) {
980 chmod 0644, $_;
981 }
982
983is equivalent to
984
985.ne 5
986 open(foo, "echo *.c | tr \-s \' \et\er\ef\' \'\e\e012\e\e012\e\e012\e\e012\'|");
987 while (<foo>) {
988 chop;
989 chmod 0644, $_;
990 }
991
992.fi
993In fact, it's currently implemented that way.
994(Which means it will not work on filenames with spaces in them unless
995you have /bin/csh on your machine.)
996Of course, the shortest way to do the above is:
997.nf
998
999 chmod 0644, <*.c>;
1000
1001.fi
1002.Sh "Syntax"
1003.PP
1004A
1005.I perl
1006script consists of a sequence of declarations and commands.
1007The only things that need to be declared in
1008.I perl
1009are report formats and subroutines.
1010See the sections below for more information on those declarations.
1011All uninitialized user-created objects are assumed to
1012start with a null or 0 value until they
1013are defined by some explicit operation such as assignment.
1014The sequence of commands is executed just once, unlike in
1015.I sed
1016and
1017.I awk
1018scripts, where the sequence of commands is executed for each input line.
1019While this means that you must explicitly loop over the lines of your input file
1020(or files), it also means you have much more control over which files and which
1021lines you look at.
1022(Actually, I'm lying\*(--it is possible to do an implicit loop with either the
1023.B \-n
1024or
1025.B \-p
1026switch.)
1027.PP
1028A declaration can be put anywhere a command can, but has no effect on the
1029execution of the primary sequence of commands\*(--declarations all take effect
1030at compile time.
1031Typically all the declarations are put at the beginning or the end of the script.
1032.PP
1033.I Perl
1034is, for the most part, a free-form language.
1035(The only exception to this is format declarations, for fairly obvious reasons.)
1036Comments are indicated by the # character, and extend to the end of the line.
1037If you attempt to use /* */ C comments, it will be interpreted either as
1038division or pattern matching, depending on the context.
1039So don't do that.
1040.Sh "Compound statements"
1041In
1042.IR perl ,
1043a sequence of commands may be treated as one command by enclosing it
1044in curly brackets.
1045We will call this a BLOCK.
1046.PP
1047The following compound commands may be used to control flow:
1048.nf
1049
1050.ne 4
1051 if (EXPR) BLOCK
1052 if (EXPR) BLOCK else BLOCK
1053 if (EXPR) BLOCK elsif (EXPR) BLOCK .\|.\|. else BLOCK
1054 LABEL while (EXPR) BLOCK
1055 LABEL while (EXPR) BLOCK continue BLOCK
1056 LABEL for (EXPR; EXPR; EXPR) BLOCK
1057 LABEL foreach VAR (ARRAY) BLOCK
1058 LABEL BLOCK continue BLOCK
1059
1060.fi
1061Note that, unlike C and Pascal, these are defined in terms of BLOCKs, not
1062statements.
1063This means that the curly brackets are \fIrequired\fR\*(--no dangling statements allowed.
1064If you want to write conditionals without curly brackets there are several
1065other ways to do it.
1066The following all do the same thing:
1067.nf
1068
1069.ne 5
1070 if (!open(foo)) { die "Can't open $foo: $!"; }
1071 die "Can't open $foo: $!" unless open(foo);
1072 open(foo) || die "Can't open $foo: $!"; # foo or bust!
1073 open(foo) ? \'hi mom\' : die "Can't open $foo: $!";
1074 # a bit exotic, that last one
1075
1076.fi
1077.PP
1078The
1079.I if
1080statement is straightforward.
1081Since BLOCKs are always bounded by curly brackets, there is never any
1082ambiguity about which
1083.I if
1084an
1085.I else
1086goes with.
1087If you use
1088.I unless
1089in place of
1090.IR if ,
1091the sense of the test is reversed.
1092.PP
1093The
1094.I while
1095statement executes the block as long as the expression is true
1096(does not evaluate to the null string or 0).
1097The LABEL is optional, and if present, consists of an identifier followed by
1098a colon.
1099The LABEL identifies the loop for the loop control statements
1100.IR next ,
1101.IR last ,
1102and
1103.I redo
1104(see below).
1105If there is a
1106.I continue
1107BLOCK, it is always executed just before
1108the conditional is about to be evaluated again, similarly to the third part
1109of a
1110.I for
1111loop in C.
1112Thus it can be used to increment a loop variable, even when the loop has
1113been continued via the
1114.I next
1115statement (similar to the C \*(L"continue\*(R" statement).
1116.PP
1117If the word
1118.I while
1119is replaced by the word
1120.IR until ,
1121the sense of the test is reversed, but the conditional is still tested before
1122the first iteration.
1123.PP
1124In either the
1125.I if
1126or the
1127.I while
1128statement, you may replace \*(L"(EXPR)\*(R" with a BLOCK, and the conditional
1129is true if the value of the last command in that block is true.
1130.PP
1131The
1132.I for
1133loop works exactly like the corresponding
1134.I while
1135loop:
1136.nf
1137
1138.ne 12
1139 for ($i = 1; $i < 10; $i++) {
1140 .\|.\|.
1141 }
1142
1143is the same as
1144
1145 $i = 1;
1146 while ($i < 10) {
1147 .\|.\|.
1148 } continue {
1149 $i++;
1150 }
1151.fi
1152.PP
1153The foreach loop iterates over a normal array value and sets the variable
1154VAR to be each element of the array in turn.
1155The variable is implicitly local to the loop, and regains its former value
1156upon exiting the loop.
1157The \*(L"foreach\*(R" keyword is actually identical to the \*(L"for\*(R" keyword,
1158so you can use \*(L"foreach\*(R" for readability or \*(L"for\*(R" for brevity.
1159If VAR is omitted, $_ is set to each value.
1160If ARRAY is an actual array (as opposed to an expression returning an array
1161value), you can modify each element of the array
1162by modifying VAR inside the loop.
1163Examples:
1164.nf
1165
1166.ne 5
1167 for (@ary) { s/foo/bar/; }
1168
1169 foreach $elem (@elements) {
1170 $elem *= 2;
1171 }
1172
1173.ne 3
1174 for ((10,9,8,7,6,5,4,3,2,1,\'BOOM\')) {
1175 print $_, "\en"; sleep(1);
1176 }
1177
1178 for (1..15) { print "Merry Christmas\en"; }
1179
1180.ne 3
1181 foreach $item (split(/:[\e\e\en:]*/, $ENV{\'TERMCAP\'})) {
1182 print "Item: $item\en";
1183 }
1184
1185.fi
1186.PP
1187The BLOCK by itself (labeled or not) is equivalent to a loop that executes
1188once.
1189Thus you can use any of the loop control statements in it to leave or
1190restart the block.
1191The
1192.I continue
1193block is optional.
1194This construct is particularly nice for doing case structures.
1195.nf
1196
1197.ne 6
1198 foo: {
1199 if (/^abc/) { $abc = 1; last foo; }
1200 if (/^def/) { $def = 1; last foo; }
1201 if (/^xyz/) { $xyz = 1; last foo; }
1202 $nothing = 1;
1203 }
1204
1205.fi
1206There is no official switch statement in perl, because there
1207are already several ways to write the equivalent.
1208In addition to the above, you could write
1209.nf
1210
1211.ne 6
1212 foo: {
1213 $abc = 1, last foo if /^abc/;
1214 $def = 1, last foo if /^def/;
1215 $xyz = 1, last foo if /^xyz/;
1216 $nothing = 1;
1217 }
1218
1219or
1220
1221.ne 6
1222 foo: {
1223 /^abc/ && do { $abc = 1; last foo; };
1224 /^def/ && do { $def = 1; last foo; };
1225 /^xyz/ && do { $xyz = 1; last foo; };
1226 $nothing = 1;
1227 }
1228
1229or
1230
1231.ne 6
1232 foo: {
1233 /^abc/ && ($abc = 1, last foo);
1234 /^def/ && ($def = 1, last foo);
1235 /^xyz/ && ($xyz = 1, last foo);
1236 $nothing = 1;
1237 }
1238
1239or even
1240
1241.ne 8
1242 if (/^abc/)
1243 { $abc = 1; }
1244 elsif (/^def/)
1245 { $def = 1; }
1246 elsif (/^xyz/)
1247 { $xyz = 1; }
1248 else
1249 {$nothing = 1;}
1250
1251.fi
1252As it happens, these are all optimized internally to a switch structure,
1253so perl jumps directly to the desired statement, and you needn't worry
1254about perl executing a lot of unnecessary statements when you have a string
1255of 50 elsifs, as long as you are testing the same simple scalar variable
1256using ==, eq, or pattern matching as above.
1257(If you're curious as to whether the optimizer has done this for a particular
1258case statement, you can use the \-D1024 switch to list the syntax tree
1259before execution.)
1260.Sh "Simple statements"
1261The only kind of simple statement is an expression evaluated for its side
1262effects.
1263Every expression (simple statement) must be terminated with a semicolon.
1264Note that this is like C, but unlike Pascal (and
1265.IR awk ).
1266.PP
1267Any simple statement may optionally be followed by a
1268single modifier, just before the terminating semicolon.
1269The possible modifiers are:
1270.nf
1271
1272.ne 4
1273 if EXPR
1274 unless EXPR
1275 while EXPR
1276 until EXPR
1277
1278.fi
1279The
1280.I if
1281and
1282.I unless
1283modifiers have the expected semantics.
1284The
1285.I while
1286and
1287.I until
1288modifiers also have the expected semantics (conditional evaluated first),
1289except when applied to a do-BLOCK or a do-SUBROUTINE command,
1290in which case the block executes once before the conditional is evaluated.
1291This is so that you can write loops like:
1292.nf
1293
1294.ne 4
1295 do {
1296 $_ = <STDIN>;
1297 .\|.\|.
1298 } until $_ \|eq \|".\|\e\|n";
1299
1300.fi
1301(See the
1302.I do
1303operator below. Note also that the loop control commands described later will
1304NOT work in this construct, since modifiers don't take loop labels.
1305Sorry.)
1306.Sh "Expressions"
1307Since
1308.I perl
1309expressions work almost exactly like C expressions, only the differences
1310will be mentioned here.
1311.PP
1312Here's what
1313.I perl
1314has that C doesn't:
1315.Ip ** 8 2
1316The exponentiation operator.
1317.Ip **= 8
1318The exponentiation assignment operator.
1319.Ip (\|) 8 3
1320The null list, used to initialize an array to null.
1321.Ip . 8
1322Concatenation of two strings.
1323.Ip .= 8
1324The concatenation assignment operator.
1325.Ip eq 8
1326String equality (== is numeric equality).
1327For a mnemonic just think of \*(L"eq\*(R" as a string.
1328(If you are used to the
1329.I awk
1330behavior of using == for either string or numeric equality
1331based on the current form of the comparands, beware!
1332You must be explicit here.)
1333.Ip ne 8
1334String inequality (!= is numeric inequality).
1335.Ip lt 8
1336String less than.
1337.Ip gt 8
1338String greater than.
1339.Ip le 8
1340String less than or equal.
1341.Ip ge 8
1342String greater than or equal.
1343.Ip cmp 8
1344String comparison, returning -1, 0, or 1.
1345.Ip <=> 8
1346Numeric comparison, returning -1, 0, or 1.
1347.Ip =~ 8 2
1348Certain operations search or modify the string \*(L"$_\*(R" by default.
1349This operator makes that kind of operation work on some other string.
1350The right argument is a search pattern, substitution, or translation.
1351The left argument is what is supposed to be searched, substituted, or
1352translated instead of the default \*(L"$_\*(R".
1353The return value indicates the success of the operation.
1354(If the right argument is an expression other than a search pattern,
1355substitution, or translation, it is interpreted as a search pattern
1356at run time.
1357This is less efficient than an explicit search, since the pattern must
1358be compiled every time the expression is evaluated.)
1359The precedence of this operator is lower than unary minus and autoincrement/decrement, but higher than everything else.
1360.Ip !~ 8
1361Just like =~ except the return value is negated.
1362.Ip x 8
1363The repetition operator.
1364Returns a string consisting of the left operand repeated the
1365number of times specified by the right operand.
1366In an array context, if the left operand is a list in parens, it repeats
1367the list.
1368.nf
1369
1370 print \'\-\' x 80; # print row of dashes
1371 print \'\-\' x80; # illegal, x80 is identifier
1372
1373 print "\et" x ($tab/8), \' \' x ($tab%8); # tab over
1374
1375 @ones = (1) x ; # an array of 80 1's
1376 @ones = (5) x @ones; # set all elements to 5
1377
1378.fi
1379.Ip x= 8
1380The repetition assignment operator.
1381Only works on scalars.
1382.Ip .\|. 8
1383The range operator, which is really two different operators depending
1384on the context.
1385In an array context, returns an array of values counting (by ones)
1386from the left value to the right value.
1387This is useful for writing \*(L"for (1..10)\*(R" loops and for doing
1388slice operations on arrays.
1389.Sp
1390In a scalar context, .\|. returns a boolean value.
1391The operator is bistable, like a flip-flop..
1392Each .\|. operator maintains its own boolean state.
1393It is false as long as its left operand is false.
1394Once the left operand is true, the range operator stays true
1395until the right operand is true,
1396AFTER which the range operator becomes false again.
1397(It doesn't become false till the next time the range operator is evaluated.
1398It can become false on the same evaluation it became true, but it still returns
1399true once.)
1400The right operand is not evaluated while the operator is in the \*(L"false\*(R" state,
1401and the left operand is not evaluated while the operator is in the \*(L"true\*(R" state.
1402The scalar .\|. operator is primarily intended for doing line number ranges
1403after
1404the fashion of \fIsed\fR or \fIawk\fR.
1405The precedence is a little lower than || and &&.
1406The value returned is either the null string for false, or a sequence number
1407(beginning with 1) for true.
1408The sequence number is reset for each range encountered.
1409The final sequence number in a range has the string \'E0\' appended to it, which
1410doesn't affect its numeric value, but gives you something to search for if you
1411want to exclude the endpoint.
1412You can exclude the beginning point by waiting for the sequence number to be
1413greater than 1.
1414If either operand of scalar .\|. is static, that operand is implicitly compared
1415to the $. variable, the current line number.
1416Examples:
1417.nf
1418
1419.ne 6
1420As a scalar operator:
1421 if (101 .\|. 200) { print; } # print 2nd hundred lines
1422
1423 next line if (1 .\|. /^$/); # skip header lines
1424
1425 s/^/> / if (/^$/ .\|. eof()); # quote body
1426
1427.ne 4
1428As an array operator:
1429 for (101 .\|. 200) { print; } # print $_ 100 times
1430
1431 @foo = @foo[$[ .\|. $#foo]; # an expensive no-op
1432 @foo = @foo[$#foo-4 .\|. $#foo]; # slice last 5 items
1433
1434.fi
1435.Ip \-x 8
1436A file test.
1437This unary operator takes one argument, either a filename or a filehandle,
1438and tests the associated file to see if something is true about it.
1439If the argument is omitted, tests $_, except for \-t, which tests
1440.IR STDIN .
1441It returns 1 for true and \'\' for false, or the undefined value if the
1442file doesn't exist.
1443Precedence is higher than logical and relational operators, but lower than
1444arithmetic operators.
1445The operator may be any of:
1446.nf
1447 \-r File is readable by effective uid.
1448 \-w File is writable by effective uid.
1449 \-x File is executable by effective uid.
1450 \-o File is owned by effective uid.
1451 \-R File is readable by real uid.
1452 \-W File is writable by real uid.
1453 \-X File is executable by real uid.
1454 \-O File is owned by real uid.
1455 \-e File exists.
1456 \-z File has zero size.
1457 \-s File has non-zero size (returns size).
1458 \-f File is a plain file.
1459 \-d File is a directory.
1460 \-l File is a symbolic link.
1461 \-p File is a named pipe (FIFO).
1462 \-S File is a socket.
1463 \-b File is a block special file.
1464 \-c File is a character special file.
1465 \-u File has setuid bit set.
1466 \-g File has setgid bit set.
1467 \-k File has sticky bit set.
1468 \-t Filehandle is opened to a tty.
1469 \-T File is a text file.
1470 \-B File is a binary file (opposite of \-T).
1471 \-M Age of file in days when script started.
1472 \-A Same for access time.
1473 \-C Same for inode change time.
1474
1475.fi
1476The interpretation of the file permission operators \-r, \-R, \-w, \-W, \-x and \-X
1477is based solely on the mode of the file and the uids and gids of the user.
1478There may be other reasons you can't actually read, write or execute the file.
1479Also note that, for the superuser, \-r, \-R, \-w and \-W always return 1, and
1480\-x and \-X return 1 if any execute bit is set in the mode.
1481Scripts run by the superuser may thus need to do a stat() in order to determine
1482the actual mode of the file, or temporarily set the uid to something else.
1483.Sp
1484Example:
1485.nf
1486.ne 7
1487
1488 while (<>) {
1489 chop;
1490 next unless \-f $_; # ignore specials
1491 .\|.\|.
1492 }
1493
1494.fi
1495Note that \-s/a/b/ does not do a negated substitution.
1496Saying \-exp($foo) still works as expected, however\*(--only single letters
1497following a minus are interpreted as file tests.
1498.Sp
1499The \-T and \-B switches work as follows.
1500The first block or so of the file is examined for odd characters such as
1501strange control codes or metacharacters.
1502If too many odd characters (>10%) are found, it's a \-B file, otherwise it's a \-T file.
1503Also, any file containing null in the first block is considered a binary file.
1504If \-T or \-B is used on a filehandle, the current stdio buffer is examined
1505rather than the first block.
1506Both \-T and \-B return TRUE on a null file, or a file at EOF when testing
1507a filehandle.
1508.PP
1509If any of the file tests (or either stat operator) are given the special
1510filehandle consisting of a solitary underline, then the stat structure
1511of the previous file test (or stat operator) is used, saving a system
1512call.
1513(This doesn't work with \-t, and you need to remember that lstat and -l
1514will leave values in the stat structure for the symbolic link, not the
1515real file.)
1516Example:
1517.nf
1518
1519 print "Can do.\en" if -r $a || -w _ || -x _;
1520
1521.ne 9
1522 stat($filename);
1523 print "Readable\en" if -r _;
1524 print "Writable\en" if -w _;
1525 print "Executable\en" if -x _;
1526 print "Setuid\en" if -u _;
1527 print "Setgid\en" if -g _;
1528 print "Sticky\en" if -k _;
1529 print "Text\en" if -T _;
1530 print "Binary\en" if -B _;
1531
1532.fi
1533.PP
1534Here is what C has that
1535.I perl
1536doesn't:
1537.Ip "unary &" 12
1538Address-of operator.
1539.Ip "unary *" 12
1540Dereference-address operator.
1541.Ip "(TYPE)" 12
1542Type casting operator.
1543.PP
1544Like C,
1545.I perl
1546does a certain amount of expression evaluation at compile time, whenever
1547it determines that all of the arguments to an operator are static and have
1548no side effects.
1549In particular, string concatenation happens at compile time between literals that don't do variable substitution.
1550Backslash interpretation also happens at compile time.
1551You can say
1552.nf
1553
1554.ne 2
1555 \'Now is the time for all\' . "\|\e\|n" .
1556 \'good men to come to.\'
1557
1558.fi
1559and this all reduces to one string internally.
1560.PP
1561The autoincrement operator has a little extra built-in magic to it.
1562If you increment a variable that is numeric, or that has ever been used in
1563a numeric context, you get a normal increment.
1564If, however, the variable has only been used in string contexts since it
1565was set, and has a value that is not null and matches the
1566pattern /^[a\-zA\-Z]*[0\-9]*$/, the increment is done
1567as a string, preserving each character within its range, with carry:
1568.nf
1569
1570 print ++($foo = \'99\'); # prints \*(L'100\*(R'
1571 print ++($foo = \'a0\'); # prints \*(L'a1\*(R'
1572 print ++($foo = \'Az\'); # prints \*(L'Ba\*(R'
1573 print ++($foo = \'zz\'); # prints \*(L'aaa\*(R'
1574
1575.fi
1576The autodecrement is not magical.
1577.PP
1578The range operator (in an array context) makes use of the magical
1579autoincrement algorithm if the minimum and maximum are strings.
1580You can say
1581
1582 @alphabet = (\'A\' .. \'Z\');
1583
1584to get all the letters of the alphabet, or
1585
1586 $hexdigit = (0 .. 9, \'a\' .. \'f\')[$num & 15];
1587
1588to get a hexadecimal digit, or
1589
1590 @z2 = (\'01\' .. \'31\'); print @z2[$mday];
1591
1592to get dates with leading zeros.
1593(If the final value specified is not in the sequence that the magical increment
1594would produce, the sequence goes until the next value would be longer than
1595the final value specified.)
1596.PP
1597The || and && operators differ from C's in that, rather than returning 0 or 1,
1598they return the last value evaluated.
1599Thus, a portable way to find out the home directory might be:
1600.nf
1601
1602 $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
1603 (getpwuid($<))[7] || die "You're homeless!\en";
1604
1605.fi
1606''' Beginning of part 2
1607''' $Header: perl.man,v 4.0 91/03/20 01:38:08 lwall Locked $
1608'''
1609''' $Log: perl.man,v $
1610''' Revision 4.0 91/03/20 01:38:08 lwall
1611''' 4.0 baseline.
1612'''
1613''' Revision 3.0.1.11 91/01/11 18:17:08 lwall
1614''' patch42: fixed some man page entries
1615'''
1616''' Revision 3.0.1.10 90/11/10 01:46:29 lwall
1617''' patch38: random cleanup
1618''' patch38: added alarm function
1619'''
1620''' Revision 3.0.1.9 90/10/15 18:17:37 lwall
1621''' patch29: added caller
1622''' patch29: index and substr now have optional 3rd args
1623''' patch29: added SysV IPC
1624'''
1625''' Revision 3.0.1.8 90/08/13 22:21:00 lwall
1626''' patch28: documented that you can't interpolate $) or $| in pattern
1627'''
1628''' Revision 3.0.1.7 90/08/09 04:27:04 lwall
1629''' patch19: added require operator
1630'''
1631''' Revision 3.0.1.6 90/08/03 11:15:29 lwall
1632''' patch19: Intermediate diffs for Randal
1633'''
1634''' Revision 3.0.1.5 90/03/27 16:15:17 lwall
1635''' patch16: MSDOS support
1636'''
1637''' Revision 3.0.1.4 90/03/12 16:46:02 lwall
1638''' patch13: documented behavior of @array = /noparens/
1639'''
1640''' Revision 3.0.1.3 90/02/28 17:55:58 lwall
1641''' patch9: grep now returns number of items matched in scalar context
1642''' patch9: documented in-place modification capabilites of grep
1643'''
1644''' Revision 3.0.1.2 89/11/17 15:30:16 lwall
1645''' patch5: fixed some manual typos and indent problems
1646'''
1647''' Revision 3.0.1.1 89/11/11 04:43:10 lwall
1648''' patch2: made some line breaks depend on troff vs. nroff
1649''' patch2: example of unshift had args backwards
1650'''
1651''' Revision 3.0 89/10/18 15:21:37 lwall
1652''' 3.0 baseline
1653'''
1654'''
1655.PP
1656Along with the literals and variables mentioned earlier,
1657the operations in the following section can serve as terms in an expression.
1658Some of these operations take a LIST as an argument.
1659Such a list can consist of any combination of scalar arguments or array values;
1660the array values will be included in the list as if each individual element were
1661interpolated at that point in the list, forming a longer single-dimensional
1662array value.
1663Elements of the LIST should be separated by commas.
1664If an operation is listed both with and without parentheses around its
1665arguments, it means you can either use it as a unary operator or
1666as a function call.
1667To use it as a function call, the next token on the same line must
1668be a left parenthesis.
1669(There may be intervening white space.)
1670Such a function then has highest precedence, as you would expect from
1671a function.
1672If any token other than a left parenthesis follows, then it is a
1673unary operator, with a precedence depending only on whether it is a LIST
1674operator or not.
1675LIST operators have lowest precedence.
1676All other unary operators have a precedence greater than relational operators
1677but less than arithmetic operators.
1678See the section on Precedence.
1679.Ip "/PATTERN/" 8 4
1680See m/PATTERN/.
1681.Ip "?PATTERN?" 8 4
1682This is just like the /pattern/ search, except that it matches only once between
1683calls to the
1684.I reset
1685operator.
1686This is a useful optimization when you only want to see the first occurrence of
1687something in each file of a set of files, for instance.
1688Only ?? patterns local to the current package are reset.
1689.Ip "accept(NEWSOCKET,GENERICSOCKET)" 8 2
1690Does the same thing that the accept system call does.
1691Returns true if it succeeded, false otherwise.
1692See example in section on Interprocess Communication.
1693.Ip "alarm(SECONDS)" 8 4
1694.Ip "alarm SECONDS" 8
1695Arranges to have a SIGALRM delivered to this process after the specified number
1696of seconds (minus 1, actually) have elapsed. Thus, alarm(15) will cause
1697a SIGALRM at some point more than 14 seconds in the future.
1698Only one timer may be counting at once. Each call disables the previous
1699timer, and an argument of 0 may be supplied to cancel the previous timer
1700without starting a new one.
1701The returned value is the amount of time remaining on the previous timer.
1702.Ip "atan2(Y,X)" 8 2
1703Returns the arctangent of Y/X in the range
1704.if t \-\(*p to \(*p.
1705.if n \-PI to PI.
1706.Ip "bind(SOCKET,NAME)" 8 2
1707Does the same thing that the bind system call does.
1708Returns true if it succeeded, false otherwise.
1709NAME should be a packed address of the proper type for the socket.
1710See example in section on Interprocess Communication.
1711.Ip "binmode(FILEHANDLE)" 8 4
1712.Ip "binmode FILEHANDLE" 8 4
1713Arranges for the file to be read in \*(L"binary\*(R" mode in operating systems
1714that distinguish between binary and text files.
1715Files that are not read in binary mode have CR LF sequences translated
1716to LF on input and LF translated to CR LF on output.
1717Binmode has no effect under Unix.
1718If FILEHANDLE is an expression, the value is taken as the name of
1719the filehandle.
1720.Ip "caller(EXPR)"
1721.Ip "caller"
1722Returns the context of the current subroutine call:
1723.nf
1724
1725 ($package,$filename,$line) = caller;
1726
1727.fi
1728With EXPR, returns some extra information that the debugger uses to print
1729a stack trace. The value of EXPR indicates how many call frames to go
1730back before the current one.
1731.Ip "chdir(EXPR)" 8 2
1732.Ip "chdir EXPR" 8 2
1733Changes the working directory to EXPR, if possible.
1734If EXPR is omitted, changes to home directory.
1735Returns 1 upon success, 0 otherwise.
1736See example under
1737.IR die .
1738.Ip "chmod(LIST)" 8 2
1739.Ip "chmod LIST" 8 2
1740Changes the permissions of a list of files.
1741The first element of the list must be the numerical mode.
1742Returns the number of files successfully changed.
1743.nf
1744
1745.ne 2
1746 $cnt = chmod 0755, \'foo\', \'bar\';
1747 chmod 0755, @executables;
1748
1749.fi
1750.Ip "chop(LIST)" 8 7
1751.Ip "chop(VARIABLE)" 8
1752.Ip "chop VARIABLE" 8
1753.Ip "chop" 8
1754Chops off the last character of a string and returns the character chopped.
1755It's used primarily to remove the newline from the end of an input record,
1756but is much more efficient than s/\en// because it neither scans nor copies
1757the string.
1758If VARIABLE is omitted, chops $_.
1759Example:
1760.nf
1761
1762.ne 5
1763 while (<>) {
1764 chop; # avoid \en on last field
1765 @array = split(/:/);
1766 .\|.\|.
1767 }
1768
1769.fi
1770You can actually chop anything that's an lvalue, including an assignment:
1771.nf
1772
1773 chop($cwd = \`pwd\`);
1774 chop($answer = <STDIN>);
1775
1776.fi
1777If you chop a list, each element is chopped.
1778Only the value of the last chop is returned.
1779.Ip "chown(LIST)" 8 2
1780.Ip "chown LIST" 8 2
1781Changes the owner (and group) of a list of files.
1782The first two elements of the list must be the NUMERICAL uid and gid,
1783in that order.
1784Returns the number of files successfully changed.
1785.nf
1786
1787.ne 2
1788 $cnt = chown $uid, $gid, \'foo\', \'bar\';
1789 chown $uid, $gid, @filenames;
1790
1791.fi
1792.ne 23
1793Here's an example of looking up non-numeric uids:
1794.nf
1795
1796 print "User: ";
1797 $user = <STDIN>;
1798 chop($user);
1799 print "Files: "
1800 $pattern = <STDIN>;
1801 chop($pattern);
1802.ie t \{\
1803 open(pass, \'/etc/passwd\') || die "Can't open passwd: $!\en";
1804'br\}
1805.el \{\
1806 open(pass, \'/etc/passwd\')
1807 || die "Can't open passwd: $!\en";
1808'br\}
1809 while (<pass>) {
1810 ($login,$pass,$uid,$gid) = split(/:/);
1811 $uid{$login} = $uid;
1812 $gid{$login} = $gid;
1813 }
1814 @ary = <${pattern}>; # get filenames
1815 if ($uid{$user} eq \'\') {
1816 die "$user not in passwd file";
1817 }
1818 else {
1819 chown $uid{$user}, $gid{$user}, @ary;
1820 }
1821
1822.fi
1823.Ip "chroot(FILENAME)" 8 5
1824.Ip "chroot FILENAME" 8
1825Does the same as the system call of that name.
1826If you don't know what it does, don't worry about it.
1827If FILENAME is omitted, does chroot to $_.
1828.Ip "close(FILEHANDLE)" 8 5
1829.Ip "close FILEHANDLE" 8
1830Closes the file or pipe associated with the file handle.
1831You don't have to close FILEHANDLE if you are immediately going to
1832do another open on it, since open will close it for you.
1833(See
1834.IR open .)
1835However, an explicit close on an input file resets the line counter ($.), while
1836the implicit close done by
1837.I open
1838does not.
1839Also, closing a pipe will wait for the process executing on the pipe to complete,
1840in case you want to look at the output of the pipe afterwards.
1841Closing a pipe explicitly also puts the status value of the command into $?.
1842Example:
1843.nf
1844
1845.ne 4
1846 open(OUTPUT, \'|sort >foo\'); # pipe to sort
1847 .\|.\|. # print stuff to output
1848 close OUTPUT; # wait for sort to finish
1849 open(INPUT, \'foo\'); # get sort's results
1850
1851.fi
1852FILEHANDLE may be an expression whose value gives the real filehandle name.
1853.Ip "closedir(DIRHANDLE)" 8 5
1854.Ip "closedir DIRHANDLE" 8
1855Closes a directory opened by opendir().
1856.Ip "connect(SOCKET,NAME)" 8 2
1857Does the same thing that the connect system call does.
1858Returns true if it succeeded, false otherwise.
1859NAME should be a package address of the proper type for the socket.
1860See example in section on Interprocess Communication.
1861.Ip "cos(EXPR)" 8 6
1862.Ip "cos EXPR" 8 6
1863Returns the cosine of EXPR (expressed in radians).
1864If EXPR is omitted takes cosine of $_.
1865.Ip "crypt(PLAINTEXT,SALT)" 8 6
1866Encrypts a string exactly like the crypt() function in the C library.
1867Useful for checking the password file for lousy passwords.
1868Only the guys wearing white hats should do this.
1869.Ip "dbmclose(ASSOC_ARRAY)" 8 6
1870.Ip "dbmclose ASSOC_ARRAY" 8
1871Breaks the binding between a dbm file and an associative array.
1872The values remaining in the associative array are meaningless unless
1873you happen to want to know what was in the cache for the dbm file.
1874This function is only useful if you have ndbm.
1875.Ip "dbmopen(ASSOC,DBNAME,MODE)" 8 6
1876This binds a dbm or ndbm file to an associative array.
1877ASSOC is the name of the associative array.
1878(Unlike normal open, the first argument is NOT a filehandle, even though
1879it looks like one).
1880DBNAME is the name of the database (without the .dir or .pag extension).
1881If the database does not exist, it is created with protection specified
1882by MODE (as modified by the umask).
1883If your system only supports the older dbm functions, you may only have one
1884dbmopen in your program.
1885If your system has neither dbm nor ndbm, calling dbmopen produces a fatal
1886error.
1887.Sp
1888Values assigned to the associative array prior to the dbmopen are lost.
1889A certain number of values from the dbm file are cached in memory.
1890By default this number is 64, but you can increase it by preallocating
1891that number of garbage entries in the associative array before the dbmopen.
1892You can flush the cache if necessary with the reset command.
1893.Sp
1894If you don't have write access to the dbm file, you can only read
1895associative array variables, not set them.
1896If you want to test whether you can write, either use file tests or
1897try setting a dummy array entry inside an eval, which will trap the error.
1898.Sp
1899Note that functions such as keys() and values() may return huge array values
1900when used on large dbm files.
1901You may prefer to use the each() function to iterate over large dbm files.
1902Example:
1903.nf
1904
1905.ne 6
1906 # print out history file offsets
1907 dbmopen(HIST,'/usr/lib/news/history',0666);
1908 while (($key,$val) = each %HIST) {
1909 print $key, ' = ', unpack('L',$val), "\en";
1910 }
1911 dbmclose(HIST);
1912
1913.fi
1914.Ip "defined(EXPR)" 8 6
1915.Ip "defined EXPR" 8
1916Returns a boolean value saying whether the lvalue EXPR has a real value
1917or not.
1918Many operations return the undefined value under exceptional conditions,
1919such as end of file, uninitialized variable, system error and such.
1920This function allows you to distinguish between an undefined null string
1921and a defined null string with operations that might return a real null
1922string, in particular referencing elements of an array.
1923You may also check to see if arrays or subroutines exist.
1924Use on predefined variables is not guaranteed to produce intuitive results.
1925Examples:
1926.nf
1927
1928.ne 7
1929 print if defined $switch{'D'};
1930 print "$val\en" while defined($val = pop(@ary));
1931 die "Can't readlink $sym: $!"
1932 unless defined($value = readlink $sym);
1933 eval '@foo = ()' if defined(@foo);
1934 die "No XYZ package defined" unless defined %_XYZ;
1935 sub foo { defined &bar ? &bar(@_) : die "No bar"; }
1936
1937.fi
1938See also undef.
1939.Ip "delete $ASSOC{KEY}" 8 6
1940Deletes the specified value from the specified associative array.
1941Returns the deleted value, or the undefined value if nothing was deleted.
1942Deleting from $ENV{} modifies the environment.
1943Deleting from an array bound to a dbm file deletes the entry from the dbm
1944file.
1945.Sp
1946The following deletes all the values of an associative array:
1947.nf
1948
1949.ne 3
1950 foreach $key (keys %ARRAY) {
1951 delete $ARRAY{$key};
1952 }
1953
1954.fi
1955(But it would be faster to use the
1956.I reset
1957command.
1958Saying undef %ARRAY is faster yet.)
1959.Ip "die(LIST)" 8
1960.Ip "die LIST" 8
1961Outside of an eval, prints the value of LIST to
1962.I STDERR
1963and exits with the current value of $!
1964(errno).
1965If $! is 0, exits with the value of ($? >> 8) (\`command\` status).
1966If ($? >> 8) is 0, exits with 255.
1967Inside an eval, the error message is stuffed into $@ and the eval is terminated
1968with the undefined value.
1969.Sp
1970Equivalent examples:
1971.nf
1972
1973.ne 3
1974.ie t \{\
1975 die "Can't cd to spool: $!\en" unless chdir \'/usr/spool/news\';
1976'br\}
1977.el \{\
1978 die "Can't cd to spool: $!\en"
1979 unless chdir \'/usr/spool/news\';
1980'br\}
1981
1982 chdir \'/usr/spool/news\' || die "Can't cd to spool: $!\en"
1983
1984.fi
1985.Sp
1986If the value of EXPR does not end in a newline, the current script line
1987number and input line number (if any) are also printed, and a newline is
1988supplied.
1989Hint: sometimes appending \*(L", stopped\*(R" to your message will cause it to make
1990better sense when the string \*(L"at foo line 123\*(R" is appended.
1991Suppose you are running script \*(L"canasta\*(R".
1992.nf
1993
1994.ne 7
1995 die "/etc/games is no good";
1996 die "/etc/games is no good, stopped";
1997
1998produce, respectively
1999
2000 /etc/games is no good at canasta line 123.
2001 /etc/games is no good, stopped at canasta line 123.
2002
2003.fi
2004See also
2005.IR exit .
2006.Ip "do BLOCK" 8 4
2007Returns the value of the last command in the sequence of commands indicated
2008by BLOCK.
2009When modified by a loop modifier, executes the BLOCK once before testing the
2010loop condition.
2011(On other statements the loop modifiers test the conditional first.)
2012.Ip "do SUBROUTINE (LIST)" 8 3
2013Executes a SUBROUTINE declared by a
2014.I sub
2015declaration, and returns the value
2016of the last expression evaluated in SUBROUTINE.
2017If there is no subroutine by that name, produces a fatal error.
2018(You may use the \*(L"defined\*(R" operator to determine if a subroutine
2019exists.)
2020If you pass arrays as part of LIST you may wish to pass the length
2021of the array in front of each array.
2022(See the section on subroutines later on.)
2023SUBROUTINE may be a scalar variable, in which case the variable contains
2024the name of the subroutine to execute.
2025The parentheses are required to avoid confusion with the \*(L"do EXPR\*(R"
2026form.
2027.Sp
2028As an alternate form, you may call a subroutine by prefixing the name with
2029an ampersand: &foo(@args).
2030If you aren't passing any arguments, you don't have to use parentheses.
2031If you omit the parentheses, no @_ array is passed to the subroutine.
2032The & form is also used to specify subroutines to the defined and undef
2033operators.
2034.Ip "do EXPR" 8 3
2035Uses the value of EXPR as a filename and executes the contents of the file
2036as a
2037.I perl
2038script.
2039Its primary use is to include subroutines from a
2040.I perl
2041subroutine library.
2042.nf
2043
2044 do \'stat.pl\';
2045
2046is just like
2047
2048 eval \`cat stat.pl\`;
2049
2050.fi
2051except that it's more efficient, more concise, keeps track of the current
2052filename for error messages, and searches all the
2053.B \-I
2054libraries if the file
2055isn't in the current directory (see also the @INC array in Predefined Names).
2056It's the same, however, in that it does reparse the file every time you
2057call it, so if you are going to use the file inside a loop you might prefer
2058to use \-P and #include, at the expense of a little more startup time.
2059(The main problem with #include is that cpp doesn't grok # comments\*(--a
2060workaround is to use \*(L";#\*(R" for standalone comments.)
2061Note that the following are NOT equivalent:
2062.nf
2063
2064.ne 2
2065 do $foo; # eval a file
2066 do $foo(); # call a subroutine
2067
2068.fi
2069Note that inclusion of library routines is better done with
2070the \*(L"require\*(R" operator.
2071.Ip "dump LABEL" 8 6
2072This causes an immediate core dump.
2073Primarily this is so that you can use the undump program to turn your
2074core dump into an executable binary after having initialized all your
2075variables at the beginning of the program.
2076When the new binary is executed it will begin by executing a "goto LABEL"
2077(with all the restrictions that goto suffers).
2078Think of it as a goto with an intervening core dump and reincarnation.
2079If LABEL is omitted, restarts the program from the top.
2080WARNING: any files opened at the time of the dump will NOT be open any more
2081when the program is reincarnated, with possible resulting confusion on the part
2082of perl.
2083See also \-u.
2084.Sp
2085Example:
2086.nf
2087
2088.ne 16
2089 #!/usr/bin/perl
2090 require 'getopt.pl';
2091 require 'stat.pl';
2092 %days = (
2093 'Sun',1,
2094 'Mon',2,
2095 'Tue',3,
2096 'Wed',4,
2097 'Thu',5,
2098 'Fri',6,
2099 'Sat',7);
2100
2101 dump QUICKSTART if $ARGV[0] eq '-d';
2102
2103 QUICKSTART:
2104 do Getopt('f');
2105
2106.fi
2107.Ip "each(ASSOC_ARRAY)" 8 6
2108.Ip "each ASSOC_ARRAY" 8
2109Returns a 2 element array consisting of the key and value for the next
2110value of an associative array, so that you can iterate over it.
2111Entries are returned in an apparently random order.
2112When the array is entirely read, a null array is returned (which when
2113assigned produces a FALSE (0) value).
2114The next call to each() after that will start iterating again.
2115The iterator can be reset only by reading all the elements from the array.
2116You must not modify the array while iterating over it.
2117There is a single iterator for each associative array, shared by all
2118each(), keys() and values() function calls in the program.
2119The following prints out your environment like the printenv program, only
2120in a different order:
2121.nf
2122
2123.ne 3
2124 while (($key,$value) = each %ENV) {
2125 print "$key=$value\en";
2126 }
2127
2128.fi
2129See also keys() and values().
2130.Ip "eof(FILEHANDLE)" 8 8
2131.Ip "eof()" 8
2132.Ip "eof" 8
2133Returns 1 if the next read on FILEHANDLE will return end of file, or if
2134FILEHANDLE is not open.
2135FILEHANDLE may be an expression whose value gives the real filehandle name.
2136(Note that this function actually reads a character and then ungetc's it,
2137so it is not very useful in an interactive context.)
2138An eof without an argument returns the eof status for the last file read.
2139Empty parentheses () may be used to indicate the pseudo file formed of the
2140files listed on the command line, i.e. eof() is reasonable to use inside
2141a while (<>) loop to detect the end of only the last file.
2142Use eof(ARGV) or eof without the parentheses to test EACH file in a while (<>) loop.
2143Examples:
2144.nf
2145
2146.ne 7
2147 # insert dashes just before last line of last file
2148 while (<>) {
2149 if (eof()) {
2150 print "\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\en";
2151 }
2152 print;
2153 }
2154
2155.ne 7
2156 # reset line numbering on each input file
2157 while (<>) {
2158 print "$.\et$_";
2159 if (eof) { # Not eof().
2160 close(ARGV);
2161 }
2162 }
2163
2164.fi
2165.Ip "eval(EXPR)" 8 6
2166.Ip "eval EXPR" 8 6
2167EXPR is parsed and executed as if it were a little
2168.I perl
2169program.
2170It is executed in the context of the current
2171.I perl
2172program, so that
2173any variable settings, subroutine or format definitions remain afterwards.
2174The value returned is the value of the last expression evaluated, just
2175as with subroutines.
2176If there is a syntax error or runtime error, or a die statement is
2177executed, an undefined value is returned by
2178eval, and $@ is set to the error message.
2179If there was no error, $@ is guaranteed to be a null string.
2180If EXPR is omitted, evaluates $_.
2181The final semicolon, if any, may be omitted from the expression.
2182.Sp
2183Note that, since eval traps otherwise-fatal errors, it is useful for
2184determining whether a particular feature
2185(such as dbmopen or symlink) is implemented.
2186It is also Perl's exception trapping mechanism, where the die operator is
2187used to raise exceptions.
2188.Ip "exec(LIST)" 8 8
2189.Ip "exec LIST" 8 6
2190If there is more than one argument in LIST, or if LIST is an array with
2191more than one value,
2192calls execvp() with the arguments in LIST.
2193If there is only one scalar argument, the argument is checked for shell metacharacters.
2194If there are any, the entire argument is passed to \*(L"/bin/sh \-c\*(R" for parsing.
2195If there are none, the argument is split into words and passed directly to
2196execvp(), which is more efficient.
2197Note: exec (and system) do not flush your output buffer, so you may need to
2198set $| to avoid lost output.
2199Examples:
2200.nf
2201
2202 exec \'/bin/echo\', \'Your arguments are: \', @ARGV;
2203 exec "sort $outfile | uniq";
2204
2205.fi
2206.Sp
2207If you don't really want to execute the first argument, but want to lie
2208to the program you are executing about its own name, you can specify
2209the program you actually want to run by assigning that to a variable and
2210putting the name of the variable in front of the LIST without a comma.
2211(This always forces interpretation of the LIST as a multi-valued list, even
2212if there is only a single scalar in the list.)
2213Example:
2214.nf
2215
2216.ne 2
2217 $shell = '/bin/csh';
2218 exec $shell '-sh'; # pretend it's a login shell
2219
2220.fi
2221.Ip "exit(EXPR)" 8 6
2222.Ip "exit EXPR" 8
2223Evaluates EXPR and exits immediately with that value.
2224Example:
2225.nf
2226
2227.ne 2
2228 $ans = <STDIN>;
2229 exit 0 \|if \|$ans \|=~ \|/\|^[Xx]\|/\|;
2230
2231.fi
2232See also
2233.IR die .
2234If EXPR is omitted, exits with 0 status.
2235.Ip "exp(EXPR)" 8 3
2236.Ip "exp EXPR" 8
2237Returns
2238.I e
2239to the power of EXPR.
2240If EXPR is omitted, gives exp($_).
2241.Ip "fcntl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
2242Implements the fcntl(2) function.
2243You'll probably have to say
2244.nf
2245
2246 require "fcntl.ph"; # probably /usr/local/lib/perl/fcntl.ph
2247
2248.fi
2249first to get the correct function definitions.
2250If fcntl.ph doesn't exist or doesn't have the correct definitions
2251you'll have to roll
2252your own, based on your C header files such as <sys/fcntl.h>.
2253(There is a perl script called h2ph that comes with the perl kit
2254which may help you in this.)
2255Argument processing and value return works just like ioctl below.
2256Note that fcntl will produce a fatal error if used on a machine that doesn't implement
2257fcntl(2).
2258.Ip "fileno(FILEHANDLE)" 8 4
2259.Ip "fileno FILEHANDLE" 8 4
2260Returns the file descriptor for a filehandle.
2261Useful for constructing bitmaps for select().
2262If FILEHANDLE is an expression, the value is taken as the name of
2263the filehandle.
2264.Ip "flock(FILEHANDLE,OPERATION)" 8 4
2265Calls flock(2) on FILEHANDLE.
2266See manual page for flock(2) for definition of OPERATION.
2267Returns true for success, false on failure.
2268Will produce a fatal error if used on a machine that doesn't implement
2269flock(2).
2270Here's a mailbox appender for BSD systems.
2271.nf
2272
2273.ne 20
2274 $LOCK_SH = 1;
2275 $LOCK_EX = 2;
2276 $LOCK_NB = 4;
2277 $LOCK_UN = 8;
2278
2279 sub lock {
2280 flock(MBOX,$LOCK_EX);
2281 # and, in case someone appended
2282 # while we were waiting...
2283 seek(MBOX, 0, 2);
2284 }
2285
2286 sub unlock {
2287 flock(MBOX,$LOCK_UN);
2288 }
2289
2290 open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
2291 || die "Can't open mailbox: $!";
2292
2293 do lock();
2294 print MBOX $msg,"\en\en";
2295 do unlock();
2296
2297.fi
2298.Ip "fork" 8 4
2299Does a fork() call.
2300Returns the child pid to the parent process and 0 to the child process.
2301Note: unflushed buffers remain unflushed in both processes, which means
2302you may need to set $| to avoid duplicate output.
2303.Ip "getc(FILEHANDLE)" 8 4
2304.Ip "getc FILEHANDLE" 8
2305.Ip "getc" 8
2306Returns the next character from the input file attached to FILEHANDLE, or
2307a null string at EOF.
2308If FILEHANDLE is omitted, reads from STDIN.
2309.Ip "getlogin" 8 3
2310Returns the current login from /etc/utmp, if any.
2311If null, use getpwuid.
2312
2313 $login = getlogin || (getpwuid($<))[0] || "Somebody";
2314
2315.Ip "getpeername(SOCKET)" 8 3
2316Returns the packed sockaddr address of other end of the SOCKET connection.
2317.nf
2318
2319.ne 4
2320 # An internet sockaddr
2321 $sockaddr = 'S n a4 x8';
2322 $hersockaddr = getpeername(S);
2323.ie t \{\
2324 ($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
2325'br\}
2326.el \{\
2327 ($family, $port, $heraddr) =
2328 unpack($sockaddr,$hersockaddr);
2329'br\}
2330
2331.fi
2332.Ip "getpgrp(PID)" 8 4
2333.Ip "getpgrp PID" 8
2334Returns the current process group for the specified PID, 0 for the current
2335process.
2336Will produce a fatal error if used on a machine that doesn't implement
2337getpgrp(2).
2338If EXPR is omitted, returns process group of current process.
2339.Ip "getppid" 8 4
2340Returns the process id of the parent process.
2341.Ip "getpriority(WHICH,WHO)" 8 4
2342Returns the current priority for a process, a process group, or a user.
2343(See getpriority(2).)
2344Will produce a fatal error if used on a machine that doesn't implement
2345getpriority(2).
2346.Ip "getpwnam(NAME)" 8
2347.Ip "getgrnam(NAME)" 8
2348.Ip "gethostbyname(NAME)" 8
2349.Ip "getnetbyname(NAME)" 8
2350.Ip "getprotobyname(NAME)" 8
2351.Ip "getpwuid(UID)" 8
2352.Ip "getgrgid(GID)" 8
2353.Ip "getservbyname(NAME,PROTO)" 8
2354.Ip "gethostbyaddr(ADDR,ADDRTYPE)" 8
2355.Ip "getnetbyaddr(ADDR,ADDRTYPE)" 8
2356.Ip "getprotobynumber(NUMBER)" 8
2357.Ip "getservbyport(PORT,PROTO)" 8
2358.Ip "getpwent" 8
2359.Ip "getgrent" 8
2360.Ip "gethostent" 8
2361.Ip "getnetent" 8
2362.Ip "getprotoent" 8
2363.Ip "getservent" 8
2364.Ip "setpwent" 8
2365.Ip "setgrent" 8
2366.Ip "sethostent(STAYOPEN)" 8
2367.Ip "setnetent(STAYOPEN)" 8
2368.Ip "setprotoent(STAYOPEN)" 8
2369.Ip "setservent(STAYOPEN)" 8
2370.Ip "endpwent" 8
2371.Ip "endgrent" 8
2372.Ip "endhostent" 8
2373.Ip "endnetent" 8
2374.Ip "endprotoent" 8
2375.Ip "endservent" 8
2376These routines perform the same functions as their counterparts in the
2377system library.
2378The return values from the various get routines are as follows:
2379.nf
2380
2381 ($name,$passwd,$uid,$gid,
2382 $quota,$comment,$gcos,$dir,$shell) = getpw.\|.\|.
2383 ($name,$passwd,$gid,$members) = getgr.\|.\|.
2384 ($name,$aliases,$addrtype,$length,@addrs) = gethost.\|.\|.
2385 ($name,$aliases,$addrtype,$net) = getnet.\|.\|.
2386 ($name,$aliases,$proto) = getproto.\|.\|.
2387 ($name,$aliases,$port,$proto) = getserv.\|.\|.
2388
2389.fi
2390The $members value returned by getgr.\|.\|. is a space separated list
2391of the login names of the members of the group.
2392.Sp
2393The @addrs value returned by the gethost.\|.\|. functions is a list of the
2394raw addresses returned by the corresponding system library call.
2395In the Internet domain, each address is four bytes long and you can unpack
2396it by saying something like:
2397.nf
2398
2399 ($a,$b,$c,$d) = unpack('C4',$addr[0]);
2400
2401.fi
2402.Ip "getsockname(SOCKET)" 8 3
2403Returns the packed sockaddr address of this end of the SOCKET connection.
2404.nf
2405
2406.ne 4
2407 # An internet sockaddr
2408 $sockaddr = 'S n a4 x8';
2409 $mysockaddr = getsockname(S);
2410.ie t \{\
2411 ($family, $port, $myaddr) = unpack($sockaddr,$mysockaddr);
2412'br\}
2413.el \{\
2414 ($family, $port, $myaddr) =
2415 unpack($sockaddr,$mysockaddr);
2416'br\}
2417
2418.fi
2419.Ip "getsockopt(SOCKET,LEVEL,OPTNAME)" 8 3
2420Returns the socket option requested, or undefined if there is an error.
2421.Ip "gmtime(EXPR)" 8 4
2422.Ip "gmtime EXPR" 8
2423Converts a time as returned by the time function to a 9-element array with
2424the time analyzed for the Greenwich timezone.
2425Typically used as follows:
2426.nf
2427
2428.ne 3
2429.ie t \{\
2430 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time);
2431'br\}
2432.el \{\
2433 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
2434 gmtime(time);
2435'br\}
2436
2437.fi
2438All array elements are numeric, and come straight out of a struct tm.
2439In particular this means that $mon has the range 0.\|.11 and $wday has the
2440range 0.\|.6.
2441If EXPR is omitted, does gmtime(time).
2442.Ip "goto LABEL" 8 6
2443Finds the statement labeled with LABEL and resumes execution there.
2444Currently you may only go to statements in the main body of the program
2445that are not nested inside a do {} construct.
2446This statement is not implemented very efficiently, and is here only to make
2447the
2448.IR sed -to- perl
2449translator easier.
2450I may change its semantics at any time, consistent with support for translated
2451.I sed
2452scripts.
2453Use it at your own risk.
2454Better yet, don't use it at all.
2455.Ip "grep(EXPR,LIST)" 8 4
2456Evaluates EXPR for each element of LIST (locally setting $_ to each element)
2457and returns the array value consisting of those elements for which the
2458expression evaluated to true.
2459In a scalar context, returns the number of times the expression was true.
2460.nf
2461
2462 @foo = grep(!/^#/, @bar); # weed out comments
2463
2464.fi
2465Note that, since $_ is a reference into the array value, it can be
2466used to modify the elements of the array.
2467While this is useful and supported, it can cause bizarre results if
2468the LIST is not a named array.
2469.Ip "hex(EXPR)" 8 4
2470.Ip "hex EXPR" 8
2471Returns the decimal value of EXPR interpreted as an hex string.
2472(To interpret strings that might start with 0 or 0x see oct().)
2473If EXPR is omitted, uses $_.
2474.Ip "index(STR,SUBSTR,POSITION)" 8 4
2475.Ip "index(STR,SUBSTR)" 8 4
2476Returns the position of the first occurrence of SUBSTR in STR at or after
2477POSITION.
2478If POSITION is omitted, starts searching from the beginning of the string.
2479The return value is based at 0, or whatever you've
2480set the $[ variable to.
2481If the substring is not found, returns one less than the base, ordinarily \-1.
2482.Ip "int(EXPR)" 8 4
2483.Ip "int EXPR" 8
2484Returns the integer portion of EXPR.
2485If EXPR is omitted, uses $_.
2486.Ip "ioctl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
2487Implements the ioctl(2) function.
2488You'll probably have to say
2489.nf
2490
2491 require "ioctl.ph"; # probably /usr/local/lib/perl/ioctl.ph
2492
2493.fi
2494first to get the correct function definitions.
2495If ioctl.ph doesn't exist or doesn't have the correct definitions
2496you'll have to roll
2497your own, based on your C header files such as <sys/ioctl.h>.
2498(There is a perl script called h2ph that comes with the perl kit
2499which may help you in this.)
2500SCALAR will be read and/or written depending on the FUNCTION\*(--a pointer
2501to the string value of SCALAR will be passed as the third argument of
2502the actual ioctl call.
2503(If SCALAR has no string value but does have a numeric value, that value
2504will be passed rather than a pointer to the string value.
2505To guarantee this to be true, add a 0 to the scalar before using it.)
2506The pack() and unpack() functions are useful for manipulating the values
2507of structures used by ioctl().
2508The following example sets the erase character to DEL.
2509.nf
2510
2511.ne 9
2512 require 'ioctl.ph';
2513 $sgttyb_t = "ccccs"; # 4 chars and a short
2514 if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
2515 @ary = unpack($sgttyb_t,$sgttyb);
2516 $ary[2] = 127;
2517 $sgttyb = pack($sgttyb_t,@ary);
2518 ioctl(STDIN,$TIOCSETP,$sgttyb)
2519 || die "Can't ioctl: $!";
2520 }
2521
2522.fi
2523The return value of ioctl (and fcntl) is as follows:
2524.nf
2525
2526.ne 4
2527 if OS returns:\h'|3i'perl returns:
2528 -1\h'|3i' undefined value
2529 0\h'|3i' string "0 but true"
2530 anything else\h'|3i' that number
2531
2532.fi
2533Thus perl returns true on success and false on failure, yet you can still
2534easily determine the actual value returned by the operating system:
2535.nf
2536
2537 ($retval = ioctl(...)) || ($retval = -1);
2538 printf "System returned %d\en", $retval;
2539.fi
2540.Ip "join(EXPR,LIST)" 8 8
2541.Ip "join(EXPR,ARRAY)" 8
2542Joins the separate strings of LIST or ARRAY into a single string with fields
2543separated by the value of EXPR, and returns the string.
2544Example:
2545.nf
2546
2547.ie t \{\
2548 $_ = join(\|\':\', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2549'br\}
2550.el \{\
2551 $_ = join(\|\':\',
2552 $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2553'br\}
2554
2555.fi
2556See
2557.IR split .
2558.Ip "keys(ASSOC_ARRAY)" 8 6
2559.Ip "keys ASSOC_ARRAY" 8
2560Returns a normal array consisting of all the keys of the named associative
2561array.
2562The keys are returned in an apparently random order, but it is the same order
2563as either the values() or each() function produces (given that the associative array
2564has not been modified).
2565Here is yet another way to print your environment:
2566.nf
2567
2568.ne 5
2569 @keys = keys %ENV;
2570 @values = values %ENV;
2571 while ($#keys >= 0) {
2572 print pop(@keys), \'=\', pop(@values), "\en";
2573 }
2574
2575or how about sorted by key:
2576
2577.ne 3
2578 foreach $key (sort(keys %ENV)) {
2579 print $key, \'=\', $ENV{$key}, "\en";
2580 }
2581
2582.fi
2583.Ip "kill(LIST)" 8 8
2584.Ip "kill LIST" 8 2
2585Sends a signal to a list of processes.
2586The first element of the list must be the signal to send.
2587Returns the number of processes successfully signaled.
2588.nf
2589
2590 $cnt = kill 1, $child1, $child2;
2591 kill 9, @goners;
2592
2593.fi
2594If the signal is negative, kills process groups instead of processes.
2595(On System V, a negative \fIprocess\fR number will also kill process groups,
2596but that's not portable.)
2597You may use a signal name in quotes.
2598.Ip "last LABEL" 8 8
2599.Ip "last" 8
2600The
2601.I last
2602command is like the
2603.I break
2604statement in C (as used in loops); it immediately exits the loop in question.
2605If the LABEL is omitted, the command refers to the innermost enclosing loop.
2606The
2607.I continue
2608block, if any, is not executed:
2609.nf
2610
2611.ne 4
2612 line: while (<STDIN>) {
2613 last line if /\|^$/; # exit when done with header
2614 .\|.\|.
2615 }
2616
2617.fi
2618.Ip "length(EXPR)" 8 4
2619.Ip "length EXPR" 8
2620Returns the length in characters of the value of EXPR.
2621If EXPR is omitted, returns length of $_.
2622.Ip "link(OLDFILE,NEWFILE)" 8 2
2623Creates a new filename linked to the old filename.
2624Returns 1 for success, 0 otherwise.
2625.Ip "listen(SOCKET,QUEUESIZE)" 8 2
2626Does the same thing that the listen system call does.
2627Returns true if it succeeded, false otherwise.
2628See example in section on Interprocess Communication.
2629.Ip "local(LIST)" 8 4
2630Declares the listed variables to be local to the enclosing block,
2631subroutine, eval or \*(L"do\*(R".
2632All the listed elements must be legal lvalues.
2633This operator works by saving the current values of those variables in LIST
2634on a hidden stack and restoring them upon exiting the block, subroutine or eval.
2635This means that called subroutines can also reference the local variable,
2636but not the global one.
2637The LIST may be assigned to if desired, which allows you to initialize
2638your local variables.
2639(If no initializer is given for a particular variable, it is created with
2640an undefined value.)
2641Commonly this is used to name the parameters to a subroutine.
2642Examples:
2643.nf
2644
2645.ne 13
2646 sub RANGEVAL {
2647 local($min, $max, $thunk) = @_;
2648 local($result) = \'\';
2649 local($i);
2650
2651 # Presumably $thunk makes reference to $i
2652
2653 for ($i = $min; $i < $max; $i++) {
2654 $result .= eval $thunk;
2655 }
2656
2657 $result;
2658 }
2659
2660.ne 6
2661 if ($sw eq \'-v\') {
2662 # init local array with global array
2663 local(@ARGV) = @ARGV;
2664 unshift(@ARGV,\'echo\');
2665 system @ARGV;
2666 }
2667 # @ARGV restored
2668
2669.ne 6
2670 # temporarily add to digits associative array
2671 if ($base12) {
2672 # (NOTE: not claiming this is efficient!)
2673 local(%digits) = (%digits,'t',10,'e',11);
2674 do parse_num();
2675 }
2676
2677.fi
2678Note that local() is a run-time command, and so gets executed every time
2679through a loop, using up more stack storage each time until it's all
2680released at once when the loop is exited.
2681.Ip "localtime(EXPR)" 8 4
2682.Ip "localtime EXPR" 8
2683Converts a time as returned by the time function to a 9-element array with
2684the time analyzed for the local timezone.
2685Typically used as follows:
2686.nf
2687
2688.ne 3
2689.ie t \{\
2690 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
2691'br\}
2692.el \{\
2693 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
2694 localtime(time);
2695'br\}
2696
2697.fi
2698All array elements are numeric, and come straight out of a struct tm.
2699In particular this means that $mon has the range 0.\|.11 and $wday has the
2700range 0.\|.6.
2701If EXPR is omitted, does localtime(time).
2702.Ip "log(EXPR)" 8 4
2703.Ip "log EXPR" 8
2704Returns logarithm (base
2705.IR e )
2706of EXPR.
2707If EXPR is omitted, returns log of $_.
2708.Ip "lstat(FILEHANDLE)" 8 6
2709.Ip "lstat FILEHANDLE" 8
2710.Ip "lstat(EXPR)" 8
2711.Ip "lstat SCALARVARIABLE" 8
2712Does the same thing as the stat() function, but stats a symbolic link
2713instead of the file the symbolic link points to.
2714If symbolic links are unimplemented on your system, a normal stat is done.
2715.Ip "m/PATTERN/io" 8 4
2716.Ip "/PATTERN/io" 8
2717Searches a string for a pattern match, and returns true (1) or false (\'\').
2718If no string is specified via the =~ or !~ operator,
2719the $_ string is searched.
2720(The string specified with =~ need not be an lvalue\*(--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.)
2721See also the section on regular expressions.
2722.Sp
2723If / is the delimiter then the initial \*(L'm\*(R' is optional.
2724With the \*(L'm\*(R' you can use any pair of non-alphanumeric characters
2725as delimiters.
2726This is particularly useful for matching Unix path names that contain \*(L'/\*(R'.
2727If the final delimiter is followed by the optional letter \*(L'i\*(R', the matching is
2728done in a case-insensitive manner.
2729PATTERN may contain references to scalar variables, which will be interpolated
2730(and the pattern recompiled) every time the pattern search is evaluated.
2731(Note that $) and $| may not be interpolated because they look like end-of-string tests.)
2732If you want such a pattern to be compiled only once, add an \*(L"o\*(R" after
2733the trailing delimiter.
2734This avoids expensive run-time recompilations, and
2735is useful when the value you are interpolating won't change over the
2736life of the script.
2737If the PATTERN evaluates to a null string, the most recent successful
2738regular expression is used instead.
2739.Sp
2740If used in a context that requires an array value, a pattern match returns an
2741array consisting of the subexpressions matched by the parentheses in the
2742pattern,
2743i.e. ($1, $2, $3.\|.\|.).
2744It does NOT actually set $1, $2, etc. in this case, nor does it set $+, $`, $&
2745or $'.
2746If the match fails, a null array is returned.
2747If the match succeeds, but there were no parentheses, an array value of (1)
2748is returned.
2749.Sp
2750Examples:
2751.nf
2752
2753.ne 4
2754 open(tty, \'/dev/tty\');
2755 <tty> \|=~ \|/\|^y\|/i \|&& \|do foo(\|); # do foo if desired
2756
2757 if (/Version: \|*\|([0\-9.]*\|)\|/\|) { $version = $1; }
2758
2759 next if m#^/usr/spool/uucp#;
2760
2761.ne 5
2762 # poor man's grep
2763 $arg = shift;
2764 while (<>) {
2765 print if /$arg/o; # compile only once
2766 }
2767
2768 if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
2769
2770.fi
2771This last example splits $foo into the first two words and the remainder
2772of the line, and assigns those three fields to $F1, $F2 and $Etc.
2773The conditional is true if any variables were assigned, i.e. if the pattern
2774matched.
2775.Ip "mkdir(FILENAME,MODE)" 8 3
2776Creates the directory specified by FILENAME, with permissions specified by
2777MODE (as modified by umask).
2778If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
2779.Ip "msgctl(ID,CMD,ARG)" 8 4
2780Calls the System V IPC function msgctl. If CMD is &IPC_STAT, then ARG
2781must be a variable which will hold the returned msqid_ds structure.
2782Returns like ioctl: the undefined value for error, "0 but true" for
2783zero, or the actual return value otherwise.
2784.Ip "msgget(KEY,FLAGS)" 8 4
2785Calls the System V IPC function msgget. Returns the message queue id,
2786or the undefined value if there is an error.
2787.Ip "msgsnd(ID,MSG,FLAGS)" 8 4
2788Calls the System V IPC function msgsnd to send the message MSG to the
2789message queue ID. MSG must begin with the long integer message type,
2790which may be created with pack("L", $type). Returns true if
2791successful, or false if there is an error.
2792.Ip "msgrcv(ID,VAR,SIZE,TYPE,FLAGS)" 8 4
2793Calls the System V IPC function msgrcv to receive a message from
2794message queue ID into variable VAR with a maximum message size of
2795SIZE. Note that if a message is received, the message type will be
2796the first thing in VAR, and the maximum length of VAR is SIZE plus the
2797size of the message type. Returns true if successful, or false if
2798there is an error.
2799''' Beginning of part 3
2800''' $Header: perl.man,v 4.0 91/03/20 01:38:08 lwall Locked $
2801'''
2802''' $Log: perl.man,v $
2803''' Revision 4.0 91/03/20 01:38:08 lwall
2804''' 4.0 baseline.
2805'''
2806''' Revision 3.0.1.12 91/01/11 18:18:15 lwall
2807''' patch42: added binary and hex pack/unpack options
2808'''
2809''' Revision 3.0.1.11 90/11/10 01:48:21 lwall
2810''' patch38: random cleanup
2811''' patch38: documented tr///cds
2812'''
2813''' Revision 3.0.1.10 90/10/20 02:15:17 lwall
2814''' patch37: patch37: fixed various typos in man page
2815'''
2816''' Revision 3.0.1.9 90/10/16 10:02:43 lwall
2817''' patch29: you can now read into the middle string
2818''' patch29: index and substr now have optional 3rd args
2819''' patch29: added scalar reverse
2820''' patch29: added scalar
2821''' patch29: added SysV IPC
2822''' patch29: added waitpid
2823''' patch29: added sysread and syswrite
2824'''
2825''' Revision 3.0.1.8 90/08/09 04:39:04 lwall
2826''' patch19: added require operator
2827''' patch19: added truncate operator
2828''' patch19: unpack can do checksumming
2829'''
2830''' Revision 3.0.1.7 90/08/03 11:15:42 lwall
2831''' patch19: Intermediate diffs for Randal
2832'''
2833''' Revision 3.0.1.6 90/03/27 16:17:56 lwall
2834''' patch16: MSDOS support
2835'''
2836''' Revision 3.0.1.5 90/03/12 16:52:21 lwall
2837''' patch13: documented that print $filehandle &foo is ambiguous
2838''' patch13: added splice operator: @oldelems = splice(@array,$offset,$len,LIST)
2839'''
2840''' Revision 3.0.1.4 90/02/28 18:00:09 lwall
2841''' patch9: added pipe function
2842''' patch9: documented how to handle arbitrary weird characters in filenames
2843''' patch9: documented the unflushed buffers problem on piped opens
2844''' patch9: documented how to force top of page
2845'''
2846''' Revision 3.0.1.3 89/12/21 20:10:12 lwall
2847''' patch7: documented that s`pat`repl` does command substitution on replacement
2848''' patch7: documented that $timeleft from select() is likely not implemented
2849'''
2850''' Revision 3.0.1.2 89/11/17 15:31:05 lwall
2851''' patch5: fixed some manual typos and indent problems
2852''' patch5: added warning about print making an array context
2853'''
2854''' Revision 3.0.1.1 89/11/11 04:45:06 lwall
2855''' patch2: made some line breaks depend on troff vs. nroff
2856'''
2857''' Revision 3.0 89/10/18 15:21:46 lwall
2858''' 3.0 baseline
2859'''
2860.Ip "next LABEL" 8 8
2861.Ip "next" 8
2862The
2863.I next
2864command is like the
2865.I continue
2866statement in C; it starts the next iteration of the loop:
2867.nf
2868
2869.ne 4
2870 line: while (<STDIN>) {
2871 next line if /\|^#/; # discard comments
2872 .\|.\|.
2873 }
2874
2875.fi
2876Note that if there were a
2877.I continue
2878block on the above, it would get executed even on discarded lines.
2879If the LABEL is omitted, the command refers to the innermost enclosing loop.
2880.Ip "oct(EXPR)" 8 4
2881.Ip "oct EXPR" 8
2882Returns the decimal value of EXPR interpreted as an octal string.
2883(If EXPR happens to start off with 0x, interprets it as a hex string instead.)
2884The following will handle decimal, octal and hex in the standard notation:
2885.nf
2886
2887 $val = oct($val) if $val =~ /^0/;
2888
2889.fi
2890If EXPR is omitted, uses $_.
2891.Ip "open(FILEHANDLE,EXPR)" 8 8
2892.Ip "open(FILEHANDLE)" 8
2893.Ip "open FILEHANDLE" 8
2894Opens the file whose filename is given by EXPR, and associates it with
2895FILEHANDLE.
2896If FILEHANDLE is an expression, its value is used as the name of the
2897real filehandle wanted.
2898If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE
2899contains the filename.
2900If the filename begins with \*(L"<\*(R" or nothing, the file is opened for
2901input.
2902If the filename begins with \*(L">\*(R", the file is opened for output.
2903If the filename begins with \*(L">>\*(R", the file is opened for appending.
2904(You can put a \'+\' in front of the \'>\' or \'<\' to indicate that you
2905want both read and write access to the file.)
2906If the filename begins with \*(L"|\*(R", the filename is interpreted
2907as a command to which output is to be piped, and if the filename ends
2908with a \*(L"|\*(R", the filename is interpreted as command which pipes
2909input to us.
2910(You may not have a command that pipes both in and out.)
2911Opening \'\-\' opens
2912.I STDIN
2913and opening \'>\-\' opens
2914.IR STDOUT .
2915Open returns non-zero upon success, the undefined value otherwise.
2916If the open involved a pipe, the return value happens to be the pid
2917of the subprocess.
2918Examples:
2919.nf
2920
2921.ne 3
2922 $article = 100;
2923 open article || die "Can't find article $article: $!\en";
2924 while (<article>) {\|.\|.\|.
2925
2926.ie t \{\
2927 open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved)
2928'br\}
2929.el \{\
2930 open(LOG, \'>>/usr/spool/news/twitlog\'\|);
2931 # (log is reserved)
2932'br\}
2933
2934.ie t \{\
2935 open(article, "caesar <$article |"\|); # decrypt article
2936'br\}
2937.el \{\
2938 open(article, "caesar <$article |"\|);
2939 # decrypt article
2940'br\}
2941
2942.ie t \{\
2943 open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process#
2944'br\}
2945.el \{\
2946 open(extract, "|sort >/tmp/Tmp$$"\|);
2947 # $$ is our process#
2948'br\}
2949
2950.ne 7
2951 # process argument list of files along with any includes
2952
2953 foreach $file (@ARGV) {
2954 do process($file, \'fh00\'); # no pun intended
2955 }
2956
2957 sub process {
2958 local($filename, $input) = @_;
2959 $input++; # this is a string increment
2960 unless (open($input, $filename)) {
2961 print STDERR "Can't open $filename: $!\en";
2962 return;
2963 }
2964.ie t \{\
2965 while (<$input>) { # note the use of indirection
2966'br\}
2967.el \{\
2968 while (<$input>) { # note use of indirection
2969'br\}
2970 if (/^#include "(.*)"/) {
2971 do process($1, $input);
2972 next;
2973 }
2974 .\|.\|. # whatever
2975 }
2976 }
2977
2978.fi
2979You may also, in the Bourne shell tradition, specify an EXPR beginning
2980with \*(L">&\*(R", in which case the rest of the string
2981is interpreted as the name of a filehandle
2982(or file descriptor, if numeric) which is to be duped and opened.
2983You may use & after >, >>, <, +>, +>> and +<.
2984The mode you specify should match the mode of the original filehandle.
2985Here is a script that saves, redirects, and restores
2986.I STDOUT
2987and
2988.IR STDERR :
2989.nf
2990
2991.ne 21
2992 #!/usr/bin/perl
2993 open(SAVEOUT, ">&STDOUT");
2994 open(SAVEERR, ">&STDERR");
2995
2996 open(STDOUT, ">foo.out") || die "Can't redirect stdout";
2997 open(STDERR, ">&STDOUT") || die "Can't dup stdout";
2998
2999 select(STDERR); $| = 1; # make unbuffered
3000 select(STDOUT); $| = 1; # make unbuffered
3001
3002 print STDOUT "stdout 1\en"; # this works for
3003 print STDERR "stderr 1\en"; # subprocesses too
3004
3005 close(STDOUT);
3006 close(STDERR);
3007
3008 open(STDOUT, ">&SAVEOUT");
3009 open(STDERR, ">&SAVEERR");
3010
3011 print STDOUT "stdout 2\en";
3012 print STDERR "stderr 2\en";
3013
3014.fi
3015If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R",
3016then there is an implicit fork done, and the return value of open
3017is the pid of the child within the parent process, and 0 within the child
3018process.
3019(Use defined($pid) to determine if the open was successful.)
3020The filehandle behaves normally for the parent, but i/o to that
3021filehandle is piped from/to the
3022.IR STDOUT / STDIN
3023of the child process.
3024In the child process the filehandle isn't opened\*(--i/o happens from/to
3025the new
3026.I STDOUT
3027or
3028.IR STDIN .
3029Typically this is used like the normal piped open when you want to exercise
3030more control over just how the pipe command gets executed, such as when
3031you are running setuid, and don't want to have to scan shell commands
3032for metacharacters.
3033The following pairs are more or less equivalent:
3034.nf
3035
3036.ne 5
3037 open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'");
3038 open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\';
3039
3040 open(FOO, "cat \-n '$file'|");
3041 open(FOO, "\-|") || exec \'cat\', \'\-n\', $file;
3042
3043.fi
3044Explicitly closing any piped filehandle causes the parent process to wait for the
3045child to finish, and returns the status value in $?.
3046Note: on any operation which may do a fork,
3047unflushed buffers remain unflushed in both
3048processes, which means you may need to set $| to
3049avoid duplicate output.
3050.Sp
3051The filename that is passed to open will have leading and trailing
3052whitespace deleted.
3053In order to open a file with arbitrary weird characters in it, it's necessary
3054to protect any leading and trailing whitespace thusly:
3055.nf
3056
3057.ne 2
3058 $file =~ s#^(\es)#./$1#;
3059 open(FOO, "< $file\e0");
3060
3061.fi
3062.Ip "opendir(DIRHANDLE,EXPR)" 8 3
3063Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(),
3064rewinddir() and closedir().
3065Returns true if successful.
3066DIRHANDLEs have their own namespace separate from FILEHANDLEs.
3067.Ip "ord(EXPR)" 8 4
3068.Ip "ord EXPR" 8
3069Returns the numeric ascii value of the first character of EXPR.
3070If EXPR is omitted, uses $_.
3071''' Comments on f & d by gnb@melba.bby.oz.au 22/11/89
3072.Ip "pack(TEMPLATE,LIST)" 8 4
3073Takes an array or list of values and packs it into a binary structure,
3074returning the string containing the structure.
3075The TEMPLATE is a sequence of characters that give the order and type
3076of values, as follows:
3077.nf
3078
3079 A An ascii string, will be space padded.
3080 a An ascii string, will be null padded.
3081 c A signed char value.
3082 C An unsigned char value.
3083 s A signed short value.
3084 S An unsigned short value.
3085 i A signed integer value.
3086 I An unsigned integer value.
3087 l A signed long value.
3088 L An unsigned long value.
3089 n A short in \*(L"network\*(R" order.
3090 N A long in \*(L"network\*(R" order.
3091 f A single-precision float in the native format.
3092 d A double-precision float in the native format.
3093 p A pointer to a string.
3094 x A null byte.
3095 X Back up a byte.
3096 @ Null fill to absolute position.
3097 u A uuencoded string.
3098 b A bit string (ascending bit order, like vec()).
3099 B A bit string (descending bit order).
3100 h A hex string (low nybble first).
3101 H A hex string (high nybble first).
3102
3103.fi
3104Each letter may optionally be followed by a number which gives a repeat
3105count.
3106With all types except "a", "A", "b", "B", "h" and "H",
3107the pack function will gobble up that many values
3108from the LIST.
3109A * for the repeat count means to use however many items are left.
3110The "a" and "A" types gobble just one value, but pack it as a string of length
3111count,
3112padding with nulls or spaces as necessary.
3113(When unpacking, "A" strips trailing spaces and nulls, but "a" does not.)
3114Likewise, the "b" and "B" fields pack a string that many bits long.
3115The "h" and "H" fields pack a string that many nybbles long.
3116Real numbers (floats and doubles) are in the native machine format
3117only; due to the multiplicity of floating formats around, and the lack
3118of a standard \*(L"network\*(R" representation, no facility for
3119interchange has been made.
3120This means that packed floating point data
3121written on one machine may not be readable on another - even if both
3122use IEEE floating point arithmetic (as the endian-ness of the memory
3123representation is not part of the IEEE spec).
3124Note that perl uses
3125doubles internally for all numeric calculation, and converting from
3126double -> float -> double will lose precision (i.e. unpack("f",
3127pack("f", $foo)) will not in general equal $foo).
3128.br
3129Examples:
3130.nf
3131
3132 $foo = pack("cccc",65,66,67,68);
3133 # foo eq "ABCD"
3134 $foo = pack("c4",65,66,67,68);
3135 # same thing
3136
3137 $foo = pack("ccxxcc",65,66,67,68);
3138 # foo eq "AB\e0\e0CD"
3139
3140 $foo = pack("s2",1,2);
3141 # "\e1\e0\e2\e0" on little-endian
3142 # "\e0\e1\e0\e2" on big-endian
3143
3144 $foo = pack("a4","abcd","x","y","z");
3145 # "abcd"
3146
3147 $foo = pack("aaaa","abcd","x","y","z");
3148 # "axyz"
3149
3150 $foo = pack("a14","abcdefg");
3151 # "abcdefg\e0\e0\e0\e0\e0\e0\e0"
3152
3153 $foo = pack("i9pl", gmtime);
3154 # a real struct tm (on my system anyway)
3155
3156 sub bintodec {
3157 unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
3158 }
3159.fi
3160The same template may generally also be used in the unpack function.
3161.Ip "pipe(READHANDLE,WRITEHANDLE)" 8 3
3162Opens a pair of connected pipes like the corresponding system call.
3163Note that if you set up a loop of piped processes, deadlock can occur
3164unless you are very careful.
3165In addition, note that perl's pipes use stdio buffering, so you may need
3166to set $| to flush your WRITEHANDLE after each command, depending on
3167the application.
3168[Requires version 3.0 patchlevel 9.]
3169.Ip "pop(ARRAY)" 8
3170.Ip "pop ARRAY" 8 6
3171Pops and returns the last value of the array, shortening the array by 1.
3172Has the same effect as
3173.nf
3174
3175 $tmp = $ARRAY[$#ARRAY\-\|\-];
3176
3177.fi
3178If there are no elements in the array, returns the undefined value.
3179.Ip "print(FILEHANDLE LIST)" 8 10
3180.Ip "print(LIST)" 8
3181.Ip "print FILEHANDLE LIST" 8
3182.Ip "print LIST" 8
3183.Ip "print" 8
3184Prints a string or a comma-separated list of strings.
3185Returns non-zero if successful.
3186FILEHANDLE may be a scalar variable name, in which case the variable contains
3187the name of the filehandle, thus introducing one level of indirection.
3188(NOTE: If FILEHANDLE is a variable and the next token is a term, it may be
3189misinterpreted as an operator unless you interpose a + or put parens around
3190the arguments.)
3191If FILEHANDLE is omitted, prints by default to standard output (or to the
3192last selected output channel\*(--see select()).
3193If LIST is also omitted, prints $_ to
3194.IR STDOUT .
3195To set the default output channel to something other than
3196.I STDOUT
3197use the select operation.
3198Note that, because print takes a LIST, anything in the LIST is evaluated
3199in an array context, and any subroutine that you call will have one or more
3200of its expressions evaluated in an array context.
3201Also be careful not to follow the print keyword with a left parenthesis
3202unless you want the corresponding right parenthesis to terminate the
3203arguments to the print\*(--interpose a + or put parens around all the arguments.
3204.Ip "printf(FILEHANDLE LIST)" 8 10
3205.Ip "printf(LIST)" 8
3206.Ip "printf FILEHANDLE LIST" 8
3207.Ip "printf LIST" 8
3208Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R".
3209.Ip "push(ARRAY,LIST)" 8 7
3210Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST
3211onto the end of ARRAY.
3212The length of ARRAY increases by the length of LIST.
3213Has the same effect as
3214.nf
3215
3216 for $value (LIST) {
3217 $ARRAY[++$#ARRAY] = $value;
3218 }
3219
3220.fi
3221but is more efficient.
3222.Ip "q/STRING/" 8 5
3223.Ip "qq/STRING/" 8
3224.Ip "qx/STRING/" 8
3225These are not really functions, but simply syntactic sugar to let you
3226avoid putting too many backslashes into quoted strings.
3227The q operator is a generalized single quote, and the qq operator a
3228generalized double quote.
3229The qx operator is a generalized backquote.
3230Any non-alphanumeric delimiter can be used in place of /, including newline.
3231If the delimiter is an opening bracket or parenthesis, the final delimiter
3232will be the corresponding closing bracket or parenthesis.
3233(Embedded occurrences of the closing bracket need to be backslashed as usual.)
3234Examples:
3235.nf
3236
3237.ne 5
3238 $foo = q!I said, "You said, \'She said it.\'"!;
3239 $bar = q(\'This is it.\');
3240 $today = qx{ date };
3241 $_ .= qq
3242*** The previous line contains the naughty word "$&".\en
3243 if /(ibm|apple|awk)/; # :-)
3244
3245.fi
3246.Ip "rand(EXPR)" 8 8
3247.Ip "rand EXPR" 8
3248.Ip "rand" 8
3249Returns a random fractional number between 0 and the value of EXPR.
3250(EXPR should be positive.)
3251If EXPR is omitted, returns a value between 0 and 1.
3252See also srand().
3253.Ip "read(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
3254.Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5
3255Attempts to read LENGTH bytes of data into variable SCALAR from the specified
3256FILEHANDLE.
3257Returns the number of bytes actually read, or undef if there was an error.
3258SCALAR will be grown or shrunk to the length actually read.
3259An OFFSET may be specified to place the read data at some other place
3260than the beginning of the string.
3261This call is actually implemented in terms of stdio's fread call. To get
3262a true read system call, see sysread.
3263.Ip "readdir(DIRHANDLE)" 8 3
3264.Ip "readdir DIRHANDLE" 8
3265Returns the next directory entry for a directory opened by opendir().
3266If used in an array context, returns all the rest of the entries in the
3267directory.
3268If there are no more entries, returns an undefined value in a scalar context
3269or a null list in an array context.
3270.Ip "readlink(EXPR)" 8 6
3271.Ip "readlink EXPR" 8
3272Returns the value of a symbolic link, if symbolic links are implemented.
3273If not, gives a fatal error.
3274If there is some system error, returns the undefined value and sets $! (errno).
3275If EXPR is omitted, uses $_.
3276.Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4
3277Receives a message on a socket.
3278Attempts to receive LENGTH bytes of data into variable SCALAR from the specified
3279SOCKET filehandle.
3280Returns the address of the sender, or the undefined value if there's an error.
3281SCALAR will be grown or shrunk to the length actually read.
3282Takes the same flags as the system call of the same name.
3283.Ip "redo LABEL" 8 8
3284.Ip "redo" 8
3285The
3286.I redo
3287command restarts the loop block without evaluating the conditional again.
3288The
3289.I continue
3290block, if any, is not executed.
3291If the LABEL is omitted, the command refers to the innermost enclosing loop.
3292This command is normally used by programs that want to lie to themselves
3293about what was just input:
3294.nf
3295
3296.ne 16
3297 # a simpleminded Pascal comment stripper
3298 # (warning: assumes no { or } in strings)
3299 line: while (<STDIN>) {
3300 while (s|\|({.*}.*\|){.*}|$1 \||) {}
3301 s|{.*}| \||;
3302 if (s|{.*| \||) {
3303 $front = $_;
3304 while (<STDIN>) {
3305 if (\|/\|}/\|) { # end of comment?
3306 s|^|$front{|;
3307 redo line;
3308 }
3309 }
3310 }
3311 print;
3312 }
3313
3314.fi
3315.Ip "rename(OLDNAME,NEWNAME)" 8 2
3316Changes the name of a file.
3317Returns 1 for success, 0 otherwise.
3318Will not work across filesystem boundaries.
3319.Ip "require(EXPR)" 8 6
3320.Ip "require EXPR" 8
3321.Ip "require" 8
3322Includes the library file specified by EXPR, or by $_ if EXPR is not supplied.
3323Has semantics similar to the following subroutine:
3324.nf
3325
3326 sub require {
3327 local($filename) = @_;
3328 return 1 if $INC{$filename};
3329 local($realfilename,$result);
3330 ITER: {
3331 foreach $prefix (@INC) {
3332 $realfilename = "$prefix/$filename";
3333 if (-f $realfilename) {
3334 $result = do $realfilename;
3335 last ITER;
3336 }
3337 }
3338 die "Can't find $filename in \e@INC";
3339 }
3340 die $@ if $@;
3341 die "$filename did not return true value" unless $result;
3342 $INC{$filename} = $realfilename;
3343 $result;
3344 }
3345
3346.fi
3347Note that the file will not be included twice under the same specified name.
3348.Ip "reset(EXPR)" 8 6
3349.Ip "reset EXPR" 8
3350.Ip "reset" 8
3351Generally used in a
3352.I continue
3353block at the end of a loop to clear variables and reset ?? searches
3354so that they work again.
3355The expression is interpreted as a list of single characters (hyphens allowed
3356for ranges).
3357All variables and arrays beginning with one of those letters are reset to
3358their pristine state.
3359If the expression is omitted, one-match searches (?pattern?) are reset to
3360match again.
3361Only resets variables or searches in the current package.
3362Always returns 1.
3363Examples:
3364.nf
3365
3366.ne 3
3367 reset \'X\'; \h'|2i'# reset all X variables
3368 reset \'a\-z\';\h'|2i'# reset lower case variables
3369 reset; \h'|2i'# just reset ?? searches
3370
3371.fi
3372Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV
3373arrays.
3374.Sp
3375The use of reset on dbm associative arrays does not change the dbm file.
3376(It does, however, flush any entries cached by perl, which may be useful if
3377you are sharing the dbm file.
3378Then again, maybe not.)
3379.Ip "return LIST" 8 3
3380Returns from a subroutine with the value specified.
3381(Note that a subroutine can automatically return
3382the value of the last expression evaluated.
3383That's the preferred method\*(--use of an explicit
3384.I return
3385is a bit slower.)
3386.Ip "reverse(LIST)" 8 4
3387.Ip "reverse LIST" 8
3388In an array context, returns an array value consisting of the elements
3389of LIST in the opposite order.
3390In a scalar context, returns a string value consisting of the bytes of
3391the first element of LIST in the opposite order.
3392.Ip "rewinddir(DIRHANDLE)" 8 5
3393.Ip "rewinddir DIRHANDLE" 8
3394Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE.
3395.Ip "rindex(STR,SUBSTR,POSITION)" 8 6
3396.Ip "rindex(STR,SUBSTR)" 8 4
3397Works just like index except that it
3398returns the position of the LAST occurrence of SUBSTR in STR.
3399If POSITION is specified, returns the last occurrence at or before that
3400position.
3401.Ip "rmdir(FILENAME)" 8 4
3402.Ip "rmdir FILENAME" 8
3403Deletes the directory specified by FILENAME if it is empty.
3404If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
3405If FILENAME is omitted, uses $_.
3406.Ip "s/PATTERN/REPLACEMENT/gieo" 8 3
3407Searches a string for a pattern, and if found, replaces that pattern with the
3408replacement text and returns the number of substitutions made.
3409Otherwise it returns false (0).
3410The \*(L"g\*(R" is optional, and if present, indicates that all occurrences
3411of the pattern are to be replaced.
3412The \*(L"i\*(R" is also optional, and if present, indicates that matching
3413is to be done in a case-insensitive manner.
3414The \*(L"e\*(R" is likewise optional, and if present, indicates that
3415the replacement string is to be evaluated as an expression rather than just
3416as a double-quoted string.
3417Any non-alphanumeric delimiter may replace the slashes;
3418if single quotes are used, no
3419interpretation is done on the replacement string (the e modifier overrides
3420this, however); if backquotes are used, the replacement string is a command
3421to execute whose output will be used as the actual replacement text.
3422If no string is specified via the =~ or !~ operator,
3423the $_ string is searched and modified.
3424(The string specified with =~ must be a scalar variable, an array element,
3425or an assignment to one of those, i.e. an lvalue.)
3426If the pattern contains a $ that looks like a variable rather than an
3427end-of-string test, the variable will be interpolated into the pattern at
3428run-time.
3429If you only want the pattern compiled once the first time the variable is
3430interpolated, add an \*(L"o\*(R" at the end.
3431If the PATTERN evaluates to a null string, the most recent successful
3432regular expression is used instead.
3433See also the section on regular expressions.
3434Examples:
3435.nf
3436
3437 s/\|\e\|bgreen\e\|b/mauve/g; # don't change wintergreen
3438
3439 $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;
3440
3441 s/Login: $foo/Login: $bar/; # run-time pattern
3442
3443 ($foo = $bar) =~ s/bar/foo/;
3444
3445 $_ = \'abc123xyz\';
3446 s/\ed+/$&*2/e; # yields \*(L'abc246xyz\*(R'
3447 s/\ed+/sprintf("%5d",$&)/e; # yields \*(L'abc 246xyz\*(R'
3448 s/\ew/$& x 2/eg; # yields \*(L'aabbcc 224466xxyyzz\*(R'
3449
3450 s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/; # reverse 1st two fields
3451
3452.fi
3453(Note the use of $ instead of \|\e\| in the last example. See section
3454on regular expressions.)
3455.Ip "scalar(EXPR)" 8 3
3456Forces EXPR to be interpreted in a scalar context and returns the value
3457of EXPR.
3458.Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
3459Randomly positions the file pointer for FILEHANDLE, just like the fseek()
3460call of stdio.
3461FILEHANDLE may be an expression whose value gives the name of the filehandle.
3462Returns 1 upon success, 0 otherwise.
3463.Ip "seekdir(DIRHANDLE,POS)" 8 3
3464Sets the current position for the readdir() routine on DIRHANDLE.
3465POS must be a value returned by telldir().
3466Has the same caveats about possible directory compaction as the corresponding
3467system library routine.
3468.Ip "select(FILEHANDLE)" 8 3
3469.Ip "select" 8 3
3470Returns the currently selected filehandle.
3471Sets the current default filehandle for output, if FILEHANDLE is supplied.
3472This has two effects: first, a
3473.I write
3474or a
3475.I print
3476without a filehandle will default to this FILEHANDLE.
3477Second, references to variables related to output will refer to this output
3478channel.
3479For example, if you have to set the top of form format for more than
3480one output channel, you might do the following:
3481.nf
3482
3483.ne 4
3484 select(REPORT1);
3485 $^ = \'report1_top\';
3486 select(REPORT2);
3487 $^ = \'report2_top\';
3488
3489.fi
3490FILEHANDLE may be an expression whose value gives the name of the actual filehandle.
3491Thus:
3492.nf
3493
3494 $oldfh = select(STDERR); $| = 1; select($oldfh);
3495
3496.fi
3497.Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3
3498This calls the select system call with the bitmasks specified, which can
3499be constructed using fileno() and vec(), along these lines:
3500.nf
3501
3502 $rin = $win = $ein = '';
3503 vec($rin,fileno(STDIN),1) = 1;
3504 vec($win,fileno(STDOUT),1) = 1;
3505 $ein = $rin | $win;
3506
3507.fi
3508If you want to select on many filehandles you might wish to write a subroutine:
3509.nf
3510
3511 sub fhbits {
3512 local(@fhlist) = split(' ',$_[0]);
3513 local($bits);
3514 for (@fhlist) {
3515 vec($bits,fileno($_),1) = 1;
3516 }
3517 $bits;
3518 }
3519 $rin = &fhbits('STDIN TTY SOCK');
3520
3521.fi
3522The usual idiom is:
3523.nf
3524
3525 ($nfound,$timeleft) =
3526 select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
3527
3528or to block until something becomes ready:
3529
3530.ie t \{\
3531 $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
3532'br\}
3533.el \{\
3534 $nfound = select($rout=$rin, $wout=$win,
3535 $eout=$ein, undef);
3536'br\}
3537
3538.fi
3539Any of the bitmasks can also be undef.
3540The timeout, if specified, is in seconds, which may be fractional.
3541NOTE: not all implementations are capable of returning the $timeleft.
3542If not, they always return $timeleft equal to the supplied $timeout.
3543.Ip "semctl(ID,SEMNUM,CMD,ARG)" 8 4
3544Calls the System V IPC function semctl. If CMD is &IPC_STAT or
3545&GETALL, then ARG must be a variable which will hold the returned
3546semid_ds structure or semaphore value array. Returns like ioctl: the
3547undefined value for error, "0 but true" for zero, or the actual return
3548value otherwise.
3549.Ip "semget(KEY,NSEMS,SIZE,FLAGS)" 8 4
3550Calls the System V IPC function semget. Returns the semaphore id, or
3551the undefined value if there is an error.
3552.Ip "semop(KEY,OPSTRING)" 8 4
3553Calls the System V IPC function semop to perform semaphore operations
3554such as signaling and waiting. OPSTRING must be a packed array of
3555semop structures. Each semop structure can be generated with
3556\&'pack("sss", $semnum, $semop, $semflag)'. The number of semaphore
3557operations is implied by the length of OPSTRING. Returns true if
3558successful, or false if there is an error. As an example, the
3559following code waits on semaphore $semnum of semaphore id $semid:
3560.nf
3561
3562 $semop = pack("sss", $semnum, -1, 0);
3563 die "Semaphore trouble: $!\en" unless semop($semid, $semop);
3564
3565.fi
3566To signal the semaphore, replace "-1" with "1".
3567.Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4
3568.Ip "send(SOCKET,MSG,FLAGS)" 8
3569Sends a message on a socket.
3570Takes the same flags as the system call of the same name.
3571On unconnected sockets you must specify a destination to send TO.
3572Returns the number of characters sent, or the undefined value if
3573there is an error.
3574.Ip "setpgrp(PID,PGRP)" 8 4
3575Sets the current process group for the specified PID, 0 for the current
3576process.
3577Will produce a fatal error if used on a machine that doesn't implement
3578setpgrp(2).
3579.Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4
3580Sets the current priority for a process, a process group, or a user.
3581(See setpriority(2).)
3582Will produce a fatal error if used on a machine that doesn't implement
3583setpriority(2).
3584.Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3
3585Sets the socket option requested.
3586Returns undefined if there is an error.
3587OPTVAL may be specified as undef if you don't want to pass an argument.
3588.Ip "shift(ARRAY)" 8 6
3589.Ip "shift ARRAY" 8
3590.Ip "shift" 8
3591Shifts the first value of the array off and returns it,
3592shortening the array by 1 and moving everything down.
3593If there are no elements in the array, returns the undefined value.
3594If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_
3595array in subroutines.
3596(This is determined lexically.)
3597See also unshift(), push() and pop().
3598Shift() and unshift() do the same thing to the left end of an array that push()
3599and pop() do to the right end.
3600.Ip "shmctl(ID,CMD,ARG)" 8 4
3601Calls the System V IPC function shmctl. If CMD is &IPC_STAT, then ARG
3602must be a variable which will hold the returned shmid_ds structure.
3603Returns like ioctl: the undefined value for error, "0 but true" for
3604zero, or the actual return value otherwise.
3605.Ip "shmget(KEY,SIZE,FLAGS)" 8 4
3606Calls the System V IPC function shmget. Returns the shared memory
3607segment id, or the undefined value if there is an error.
3608.Ip "shmread(ID,VAR,POS,SIZE)" 8 4
3609.Ip "shmwrite(ID,STRING,POS,SIZE)" 8
3610Reads or writes the System V shared memory segment ID starting at
3611position POS for size SIZE by attaching to it, copying in/out, and
3612detaching from it. When reading, VAR must be a variable which
3613will hold the data read. When writing, if STRING is too long,
3614only SIZE bytes are used; if STRING is too short, nulls are
3615written to fill out SIZE bytes. Return true if successful, or
3616false if there is an error.
3617.Ip "shutdown(SOCKET,HOW)" 8 3
3618Shuts down a socket connection in the manner indicated by HOW, which has
3619the same interpretation as in the system call of the same name.
3620.Ip "sin(EXPR)" 8 4
3621.Ip "sin EXPR" 8
3622Returns the sine of EXPR (expressed in radians).
3623If EXPR is omitted, returns sine of $_.
3624.Ip "sleep(EXPR)" 8 6
3625.Ip "sleep EXPR" 8
3626.Ip "sleep" 8
3627Causes the script to sleep for EXPR seconds, or forever if no EXPR.
3628May be interrupted by sending the process a SIGALARM.
3629Returns the number of seconds actually slept.
3630.Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3
3631Opens a socket of the specified kind and attaches it to filehandle SOCKET.
3632DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
3633of the same name.
3634You may need to run h2ph on sys/socket.h to get the proper values handy
3635in a perl library file.
3636Return true if successful.
3637See the example in the section on Interprocess Communication.
3638.Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3
3639Creates an unnamed pair of sockets in the specified domain, of the specified
3640type.
3641DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
3642of the same name.
3643If unimplemented, yields a fatal error.
3644Return true if successful.
3645.Ip "sort(SUBROUTINE LIST)" 8 9
3646.Ip "sort(LIST)" 8
3647.Ip "sort SUBROUTINE LIST" 8
3648.Ip "sort LIST" 8
3649Sorts the LIST and returns the sorted array value.
3650Nonexistent values of arrays are stripped out.
3651If SUBROUTINE is omitted, sorts in standard string comparison order.
3652If SUBROUTINE is specified, gives the name of a subroutine that returns
3653an integer less than, equal to, or greater than 0,
3654depending on how the elements of the array are to be ordered.
3655In the interests of efficiency the normal calling code for subroutines
3656is bypassed, with the following effects: the subroutine may not be a recursive
3657subroutine, and the two elements to be compared are passed into the subroutine
3658not via @_ but as $a and $b (see example below).
3659They are passed by reference so don't modify $a and $b.
3660SUBROUTINE may be a scalar variable name, in which case the value provides
3661the name of the subroutine to use.
3662Examples:
3663.nf
3664
3665.ne 4
3666 sub byage {
3667 $age{$a} - $age{$b}; # presuming integers
3668 }
3669 @sortedclass = sort byage @class;
3670
3671.ne 9
3672 sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; }
3673 @harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\');
3674 @george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\');
3675 print sort @harry;
3676 # prints AbelCaincatdogx
3677 print sort reverse @harry;
3678 # prints xdogcatCainAbel
3679 print sort @george, \'to\', @harry;
3680 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
3681
3682.fi
3683.Ip "splice(ARRAY,OFFSET,LENGTH,LIST)" 8 8
3684.Ip "splice(ARRAY,OFFSET,LENGTH)" 8
3685.Ip "splice(ARRAY,OFFSET)" 8
3686Removes the elements designated by OFFSET and LENGTH from an array, and
3687replaces them with the elements of LIST, if any.
3688Returns the elements removed from the array.
3689The array grows or shrinks as necessary.
3690If LENGTH is omitted, removes everything from OFFSET onward.
3691The following equivalencies hold (assuming $[ == 0):
3692.nf
3693
3694 push(@a,$x,$y)\h'|3.5i'splice(@a,$#a+1,0,$x,$y)
3695 pop(@a)\h'|3.5i'splice(@a,-1)
3696 shift(@a)\h'|3.5i'splice(@a,0,1)
3697 unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y)
3698 $a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y);
3699
3700Example, assuming array lengths are passed before arrays:
3701
3702 sub aeq { # compare two array values
3703 local(@a) = splice(@_,0,shift);
3704 local(@b) = splice(@_,0,shift);
3705 return 0 unless @a == @b; # same len?
3706 while (@a) {
3707 return 0 if pop(@a) ne pop(@b);
3708 }
3709 return 1;
3710 }
3711 if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
3712
3713.fi
3714.Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
3715.Ip "split(/PATTERN/,EXPR)" 8 8
3716.Ip "split(/PATTERN/)" 8
3717.Ip "split" 8
3718Splits a string into an array of strings, and returns it.
3719(If not in an array context, returns the number of fields found and splits
3720into the @_ array.
3721(In an array context, you can force the split into @_
3722by using ?? as the pattern delimiters, but it still returns the array value.))
3723If EXPR is omitted, splits the $_ string.
3724If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
3725Anything matching PATTERN is taken to be a delimiter separating the fields.
3726(Note that the delimiter may be longer than one character.)
3727If LIMIT is specified, splits into no more than that many fields (though it
3728may split into fewer).
3729If LIMIT is unspecified, trailing null fields are stripped (which
3730potential users of pop() would do well to remember).
3731A pattern matching the null string (not to be confused with a null pattern //,
3732which is just one member of the set of patterns matching a null string)
3733will split the value of EXPR into separate characters at each point it
3734matches that way.
3735For example:
3736.nf
3737
3738 print join(\':\', split(/ */, \'hi there\'));
3739
3740.fi
3741produces the output \*(L'h:i:t:h:e:r:e\*(R'.
3742.Sp
3743The LIMIT parameter can be used to partially split a line
3744.nf
3745
3746 ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);
3747
3748.fi
3749(When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one
3750larger than the number of variables in the list, to avoid unnecessary work.
3751For the list above LIMIT would have been 4 by default.
3752In time critical applications it behooves you not to split into
3753more fields than you really need.)
3754.Sp
3755If the PATTERN contains parentheses, additional array elements are created
3756from each matching substring in the delimiter.
3757.Sp
3758 split(/([,-])/,"1-10,20");
3759.Sp
3760produces the array value
3761.Sp
3762 (1,'-',10,',',20)
3763.Sp
3764The pattern /PATTERN/ may be replaced with an expression to specify patterns
3765that vary at runtime.
3766(To do runtime compilation only once, use /$variable/o.)
3767As a special case, specifying a space (\'\ \') will split on white space
3768just as split with no arguments does, but leading white space does NOT
3769produce a null first field.
3770Thus, split(\'\ \') can be used to emulate
3771.IR awk 's
3772default behavior, whereas
3773split(/\ /) will give you as many null initial fields as there are
3774leading spaces.
3775.Sp
3776Example:
3777.nf
3778
3779.ne 5
3780 open(passwd, \'/etc/passwd\');
3781 while (<passwd>) {
3782.ie t \{\
3783 ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
3784'br\}
3785.el \{\
3786 ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
3787 = split(\|/\|:\|/\|);
3788'br\}
3789 .\|.\|.
3790 }
3791
3792.fi
3793(Note that $shell above will still have a newline on it. See chop().)
3794See also
3795.IR join .
3796.Ip "sprintf(FORMAT,LIST)" 8 4
3797Returns a string formatted by the usual printf conventions.
3798The * character is not supported.
3799.Ip "sqrt(EXPR)" 8 4
3800.Ip "sqrt EXPR" 8
3801Return the square root of EXPR.
3802If EXPR is omitted, returns square root of $_.
3803.Ip "srand(EXPR)" 8 4
3804.Ip "srand EXPR" 8
3805Sets the random number seed for the
3806.I rand
3807operator.
3808If EXPR is omitted, does srand(time).
3809.Ip "stat(FILEHANDLE)" 8 8
3810.Ip "stat FILEHANDLE" 8
3811.Ip "stat(EXPR)" 8
3812.Ip "stat SCALARVARIABLE" 8
3813Returns a 13-element array giving the statistics for a file, either the file
3814opened via FILEHANDLE, or named by EXPR.
3815Typically used as follows:
3816.nf
3817
3818.ne 3
3819 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
3820 $atime,$mtime,$ctime,$blksize,$blocks)
3821 = stat($filename);
3822
3823.fi
3824If stat is passed the special filehandle consisting of an underline,
3825no stat is done, but the current contents of the stat structure from
3826the last stat or filetest are returned.
3827Example:
3828.nf
3829
3830.ne 3
3831 if (-x $file && (($d) = stat(_)) && $d < 0) {
3832 print "$file is executable NFS file\en";
3833 }
3834
3835.fi
3836.Ip "study(SCALAR)" 8 6
3837.Ip "study SCALAR" 8
3838.Ip "study"
3839Takes extra time to study SCALAR ($_ if unspecified) in anticipation of
3840doing many pattern matches on the string before it is next modified.
3841This may or may not save time, depending on the nature and number of patterns
3842you are searching on, and on the distribution of character frequencies in
3843the string to be searched\*(--you probably want to compare runtimes with and
3844without it to see which runs faster.
3845Those loops which scan for many short constant strings (including the constant
3846parts of more complex patterns) will benefit most.
3847You may have only one study active at a time\*(--if you study a different
3848scalar the first is \*(L"unstudied\*(R".
3849(The way study works is this: a linked list of every character in the string
3850to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters
3851are.
3852From each search string, the rarest character is selected, based on some
3853static frequency tables constructed from some C programs and English text.
3854Only those places that contain this \*(L"rarest\*(R" character are examined.)
3855.Sp
3856For example, here is a loop which inserts index producing entries before any line
3857containing a certain pattern:
3858.nf
3859
3860.ne 8
3861 while (<>) {
3862 study;
3863 print ".IX foo\en" if /\ebfoo\eb/;
3864 print ".IX bar\en" if /\ebbar\eb/;
3865 print ".IX blurfl\en" if /\ebblurfl\eb/;
3866 .\|.\|.
3867 print;
3868 }
3869
3870.fi
3871In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R'
3872will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'.
3873In general, this is a big win except in pathological cases.
3874The only question is whether it saves you more time than it took to build
3875the linked list in the first place.
3876.Sp
3877Note that if you have to look for strings that you don't know till runtime,
3878you can build an entire loop as a string and eval that to avoid recompiling
3879all your patterns all the time.
3880Together with undefining $/ to input entire files as one record, this can
3881be very fast, often faster than specialized programs like fgrep.
3882The following scans a list of files (@files)
3883for a list of words (@words), and prints out the names of those files that
3884contain a match:
3885.nf
3886
3887.ne 12
3888 $search = \'while (<>) { study;\';
3889 foreach $word (@words) {
3890 $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en";
3891 }
3892 $search .= "}";
3893 @ARGV = @files;
3894 undef $/;
3895 eval $search; # this screams
3896 $/ = "\en"; # put back to normal input delim
3897 foreach $file (sort keys(%seen)) {
3898 print $file, "\en";
3899 }
3900
3901.fi
3902.Ip "substr(EXPR,OFFSET,LEN)" 8 2
3903.Ip "substr(EXPR,OFFSET)" 8 2
3904Extracts a substring out of EXPR and returns it.
3905First character is at offset 0, or whatever you've set $[ to.
3906If OFFSET is negative, starts that far from the end of the string.
3907If LEN is omitted, returns everything to the end of the string.
3908You can use the substr() function as an lvalue, in which case EXPR must
3909be an lvalue.
3910If you assign something shorter than LEN, the string will shrink, and
3911if you assign something longer than LEN, the string will grow to accommodate it.
3912To keep the string the same length you may need to pad or chop your value using
3913sprintf().
3914.Ip "symlink(OLDFILE,NEWFILE)" 8 2
3915Creates a new filename symbolically linked to the old filename.
3916Returns 1 for success, 0 otherwise.
3917On systems that don't support symbolic links, produces a fatal error at
3918run time.
3919To check for that, use eval:
3920.nf
3921
3922 $symlink_exists = (eval \'symlink("","");\', $@ eq \'\');
3923
3924.fi
3925.Ip "syscall(LIST)" 8 6
3926.Ip "syscall LIST" 8
3927Calls the system call specified as the first element of the list, passing
3928the remaining elements as arguments to the system call.
3929If unimplemented, produces a fatal error.
3930The arguments are interpreted as follows: if a given argument is numeric,
3931the argument is passed as an int.
3932If not, the pointer to the string value is passed.
3933You are responsible to make sure a string is pre-extended long enough
3934to receive any result that might be written into a string.
3935If your integer arguments are not literals and have never been interpreted
3936in a numeric context, you may need to add 0 to them to force them to look
3937like numbers.
3938.nf
3939
3940 require 'syscall.ph'; # may need to run h2ph
3941 syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9);
3942
3943.fi
3944.Ip "sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
3945.Ip "sysread(FILEHANDLE,SCALAR,LENGTH)" 8 5
3946Attempts to read LENGTH bytes of data into variable SCALAR from the specified
3947FILEHANDLE, using the system call read(2).
3948It bypasses stdio, so mixing this with other kinds of reads may cause
3949confusion.
3950Returns the number of bytes actually read, or undef if there was an error.
3951SCALAR will be grown or shrunk to the length actually read.
3952An OFFSET may be specified to place the read data at some other place
3953than the beginning of the string.
3954.Ip "system(LIST)" 8 6
3955.Ip "system LIST" 8
3956Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork
3957is done first, and the parent process waits for the child process to complete.
3958Note that argument processing varies depending on the number of arguments.
3959The return value is the exit status of the program as returned by the wait()
3960call.
3961To get the actual exit value divide by 256.
3962See also
3963.IR exec .
3964.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
3965.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH)" 8 5
3966Attempts to write LENGTH bytes of data from variable SCALAR to the specified
3967FILEHANDLE, using the system call write(2).
3968It bypasses stdio, so mixing this with prints may cause
3969confusion.
3970Returns the number of bytes actually written, or undef if there was an error.
3971An OFFSET may be specified to place the read data at some other place
3972than the beginning of the string.
3973.Ip "tell(FILEHANDLE)" 8 6
3974.Ip "tell FILEHANDLE" 8 6
3975.Ip "tell" 8
3976Returns the current file position for FILEHANDLE.
3977FILEHANDLE may be an expression whose value gives the name of the actual
3978filehandle.
3979If FILEHANDLE is omitted, assumes the file last read.
3980.Ip "telldir(DIRHANDLE)" 8 5
3981.Ip "telldir DIRHANDLE" 8
3982Returns the current position of the readdir() routines on DIRHANDLE.
3983Value may be given to seekdir() to access a particular location in
3984a directory.
3985Has the same caveats about possible directory compaction as the corresponding
3986system library routine.
3987.Ip "time" 8 4
3988Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970.
3989Suitable for feeding to gmtime() and localtime().
3990.Ip "times" 8 4
3991Returns a four-element array giving the user and system times, in seconds, for this
3992process and the children of this process.
3993.Sp
3994 ($user,$system,$cuser,$csystem) = times;
3995.Sp
3996.Ip "tr/SEARCHLIST/REPLACEMENTLIST/cds" 8 5
3997.Ip "y/SEARCHLIST/REPLACEMENTLIST/cds" 8
3998Translates all occurrences of the characters found in the search list with
3999the corresponding character in the replacement list.
4000It returns the number of characters replaced or deleted.
4001If no string is specified via the =~ or !~ operator,
4002the $_ string is translated.
4003(The string specified with =~ must be a scalar variable, an array element,
4004or an assignment to one of those, i.e. an lvalue.)
4005For
4006.I sed
4007devotees,
4008.I y
4009is provided as a synonym for
4010.IR tr .
4011.Sp
4012If the c modifier is specified, the SEARCHLIST character set is complemented.
4013If the d modifier is specified, any characters specified by SEARCHLIST that
4014are not found in REPLACEMENTLIST are deleted.
4015(Note that this is slightly more flexible than the behavior of some
4016.I tr
4017programs, which delete anything they find in the SEARCHLIST, period.)
4018If the s modifier is specified, sequences of characters that were translated
4019to the same character are squashed down to 1 instance of the character.
4020.Sp
4021If the d modifier was used, the REPLACEMENTLIST is always interpreted exactly
4022as specified.
4023Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST,
4024the final character is replicated till it is long enough.
4025If the REPLACEMENTLIST is null, the SEARCHLIST is replicated.
4026This latter is useful for counting characters in a class, or for squashing
4027character sequences in a class.
4028.Sp
4029Examples:
4030.nf
4031
4032 $ARGV[1] \|=~ \|y/A\-Z/a\-z/; \h'|3i'# canonicalize to lower case
4033
4034 $cnt = tr/*/*/; \h'|3i'# count the stars in $_
4035
4036 $cnt = tr/0\-9//; \h'|3i'# count the digits in $_
4037
4038 tr/a\-zA\-Z//s; \h'|3i'# bookkeeper \-> bokeper
4039
4040 ($HOST = $host) =~ tr/a\-z/A\-Z/;
4041
4042 y/a\-zA\-Z/ /cs; \h'|3i'# change non-alphas to single space
4043
4044 tr/\e200\-\e377/\e0\-\e177/;\h'|3i'# delete 8th bit
4045
4046.fi
4047.Ip "truncate(FILEHANDLE,LENGTH)" 8 4
4048.Ip "truncate(EXPR,LENGTH)" 8
4049Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified
4050length.
4051Produces a fatal error if truncate isn't implemented on your system.
4052.Ip "umask(EXPR)" 8 4
4053.Ip "umask EXPR" 8
4054.Ip "umask" 8
4055Sets the umask for the process and returns the old one.
4056If EXPR is omitted, merely returns current umask.
4057.Ip "undef(EXPR)" 8 6
4058.Ip "undef EXPR" 8
4059.Ip "undef" 8
4060Undefines the value of EXPR, which must be an lvalue.
4061Use only on a scalar value, an entire array, or a subroutine name (using &).
4062(Undef will probably not do what you expect on most predefined variables or
4063dbm array values.)
4064Always returns the undefined value.
4065You can omit the EXPR, in which case nothing is undefined, but you still
4066get an undefined value that you could, for instance, return from a subroutine.
4067Examples:
4068.nf
4069
4070.ne 6
4071 undef $foo;
4072 undef $bar{'blurfl'};
4073 undef @ary;
4074 undef %assoc;
4075 undef &mysub;
4076 return (wantarray ? () : undef) if $they_blew_it;
4077
4078.fi
4079.Ip "unlink(LIST)" 8 4
4080.Ip "unlink LIST" 8
4081Deletes a list of files.
4082Returns the number of files successfully deleted.
4083.nf
4084
4085.ne 2
4086 $cnt = unlink \'a\', \'b\', \'c\';
4087 unlink @goners;
4088 unlink <*.bak>;
4089
4090.fi
4091Note: unlink will not delete directories unless you are superuser and the
4092.B \-U
4093flag is supplied to
4094.IR perl .
4095Even if these conditions are met, be warned that unlinking a directory
4096can inflict damage on your filesystem.
4097Use rmdir instead.
4098.Ip "unpack(TEMPLATE,EXPR)" 8 4
4099Unpack does the reverse of pack: it takes a string representing
4100a structure and expands it out into an array value, returning the array
4101value.
4102(In a scalar context, it merely returns the first value produced.)
4103The TEMPLATE has the same format as in the pack function.
4104Here's a subroutine that does substring:
4105.nf
4106
4107.ne 4
4108 sub substr {
4109 local($what,$where,$howmuch) = @_;
4110 unpack("x$where a$howmuch", $what);
4111 }
4112
4113.ne 3
4114and then there's
4115
4116 sub ord { unpack("c",$_[0]); }
4117
4118.fi
4119In addition, you may prefix a field with a %<number> to indicate that
4120you want a <number>-bit checksum of the items instead of the items themselves.
4121Default is a 16-bit checksum.
4122For example, the following computes the same number as the System V sum program:
4123.nf
4124
4125.ne 4
4126 while (<>) {
4127 $checksum += unpack("%16C*", $_);
4128 }
4129 $checksum %= 65536;
4130
4131.fi
4132.Ip "unshift(ARRAY,LIST)" 8 4
4133Does the opposite of a
4134.IR shift .
4135Or the opposite of a
4136.IR push ,
4137depending on how you look at it.
4138Prepends list to the front of the array, and returns the number of elements
4139in the new array.
4140.nf
4141
4142 unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/;
4143
4144.fi
4145.Ip "utime(LIST)" 8 2
4146.Ip "utime LIST" 8 2
4147Changes the access and modification times on each file of a list of files.
4148The first two elements of the list must be the NUMERICAL access and
4149modification times, in that order.
4150Returns the number of files successfully changed.
4151The inode modification time of each file is set to the current time.
4152Example of a \*(L"touch\*(R" command:
4153.nf
4154
4155.ne 3
4156 #!/usr/bin/perl
4157 $now = time;
4158 utime $now, $now, @ARGV;
4159
4160.fi
4161.Ip "values(ASSOC_ARRAY)" 8 6
4162.Ip "values ASSOC_ARRAY" 8
4163Returns a normal array consisting of all the values of the named associative
4164array.
4165The values are returned in an apparently random order, but it is the same order
4166as either the keys() or each() function would produce on the same array.
4167See also keys() and each().
4168.Ip "vec(EXPR,OFFSET,BITS)" 8 2
4169Treats a string as a vector of unsigned integers, and returns the value
4170of the bitfield specified.
4171May also be assigned to.
4172BITS must be a power of two from 1 to 32.
4173.Sp
4174Vectors created with vec() can also be manipulated with the logical operators
4175|, & and ^,
4176which will assume a bit vector operation is desired when both operands are
4177strings.
4178This interpretation is not enabled unless there is at least one vec() in
4179your program, to protect older programs.
4180.Sp
4181To transform a bit vector into a string or array of 0's and 1's, use these:
4182.nf
4183
4184 $bits = unpack("b*", $vector);
4185 @bits = split(//, unpack("b*", $vector));
4186
4187.fi
4188If you know the exact length in bits, it can be used in place of the *.
4189.Ip "wait" 8 6
4190Waits for a child process to terminate and returns the pid of the deceased
4191process, or -1 if there are no child processes.
4192The status is returned in $?.
4193.Ip "waitpid(PID,FLAGS)" 8 6
4194Waits for a particular child process to terminate and returns the pid of the deceased
4195process, or -1 if there is no such child process.
4196The status is returned in $?.
4197If you say
4198.nf
4199
4200 require "sys/wait.h";
4201 .\|.\|.
4202 waitpid(-1,&WNOHANG);
4203
4204.fi
4205then you can do a non-blocking wait for any process. Non-blocking wait
4206is only available on machines supporting either the
4207.I waitpid (2)
4208or
4209.I wait4 (2)
4210system calls.
4211However, waiting for a particular pid with FLAGS of 0 is implemented
4212everywhere. (Perl emulates the system call by remembering the status
4213values of processes that have exited but have not been harvested by the
4214Perl script yet.)
4215.Ip "wantarray" 8 4
4216Returns true if the context of the currently executing subroutine
4217is looking for an array value.
4218Returns false if the context is looking for a scalar.
4219.nf
4220
4221 return wantarray ? () : undef;
4222
4223.fi
4224.Ip "warn(LIST)" 8 4
4225.Ip "warn LIST" 8
4226Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
4227.Ip "write(FILEHANDLE)" 8 6
4228.Ip "write(EXPR)" 8
4229.Ip "write" 8
4230Writes a formatted record (possibly multi-line) to the specified file,
4231using the format associated with that file.
4232By default the format for a file is the one having the same name is the
4233filehandle, but the format for the current output channel (see
4234.IR select )
4235may be set explicitly
4236by assigning the name of the format to the $~ variable.
4237.Sp
4238Top of form processing is handled automatically:
4239if there is insufficient room on the current page for the formatted
4240record, the page is advanced by writing a form feed,
4241a special top-of-page format is used
4242to format the new page header, and then the record is written.
4243By default the top-of-page format is \*(L"top\*(R", but it
4244may be set to the
4245format of your choice by assigning the name to the $^ variable.
4246The number of lines remaining on the current page is in variable $-, which
4247can be set to 0 to force a new page.
4248.Sp
4249If FILEHANDLE is unspecified, output goes to the current default output channel,
4250which starts out as
4251.I STDOUT
4252but may be changed by the
4253.I select
4254operator.
4255If the FILEHANDLE is an EXPR, then the expression is evaluated and the
4256resulting string is used to look up the name of the FILEHANDLE at run time.
4257For more on formats, see the section on formats later on.
4258.Sp
4259Note that write is NOT the opposite of read.
4260''' Beginning of part 4
4261''' $Header: perl.man,v 4.0 91/03/20 01:38:08 lwall Locked $
4262'''
4263''' $Log: perl.man,v $
4264''' Revision 4.0 91/03/20 01:38:08 lwall
4265''' 4.0 baseline.
4266'''
4267''' Revision 3.0.1.14 91/01/11 18:18:53 lwall
4268''' patch42: started an addendum and errata section in the man page
4269'''
4270''' Revision 3.0.1.13 90/11/10 01:51:00 lwall
4271''' patch38: random cleanup
4272'''
4273''' Revision 3.0.1.12 90/10/20 02:15:43 lwall
4274''' patch37: patch37: fixed various typos in man page
4275'''
4276''' Revision 3.0.1.11 90/10/16 10:04:28 lwall
4277''' patch29: added @###.## fields to format
4278'''
4279''' Revision 3.0.1.10 90/08/09 04:47:35 lwall
4280''' patch19: added require operator
4281''' patch19: added numeric interpretation of $]
4282'''
4283''' Revision 3.0.1.9 90/08/03 11:15:58 lwall
4284''' patch19: Intermediate diffs for Randal
4285'''
4286''' Revision 3.0.1.8 90/03/27 16:19:31 lwall
4287''' patch16: MSDOS support
4288'''
4289''' Revision 3.0.1.7 90/03/14 12:29:50 lwall
4290''' patch15: man page falsely states that you can't subscript array values
4291'''
4292''' Revision 3.0.1.6 90/03/12 16:54:04 lwall
4293''' patch13: improved documentation of *name
4294'''
4295''' Revision 3.0.1.5 90/02/28 18:01:52 lwall
4296''' patch9: $0 is now always the command name
4297'''
4298''' Revision 3.0.1.4 89/12/21 20:12:39 lwall
4299''' patch7: documented that package'filehandle works as well as $package'variable
4300''' patch7: documented which identifiers are always in package main
4301'''
4302''' Revision 3.0.1.3 89/11/17 15:32:25 lwall
4303''' patch5: fixed some manual typos and indent problems
4304''' patch5: clarified difference between $! and $@
4305'''
4306''' Revision 3.0.1.2 89/11/11 04:46:40 lwall
4307''' patch2: made some line breaks depend on troff vs. nroff
4308''' patch2: clarified operation of ^ and $ when $* is false
4309'''
4310''' Revision 3.0.1.1 89/10/26 23:18:43 lwall
4311''' patch1: documented the desirability of unnecessary parentheses
4312'''
4313''' Revision 3.0 89/10/18 15:21:55 lwall
4314''' 3.0 baseline
4315'''
4316.Sh "Precedence"
4317.I Perl
4318operators have the following associativity and precedence:
4319.nf
4320
4321nonassoc\h'|1i'print printf exec system sort reverse
4322\h'1.5i'chmod chown kill unlink utime die return
4323left\h'|1i',
4324right\h'|1i'= += \-= *= etc.
4325right\h'|1i'?:
4326nonassoc\h'|1i'.\|.
4327left\h'|1i'||
4328left\h'|1i'&&
4329left\h'|1i'| ^
4330left\h'|1i'&
4331nonassoc\h'|1i'== != <=> eq ne cmp
4332nonassoc\h'|1i'< > <= >= lt gt le ge
4333nonassoc\h'|1i'chdir exit eval reset sleep rand umask
4334nonassoc\h'|1i'\-r \-w \-x etc.
4335left\h'|1i'<< >>
4336left\h'|1i'+ \- .
4337left\h'|1i'* / % x
4338left\h'|1i'=~ !~
4339right\h'|1i'! ~ and unary minus
4340right\h'|1i'**
4341nonassoc\h'|1i'++ \-\|\-
4342left\h'|1i'\*(L'(\*(R'
4343
4344.fi
4345As mentioned earlier, if any list operator (print, etc.) or
4346any unary operator (chdir, etc.)
4347is followed by a left parenthesis as the next token on the same line,
4348the operator and arguments within parentheses are taken to
4349be of highest precedence, just like a normal function call.
4350Examples:
4351.nf
4352
4353 chdir $foo || die;\h'|3i'# (chdir $foo) || die
4354 chdir($foo) || die;\h'|3i'# (chdir $foo) || die
4355 chdir ($foo) || die;\h'|3i'# (chdir $foo) || die
4356 chdir +($foo) || die;\h'|3i'# (chdir $foo) || die
4357
4358but, because * is higher precedence than ||:
4359
4360 chdir $foo * 20;\h'|3i'# chdir ($foo * 20)
4361 chdir($foo) * 20;\h'|3i'# (chdir $foo) * 20
4362 chdir ($foo) * 20;\h'|3i'# (chdir $foo) * 20
4363 chdir +($foo) * 20;\h'|3i'# chdir ($foo * 20)
4364
4365 rand 10 * 20;\h'|3i'# rand (10 * 20)
4366 rand(10) * 20;\h'|3i'# (rand 10) * 20
4367 rand (10) * 20;\h'|3i'# (rand 10) * 20
4368 rand +(10) * 20;\h'|3i'# rand (10 * 20)
4369
4370.fi
4371In the absence of parentheses,
4372the precedence of list operators such as print, sort or chmod is
4373either very high or very low depending on whether you look at the left
4374side of operator or the right side of it.
4375For example, in
4376.nf
4377
4378 @ary = (1, 3, sort 4, 2);
4379 print @ary; # prints 1324
4380
4381.fi
4382the commas on the right of the sort are evaluated before the sort, but
4383the commas on the left are evaluated after.
4384In other words, list operators tend to gobble up all the arguments that
4385follow them, and then act like a simple term with regard to the preceding
4386expression.
4387Note that you have to be careful with parens:
4388.nf
4389
4390.ne 3
4391 # These evaluate exit before doing the print:
4392 print($foo, exit); # Obviously not what you want.
4393 print $foo, exit; # Nor is this.
4394
4395.ne 4
4396 # These do the print before evaluating exit:
4397 (print $foo), exit; # This is what you want.
4398 print($foo), exit; # Or this.
4399 print ($foo), exit; # Or even this.
4400
4401Also note that
4402
4403 print ($foo & 255) + 1, "\en";
4404
4405.fi
4406probably doesn't do what you expect at first glance.
4407.Sh "Subroutines"
4408A subroutine may be declared as follows:
4409.nf
4410
4411 sub NAME BLOCK
4412
4413.fi
4414.PP
4415Any arguments passed to the routine come in as array @_,
4416that is ($_[0], $_[1], .\|.\|.).
4417The array @_ is a local array, but its values are references to the
4418actual scalar parameters.
4419The return value of the subroutine is the value of the last expression
4420evaluated, and can be either an array value or a scalar value.
4421Alternately, a return statement may be used to specify the returned value and
4422exit the subroutine.
4423To create local variables see the
4424.I local
4425operator.
4426.PP
4427A subroutine is called using the
4428.I do
4429operator or the & operator.
4430.nf
4431
4432.ne 12
4433Example:
4434
4435 sub MAX {
4436 local($max) = pop(@_);
4437 foreach $foo (@_) {
4438 $max = $foo \|if \|$max < $foo;
4439 }
4440 $max;
4441 }
4442
4443 .\|.\|.
4444 $bestday = &MAX($mon,$tue,$wed,$thu,$fri);
4445
4446.ne 21
4447Example:
4448
4449 # get a line, combining continuation lines
4450 # that start with whitespace
4451 sub get_line {
4452 $thisline = $lookahead;
4453 line: while ($lookahead = <STDIN>) {
4454 if ($lookahead \|=~ \|/\|^[ \^\e\|t]\|/\|) {
4455 $thisline \|.= \|$lookahead;
4456 }
4457 else {
4458 last line;
4459 }
4460 }
4461 $thisline;
4462 }
4463
4464 $lookahead = <STDIN>; # get first line
4465 while ($_ = do get_line(\|)) {
4466 .\|.\|.
4467 }
4468
4469.fi
4470.nf
4471.ne 6
4472Use array assignment to a local list to name your formal arguments:
4473
4474 sub maybeset {
4475 local($key, $value) = @_;
4476 $foo{$key} = $value unless $foo{$key};
4477 }
4478
4479.fi
4480This also has the effect of turning call-by-reference into call-by-value,
4481since the assignment copies the values.
4482.Sp
4483Subroutines may be called recursively.
4484If a subroutine is called using the & form, the argument list is optional.
4485If omitted, no @_ array is set up for the subroutine; the @_ array at the
4486time of the call is visible to subroutine instead.
4487.nf
4488
4489 do foo(1,2,3); # pass three arguments
4490 &foo(1,2,3); # the same
4491
4492 do foo(); # pass a null list
4493 &foo(); # the same
4494 &foo; # pass no arguments\*(--more efficient
4495
4496.fi
4497.Sh "Passing By Reference"
4498Sometimes you don't want to pass the value of an array to a subroutine but
4499rather the name of it, so that the subroutine can modify the global copy
4500of it rather than working with a local copy.
4501In perl you can refer to all the objects of a particular name by prefixing
4502the name with a star: *foo.
4503When evaluated, it produces a scalar value that represents all the objects
4504of that name, including any filehandle, format or subroutine.
4505When assigned to within a local() operation, it causes the name mentioned
4506to refer to whatever * value was assigned to it.
4507Example:
4508.nf
4509
4510 sub doubleary {
4511 local(*someary) = @_;
4512 foreach $elem (@someary) {