Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PERL(1)			    General Commands Manual		       PERL(1)

NAME
       perl - Practical	Extraction and Report Language

SYNOPSIS
       perl [options] filename args

DESCRIPTION
       Perl  is	 an interpreted	language optimized for scanning	arbitrary text
       files, extracting information  from  those  text	 files,	 and  printing
       reports	based on that information.  It's also a	good language for many
       system management tasks.	 The language  is  intended  to	 be  practical
       (easy  to  use,	efficient, complete) rather than beautiful (tiny, ele-
       gant, minimal).	It combines (in	the author's opinion, anyway) some  of
       the best	features of C, sed, awk, and sh, so people familiar with those
       languages should	have little difficulty with it.	 (Language  historians
       will  also  note	 some  vestiges	 of csh, Pascal, and even BASIC-PLUS.)
       Expression syntax corresponds quite closely  to	C  expression  syntax.
       Unlike most Unix	utilities, perl	does not arbitrarily limit the size of
       your data--if you've got	the memory, perl can slurp in your whole  file
       as  a  single  string.	Recursion is of	unlimited depth.  And the hash
       tables used by associative arrays grow as necessary to prevent degraded
       performance.   Perl  uses  sophisticated	pattern	matching techniques to
       scan large amounts of data very quickly.	 Although optimized for	 scan-
       ning  text, perl	can also deal with binary data,	and can	make dbm files
       look like associative arrays (where dbm	is  available).	  Setuid  perl
       scripts	are safer than C programs through a dataflow tracing mechanism
       which prevents many stupid security holes.  If you have a problem  that
       would  ordinarily  use sed or awk or sh,	but it exceeds their capabili-
       ties or must run	a little faster, and you don't want to write the silly
       thing  in  C,  then perl	may be for you.	 There are also	translators to
       turn your sed and awk scripts into perl scripts.	 OK, enough hype.

       Upon startup, perl looks	for  your  script  in  one  of	the  following
       places:

       1.  Specified line by line via -e switches on the command line.

       2.  Contained  in  the file specified by	the first filename on the com-
	   mand	line.  (Note that systems supporting the  #!  notation	invoke
	   interpreters	this way.)

       3.  Passed  in implicitly via standard input.  This only	works if there
	   are no filename arguments--to pass arguments	to a stdin script  you
	   must	explicitly specify a - for the script name.

       After  locating	your script, perl compiles it to an internal form.  If
       the script is syntactically correct, it is executed.

       Options

       Note: on	first reading this section may not make	 much  sense  to  you.
       It's here at the	front for easy reference.

       A single-character option may be	combined with the following option, if
       any.  This is particularly useful when invoking a script	using  the  #!
       construct which only allows one argument.  Example:

	    #!/usr/bin/perl -spi.bak # same as -s -p -i.bak
	    ...

       Options include:

       -0digits
	    specifies  the record separator ($/) as an octal number.  If there
	    are	no  digits,  the  null	character  is  the  separator.	 Other
	    switches  may  precede  or follow the digits.  For example,	if you
	    have a version of find which can print filenames terminated	by the
	    null character, you	can say	this:

		find . -name '*.bak' -print0 | perl -n0e unlink

	    The	 special  value	00 will	cause Perl to slurp files in paragraph
	    mode.  The value 0777 will cause Perl to slurp files  whole	 since
	    there is no	legal character	with that value.

       -a   turns  on  autosplit  mode when used with a	-n or -p.  An implicit
	    split command to the @F array is done as the  first	 thing	inside
	    the	implicit while loop produced by	the -n or -p.

		 perl -ane 'print pop(@F), "\n";'

	    is equivalent to

		 while (<>) {
		      @F = split(' ');
		      print pop(@F), "\n";
		 }

       -c   causes  perl to check the syntax of	the script and then exit with-
	    out	executing it.

       -d   runs the script under the  perl  debugger.	 See  the  section  on
	    Debugging.

       -Dnumber
	    sets  debugging  flags.  To	watch how it executes your script, use
	    -D14.  (This only works if debugging is compiled into your	perl.)
	    Another  nice  value  is  -D1024, which lists your compiled	syntax
	    tree.  And -D512 displays compiled regular expressions.

       -e commandline
	    may	be used	to enter one line of script.  Multiple -e commands may
	    be	given  to  build up a multi-line script.  If -e	is given, perl
	    will not look for a	script filename	in the argument	list.

       -iextension
	    specifies that files processed by  the  <>	construct  are	to  be
	    edited in-place.  It does this by renaming the input file, opening
	    the	output file by the same	name, and selecting that  output  file
	    as	the default for	print statements.  The extension, if supplied,
	    is added to	the name of the	old file to make a backup copy.	 If no
	    extension  is supplied, no backup is made.	Saying "perl -p	-i.bak
	    -e "s/foo/bar/;" ... " is the same as using	the script:

		 #!/usr/bin/perl -pi.bak
		 s/foo/bar/;

	    which is equivalent	to

		 #!/usr/bin/perl
		 while (<>) {
		      if ($ARGV	ne $oldargv) {
			   rename($ARGV, $ARGV . '.bak');
			   open(ARGVOUT, ">$ARGV");
			   select(ARGVOUT);
			   $oldargv = $ARGV;
		      }
		      s/foo/bar/;
		 }
		 continue {
		     print;	# this prints to original filename
		 }
		 select(STDOUT);

	    except that	the -i form doesn't need to compare $ARGV to  $oldargv
	    to	know  when  the	 filename  has changed.	 It does, however, use
	    ARGVOUT for	the selected filehandle.  Note that STDOUT is restored
	    as the default output filehandle after the loop.

	    You	 can use eof to	locate the end of each input file, in case you
	    want to append to each file, or reset line numbering (see  example
	    under eof).

       -Idirectory
	    may	 be  used  in  conjunction  with -P to tell the	C preprocessor
	    where to look for include  files.	By  default  /usr/include  and
	    /usr/lib/perl are searched.

       -loctnum
	    enables  automatic	line-ending  processing.   It has two effects:
	    first, it automatically chops the line terminator when  used  with
	    -n	or  -p , and second, it	assigns	$\ to have the value of	octnum
	    so that any	print statements will have that	line terminator	 added
	    back  on.	If  octnum is omitted, sets $\ to the current value of
	    $/.	 For instance, to trim lines to	80 columns:

		 perl -lpe 'substr($_, 80) = ""'

	    Note that the assignment $\	= $/ is	done when the switch  is  pro-
	    cessed,  so	 the  input record separator can be different than the
	    output record separator if the -l  switch  is  followed  by	 a  -0
	    switch:

		 gnufind / -print0 | perl -ln0e	'print "found $_" if -p'

	    This sets $\ to newline and	then sets $/ to	the null character.

       -n   causes perl	to assume the following	loop around your script, which
	    makes it iterate over filename arguments somewhat like "sed	-n" or
	    awk:

		 while (<>) {
		      ...	# your script goes here
		 }

	    Note  that	the  lines are not printed by default.	See -p to have
	    lines printed.  Here is an efficient way to	delete all files older
	    than a week:

		 find .	-mtime +7 -print | perl	-nle 'unlink;'

	    This  is  faster  than  using the -exec switch of find because you
	    don't have to start	a process on every filename found.

       -p   causes perl	to assume the following	loop around your script, which
	    makes it iterate over filename arguments somewhat like sed:

		 while (<>) {
		      ...	# your script goes here
		 } continue {
		      print;
		 }

	    Note that the lines	are printed automatically.  To suppress	print-
	    ing	use the	-n switch.  A -p overrides a -n	switch.

       -P   causes your	script to be run through  the  C  preprocessor	before
	    compilation	 by  perl.   (Since  both  comments and	cpp directives
	    begin with the # character,	you  should  avoid  starting  comments
	    with  any  words  recognized  by  the C preprocessor such as "if",
	    "else" or "define".)

       -s   enables some rudimentary switch parsing for	switches on  the  com-
	    mand  line after the script	name but before	any filename arguments
	    (or	before a --).  Any switch found	there is  removed  from	 @ARGV
	    and	 sets the corresponding	variable in the	perl script.  The fol-
	    lowing script prints "true"	if and only if the script  is  invoked
	    with a -xyz	switch.

		 #!/usr/bin/perl -s
		 if ($xyz) { print "true\n"; }

       -S   makes  perl	 use  the  PATH	environment variable to	search for the
	    script (unless the name of the script starts with a	slash).	 Typi-
	    cally  this	 is  used to emulate #!	startup	on machines that don't
	    support #!,	in the following manner:

		 #!/usr/bin/perl
		 eval "exec /usr/bin/perl -S $0	$*"
		      if $running_under_some_shell;

	    The	system ignores the first line and feeds	the script to /bin/sh,
	    which  proceeds  to	 try  to  execute  the	perl script as a shell
	    script.  The shell executes	the second line	as a normal shell com-
	    mand, and thus starts up the perl interpreter.  On some systems $0
	    doesn't always contain the full pathname, so the -S	tells perl  to
	    search  for	 the  script  if  necessary.   After  perl locates the
	    script, it parses the lines	and ignores them because the  variable
	    $running_under_some_shell  is never	true.  A better	construct than
	    $* would be	${1+"$@"}, which handles embedded spaces and  such  in
	    the	filenames, but doesn't work if the script is being interpreted
	    by csh.  In	order to start up sh rather than csh, some systems may
	    have  to  replace the #! line with a line containing just a	colon,
	    which will be politely ignored by perl.  Other systems can't  con-
	    trol  that,	 and  need  a totally devious construct	that will work
	    under any of csh, sh or perl, such as the following:

		 eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
		 & eval	'exec /usr/bin/perl -S $0 $argv:q'
		      if 0;

       -u   causes perl	to dump	core after compiling  your  script.   You  can
	    then  take	this  core dump	and turn it into an executable file by
	    using the undump program (not supplied).  This speeds  startup  at
	    the	 expense  of some disk space (which you	can minimize by	strip-
	    ping the executable).  (Still, a "hello  world"  executable	 comes
	    out	 to  about  200K on my machine.)  If you are going to run your
	    executable as a set-id program then	you should probably compile it
	    using taintperl rather than	normal perl.  If you want to execute a
	    portion of your script  before  dumping,  use  the	dump  operator
	    instead.   Note:  availability  of undump is platform specific and
	    may	not be available for a specific	port of	perl.

       -U   allows perl	to do unsafe operations.  Currently the	only  "unsafe"
	    operations are the unlinking of directories	while running as supe-
	    ruser, and running setuid programs with fatal taint	checks	turned
	    into warnings.

       -v   prints the version and patchlevel of your perl executable.

       -w   prints  warnings  about  identifiers that are mentioned only once,
	    and	scalar variables that are used before being set.   Also	 warns
	    about  redefined subroutines, and references to undefined filehan-
	    dles or filehandles	opened readonly	that  you  are	attempting  to
	    write  on.	Also warns you if you use == on	values that don't look
	    like numbers, and if your subroutines recurse more than 100	deep.

       -xdirectory
	    tells perl that the	script is  embedded  in	 a  message.   Leading
	    garbage will be discarded until the	first line that	starts with #!
	    and	contains the string "perl".  Any meaningful switches  on  that
	    line will be applied (but only one group of	switches, as with nor-
	    mal	#! processing).	 If a directory	name is	specified,  Perl  will
	    switch to that directory before running the	script.	 The -x	switch
	    only controls the disposal of leading garbage.  The	script must be
	    terminated with __END__ if there is	trailing garbage to be ignored
	    (the script	can process any	or all of the trailing garbage via the
	    DATA filehandle if desired).

       Data Types and Objects

       Perl  has three data types: scalars, arrays of scalars, and associative
       arrays of scalars.  Normal arrays are indexed by	number,	 and  associa-
       tive arrays by string.

       The  interpretation  of operations and values in	perl sometimes depends
       on the requirements of the  context  around  the	 operation  or	value.
       There  are  three  major	 contexts: string, numeric and array.  Certain
       operations return array values in contexts wanting an array, and	scalar
       values  otherwise.   (If	 this  is true of an operation it will be men-
       tioned in the documentation  for	 that  operation.)   Operations	 which
       return  scalars	don't care whether the context is looking for a	string
       or a number, but	scalar variables and values are	interpreted as strings
       or  numbers  as appropriate to the context.  A scalar is	interpreted as
       TRUE in the boolean sense if it is not the null string or 0.   Booleans
       returned	 by operators are 1 for	true and 0 or '' (the null string) for
       false.

       There are actually two varieties	of null	string:	defined	and undefined.
       Undefined  null	strings	 are  returned when there is no	real value for
       something, such as when there was an error, or at end of	file, or  when
       you  refer  to  an  uninitialized  variable or element of an array.  An
       undefined null string may become	defined	the first time you access  it,
       but  prior  to  that  you  can  use the defined() operator to determine
       whether the value is defined or not.

       References to scalar variables always begin with	'$', even when	refer-
       ring to a scalar	that is	part of	an array.  Thus:

	   $days	   # a simple scalar variable
	   $days[28]	   # 29th element of array @days
	   $days{'Feb'}	   # one value from an associative array
	   $#days	   # last index	of array @days

       but entire arrays or array slices are denoted by	'@':

	   @days	   # ($days[0],	$days[1],... $days[n])
	   @days[3,4,5]	   # same as @days[3..5]
	   @days{'a','c'}  # same as ($days{'a'},$days{'c'})

       and entire associative arrays are denoted by '%':

	   %days	   # (key1, val1, key2,	val2 ...)

       Any  of	these eight constructs may serve as an lvalue, that is,	may be
       assigned	to.  (It also turns out	that an	assignment is itself an	lvalue
       in certain contexts--see	examples under s, tr and chop.)	 Assignment to
       a scalar	evaluates the  righthand  side	in  a  scalar  context,	 while
       assignment  to  an array	or array slice evaluates the righthand side in
       an array	context.

       You may find the	length of array	@days by evaluating  "$#days",	as  in
       csh.   (Actually,  it's not the length of the array, it's the subscript
       of the last element,  since  there  is  (ordinarily)  a	0th  element.)
       Assigning  to  $#days  changes  the length of the array.	 Shortening an
       array by	this method does not actually destroy any values.  Lengthening
       an array	that was previously shortened recovers the values that were in
       those elements.	You can	also gain some measure of efficiency by	preex-
       tending	an  array  that	 is going to get big.  (You can	also extend an
       array by	assigning to an	element	that is	off  the  end  of  the	array.
       This  differs  from  assigning to $#whatever in that intervening	values
       are set to null rather than recovered.)	You can	truncate an array down
       to  nothing  by	assigning  the	null list () to	it.  The following are
       exactly equivalent

	    @whatever =	();
	    $#whatever = $[ - 1;

       If you evaluate an array	in a scalar context, it	returns	the length  of
       the array.  The following is always true:

	    scalar(@whatever) == $#whatever - $[ + 1;

       If  you evaluate	an associative array in	a scalar context, it returns a
       value which is true if and only if the  array  contains	any  elements.
       (If  there  are any elements, the value returned	is a string consisting
       of the number of	used buckets and the number of allocated buckets, sep-
       arated by a slash.)

       Multi-dimensional  arrays  are not directly supported, but see the dis-
       cussion of the $; variable later	for a means of emulating multiple sub-
       scripts	with  an associative array.  You could also write a subroutine
       to turn multiple	subscripts into	a single subscript.

       Every data type has its own namespace.  You can,	without	fear  of  con-
       flict,  use  the	same name for a	scalar variable, an array, an associa-
       tive array, a filehandle, a subroutine name,  and/or  a	label.	 Since
       variable	 and  array references always start with '$', '@', or '%', the
       "reserved" words	aren't in  fact	 reserved  with	 respect  to  variable
       names.  (They ARE reserved with respect to labels and filehandles, how-
       ever, which don't have an initial special character.  Hint:  you	 could
       say  open(LOG,'logfile')	rather than open(log,'logfile').  Using	upper-
       case filehandles	also improves readability and protects you  from  con-
       flict  with  future reserved words.)  Case IS significant--"FOO", "Foo"
       and "foo" are all different names.  Names which start with a letter may
       also  contain  digits and underscores.  Names which do not start	with a
       letter are limited to one character, e.g. "$%" or "$$".	(Most  of  the
       one  character  names  have  a  predefined  significance	to perl.  More
       later.)

       Numeric literals	are specified in any of	the usual  floating  point  or
       integer formats:

	   12345
	   12345.67
	   .23E-10
	   0xffff     #	hex
	   0377	 # octal
	   4_294_967_296

       String  literals	are delimited by either	single or double quotes.  They
       work much like shell quotes: double-quoted string literals are  subject
       to  backslash  and variable substitution; single-quoted strings are not
       (except for \' and \\).	The usual backslash  rules  apply  for	making
       characters  such	 as  newline,  tab,  etc., as well as some more	exotic
       forms:

	    \t	      tab
	    \n	      newline
	    \r	      return
	    \f	      form feed
	    \b	      backspace
	    \a	      alarm (bell)
	    \e	      escape
	    \033      octal char
	    \x1b      hex char
	    \c[	      control char
	    \l	      lowercase	next char
	    \u	      uppercase	next char
	    \L	      lowercase	till \E
	    \U	      uppercase	till \E
	    \E	      end case modification

       You can also embed newlines directly in your strings, i.e. they can end
       on  a  different	line than they begin.  This is nice, but if you	forget
       your trailing quote, the	error will not be reported  until  perl	 finds
       another	line containing	the quote character, which may be much further
       on in the script.  Variable substitution	inside strings is  limited  to
       scalar  variables,  normal  array  values, and array slices.  (In other
       words, identifiers beginning with $  or	@,  followed  by  an  optional
       bracketed  expression  as  a  subscript.)   The	following code segment
       prints out "The price is	$100."

	   $Price = '$100';		  # not	interpreted
	   print "The price is $Price.\n";# interpreted

       Note that you can put curly brackets around the identifier  to  delimit
       it from following alphanumerics.	 Also note that	a single quoted	string
       must be separated from a	preceding word by a space, since single	 quote
       is a valid character in an identifier (see Packages).

       Two  special  literals  are  __LINE__ and __FILE__, which represent the
       current line number and filename	at that	point in your  program.	  They
       may only	be used	as separate tokens; they will not be interpolated into
       strings.	 In addition, the token	__END__	may be used  to	 indicate  the
       logical end of the script before	the actual end of file.	 Any following
       text is ignored,	but may	be read	via the	DATA  filehandle.   (The  DATA
       filehandle  may	read  data only	from the main script, but not from any
       required	file or	evaluated string.)  The	two control characters ^D  and
       ^Z are synonyms for __END__.

       A  word	that doesn't have any other interpretation in the grammar will
       be treated as if	it had single quotes around it.	 For this  purpose,  a
       word  consists  only of alphanumeric characters and underline, and must
       start with an alphabetic	character.  As with filehandles	and labels,  a
       bare  word  that	 consists entirely of lowercase	letters	risks conflict
       with future reserved words, and if you use the  -w  switch,  Perl  will
       warn you	about any such words.

       Array values are	interpolated into double-quoted	strings	by joining all
       the elements of the array with the delimiter specified in the $"	 vari-
       able,  space by default.	 (Since	in versions of perl prior to 3.0 the @
       character was not a metacharacter in double-quoted strings, the	inter-
       polation	  of  @array,  $array[EXPR],  @array[LIST],  $array{EXPR},  or
       @array{LIST} only happens if array is referenced	elsewhere in the  pro-
       gram or is predefined.)	The following are equivalent:

	    $temp = join($",@ARGV);
	    system "echo $temp";

	    system "echo @ARGV";

       Within search patterns (which also undergo double-quotish substitution)
       there is	 a  bad	 ambiguity:   Is  /$foo[bar]/  to  be  interpreted  as
       /${foo}[bar]/ (where [bar] is a character class for the regular expres-
       sion) or	as /${foo[bar]}/ (where	[bar] is the subscript to array	@foo)?
       If @foo doesn't otherwise exist,	then it's obviously a character	class.
       If @foo exists, perl takes a good guess	about  [bar],  and  is	almost
       always  right.	If  it does guess wrong, or if you're just plain para-
       noid, you can force the correct interpretation with curly  brackets  as
       above.

       A  line-oriented	 form of quoting is based on the shell here-is syntax.
       Following a << you specify a string to terminate	the  quoted  material,
       and all lines following the current line	down to	the terminating	string
       are the value of	the item.  The terminating string  may	be  either  an
       identifier  (a  word),  or  some	 quoted	 text.	If quoted, the type of
       quotes you use determines the treatment of the text, just as in regular
       quoting.	  An unquoted identifier works like double quotes.  There must
       be no space between the << and the identifier.  (If you put a space  it
       will  be	 treated as a null identifier, which is	valid, and matches the
       first blank line--see Merry Christmas example below.)  The  terminating
       string  must  appear by itself (unquoted	and with no surrounding	white-
       space) on the terminating line.

	    print <<EOF;	# same as above
       The price is $Price.
       EOF

	    print <<"EOF";	# same as above
       The price is $Price.
       EOF

	    print << x 10;	# null identifier is delimiter
       Merry Christmas!

	    print <<`EOC`;	# execute commands
       echo hi there
       echo lo there
       EOC

	    print <<foo, <<bar;	# you can stack	them
       I said foo.
       foo
       I said bar.
       bar

       Array literals are denoted by separating	individual values  by  commas,
       and enclosing the list in parentheses:

	    (LIST)

       In  a context not requiring an array value, the value of	the array lit-
       eral is the value of the	final element, as in  the  C  comma  operator.
       For example,

	   @foo	= ('cc', '-E', $bar);

       assigns the entire array	value to array foo, but

	   $foo	= ('cc', '-E', $bar);

       assigns the value of variable bar to variable foo.  Note	that the value
       of an actual array in a scalar context is the length of the array;  the
       following assigns to $foo the value 3:

	   @foo	= ('cc', '-E', $bar);
	   $foo	= @foo;		# $foo gets 3

       You  may	 have  an  optional comma before the closing parenthesis of an
       array literal, so that you can say:

	   @foo	= (
	    1,
	    2,
	    3,
	   );

       When a LIST is evaluated, each element of the list is evaluated	in  an
       array  context, and the resulting array value is	interpolated into LIST
       just as if each individual element were a member	of LIST.  Thus	arrays
       lose their identity in a	LIST--the list

	    (@foo,@bar,&SomeSub)

       contains	all the	elements of @foo followed by all the elements of @bar,
       followed	by all the elements returned by	the subroutine named SomeSub.

       A list value may	also be	subscripted like a normal array.  Examples:

	    $time = (stat($file))[8];	  # stat returns array value
	    $digit = ('a','b','c','d','e','f')[$digit-10];
	    return (pop(@foo),pop(@foo))[0];

       Array lists may be assigned to if and only if each element of the  list
       is an lvalue:

	   ($a,	$b, $c)	= (1, 2, 3);

	   ($map{'red'}, $map{'blue'}, $map{'green'}) =	(0x00f,	0x0f0, 0xf00);

       The final element may be	an array or an associative array:

	   ($a,	$b, @rest) = split;
	   local($a, $b, %rest)	= @_;

       You can actually	put an array anywhere in the list, but the first array
       in the list will	soak up	all the	values,	and anything after it will get
       a null value.  This may be useful in a local().

       An associative array literal contains pairs of values to	be interpreted
       as a key	and a value:

	   # same as map assignment above
	   %map	= ('red',0x00f,'blue',0x0f0,'green',0xf00);

       Array assignment	in a scalar context returns  the  number  of  elements
       produced	by the expression on the right side of the assignment:

	    $x = (($foo,$bar) =	(3,2,1)); # set	$x to 3, not 2

       There are several other pseudo-literals that you	should know about.  If
       a string	is enclosed by backticks (grave	accents), it  first  undergoes
       variable	 substitution  just  like  a double quoted string.  It is then
       interpreted as a	command, and the output	of that	command	is  the	 value
       of  the pseudo-literal, like in a shell.	 In a scalar context, a	single
       string consisting of all	the output is returned.	 In an array  context,
       an  array of values is returned,	one for	each line of output.  (You can
       set $/ to use a different line terminator.)  The	 command  is  executed
       each  time  the	pseudo-literal	is evaluated.  The status value	of the
       command is returned in $? (see Predefined Names for the	interpretation
       of $?).	Unlike in csh, no translation is done on the return data--new-
       lines remain newlines.  Unlike in any of	the shells, single  quotes  do
       not  hide variable names	in the command from interpretation.  To	pass a
       $ through to the	shell you need to hide it with a backslash.

       Evaluating a filehandle in angle	brackets yields	 the  next  line  from
       that  file  (newline  included, so it's never false until EOF, at which
       time an undefined value is returned).  Ordinarily you must assign  that
       value  to  a  variable,	but  there is one situation where an automatic
       assignment happens.  If (and only if) the  input	 symbol	 is  the  only
       thing  inside  the  conditional of a while loop,	the value is automati-
       cally assigned to the variable "$_".  (This may seem like an odd	 thing
       to  you,	 but  you'll use the construct in almost every perl script you
       write.)	Anyway,	the following lines are	equivalent to each other:

	   while ($_ = <STDIN>)	{ print; }
	   while (<STDIN>) { print; }
	   for (;<STDIN>;) { print; }
	   print while $_ = <STDIN>;
	   print while <STDIN>;

       The filehandles STDIN, STDOUT and STDERR	are predefined.	 (The filehan-
       dles  stdin, stdout and stderr will also	work except in packages, where
       they would be interpreted as local  identifiers	rather	than  global.)
       Additional filehandles may be created with the open function.

       If a <FILEHANDLE> is used in a context that is looking for an array, an
       array consisting	of all the input lines is returned, one	line per array
       element.	  It's	easy  to make a	LARGE data space this way, so use with
       care.

       The null	filehandle <> is special and can be used to emulate the	behav-
       ior of sed and awk.  Input from <> comes	either from standard input, or
       from each file listed on	the command line.  Here's how  it  works:  the
       first  time  <>	is  evaluated, the ARGV	array is checked, and if it is
       null, $ARGV[0] is set to	'-', which  when  opened  gives	 you  standard
       input.	The  ARGV array	is then	processed as a list of filenames.  The
       loop

	    while (<>) {
		 ...		# code for each	line
	    }

       is equivalent to	the following Perl-like	pseudo code:

	    unshift(@ARGV, '-')	if $#ARGV < $[;
	    while ($ARGV = shift) {
		 open(ARGV, $ARGV);
		 while (<ARGV>)	{
		      ...	# code for each	line
		 }
	    }

       except that it isn't as cumbersome to say, and will actually work.   It
       really does shift array ARGV and	put the	current	filename into variable
       ARGV.  It also uses filehandle ARGV internally--<> is  just  a  synonym
       for  <ARGV>,  which  is	magical.   (The	pseudo code above doesn't work
       because it treats <ARGV>	as non-magical.)

       You can modify @ARGV before the first <>	as long	as the array  ends  up
       containing  the	list  of filenames you really want.  Line numbers ($.)
       continue	as if the input	was one	big  happy  file.   (But  see  example
       under eof for how to reset line numbers on each file.)

       If you want to set @ARGV	to your	own list of files, go right ahead.  If
       you want	to pass	switches into your script, you can put a loop  on  the
       front like this:

	    while ($_ =	$ARGV[0], /^-/)	{
		 shift;
		last if	/^--$/;
		 /^-D(.*)/ && ($debug =	$1);
		 /^-v/ && $verbose++;
		 ...	   # other switches
	    }
	    while (<>) {
		 ...	   # code for each line
	    }

       The  <> symbol will return FALSE	only once.  If you call	it again after
       this it will assume you are processing another @ARGV list, and  if  you
       haven't set @ARGV, will input from STDIN.

       If  the	string	inside	the  angle brackets is a reference to a	scalar
       variable	(e.g. <$foo>), then that variable contains  the	 name  of  the
       filehandle to input from.

       If  the	string inside angle brackets is	not a filehandle, it is	inter-
       preted as a filename pattern to be globbed,  and	 either	 an  array  of
       filenames  or  the  next	filename in the	list is	returned, depending on
       context.	 One level of $	interpretation is done first,  but  you	 can't
       say  <$foo>  because  that's an indirect	filehandle as explained	in the
       previous	paragraph.  You	could insert curly brackets to force interpre-
       tation as a filename glob: <${foo}>.  Example:

	    while (<*.c>) {
		 chmod 0644, $_;
	    }

       is equivalent to

	    open(foo, "echo *.c	| tr -s	' \t\r\f' '\\012\\012\\012\\012'|");
	    while (<foo>) {
		 chop;
		 chmod 0644, $_;
	    }

       In fact,	it's currently implemented that	way.  (Which means it will not
       work on filenames with spaces in	them unless you	have /bin/csh on  your
       machine.)  Of course, the shortest way to do the	above is:

	    chmod 0644,	<*.c>;

       Syntax

       A perl script consists of a sequence of declarations and	commands.  The
       only things that	need to	be declared in perl  are  report  formats  and
       subroutines.  See the sections below for	more information on those dec-
       larations.  All uninitialized user-created objects are assumed to start
       with  a	null or	0 value	until they are defined by some explicit	opera-
       tion such as assignment.	 The sequence of  commands  is	executed  just
       once,  unlike in	sed and	awk scripts, where the sequence	of commands is
       executed	for each input line.  While this means that you	 must  explic-
       itly  loop  over	the lines of your input	file (or files), it also means
       you have	much more control over which files and which  lines  you  look
       at.   (Actually,	 I'm lying--it is possible to do an implicit loop with
       either the -n or	-p switch.)

       A declaration can be put	anywhere a command can,	but has	no  effect  on
       the  execution  of  the	primary	sequence of commands--declarations all
       take effect at compile time.  Typically all the declarations are	put at
       the beginning or	the end	of the script.

       Perl  is, for the most part, a free-form	language.  (The	only exception
       to this is format declarations, for fairly obvious reasons.)   Comments
       are  indicated  by  the # character, and	extend to the end of the line.
       If you attempt to use /*	*/ C comments, it will be  interpreted	either
       as division or pattern matching,	depending on the context.  So don't do
       that.

       Compound	statements

       In perl,	a sequence of commands	may  be	 treated  as  one  command  by
       enclosing it in curly brackets.	We will	call this a BLOCK.

       The following compound commands may be used to control flow:

	    if (EXPR) BLOCK
	    if (EXPR) BLOCK else BLOCK
	    if (EXPR) BLOCK elsif (EXPR) BLOCK ... else	BLOCK
	    LABEL while	(EXPR) BLOCK
	    LABEL while	(EXPR) BLOCK continue BLOCK
	    LABEL for (EXPR; EXPR; EXPR) BLOCK
	    LABEL foreach VAR (ARRAY) BLOCK
	    LABEL BLOCK	continue BLOCK

       Note  that,  unlike C and Pascal, these are defined in terms of BLOCKs,
       not statements.	This means that	the curly  brackets  are  required--no
       dangling	statements allowed.  If	you want to write conditionals without
       curly brackets there are	several	other ways to do  it.	The  following
       all do the same thing:

	    if (!open(foo)) { die "Can't open $foo: $!"; }
	    die	"Can't open $foo: $!" unless open(foo);
	    open(foo) || die "Can't open $foo: $!"; # foo or bust!
	    open(foo) ?	'hi mom' : die "Can't open $foo: $!";
			   # a bit exotic, that	last one

       The  if	statement is straightforward.  Since BLOCKs are	always bounded
       by curly	brackets, there	is never any ambiguity about which if an  else
       goes  with.  If you use unless in place of if, the sense	of the test is
       reversed.

       The while statement executes the	block as long  as  the	expression  is
       true  (does  not	 evaluate  to  the  null  string  or 0).  The LABEL is
       optional, and if	present, consists  of  an  identifier  followed	 by  a
       colon.	The  LABEL identifies the loop for the loop control statements
       next, last, and redo (see below).  If there is a	continue BLOCK,	it  is
       always  executed	 just  before the conditional is about to be evaluated
       again, similarly	to the third part of a for loop	in C.  Thus it can  be
       used  to	increment a loop variable, even	when the loop has been contin-
       ued via the next	statement (similar to the C "continue" statement).

       If the word while is replaced by	the word until,	the sense of the  test
       is reversed, but	the conditional	is still tested	before the first iter-
       ation.

       In either the if	or the while statement,	you may	replace	"(EXPR)"  with
       a  BLOCK,  and the conditional is true if the value of the last command
       in that block is	true.

       The for loop works exactly like the corresponding while loop:

	    for	($i = 1; $i < 10; $i++)	{
		 ...
	    }

       is the same as

	    $i = 1;
	    while ($i <	10) {
		 ...
	    } continue {
		 $i++;
	    }

       The foreach loop	iterates over a	normal array value and sets the	 vari-
       able  VAR  to  be  each	element	of the array in	turn.  The variable is
       implicitly local	to the loop, and regains its former value upon exiting
       the  loop.   The	 "foreach"  keyword is actually	identical to the "for"
       keyword,	so you can use "foreach" for readability or "for" for brevity.
       If  VAR	is  omitted,  $_  is set to each value.	 If ARRAY is an	actual
       array (as opposed to an expression returning an array value),  you  can
       modify  each  element  of  the  array by	modifying VAR inside the loop.
       Examples:

	    for	(@ary) { s/foo/bar/; }

	    foreach $elem (@elements) {
		 $elem *= 2;
	    }

	    for	((10,9,8,7,6,5,4,3,2,1,'BOOM'))	{
		 print $_, "\n"; sleep(1);
	    }

	    for	(1..15)	{ print	"Merry Christmas\n"; }

	    foreach $item (split(/:[\\\n:]*/, $ENV{'TERMCAP'}))	{
		 print "Item: $item\n";
	    }

       The BLOCK by itself (labeled or not) is equivalent to a loop that  exe-
       cutes  once.  Thus you can use any of the loop control statements in it
       to leave	or restart the block.  The continue block is  optional.	  This
       construct is particularly nice for doing	case structures.

	    foo: {
		 if (/^abc/) { $abc = 1; last foo; }
		 if (/^def/) { $def = 1; last foo; }
		 if (/^xyz/) { $xyz = 1; last foo; }
		 $nothing = 1;
	    }

       There  is  no  official	switch	statement  in  perl, because there are
       already several ways to write  the  equivalent.	 In  addition  to  the
       above, you could	write

	    foo: {
		 $abc =	1, last	foo  if	/^abc/;
		 $def =	1, last	foo  if	/^def/;
		 $xyz =	1, last	foo  if	/^xyz/;
		 $nothing = 1;
	    }

       or

	    foo: {
		 /^abc/	&& do {	$abc = 1; last foo; };
		 /^def/	&& do {	$def = 1; last foo; };
		 /^xyz/	&& do {	$xyz = 1; last foo; };
		 $nothing = 1;
	    }

       or

	    foo: {
		 /^abc/	&& ($abc = 1, last foo);
		 /^def/	&& ($def = 1, last foo);
		 /^xyz/	&& ($xyz = 1, last foo);
		 $nothing = 1;
	    }

       or even

	    if (/^abc/)
		 { $abc	= 1; }
	    elsif (/^def/)
		 { $def	= 1; }
	    elsif (/^xyz/)
		 { $xyz	= 1; }
	    else
		 {$nothing = 1;}

       As  it  happens,	 these are all optimized internally to a switch	struc-
       ture, so	perl jumps directly to the desired statement, and you  needn't
       worry  about  perl  executing  a	lot of unnecessary statements when you
       have a string of	50 elsifs, as long as you are testing the same	simple
       scalar variable using ==, eq, or	pattern	matching as above.  (If	you're
       curious as to whether the optimizer has done this for a particular case
       statement, you can use the -D1024 switch	to list	the syntax tree	before
       execution.)

       Simple statements

       The only	kind of	simple statement is an expression  evaluated  for  its
       side  effects.	Every simple statement must be terminated with a semi-
       colon, unless it	is the final statement in a block, in which  case  the
       semicolon  is  optional.	  (Semicolon  is still encouraged there	if the
       block takes up more than	one line).

       Any simple statement may	optionally be followed by a  single  modifier,
       just before the terminating semicolon.  The possible modifiers are:

	    if EXPR
	    unless EXPR
	    while EXPR
	    until EXPR

       The if and unless modifiers have	the expected semantics.	 The while and
       until modifiers also have the expected semantics	(conditional evaluated
       first),	except	when applied to	a do-BLOCK or a	do-SUBROUTINE command,
       in which	case the block executes	once before the	conditional is	evalu-
       ated.  This is so that you can write loops like:

	    do {
		 $_ = <STDIN>;
		 ...
	    } until $_ eq ".\n";

       (See  the  do operator below.  Note also	that the loop control commands
       described later will NOT	work in	this construct,	since modifiers	 don't
       take loop labels.  Sorry.)

       Expressions

       Since perl expressions work almost exactly like C expressions, only the
       differences will	be mentioned here.

       Here's what perl	has that C doesn't:

       **      The exponentiation operator.

       **=     The exponentiation assignment operator.

       ()      The null	list, used to initialize an array to null.

       .       Concatenation of	two strings.

       .=      The concatenation assignment operator.

       eq      String equality (== is numeric equality).  For a	mnemonic  just
	       think  of "eq" as a string.  (If	you are	used to	the awk	behav-
	       ior of using == for either string or numeric equality based  on
	       the  current  form  of  the  comparands,	 beware!   You must be
	       explicit	here.)

       ne      String inequality (!= is	numeric	inequality).

       lt      String less than.

       gt      String greater than.

       le      String less than	or equal.

       ge      String greater than or equal.

       cmp     String comparison, returning -1,	0, or 1.

       <=>     Numeric comparison, returning -1, 0, or 1.

       =~      Certain operations search or modify the string "$_" by default.
	       This  operator  makes that kind of operation work on some other
	       string.	The right argument is a	search pattern,	 substitution,
	       or  translation.	  The  left argument is	what is	supposed to be
	       searched, substituted, or translated  instead  of  the  default
	       "$_".  The return value indicates the success of	the operation.
	       (If the right argument is an expression	other  than  a	search
	       pattern,	 substitution,	or translation,	it is interpreted as a
	       search pattern at run time.  This is  less  efficient  than  an
	       explicit	 search, since the pattern must	be compiled every time
	       the expression is evaluated.)  The precedence of	this  operator
	       is  lower  than	unary  minus  and autoincrement/decrement, but
	       higher than everything else.

       !~      Just like =~ except the return value is negated.

       x       The repetition operator.	 Returns a string  consisting  of  the
	       left  operand  repeated	the  number  of	times specified	by the
	       right operand.  In an array context, if the left	operand	 is  a
	       list in parens, it repeats the list.

		    print '-' x	80;	     # print row of dashes
		    print '-' x80;	# illegal, x80 is identifier

		    print "\t" x ($tab/8), ' ' x ($tab%8);  # tab over

		    @ones = (1)	x 80;	     # an array	of 80 1's
		    @ones = (5)	x @ones;	  # set	all elements to	5

       x=      The repetition assignment operator.  Only works on scalars.

       ..      The  range  operator,  which  is	really two different operators
	       depending on the	context.  In  an  array	 context,  returns  an
	       array  of  values counting (by ones) from the left value	to the
	       right value.  This is useful for	writing	 "for  (1..10)"	 loops
	       and for doing slice operations on arrays.

	       In  a scalar context, ..	returns	a boolean value.  The operator
	       is bistable, like a  flip-flop,	and  emulates  the  line-range
	       (comma)	operator  of  sed,  awk, and various editors.  Each ..
	       operator	maintains its own boolean state.  It is	false as  long
	       as  its	left operand is	false.	Once the left operand is true,
	       the range operator stays	true until the right operand is	 true,
	       AFTER  which  the  range	 operator  becomes  false  again.  (It
	       doesn't become false till the next time the range  operator  is
	       evaluated.   It	can test the right operand and become false on
	       the same	evaluation it became true (as in awk),	but  it	 still
	       returns	true once.  If you don't want it to test the right op-
	       erand till the next evaluation (as  in  sed),  use  three  dots
	       (...)  instead  of  two.)   The	right operand is not evaluated
	       while the operator is in	the "false" state, and the left	 oper-
	       and is not evaluated while the operator is in the "true"	state.
	       The precedence is a little lower	than ||	 and  &&.   The	 value
	       returned	 is  either  the  null string for false, or a sequence
	       number (beginning with 1) for true.   The  sequence  number  is
	       reset for each range encountered.  The final sequence number in
	       a range has the string  'E0'  appended  to  it,	which  doesn't
	       affect its numeric value, but gives you something to search for
	       if you want to exclude  the  endpoint.	You  can  exclude  the
	       beginning  point	 by  waiting  for  the	sequence  number to be
	       greater than 1.	If either operand of scalar .. is static, that
	       operand	is implicitly compared to the $. variable, the current
	       line number.  Examples:

	       As a scalar operator:
		   if (101 .. 200) { print; }	  # print 2nd hundred lines

		   next	line if	(1 .. /^$/); # skip header lines

		   s/^/> / if (/^$/ .. eof());	  # quote body

	       As an array operator:
		   for (101 .. 200) { print; }	  # print $_ 100 times

		   @foo	= @foo[$[ .. $#foo]; # an expensive no-op
		   @foo	= @foo[$#foo-4 .. $#foo]; # slice last 5 items

       -x      A file test.  This unary	operator takes one argument, either  a
	       filename	 or a filehandle, and tests the	associated file	to see
	       if something is true about it.  If  the	argument  is  omitted,
	       tests  $_,  except for -t, which	tests STDIN.  It returns 1 for
	       true and	'' for false, or  the  undefined  value	 if  the  file
	       doesn't	exist.	 Precedence  is	 higher	than logical and rela-
	       tional operators, but lower  than  arithmetic  operators.   The
	       operator	may be any of:
		    -r	 File is readable by effective uid/gid.
		    -w	 File is writable by effective uid/gid.
		    -x	 File is executable by effective uid/gid.
		    -o	 File is owned by effective uid.
		    -R	 File is readable by real uid/gid.
		    -W	 File is writable by real uid/gid.
		    -X	 File is executable by real uid/gid.
		    -O	 File is owned by real uid.
		    -e	 File exists.
		    -z	 File has zero size.
		    -s	 File has non-zero size	(returns size).
		    -f	 File is a plain file.
		    -d	 File is a directory.
		    -l	 File is a symbolic link.
		    -p	 File is a named pipe (FIFO).
		    -S	 File is a socket.
		    -b	 File is a block special file.
		    -c	 File is a character special file.
		    -u	 File has setuid bit set.
		    -g	 File has setgid bit set.
		    -k	 File has sticky bit set.
		    -t	 Filehandle is opened to a tty.
		    -T	 File is a text	file.
		    -B	 File is a binary file (opposite of -T).
		    -M	 Age of	file in	days when script started.
		    -A	 Same for access time.
		    -C	 Same for inode	change time.

	       The interpretation of the file permission operators -r, -R, -w,
	       -W, -x and -X is	based solely on	the mode of the	file  and  the
	       uids  and  gids	of  the	 user.	There may be other reasons you
	       can't actually read, write or  execute  the  file.   Also  note
	       that, for the superuser,	-r, -R,	-w and -W always return	1, and
	       -x and -X return	1 if any execute  bit  is  set	in  the	 mode.
	       Scripts	run  by	 the superuser may thus	need to	do a stat() in
	       order to	determine the actual mode of the file, or  temporarily
	       set the uid to something	else.

	       Example:

		    while (<>) {
			 chop;
			 next unless -f	$_;  # ignore specials
			 ...
		    }

	       Note  that  -s/a/b/ does	not do a negated substitution.	Saying
	       -exp($foo) still	works as expected, however--only  single  let-
	       ters following a	minus are interpreted as file tests.

	       The  -T and -B switches work as follows.	 The first block or so
	       of the file is examined for odd characters such as strange con-
	       trol  codes  or	metacharacters.	  If  too  many	odd characters
	       (>10%) are found, it's a	-B file, otherwise  it's  a  -T	 file.
	       Also, any file containing null in the first block is considered
	       a binary	file.  If -T or	-B is used on a	filehandle,  the  cur-
	       rent  stdio  buffer  is	examined  rather than the first	block.
	       Both -T and -B return TRUE on a null file, or  a	 file  at  EOF
	       when testing a filehandle.

       If  any	of the file tests (or either stat operator) are	given the spe-
       cial filehandle consisting of  a	 solitary  underline,  then  the  stat
       structure  of the previous file test (or	stat operator) is used,	saving
       a system	call.  (This doesn't work with -t, and you  need  to  remember
       that  lstat and -l will leave values in the stat	structure for the sym-
       bolic link, not the real	file.)	Example:

	    print "Can do.\n" if -r $a || -w _ || -x _;

	    stat($filename);
	    print "Readable\n" if -r _;
	    print "Writable\n" if -w _;
	    print "Executable\n" if -x _;
	    print "Setuid\n" if	-u _;
	    print "Setgid\n" if	-g _;
	    print "Sticky\n" if	-k _;
	    print "Text\n" if -T _;
	    print "Binary\n" if	-B _;

       Here is what C has that perl doesn't:

       unary &	   Address-of operator.

       unary *	   Dereference-address operator.

       (TYPE)	   Type	casting	operator.

       Like C, perl does a certain amount of expression	evaluation at  compile
       time,  whenever	it determines that all of the arguments	to an operator
       are static and have no side effects.  In	particular, string  concatena-
       tion  happens  at  compile time between literals	that don't do variable
       substitution.  Backslash	interpretation also happens at	compile	 time.
       You can say

	    'Now is the	time for all' .	"\n" .
	    'good men to come to.'

       and this	all reduces to one string internally.

       The autoincrement operator has a	little extra built-in magic to it.  If
       you increment a variable	that is	numeric, or that has ever been used in
       a  numeric context, you get a normal increment.	If, however, the vari-
       able has	only been used in string contexts since	it was set, and	has  a
       value that is not null and matches the pattern /^[a-zA-Z]*[0-9]*$/, the
       increment is done as a string, preserving  each	character  within  its
       range, with carry:

	    print ++($foo = '99');   # prints '100'
	    print ++($foo = 'a0');   # prints 'a1'
	    print ++($foo = 'Az');   # prints 'Ba'
	    print ++($foo = 'zz');   # prints 'aaa'

       The autodecrement is not	magical.

       The  range  operator  (in  an  array  context) makes use	of the magical
       autoincrement algorithm if the minimum and maximum  are	strings.   You
       can say

	    @alphabet =	('A' ..	'Z');

       to get all the letters of the alphabet, or

	    $hexdigit =	(0 .. 9, 'a' ..	'f')[$num & 15];

       to get a	hexadecimal digit, or

	    @z2	= ('01'	.. '31');  print @z2[$mday];

       to  get dates with leading zeros.  (If the final	value specified	is not
       in the sequence that the	magical	increment would	produce, the  sequence
       goes  until  the	next value would be longer than	the final value	speci-
       fied.)

       The || and && operators differ from C's in that,	rather than  returning
       0  or 1,	they return the	last value evaluated.  Thus, a portable	way to
       find out	the home directory might be:

	    $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
		(getpwuid($<))[7] || die "You're homeless!\n";

       Along with the literals and variables mentioned earlier,	the operations
       in  the following section can serve as terms in an expression.  Some of
       these operations	take a LIST as an argument.  Such a list  can  consist
       of  any combination of scalar arguments or array	values;	the array val-
       ues will	be included in the list	as if  each  individual	 element  were
       interpolated  at	that point in the list,	forming	a longer single-dimen-
       sional array value.  Elements of	the LIST should	be separated  by  com-
       mas.   If  an  operation	 is  listed  both with and without parentheses
       around its arguments, it	means you can either use it as a unary	opera-
       tor  or	as  a  function	 call.	To use it as a function	call, the next
       token on	the same line must be  a  left	parenthesis.   (There  may  be
       intervening white space.)  Such a function then has highest precedence,
       as you would expect from	a function.  If	any token other	 than  a  left
       parenthesis  follows,  then  it	is a unary operator, with a precedence
       depending only on whether it is a LIST operator or not.	LIST operators
       have  lowest  precedence.   All other unary operators have a precedence
       greater than relational operators but less than	arithmetic  operators.
       See the section on Precedence.

       For  operators  that  can  be used in either a scalar or	array context,
       failure is generally indicated in a scalar  context  by	returning  the
       undefined  value,  and  in an array context by returning	the null list.
       Remember	though that THERE IS NO	GENERAL	RULE  FOR  CONVERTING  A  LIST
       INTO  A SCALAR.	Each operator decides which sort of scalar it would be
       most appropriate	to return.  Some operators return the  length  of  the
       list that would have been returned in an	array context.	Some operators
       return the first	value in the list.  Some  operators  return  the  last
       value  in the list.  Some operators return a count of successful	opera-
       tions.  In general, they	do what	you want, unless you want consistency.

       /PATTERN/
	       See m/PATTERN/.

       ?PATTERN?
	       This is just like the /pattern/ search, except that it  matches
	       only  once between calls	to the reset operator.	This is	a use-
	       ful optimization	when you only want to see the first occurrence
	       of  something  in  each	file  of a set of files, for instance.
	       Only ?? patterns	local to the current package are reset.

       accept(NEWSOCKET,GENERICSOCKET)
	       Does the	same thing that	the accept system call does.   Returns
	       true  if	it succeeded, false otherwise.	See example in section
	       on Interprocess Communication.

       alarm(SECONDS)

       alarm SECONDS
	       Arranges	to have	a SIGALRM delivered to this process after  the
	       specified  number  of seconds (minus 1, actually) have elapsed.
	       Thus, alarm(15) will cause a SIGALRM at some point more than 14
	       seconds in the future.  Only one	timer may be counting at once.
	       Each call disables the previous timer, and an argument of 0 may
	       be supplied to cancel the previous timer	without	starting a new
	       one.  The returned value	is the amount of time remaining	on the
	       previous	timer.

       atan2(Y,X)
	       Returns the arctangent of Y/X in	the range -PI to PI.

       bind(SOCKET,NAME)
	       Does  the  same	thing that the bind system call	does.  Returns
	       true if it succeeded, false otherwise.  NAME should be a	packed
	       address of the proper type for the socket.  See example in sec-
	       tion on Interprocess Communication.

       binmode(FILEHANDLE)

       binmode FILEHANDLE
	       Arranges	for the	file to	be read	in "binary" mode in  operating
	       systems	that distinguish between binary	and text files.	 Files
	       that are	not read in binary mode	have CR	 LF  sequences	trans-
	       lated  to  LF  on  input	 and LF	translated to CR LF on output.
	       Binmode has no effect under Unix.  If FILEHANDLE	is an  expres-
	       sion, the value is taken	as the name of the filehandle.

       caller(EXPR)

       caller  Returns the context of the current subroutine call:

		    ($package,$filename,$line) = caller;

	       With  EXPR,  returns  some  extra information that the debugger
	       uses to print a stack trace.  The value of EXPR	indicates  how
	       many call frames	to go back before the current one.

       chdir(EXPR)

       chdir EXPR
	       Changes the working directory to	EXPR, if possible.  If EXPR is
	       omitted,	changes	to home	directory.  Returns 1 upon success,  0
	       otherwise.  See example under die.

       chmod(LIST)

       chmod LIST
	       Changes	the permissions	of a list of files.  The first element
	       of the list must	be the numerical mode.	Returns	the number  of
	       files successfully changed.

		    $cnt = chmod 0755, 'foo', 'bar';
		    chmod 0755,	@executables;

       chop(LIST)

       chop(VARIABLE)

       chop VARIABLE

       chop    Chops  off the last character of	a string and returns the char-
	       acter chopped.  It's used primarily to remove the newline  from
	       the  end	 of  an	 input record, but is much more	efficient than
	       s/\n// because it neither scans	nor  copies  the  string.   If
	       VARIABLE	is omitted, chops $_.  Example:

		    while (<>) {
			 chop;	   # avoid \n on last field
			 @array	= split(/:/);
			 ...
		    }

	       You  can	 actually chop anything	that's an lvalue, including an
	       assignment:

		    chop($cwd =	`pwd`);
		    chop($answer = <STDIN>);

	       If you chop a list, each	element	is chopped.  Only the value of
	       the last	chop is	returned.

       chown(LIST)

       chown LIST
	       Changes	the  owner  (and group)	of a list of files.  The first
	       two elements of the list	must be	the NUMERICAL uid and gid,  in
	       that order.  Returns the	number of files	successfully changed.

		    $cnt = chown $uid, $gid, 'foo', 'bar';
		    chown $uid,	$gid, @filenames;

	       Here's  an example that looks up	non-numeric uids in the	passwd
	       file:

		    print "User: ";
		    $user = <STDIN>;
		    chop($user);
		    print "Files: "
		    $pattern = <STDIN>;
		    chop($pattern);
		    open(pass, '/etc/passwd')
			 || die	"Can't open passwd: $!\n";
		    while (<pass>) {
			 ($login,$pass,$uid,$gid) = split(/:/);
			 $uid{$login} =	$uid;
			 $gid{$login} =	$gid;
		    }
		    @ary = <${pattern}>;     # get filenames
		    if ($uid{$user} eq '') {
			 die "$user not	in passwd file";
		    }
		    else {
			 chown $uid{$user}, $gid{$user}, @ary;
		    }

       chroot(FILENAME)

       chroot FILENAME
	       Does the	same as	the system call	of that	name.	If  you	 don't
	       know  what it does, don't worry about it.  If FILENAME is omit-
	       ted, does chroot	to $_.

       close(FILEHANDLE)

       close FILEHANDLE
	       Closes the file or pipe associated with the file	 handle.   You
	       don't  have to close FILEHANDLE if you are immediately going to
	       do another open on it, since open will close it for you.	  (See
	       open.)	However, an explicit close on an input file resets the
	       line counter ($.), while	the implicit close done	by  open  does
	       not.   Also, closing a pipe will	wait for the process executing
	       on the pipe to complete,	in case	you want to look at the	output
	       of  the	pipe  afterwards.  Closing a pipe explicitly also puts
	       the status value	of the command into $?.	 Example:

		    open(OUTPUT, '|sort	>foo');	  # pipe to sort
		    ...	 # print stuff to output
		    close OUTPUT;	# wait for sort	to finish
		    open(INPUT,	'foo');	# get sort's results

	       FILEHANDLE may be an expression	whose  value  gives  the  real
	       filehandle name.

       closedir(DIRHANDLE)

       closedir	DIRHANDLE
	       Closes a	directory opened by opendir().

       connect(SOCKET,NAME)
	       Does the	same thing that	the connect system call	does.  Returns
	       true if it succeeded, false otherwise.  NAME should be a	 pack-
	       age  address of the proper type for the socket.	See example in
	       section on Interprocess Communication.

       cos(EXPR)

       cos EXPR
	       Returns the cosine of EXPR (expressed in	radians).  If EXPR  is
	       omitted takes cosine of $_.

       crypt(PLAINTEXT,SALT)
	       Encrypts	 a  string  exactly like the crypt() function in the C
	       library.	 Useful	for checking the password file for lousy pass-
	       words.  Only the	guys wearing white hats	should do this.

       dbmclose(ASSOC_ARRAY)

       dbmclose	ASSOC_ARRAY
	       Breaks the binding between a dbm	file and an associative	array.
	       The values remaining in the associative array  are  meaningless
	       unless you happen to want to know what was in the cache for the
	       dbm file.  This function	is only	useful if you have ndbm.

       dbmopen(ASSOC,DBNAME,MODE)
	       This binds a dbm	or ndbm	file to	an associative	array.	 ASSOC
	       is the name of the associative array.  (Unlike normal open, the
	       first argument is NOT a filehandle, even	though it  looks  like
	       one).   DBNAME is the name of the database (without the .dir or
	       .pag extension).	 If the	database does not exist, it is created
	       with  protection	 specified by MODE (as modified	by the umask).
	       If your system only supports the	older dbm functions,  you  may
	       perform	only  one dbmopen in your program.  If your system has
	       neither dbm nor ndbm, calling dbmopen produces a	fatal error.

	       Values assigned to the associative array	prior to  the  dbmopen
	       are  lost.   A  certain	number of values from the dbm file are
	       cached in memory.  By default this number is 64,	 but  you  can
	       increase	 it by preallocating that number of garbage entries in
	       the associative array before the	dbmopen.  You  can  flush  the
	       cache if	necessary with the reset command.

	       If  you	don't  have write access to the	dbm file, you can only
	       read associative	array variables, not set them.	If you want to
	       test  whether  you can write, either use	file tests or try set-
	       ting a dummy array entry	inside an eval,	which  will  trap  the
	       error.

	       Note that functions such	as keys() and values() may return huge
	       array values when used on large dbm files.  You may  prefer  to
	       use the each() function to iterate over large dbm files.	 Exam-
	       ple:

		    # print out	history	file offsets
		    dbmopen(HIST,'/usr/lib/news/history',0666);
		    while (($key,$val) = each %HIST) {
			 print $key, ' = ', unpack('L',$val), "\n";
		    }
		    dbmclose(HIST);

       defined(EXPR)

       defined EXPR
	       Returns a boolean value saying whether the lvalue  EXPR	has  a
	       real  value or not.  Many operations return the undefined value
	       under exceptional conditions, such as end of  file,  uninitial-
	       ized variable, system error and such.  This function allows you
	       to distinguish between an undefined null	string and  a  defined
	       null  string  with  operations  that  might  return a real null
	       string, in particular referencing elements of  an  array.   You
	       may  also  check	to see if arrays or subroutines	exist.	Use on
	       predefined variables is not  guaranteed	to  produce  intuitive
	       results.	 Examples:

		    print if defined $switch{'D'};
		    print "$val\n" while defined($val =	pop(@ary));
		    die	"Can't readlink	$sym: $!"
			 unless	defined($value = readlink $sym);
		    eval '@foo = ()' if	defined(@foo);
		    die	"No XYZ	package	defined" unless	defined	%_XYZ;
		    sub	foo { defined &$bar ? &$bar(@_)	: die "No bar";	}

	       See also	undef.

       delete $ASSOC{KEY}
	       Deletes	the  specified	value  from  the specified associative
	       array.  Returns the deleted value, or the  undefined  value  if
	       nothing	was  deleted.  Deleting	from $ENV{} modifies the envi-
	       ronment.	 Deleting from an array	bound to a  dbm	 file  deletes
	       the entry from the dbm file.

	       The following deletes all the values of an associative array:

		    foreach $key (keys %ARRAY) {
			 delete	$ARRAY{$key};
		    }

	       (But it would be	faster to use the reset	command.  Saying undef
	       %ARRAY is faster	yet.)

       die(LIST)

       die LIST
	       Outside of an eval, prints the value  of	 LIST  to  STDERR  and
	       exits with the current value of $!  (errno).  If	$! is 0, exits
	       with the	value of ($? >>	8) (`command` status).	If ($?	>>  8)
	       is  0,  exits  with  255.  Inside an eval, the error message is
	       stuffed into $@ and the eval is terminated with	the  undefined
	       value.

	       Equivalent examples:

		    die	"Can't cd to spool: $!\n"
			 unless	chdir '/usr/spool/news';

		    chdir '/usr/spool/news' || die "Can't cd to	spool: $!\n"

	       If  the	value  of  EXPR	does not end in	a newline, the current
	       script line number and input line  number  (if  any)  are  also
	       printed,	 and a newline is supplied.  Hint: sometimes appending
	       ", stopped" to your message will	cause it to make better	 sense
	       when the	string "at foo line 123" is appended.  Suppose you are
	       running script "canasta".

		    die	"/etc/games is no good";
		    die	"/etc/games is no good,	stopped";

	       produce,	respectively

		    /etc/games is no good at canasta line 123.
		    /etc/games is no good, stopped at canasta line 123.

	       See also	exit.

       do BLOCK
	       Returns the value of the	last command in	the sequence  of  com-
	       mands  indicated	 by  BLOCK.  When modified by a	loop modifier,
	       executes	the BLOCK once before testing the loop condition.  (On
	       other  statements  the  loop  modifiers	test  the  conditional
	       first.)

       do SUBROUTINE (LIST)
	       Executes	a  SUBROUTINE  declared	 by  a	sub  declaration,  and
	       returns	the  value of the last expression evaluated in SUBROU-
	       TINE.  If there is no subroutine	by that	name, produces a fatal
	       error.	(You  may use the "defined" operator to	determine if a
	       subroutine exists.)  If you pass	arrays as part of LIST you may
	       wish  to	 pass  the length of the array in front	of each	array.
	       (See the	section	on subroutines later on.)  The parentheses are
	       required	to avoid confusion with	the "do	EXPR" form.

	       SUBROUTINE  may also be a single	scalar variable, in which case
	       the name	of the subroutine to execute is	taken from  the	 vari-
	       able.

	       As an alternate (and preferred) form, you may call a subroutine
	       by prefixing the	name with an ampersand:	&foo(@args).   If  you
	       aren't  passing	any arguments, you don't have to use parenthe-
	       ses.  If	you omit the parentheses, no @_	array is passed	to the
	       subroutine.   The & form	is also	used to	specify	subroutines to
	       the defined and undef operators:

		    if (defined	&$var) { &$var($parm); undef &$var; }

       do EXPR Uses the	value of EXPR as a filename and	executes the  contents
	       of  the	file  as a perl	script.	 Its primary use is to include
	       subroutines from	a perl subroutine library.

		    do 'stat.pl';

	       is just like

		    eval `cat stat.pl`;

	       except that it's	more efficient,	more concise, keeps  track  of
	       the  current  filename for error	messages, and searches all the
	       -I libraries if the file	isn't in the  current  directory  (see
	       also  the @INC array in Predefined Names).  It's	the same, how-
	       ever, in	that it	does reparse the file every time you call  it,
	       so  if  you  are	 going to use the file inside a	loop you might
	       prefer to use -P	and #include, at the expense of	a little  more
	       startup	time.	(The  main  problem  with #include is that cpp
	       doesn't grok # comments--a workaround is	to use ";#" for	stand-
	       alone comments.)	 Note that the following are NOT equivalent:

		    do $foo;  #	eval a file
		    do $foo();	   # call a subroutine

	       Note that inclusion of library routines is better done with the
	       "require" operator.

       dump LABEL
	       This causes an immediate	core dump.  Primarily this is so  that
	       you  can	 use the undump	program	to turn	your core dump into an
	       executable binary after having initialized all  your  variables
	       at  the	beginning of the program.  When	the new	binary is exe-
	       cuted it	will begin by executing	a "goto	LABEL" (with  all  the
	       restrictions that goto suffers).	 Think of it as	a goto with an
	       intervening core	dump and reincarnation.	 If LABEL is  omitted,
	       restarts	 the  program from the top.  WARNING: any files	opened
	       at the time of the dump will NOT	be open	any more when the pro-
	       gram  is	reincarnated, with possible resulting confusion	on the
	       part of perl.  See also -u.

	       Example:

		    #!/usr/bin/perl
		    require 'getopt.pl';
		    require 'stat.pl';
		    %days = (
			'Sun',1,
			'Mon',2,
			'Tue',3,
			'Wed',4,
			'Thu',5,
			'Fri',6,
			'Sat',7);

		    dump QUICKSTART if $ARGV[0]	eq '-d';

		   QUICKSTART:
		    do Getopt('f');

       each(ASSOC_ARRAY)

       each ASSOC_ARRAY
	       Returns a 2 element array consisting of the key and  value  for
	       the next	value of an associative	array, so that you can iterate
	       over it.	 Entries are returned in an apparently	random	order.
	       When  the  array	 is  entirely  read,  a	null array is returned
	       (which when assigned produces a FALSE  (0)  value).   The  next
	       call  to	 each()	 after	that  will start iterating again.  The
	       iterator	can be reset only by reading all the elements from the
	       array.	You must not modify the	array while iterating over it.
	       There is	a single iterator for each associative	array,	shared
	       by  all	each(),	keys() and values() function calls in the pro-
	       gram.  The following  prints  out  your	environment  like  the
	       printenv	program, only in a different order:

		    while (($key,$value) = each	%ENV) {
			 print "$key=$value\n";
		    }

	       See also	keys() and values().

       eof(FILEHANDLE)

       eof()

       eof     Returns	1  if  the  next read on FILEHANDLE will return	end of
	       file, or	if FILEHANDLE is  not  open.   FILEHANDLE  may	be  an
	       expression  whose  value	gives the real filehandle name.	 (Note
	       that this function actually reads a character and then ungetc's
	       it,  so	it  is not very	useful in an interactive context.)  An
	       eof without an argument returns the eof	status	for  the  last
	       file  read.   Empty  parentheses	() may be used to indicate the
	       pseudo file formed of the files listed  on  the	command	 line,
	       i.e.  eof()  is	reasonable  to use inside a while (<>) loop to
	       detect the end of only the last file.   Use  eof(ARGV)  or  eof
	       without the parentheses to test EACH file in a while (<>) loop.
	       Examples:

		    # insert dashes just before	last line of last file
		    while (<>) {
			 if (eof()) {
			      print "--------------\n";
			 }
			 print;
		    }

		    # reset line numbering on each input file
		    while (<>) {
			 print "$.\t$_";
			 if (eof) {	# Not eof().
			      close(ARGV);
			 }
		    }

       eval(EXPR)

       eval EXPR

       eval BLOCK
	       EXPR is parsed and executed as if it were a  little  perl  pro-
	       gram.   It  is executed in the context of the current perl pro-
	       gram, so	that any variable settings, subroutine or format defi-
	       nitions	remain afterwards.  The	value returned is the value of
	       the last	expression evaluated, just as  with  subroutines.   If
	       there is	a syntax error or runtime error, or a die statement is
	       executed, an undefined value is returned	by eval, and $@	is set
	       to  the error message.  If there	was no error, $@ is guaranteed
	       to be a null string.  If	EXPR is	omitted,  evaluates  $_.   The
	       final semicolon,	if any,	may be omitted from the	expression.

	       Note  that, since eval traps otherwise-fatal errors, it is use-
	       ful for determining  whether  a	particular  feature  (such  as
	       dbmopen	or  symlink) is	implemented.  It is also Perl's	excep-
	       tion trapping mechanism,	where the  die	operator  is  used  to
	       raise exceptions.

	       If  the code to be executed doesn't vary, you may use the eval-
	       BLOCK form  to  trap  run-time  errors  without	incurring  the
	       penalty	of recompiling each time.  The error, if any, is still
	       returned	in $@.	Evaluating a single-quoted  string  (as	 EXPR)
	       has  the	 same  effect,	except that the	eval-EXPR form reports
	       syntax errors at	run time via $@, whereas the  eval-BLOCK  form
	       reports	syntax	errors at compile time.	 The eval-EXPR form is
	       optimized to eval-BLOCK the first time it succeeds.  (Since the
	       replacement  side  of  a	 substitution  is considered a single-
	       quoted string when you use the e	modifier, the  same  optimiza-
	       tion occurs there.)  Examples:

		    # make divide-by-zero non-fatal
		    eval { $answer = $a	/ $b; }; warn $@ if $@;

		    # optimized	to same	thing after first use
		    eval '$answer = $a / $b'; warn $@ if $@;

		    # a	compile-time error
		    eval { $answer = };

		    # a	run-time error
		    eval '$answer =';	# sets $@

       exec(LIST)

       exec LIST
	       If  there  is  more than	one argument in	LIST, or if LIST is an
	       array with more than one	value, calls execvp() with  the	 argu-
	       ments in	LIST.  If there	is only	one scalar argument, the argu-
	       ment is checked for shell metacharacters.  If  there  are  any,
	       the  entire argument is passed to "/bin/sh -c" for parsing.  If
	       there are none, the argument is split  into  words  and	passed
	       directly	to execvp(), which is more efficient.  Note: exec (and
	       system) do not flush your output	buffer,	so you may need	to set
	       $| to avoid lost	output.	 Examples:

		    exec '/bin/echo', 'Your arguments are: ', @ARGV;
		    exec "sort $outfile	| uniq";

	       If  you	don't  really  want to execute the first argument, but
	       want to lie to the program you  are  executing  about  its  own
	       name,  you  can specify the program you actually	want to	run by
	       assigning that to a variable and	putting	the name of the	 vari-
	       able in front of	the LIST without a comma.  (This always	forces
	       interpretation of the LIST as  a	 multi-valued  list,  even  if
	       there is	only a single scalar in	the list.)  Example:

		    $shell = '/bin/csh';
		    exec $shell	'-sh';	     # pretend it's a login shell

       exit(EXPR)

       exit EXPR
	       Evaluates EXPR and exits	immediately with that value.  Example:

		    $ans = <STDIN>;
		    exit 0 if $ans =~ /^[Xx]/;

	       See also	die.  If EXPR is omitted, exits	with 0 status.

       exp(EXPR)

       exp EXPR
	       Returns	e  to  the  power  of EXPR.  If	EXPR is	omitted, gives
	       exp($_).

       fcntl(FILEHANDLE,FUNCTION,SCALAR)
	       Implements the fcntl(2) function.  You'll probably have to say

		    require "fcntl.ph";	# probably /usr/local/lib/perl/fcntl.ph

	       first to	get the	correct	 function  definitions.	  If  fcntl.ph
	       doesn't	exist  or  doesn't have	the correct definitions	you'll
	       have to roll your own, based on your C  header  files  such  as
	       <sys/fcntl.h>.	(There is a perl script	called h2ph that comes
	       with the	perl kit which may help	you in this.)	Argument  pro-
	       cessing	and  value  return  works just like ioctl below.  Note
	       that fcntl will produce a fatal error if	used on	a machine that
	       doesn't implement fcntl(2).

       fileno(FILEHANDLE)

       fileno FILEHANDLE
	       Returns	the file descriptor for	a filehandle.  Useful for con-
	       structing bitmaps for select().	If FILEHANDLE  is  an  expres-
	       sion, the value is taken	as the name of the filehandle.

       flock(FILEHANDLE,OPERATION)
	       Calls flock(2) on FILEHANDLE.  See manual page for flock(2) for
	       definition of OPERATION.	 Returns true for  success,  false  on
	       failure.	  Will produce a fatal error if	used on	a machine that
	       doesn't implement flock(2).  Here's a mailbox appender for  BSD
	       systems.

		    $LOCK_SH = 1;
		    $LOCK_EX = 2;
		    $LOCK_NB = 4;
		    $LOCK_UN = 8;

		    sub	lock {
			flock(MBOX,$LOCK_EX);
			# and, in case someone appended
			# while	we were	waiting...
			seek(MBOX, 0, 2);
		    }

		    sub	unlock {
			flock(MBOX,$LOCK_UN);
		    }

		    open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
			 || die	"Can't open mailbox: $!";

		    do lock();
		    print MBOX $msg,"\n\n";
		    do unlock();

       fork    Does  a	fork()	call.	Returns	 the  child  pid to the	parent
	       process and 0 to	the child process.   Note:  unflushed  buffers
	       remain unflushed	in both	processes, which means you may need to
	       set $| to avoid duplicate output.

       getc(FILEHANDLE)

       getc FILEHANDLE

       getc    Returns the next	character from	the  input  file  attached  to
	       FILEHANDLE, or a	null string at EOF.  If	FILEHANDLE is omitted,
	       reads from STDIN.

       getlogin
	       Returns the current login from /etc/utmp, if any.  If null, use
	       getpwuid.

		    $login = getlogin || (getpwuid($<))[0] || "Somebody";

       getpeername(SOCKET)
	       Returns	the packed sockaddr address of other end of the	SOCKET
	       connection.

		    # An internet sockaddr
		    $sockaddr =	'S n a4	x8';
		    $hersockaddr = getpeername(S);
		    ($family, $port, $heraddr) =
			      unpack($sockaddr,$hersockaddr);

       getpgrp(PID)

       getpgrp PID
	       Returns the current process group for the specified PID,	0  for
	       the  current  process.  Will produce a fatal error if used on a
	       machine that doesn't implement getpgrp(2).  If EXPR is omitted,
	       returns process group of	current	process.

       getppid Returns the process id of the parent process.

       getpriority(WHICH,WHO)
	       Returns the current priority for	a process, a process group, or
	       a user.	(See getpriority(2).)  Will produce a fatal  error  if
	       used on a machine that doesn't implement	getpriority(2).

       getpwnam(NAME)

       getgrnam(NAME)

       gethostbyname(NAME)

       getnetbyname(NAME)

       getprotobyname(NAME)

       getpwuid(UID)

       getgrgid(GID)

       getservbyname(NAME,PROTO)

       gethostbyaddr(ADDR,ADDRTYPE)

       getnetbyaddr(ADDR,ADDRTYPE)

       getprotobynumber(NUMBER)

       getservbyport(PORT,PROTO)

       getpwent

       getgrent

       gethostent

       getnetent

       getprotoent

       getservent

       setpwent

       setgrent

       sethostent(STAYOPEN)

       setnetent(STAYOPEN)

       setprotoent(STAYOPEN)

       setservent(STAYOPEN)

       endpwent

       endgrent

       endhostent

       endnetent

       endprotoent

       endservent
	       These routines perform the same functions as their counterparts
	       in the system library.  Within an  array	 context,  the	return
	       values from the various get routines are	as follows:

		    ($name,$passwd,$uid,$gid,
		       $quota,$comment,$gcos,$dir,$shell) = getpw...
		    ($name,$passwd,$gid,$members) = getgr...
		    ($name,$aliases,$addrtype,$length,@addrs) =	gethost...
		    ($name,$aliases,$addrtype,$net) = getnet...
		    ($name,$aliases,$proto) = getproto...
		    ($name,$aliases,$port,$proto) = getserv...

	       (If the entry doesn't exist you get a null list.)

	       Within  a scalar	context, you get the name, unless the function
	       was a lookup by name, in	which case you get  the	 other	thing,
	       whatever	 it is.	 (If the entry doesn't exist you get the unde-
	       fined value.)  For example:

		    $uid = getpwnam
		    $name = getpwuid
		    $name = getpwent
		    $gid = getgrnam
		    $name = getgrgid
		    $name = getgrent
		    etc.

	       The $members value returned by getgr... is  a  space  separated
	       list of the login names of the members of the group.

	       For  the	 gethost... functions, if the h_errno variable is sup-
	       ported in C, it will be returned	to you via $? if the  function
	       call  fails.  The @addrs	value returned by a successful call is
	       a list of the raw addresses returned by the corresponding  sys-
	       tem library call.  In the Internet domain, each address is four
	       bytes long and you can unpack it	by saying something like:

		    ($a,$b,$c,$d) = unpack('C4',$addr[0]);

       getsockname(SOCKET)
	       Returns the packed sockaddr address of this end of  the	SOCKET
	       connection.

		    # An internet sockaddr
		    $sockaddr =	'S n a4	x8';
		    $mysockaddr	= getsockname(S);
		    ($family, $port, $myaddr) =
			      unpack($sockaddr,$mysockaddr);

       getsockopt(SOCKET,LEVEL,OPTNAME)
	       Returns	the  socket option requested, or undefined if there is
	       an error.

       gmtime(EXPR)

       gmtime EXPR
	       Converts	a time as returned by the time function	to a 9-element
	       array with the time analyzed for	the Greenwich timezone.	 Typi-
	       cally used as follows:

	       ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
					     gmtime(time);

	       All array elements are numeric, and  come  straight  out	 of  a
	       struct  tm.   In	 particular this means that $mon has the range
	       0..11 and $wday has the range 0..6.  If EXPR is	omitted,  does
	       gmtime(time).

       goto LABEL
	       Finds  the  statement  labeled with LABEL and resumes execution
	       there.  Currently you may only go to  statements	 in  the  main
	       body  of	 the  program  that are	not nested inside a do {} con-
	       struct.	This statement is not  implemented  very  efficiently,
	       and  is here only to make the sed-to-perl translator easier.  I
	       may change its semantics	at any time, consistent	 with  support
	       for  translated	sed scripts.  Use it at	your own risk.	Better
	       yet, don't use it at all.

       grep(EXPR,LIST)
	       Evaluates EXPR for each element of LIST (locally	setting	$_  to
	       each  element)  and returns the array value consisting of those
	       elements	for which the expression  evaluated  to	 true.	 In  a
	       scalar  context,	returns	the number of times the	expression was
	       true.

		    @foo = grep(!/^#/, @bar);	 # weed	out comments

	       Note that, since	$_ is a	reference into the array value,	it can
	       be  used	 to  modify  the elements of the array.	 While this is
	       useful and supported, it	can cause bizarre results if the  LIST
	       is not a	named array.

       hex(EXPR)

       hex EXPR
	       Returns the decimal value of EXPR interpreted as	an hex string.
	       (To interpret strings that might	start with 0 or	0x see oct().)
	       If EXPR is omitted, uses	$_.

       index(STR,SUBSTR,POSITION)

       index(STR,SUBSTR)
	       Returns	the  position of the first occurrence of SUBSTR	in STR
	       at or after POSITION.  If POSITION is omitted, starts searching
	       from the	beginning of the string.  The return value is based at
	       0, or whatever you've set the $[	variable to.  If the substring
	       is not found, returns one less than the base, ordinarily	-1.

       int(EXPR)

       int EXPR
	       Returns	the integer portion of EXPR.  If EXPR is omitted, uses
	       $_.

       ioctl(FILEHANDLE,FUNCTION,SCALAR)
	       Implements the ioctl(2) function.  You'll probably have to say

		    require "ioctl.ph";	# probably /usr/local/lib/perl/ioctl.ph

	       first to	get the	correct	 function  definitions.	  If  ioctl.ph
	       doesn't	exist  or  doesn't have	the correct definitions	you'll
	       have to roll your own, based on your C  header  files  such  as
	       <sys/ioctl.h>.	(There is a perl script	called h2ph that comes
	       with the	perl kit which may help	you in this.)  SCALAR will  be
	       read and/or written depending on	the FUNCTION--a	pointer	to the
	       string value of SCALAR will be passed as	the third argument  of
	       the actual ioctl	call.  (If SCALAR has no string	value but does
	       have a numeric value, that value	will be	passed rather  than  a
	       pointer to the string value.  To	guarantee this to be true, add
	       a 0 to the scalar before	using it.)  The	 pack()	 and  unpack()
	       functions  are useful for manipulating the values of structures
	       used by ioctl().	 The following example sets the	erase  charac-
	       ter to DEL.

		    require 'ioctl.ph';
		    $sgttyb_t =	"ccccs";	  # 4 chars and	a short
		    if (ioctl(STDIN,$TIOCGETP,$sgttyb))	{
			 @ary =	unpack($sgttyb_t,$sgttyb);
			 $ary[2] = 127;
			 $sgttyb = pack($sgttyb_t,@ary);
			 ioctl(STDIN,$TIOCSETP,$sgttyb)
			      || die "Can't ioctl: $!";
		    }

	       The return value	of ioctl (and fcntl) is	as follows:

		    if OS returns:	     perl returns:
		      -1		       undefined value
		      0			       string "0 but true"
		      anything else	       that number

	       Thus perl returns true on success and false on failure, yet you
	       can still easily	determine the actual  value  returned  by  the
	       operating system:

		    ($retval = ioctl(...)) || ($retval = -1);
		    printf "System returned %d\n", $retval;

       join(EXPR,LIST)

       join(EXPR,ARRAY)
	       Joins  the  separate  strings  of  LIST	or ARRAY into a	single
	       string with fields separated by the value of EXPR, and  returns
	       the string.  Example:

	       $_ = join(':',
			 $login,$passwd,$uid,$gid,$gcos,$home,$shell);

	       See split.

       keys(ASSOC_ARRAY)

       keys ASSOC_ARRAY
	       Returns	a normal array consisting of all the keys of the named
	       associative array.  The keys are	returned in an apparently ran-
	       dom  order,  but	it is the same order as	either the values() or
	       each() function produces	(given that the	associative array  has
	       not  been  modified).   Here  is	 yet another way to print your
	       environment:

		    @keys = keys %ENV;
		    @values = values %ENV;
		    while ($#keys >= 0)	{
			 print pop(@keys), '=',	pop(@values), "\n";
		    }

	       or how about sorted by key:

		    foreach $key (sort(keys %ENV)) {
			 print $key, '=', $ENV{$key}, "\n";
		    }

       kill(LIST)

       kill LIST
	       Sends a signal to a list	of processes.  The  first  element  of
	       the  list  must	be  the	signal to send.	 Returns the number of
	       processes successfully signaled.

		    $cnt = kill	1, $child1, $child2;
		    kill 9, @goners;

	       If the signal is	negative, kills	process	groups instead of pro-
	       cesses.	(On System V, a	negative process number	will also kill
	       process groups, but that's not portable.)  You may use a	signal
	       name in quotes.

       last LABEL

       last    The  last  command is like the break statement in C (as used in
	       loops); it immediately exits the	 loop  in  question.   If  the
	       LABEL is	omitted, the command refers to the innermost enclosing
	       loop.  The continue block, if any, is not executed:

		    line: while	(<STDIN>) {
			 last line if /^$/;  # exit when done with header
			 ...
		    }

       length(EXPR)

       length EXPR
	       Returns the length in characters	of the value of	EXPR.  If EXPR
	       is omitted, returns length of $_.

       link(OLDFILE,NEWFILE)
	       Creates	a  new filename	linked to the old filename.  Returns 1
	       for success, 0 otherwise.

       listen(SOCKET,QUEUESIZE)
	       Does the	same thing that	the listen system call does.   Returns
	       true  if	it succeeded, false otherwise.	See example in section
	       on Interprocess Communication.

       local(LIST)
	       Declares	the listed variables to	 be  local  to	the  enclosing
	       block,  subroutine, eval	or "do".  All the listed elements must
	       be legal	lvalues.  This operator	works by  saving  the  current
	       values of those variables in LIST on a hidden stack and restor-
	       ing them	upon exiting the  block,  subroutine  or  eval.	  This
	       means  that  called  subroutines	 can  also reference the local
	       variable, but not the global one.  The LIST may be assigned  to
	       if  desired,  which  allows  you	to initialize your local vari-
	       ables.  (If no initializer is given for a particular  variable,
	       it  is created with an undefined	value.)	 Commonly this is used
	       to name the parameters to a subroutine.	Examples:

		    sub	RANGEVAL {
			 local($min, $max, $thunk) = @_;
			 local($result)	= '';
			 local($i);

			 # Presumably $thunk makes reference to	$i

			 for ($i = $min; $i < $max; $i++) {
			      $result .= eval $thunk;
			 }

			 $result;
		    }

		    if ($sw eq '-v') {
			# init local array with	global array
			local(@ARGV) = @ARGV;
			unshift(@ARGV,'echo');
			system @ARGV;
		    }
		    # @ARGV restored

		    # temporarily add to digits	associative array
		    if ($base12) {
			 # (NOTE: not claiming this is efficient!)
			 local(%digits)	= (%digits,'t',10,'e',11);
			 do parse_num();
		    }

	       Note that local() is a run-time command,	and so	gets  executed
	       every  time  through  a	loop, using up more stack storage each
	       time until it's all released at once when the loop is exited.

       localtime(EXPR)

       localtime EXPR
	       Converts	a time as returned by the time function	to a 9-element
	       array with the time analyzed for	the local timezone.  Typically
	       used as follows:

	       ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
					     localtime(time);

	       All array elements are numeric, and  come  straight  out	 of  a
	       struct  tm.   In	 particular this means that $mon has the range
	       0..11 and $wday has the range 0..6.  If EXPR is	omitted,  does
	       localtime(time).

       log(EXPR)

       log EXPR
	       Returns	logarithm  (base  e)  of  EXPR.	  If  EXPR is omitted,
	       returns log of $_.

       lstat(FILEHANDLE)

       lstat FILEHANDLE

       lstat(EXPR)

       lstat SCALARVARIABLE
	       Does the	same thing as the stat() function, but	stats  a  sym-
	       bolic link instead of the file the symbolic link	points to.  If
	       symbolic	links are unimplemented	on your	system,	a normal  stat
	       is done.

       m/PATTERN/gio

       /PATTERN/gio
	       Searches	 a string for a	pattern	match, and returns true	(1) or
	       false ('').  If no string is specified via the =~ or !~	opera-
	       tor,  the $_ string is searched.	 (The string specified with =~
	       need not	be an lvalue--it may be	the result  of	an  expression
	       evaluation,  but	 remember  the	=~ binds rather	tightly.)  See
	       also the	section	on regular expressions.

	       If / is the delimiter then the initial 'm' is  optional.	  With
	       the  'm'	you can	use any	pair of	non-alphanumeric characters as
	       delimiters.  This is particularly useful	for matching Unix path
	       names  that contain '/'.	 If the	final delimiter	is followed by
	       the optional letter 'i',	the matching is	done in	a  case-insen-
	       sitive  manner.	PATTERN	may contain references to scalar vari-
	       ables, which will be interpolated (and the pattern  recompiled)
	       every  time the pattern search is evaluated.  (Note that	$) and
	       $| may not be interpolated because they look like end-of-string
	       tests.)	 If  you want such a pattern to	be compiled only once,
	       add an "o" after	the trailing delimiter.	 This avoids expensive
	       run-time	 recompilations,  and is useful	when the value you are
	       interpolating won't change over the life	of the script.	If the
	       PATTERN	evaluates to a null string, the	most recent successful
	       regular expression is used instead.

	       If used in a context that requires an array  value,  a  pattern
	       match returns an	array consisting of the	subexpressions matched
	       by the parentheses in the pattern, i.e. ($1,  $2,  $3...).   It
	       does  NOT  actually  set	$1, $2,	etc. in	this case, nor does it
	       set $+, $`, $& or $'.  If the match  fails,  a  null  array  is
	       returned.   If  the match succeeds, but there were no parenthe-
	       ses, an array value of (1) is returned.

	       Examples:

		   open(tty, '/dev/tty');
		   <tty> =~ /^y/i && do	foo();	  # do foo if desired

		   if (/Version: *([0-9.]*)/) {	$version = $1; }

		   next	if m#^/usr/spool/uucp#;

		   # poor man's	grep
		   $arg	= shift;
		   while (<>) {
			print if /$arg/o;    # compile only once
		   }

		   if (($F1, $F2, $Etc)	= ($foo	=~ /^(\S+)\s+(\S+)\s*(.*)/))

	       This last example splits	$foo into the first two	words and  the
	       remainder  of  the line,	and assigns those three	fields to $F1,
	       $F2 and $Etc.  The conditional is true if  any  variables  were
	       assigned, i.e. if the pattern matched.

	       The  "g"	 modifier  specifies global pattern matching--that is,
	       matching	as many	times as possible within the string.   How  it
	       behaves	depends	 on  the  context.   In	 an  array context, it
	       returns a list of all the substrings matched by all the	paren-
	       theses in the regular expression.  If there are no parentheses,
	       it returns a list of all	the matched strings, as	if there  were
	       parentheses  around the whole pattern.  In a scalar context, it
	       iterates	through	 the  string,  returning  TRUE	each  time  it
	       matches,	and FALSE when it eventually runs out of matches.  (In
	       other words, it remembers where	it  left  off  last  time  and
	       restarts	 the search at that point.)  It	presumes that you have
	       not modified the	string since the last  match.	Modifying  the
	       string  between matches may result in undefined behavior.  (You
	       can actually get	away with in-place modifications via  substr()
	       that  do	 not  change the length	of the entire string.  In gen-
	       eral, however, you should be using  s///g  for  such  modifica-
	       tions.)	Examples:

		    # array context
		    ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);

		    # scalar context
		    $/ = ""; $*	= 1;
		    while ($paragraph =	<>) {
			while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
			 $sentences++;
			}
		    }
		    print "$sentences\n";

       mkdir(FILENAME,MODE)
	       Creates	the  directory specified by FILENAME, with permissions
	       specified by MODE (as modified by umask).  If  it  succeeds  it
	       returns 1, otherwise it returns 0 and sets $! (errno).

       msgctl(ID,CMD,ARG)
	       Calls  the  System V IPC	function msgctl.  If CMD is &IPC_STAT,
	       then ARG	must be	 a  variable  which  will  hold	 the  returned
	       msqid_ds	 structure.   Returns  like ioctl: the undefined value
	       for error, "0 but true" for zero, or the	 actual	 return	 value
	       otherwise.

       msgget(KEY,FLAGS)
	       Calls  the  System  V IPC function msgget.  Returns the message
	       queue id, or the	undefined value	if there is an error.

       msgsnd(ID,MSG,FLAGS)
	       Calls the System	V IPC function msgsnd to send the message  MSG
	       to  the message queue ID.  MSG must begin with the long integer
	       message type, which  may	 be  created  with  pack("L",  $type).
	       Returns true if successful, or false if there is	an error.

       msgrcv(ID,VAR,SIZE,TYPE,FLAGS)
	       Calls  the  System  V  IPC function msgrcv to receive a message
	       from message queue ID into variable VAR with a maximum  message
	       size  of	SIZE.  Note that if a message is received, the message
	       type will be the	first thing in VAR, and	the maximum length  of
	       VAR is SIZE plus	the size of the	message	type.  Returns true if
	       successful, or false if there is	an error.

       next LABEL

       next    The next	command	is like	the continue statement in C; it	starts
	       the next	iteration of the loop:

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

	       Note that if there were a continue block	on the above, it would
	       get executed even on discarded lines.  If the LABEL is omitted,
	       the command refers to the innermost enclosing loop.

       oct(EXPR)

       oct EXPR
	       Returns	the  decimal  value  of	 EXPR  interpreted as an octal
	       string.	(If EXPR happens to start off with 0x,	interprets  it
	       as  a  hex string instead.)  The	following will handle decimal,
	       octal and hex in	the standard notation:

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

	       If EXPR is omitted, uses	$_.

       open(FILEHANDLE,EXPR)

       open(FILEHANDLE)

       open FILEHANDLE
	       Opens the file whose filename is	given by EXPR, and  associates
	       it  with	FILEHANDLE.  If	FILEHANDLE is an expression, its value
	       is used as the name of the real filehandle wanted.  If EXPR  is
	       omitted,	the scalar variable of the same	name as	the FILEHANDLE
	       contains	the filename.  If the  filename	 begins	 with  "<"  or
	       nothing,	 the file is opened for	input.	If the filename	begins
	       with ">", the file is  opened  for  output.   If	 the  filename
	       begins  with  ">>", the file is opened for appending.  (You can
	       put a '+' in front of the '>' or	'<' to indicate	that you  want
	       both  read  and	write  access  to  the file.)  If the filename
	       begins with "|",	the filename is	interpreted as	a  command  to
	       which  output  is  to be	piped, and if the filename ends	with a
	       "|", the	filename is interpreted	as command which  pipes	 input
	       to  us.	 (You  may  not	 have a	command	that pipes both	in and
	       out.)  Opening '-' opens	STDIN and opening '>-'	opens  STDOUT.
	       Open  returns non-zero upon success, the	undefined value	other-
	       wise.  If the open involved a pipe, the return value happens to
	       be the pid of the subprocess.  Examples:

		    $article = 100;
		    open article || die	"Can't find article $article: $!\n";
		    while (<article>) {...

		    open(LOG, '>>/usr/spool/news/twitlog');
					# (log is reserved)

		    open(article, "caesar <$article |");
					# decrypt article

		    open(extract, "|sort >/tmp/Tmp$$");
					# $$ is	our process#

		    # process argument list of files along with	any includes

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

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

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

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

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

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

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

		    close(STDOUT);
		    close(STDERR);

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

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

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

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

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

	       Explicitly  closing  any	 piped	filehandle  causes  the	parent
	       process to wait for the child to	finish,	and returns the	status
	       value  in  $?.	Note:  on  any	operation which	may do a fork,
	       unflushed buffers remain	unflushed  in  both  processes,	 which
	       means you may need to set $| to avoid duplicate output.

	       The  filename  that  is	passed	to  open will have leading and
	       trailing	whitespace deleted.  In	order  to  open	 a  file  with
	       arbitrary weird characters in it, it's necessary	to protect any
	       leading and trailing whitespace thusly:

		       $file =~	s#^(\s)#./$1#;
		       open(FOO, "< $file\0");

       opendir(DIRHANDLE,EXPR)
	       Opens a directory  named	 EXPR  for  processing	by  readdir(),
	       telldir(), seekdir(), rewinddir() and closedir().  Returns true
	       if successful.  DIRHANDLEs have their  own  namespace  separate
	       from FILEHANDLEs.

       ord(EXPR)

       ord EXPR
	       Returns the numeric ascii value of the first character of EXPR.
	       If EXPR is omitted, uses	$_.

       pack(TEMPLATE,LIST)
	       Takes an	array or list of values	and packs  it  into  a	binary
	       structure,  returning the string	containing the structure.  The
	       TEMPLATE	is a sequence of characters that give  the  order  and
	       type of values, as follows:

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

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

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

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

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

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

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

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

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

		    sub	bintodec {
			unpack("N", pack("B32",	substr("0" x 32	. shift, -32)));
		    }
	       The  same  template  may	 generally  also be used in the	unpack
	       function.

       pipe(READHANDLE,WRITEHANDLE)
	       Opens a pair of connected pipes like the	 corresponding	system
	       call.  Note that	if you set up a	loop of	piped processes, dead-
	       lock can	occur unless you are very careful.  In addition,  note
	       that  perl's  pipes use stdio buffering,	so you may need	to set
	       $| to flush your	WRITEHANDLE after each command,	 depending  on
	       the application.	 [Requires version 3.0 patchlevel 9.]

       pop(ARRAY)

       pop ARRAY
	       Pops  and  returns  the last value of the array,	shortening the
	       array by	1.  Has	the same effect	as

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

	       If there	are no elements	in the array,  returns	the  undefined
	       value.

       print(FILEHANDLE	LIST)

       print(LIST)

       print FILEHANDLE	LIST

       print LIST

       print   Prints  a string	or a comma-separated list of strings.  Returns
	       non-zero	if successful.	FILEHANDLE may be  a  scalar  variable
	       name, in	which case the variable	contains the name of the file-
	       handle, thus introducing	one level of indirection.   (NOTE:  If
	       FILEHANDLE  is  a variable and the next token is	a term,	it may
	       be misinterpreted as an operator	unless you interpose  a	 +  or
	       put  parens  around  the	arguments.)  If	FILEHANDLE is omitted,
	       prints by default to standard output (or	to the	last  selected
	       output channel--see select()).  If LIST is also omitted,	prints
	       $_ to STDOUT.  To set the default output	channel	 to  something
	       other than STDOUT use the select	operation.  Note that, because
	       print takes a LIST, anything in the LIST	 is  evaluated	in  an
	       array  context,	and any	subroutine that	you call will have one
	       or more of its expressions evaluated in an array	context.  Also
	       be  careful  not	to follow the print keyword with a left	paren-
	       thesis unless you want the corresponding	right  parenthesis  to
	       terminate  the  arguments  to  the  print--interpose a +	or put
	       parens around all the arguments.

       printf(FILEHANDLE LIST)

       printf(LIST)

       printf FILEHANDLE LIST

       printf LIST
	       Equivalent to a "print FILEHANDLE sprintf(LIST)".

       push(ARRAY,LIST)
	       Treats ARRAY (@ is optional) as a stack,	and pushes the	values
	       of  LIST	 onto the end of ARRAY.	 The length of ARRAY increases
	       by the length of	LIST.  Has the same effect as

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

	       but is more efficient.

       q/STRING/

       qq/STRING/

       qx/STRING/
	       These are not really functions, but simply syntactic  sugar  to
	       let you avoid putting too many backslashes into quoted strings.
	       The q operator is a generalized single quote, and the qq	opera-
	       tor  a generalized double quote.	 The qx	operator is a general-
	       ized backquote.	Any non-alphanumeric delimiter can be used  in
	       place  of /, including newline.	If the delimiter is an opening
	       bracket or parenthesis, the final delimiter will	be the	corre-
	       sponding	closing	bracket	or parenthesis.	 (Embedded occurrences
	       of the closing bracket need to be backslashed as	usual.)	 Exam-
	       ples:

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

       rand(EXPR)

       rand EXPR

       rand    Returns	a  random fractional number between 0 and the value of
	       EXPR.  (EXPR should be positive.)  If EXPR is omitted,  returns
	       a value between 0 and 1.	 See also srand().

       read(FILEHANDLE,SCALAR,LENGTH,OFFSET)

       read(FILEHANDLE,SCALAR,LENGTH)
	       Attempts	to read	LENGTH bytes of	data into variable SCALAR from
	       the specified FILEHANDLE.  Returns the number of	bytes actually
	       read,  or undef if there	was an error.  SCALAR will be grown or
	       shrunk to the length actually read.  An OFFSET may be specified
	       to  place  the read data	at some	other place than the beginning
	       of the string.  This call is actually implemented in  terms  of
	       stdio's	fread  call.  To get a true read system	call, see sys-
	       read.

       readdir(DIRHANDLE)

       readdir DIRHANDLE
	       Returns the next	directory entry	 for  a	 directory  opened  by
	       opendir().   If	used in	an array context, returns all the rest
	       of the entries in the directory.	 If there are no more entries,
	       returns	an  undefined value in a scalar	context	or a null list
	       in an array context.

       readlink(EXPR)

       readlink	EXPR
	       Returns the value of a symbolic link,  if  symbolic  links  are
	       implemented.   If  not,	gives a	fatal error.  If there is some
	       system error, returns the undefined value and sets $!  (errno).
	       If EXPR is omitted, uses	$_.

       recv(SOCKET,SCALAR,LEN,FLAGS)
	       Receives	 a  message  on	 a socket.  Attempts to	receive	LENGTH
	       bytes of	data into variable SCALAR from	the  specified	SOCKET
	       filehandle.   Returns  the  address of the sender, or the unde-
	       fined value if there's an  error.   SCALAR  will	 be  grown  or
	       shrunk  to  the	length actually	read.  Takes the same flags as
	       the system call of the same name.

       redo LABEL

       redo    The redo	command	restarts the loop block	without	evaluating the
	       conditional  again.   The  continue  block, if any, is not exe-
	       cuted.  If the LABEL is omitted,	 the  command  refers  to  the
	       innermost  enclosing  loop.   This  command is normally used by
	       programs	that want to lie to themselves	about  what  was  just
	       input:

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

       rename(OLDNAME,NEWNAME)
	       Changes	the  name  of a	file.  Returns 1 for success, 0	other-
	       wise.  Will not work across filesystem boundaries.

       require(EXPR)

       require EXPR

       require Includes	the library file specified by EXPR, or by $_  if  EXPR
	       is  not	supplied.  Has semantics similar to the	following sub-
	       routine:

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

	       Note that the file will not be included twice  under  the  same
	       specified  name.	  The file must	return true as the last	state-
	       ment to indicate	successful  execution  of  any	initialization
	       code,  so  it's	customary  to end such a file with "1;"	unless
	       you're sure it'll return	true otherwise.

       reset(EXPR)

       reset EXPR

       reset   Generally used in a continue block at the  end  of  a  loop  to
	       clear  variables	and reset ?? searches so that they work	again.
	       The expression is interpreted as	a list	of  single  characters
	       (hyphens	 allowed for ranges).  All variables and arrays	begin-
	       ning with one of	those letters  are  reset  to  their  pristine
	       state.  If the expression is omitted, one-match searches	(?pat-
	       tern?) are reset	to match  again.   Only	 resets	 variables  or
	       searches	in the current package.	 Always	returns	1.  Examples:

		   reset 'X';	   # reset all X variables
		   reset 'a-z';	   # reset lower case variables
		   reset;	   # just reset	?? searches

	       Note:  resetting	"A-Z" is not recommended since you'll wipe out
	       your ARGV and ENV arrays.

	       The use of reset	on dbm associative arrays does not change  the
	       dbm file.  (It does, however, flush any entries cached by perl,
	       which may be useful if you are  sharing	the  dbm  file.	  Then
	       again, maybe not.)

       return LIST
	       Returns from a subroutine with the value	specified.  (Note that
	       a subroutine can	automatically return the  value	 of  the  last
	       expression  evaluated.	That's the preferred method--use of an
	       explicit	return is a bit	slower.)

       reverse(LIST)

       reverse LIST
	       In an array context, returns an array value consisting  of  the
	       elements	 of  LIST in the opposite order.  In a scalar context,
	       returns a string	value consisting of the	 bytes	of  the	 first
	       element of LIST in the opposite order.

       rewinddir(DIRHANDLE)

       rewinddir DIRHANDLE
	       Sets the	current	position to the	beginning of the directory for
	       the readdir() routine on	DIRHANDLE.

       rindex(STR,SUBSTR,POSITION)

       rindex(STR,SUBSTR)
	       Works just like index except that it returns  the  position  of
	       the  LAST  occurrence  of SUBSTR	in STR.	 If POSITION is	speci-
	       fied, returns the last occurrence at or before that position.

       rmdir(FILENAME)

       rmdir FILENAME
	       Deletes the directory specified by FILENAME if it is empty.  If
	       it  succeeds  it	 returns 1, otherwise it returns 0 and sets $!
	       (errno).	 If FILENAME is	omitted, uses $_.

       s/PATTERN/REPLACEMENT/gieo
	       Searches	a string for a pattern,	and if	found,	replaces  that
	       pattern	with  the  replacement	text and returns the number of
	       substitutions made.  Otherwise it returns false (0).   The  "g"
	       is  optional, and if present, indicates that all	occurrences of
	       the pattern are to be replaced.	The "i"	is also	optional,  and
	       if  present,  indicates	that matching is to be done in a case-
	       insensitive manner.  The	 "e"  is  likewise  optional,  and  if
	       present,	 indicates that	the replacement	string is to be	evalu-
	       ated as an expression  rather  than  just  as  a	 double-quoted
	       string.	  Any	non-alphanumeric  delimiter  may  replace  the
	       slashes;	if single quotes are used, no interpretation  is  done
	       on  the replacement string (the e modifier overrides this, how-
	       ever); if backquotes are	used, the replacement string is	a com-
	       mand  to	 execute  whose	 output	 will  be  used	 as the	actual
	       replacement text.  If the PATTERN is  delimited	by  bracketing
	       quotes,	the  REPLACEMENT has its own pair of quotes, which may
	       or  may	not  be	 bracketing  quotes,  e.g.    s(foo)(bar)   or
	       s<foo>/bar/.  If	no string is specified via the =~ or !~	opera-
	       tor, the	$_ string is searched and modified.  (The string spec-
	       ified  with  =~ must be a scalar	variable, an array element, or
	       an assignment to	one of those, i.e. an lvalue.)	If the pattern
	       contains	 a $ that looks	like a variable	rather than an end-of-
	       string test, the	variable will be interpolated into the pattern
	       at  run-time.   If  you only want the pattern compiled once the
	       first time the variable is interpolated,	add an "o" at the end.
	       If the PATTERN evaluates	to a null string, the most recent suc-
	       cessful regular expression is used instead.  See	also the  sec-
	       tion on regular expressions.  Examples:

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

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

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

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

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

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

	       (Note  the use of $ instead of \	in the last example.  See sec-
	       tion on regular expressions.)

       scalar(EXPR)
	       Forces EXPR to be interpreted in	a scalar context  and  returns
	       the value of EXPR.

       seek(FILEHANDLE,POSITION,WHENCE)
	       Randomly	 positions  the	file pointer for FILEHANDLE, just like
	       the fseek() call	of stdio.  FILEHANDLE  may  be	an  expression
	       whose  value  gives the name of the filehandle.	Returns	1 upon
	       success,	0 otherwise.

       seekdir(DIRHANDLE,POS)
	       Sets the	current	position for the readdir() routine on  DIRHAN-
	       DLE.   POS must be a value returned by telldir().  Has the same
	       caveats about possible directory	compaction as the  correspond-
	       ing system library routine.

       select(FILEHANDLE)

       select  Returns	the  currently	selected filehandle.  Sets the current
	       default filehandle for output, if FILEHANDLE is supplied.  This
	       has two effects:	first, a write or a print without a filehandle
	       will default to this FILEHANDLE.	 Second, references  to	 vari-
	       ables related to	output will refer to this output channel.  For
	       example,	if you have to set the top of  form  format  for  more
	       than one	output channel,	you might do the following:

		    select(REPORT1);
		    $^ = 'report1_top';
		    select(REPORT2);
		    $^ = 'report2_top';

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

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

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

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

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

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

	       The usual idiom is:

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

	       or to block until something becomes ready:

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

	       Any  of the bitmasks can	also be	undef.	The timeout, if	speci-
	       fied, is	in seconds, which may be fractional.   NOTE:  not  all
	       implementations	are  capable  of  returning the	$timeleft.  If
	       not, they always	return $timeleft equal to the supplied	$time-
	       out.

       semctl(ID,SEMNUM,CMD,ARG)
	       Calls the System	V IPC function semctl.	If CMD is &IPC_STAT or
	       &GETALL,	then ARG must  be  a  variable	which  will  hold  the
	       returned	 semid_ds structure or semaphore value array.  Returns
	       like ioctl: the undefined value for error,  "0  but  true"  for
	       zero, or	the actual return value	otherwise.

       semget(KEY,NSEMS,SIZE,FLAGS)
	       Calls  the System V IPC function	semget.	 Returns the semaphore
	       id, or the undefined value if there is an error.

       semop(KEY,OPSTRING)
	       Calls the System	V IPC  function	 semop	to  perform  semaphore
	       operations  such	 as signaling and waiting.  OPSTRING must be a
	       packed array of semop structures.  Each semop structure can  be
	       generated  with	'pack("sss", $semnum, $semop, $semflag)'.  The
	       number of semaphore operations is  implied  by  the  length  of
	       OPSTRING.   Returns true	if successful, or false	if there is an
	       error.  As an example, the following code  waits	 on  semaphore
	       $semnum of semaphore id $semid:

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

	       To signal the semaphore,	replace	"-1" with "1".

       send(SOCKET,MSG,FLAGS,TO)

       send(SOCKET,MSG,FLAGS)
	       Sends  a	message	on a socket.  Takes the	same flags as the sys-
	       tem call	of the same name.  On  unconnected  sockets  you  must
	       specify	a destination to send TO.  Returns the number of char-
	       acters sent, or the undefined value if there is an error.

       setpgrp(PID,PGRP)
	       Sets the	current	process	group for the specified	PID, 0 for the
	       current	process.   Will	 produce  a  fatal  error if used on a
	       machine that doesn't implement setpgrp(2).

       setpriority(WHICH,WHO,PRIORITY)
	       Sets the	current	priority for a process,	a process group, or  a
	       user.   (See  setpriority(2).)	Will  produce a	fatal error if
	       used on a machine that doesn't implement	setpriority(2).

       setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)
	       Sets the	socket option requested.  Returns undefined  if	 there
	       is  an  error.	OPTVAL	may be specified as undef if you don't
	       want to pass an argument.

       shift(ARRAY)

       shift ARRAY

       shift   Shifts the first	value of the array off and returns it,	short-
	       ening  the array	by 1 and moving	everything down.  If there are
	       no elements in the array,  returns  the	undefined  value.   If
	       ARRAY  is  omitted, shifts the @ARGV array in the main program,
	       and the @_ array	in subroutines.	  (This	 is  determined	 lexi-
	       cally.)	 See  also  unshift(),	push() and pop().  Shift() and
	       unshift() do the	same thing to the left end of  an  array  that
	       push() and pop()	do to the right	end.

       shmctl(ID,CMD,ARG)
	       Calls  the  System V IPC	function shmctl.  If CMD is &IPC_STAT,
	       then ARG	must be	 a  variable  which  will  hold	 the  returned
	       shmid_ds	 structure.   Returns  like ioctl: the undefined value
	       for error, "0 but true" for zero, or the	 actual	 return	 value
	       otherwise.

       shmget(KEY,SIZE,FLAGS)
	       Calls  the  System  V  IPC function shmget.  Returns the	shared
	       memory segment id, or the undefined value if there is an	error.

       shmread(ID,VAR,POS,SIZE)

       shmwrite(ID,STRING,POS,SIZE)
	       Reads or	writes the System V shared memory segment ID  starting
	       at  position  POS  for  size  SIZE  by attaching	to it, copying
	       in/out, and detaching from it.  When reading,  VAR  must	 be  a
	       variable	 which	will  hold  the	 data  read.  When writing, if
	       STRING is too long, only	SIZE bytes are used; if	STRING is  too
	       short,  nulls  are written to fill out SIZE bytes.  Return true
	       if successful, or false if there	is an error.

       shutdown(SOCKET,HOW)
	       Shuts down a socket connection in the manner indicated by  HOW,
	       which  has the same interpretation as in	the system call	of the
	       same name.

       sin(EXPR)

       sin EXPR
	       Returns the sine	of EXPR	(expressed in radians).	  If  EXPR  is
	       omitted,	returns	sine of	$_.

       sleep(EXPR)

       sleep EXPR

       sleep   Causes  the  script to sleep for	EXPR seconds, or forever if no
	       EXPR.  May be interrupted by sending  the  process  a  SIGALRM.
	       Returns	the  number  of	 seconds actually slept.  You probably
	       cannot mix alarm() and sleep() calls, since  sleep()  is	 often
	       implemented using alarm().

       socket(SOCKET,DOMAIN,TYPE,PROTOCOL)
	       Opens  a	 socket	of the specified kind and attaches it to file-
	       handle SOCKET.  DOMAIN, TYPE and	 PROTOCOL  are	specified  the
	       same  as	for the	system call of the same	name.  You may need to
	       run h2ph	on sys/socket.h	to get the proper values  handy	 in  a
	       perl library file.  Return true if successful.  See the example
	       in the section on Interprocess Communication.

       socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)
	       Creates an unnamed pair of sockets in the specified domain,  of
	       the  specified  type.   DOMAIN, TYPE and	PROTOCOL are specified
	       the same	as for the system call of the same name.  If  unimple-
	       mented, yields a	fatal error.  Return true if successful.

       sort(SUBROUTINE LIST)

       sort(LIST)

       sort SUBROUTINE LIST

       sort BLOCK LIST

       sort LIST
	       Sorts the LIST and returns the sorted array value.  Nonexistent
	       values of arrays	are stripped out.  If SUBROUTINE or  BLOCK  is
	       omitted,	sorts in standard string comparison order.  If SUBROU-
	       TINE is specified, gives	the name of a subroutine that  returns
	       an integer less than, equal to, or greater than 0, depending on
	       how the elements	of the array are to be ordered.	 (The <=>  and
	       cmp  operators are extremely useful in such routines.)  SUBROU-
	       TINE may	be a scalar variable name, in  which  case  the	 value
	       provides	the name of the	subroutine to use.  In place of	a SUB-
	       ROUTINE name, you can provide a BLOCK as	an anonymous,  in-line
	       sort subroutine.

	       In the interests	of efficiency the normal calling code for sub-
	       routines	is bypassed, with the following	effects:  the  subrou-
	       tine may	not be a recursive subroutine, and the two elements to
	       be compared are passed into the subroutine not via @_ but as $a
	       and  $b	(see  example below).  They are	passed by reference so
	       don't modify $a and $b.

	       Examples:

		    # sort lexically
		    @articles =	sort @files;

		    # same thing, but with explicit sort routine
		    @articles =	sort {$a cmp $b} @files;

		    # same thing in reversed order
		    @articles =	sort {$b cmp $a} @files;

		    # sort numerically ascending
		    @articles =	sort {$a <=> $b} @files;

		    # sort numerically descending
		    @articles =	sort {$b <=> $a} @files;

		    # sort using explicit subroutine name
		    sub	byage {
			$age{$a} <=> $age{$b};	  # presuming integers
		    }
		    @sortedclass = sort	byage @class;

		    sub	reverse	{ $b cmp $a; }
		    @harry = ('dog','cat','x','Cain','Abel');
		    @george = ('gone','chased','yz','Punished','Axed');
		    print sort @harry;
			 # prints AbelCaincatdogx
		    print sort reverse @harry;
			 # prints xdogcatCainAbel
		    print sort @george,	'to', @harry;
			 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz

       splice(ARRAY,OFFSET,LENGTH,LIST)

       splice(ARRAY,OFFSET,LENGTH)

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

		    push(@a,$x,$y)		  splice(@a,$#a+1,0,$x,$y)
		    pop(@a)			  splice(@a,-1)
		    shift(@a)			  splice(@a,0,1)
		    unshift(@a,$x,$y)		  splice(@a,0,0,$x,$y)
		    $a[$x] = $y			  splice(@a,$x,1,$y);

	       Example,	assuming array lengths are passed before arrays:

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

       split(/PATTERN/,EXPR,LIMIT)

       split(/PATTERN/,EXPR)

       split(/PATTERN/)

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

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

	       produces	the output 'h:i:t:h:e:r:e'.

	       The LIMIT parameter can be used to partially split a line

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

	       (When assigning to a list, if LIMIT is omitted, perl supplies a
	       LIMIT one larger	than the number	of variables in	the  list,  to
	       avoid  unnecessary  work.   For the list	above LIMIT would have
	       been 4 by default.  In time critical applications  it  behooves
	       you not to split	into more fields than you really need.)

	       If  the PATTERN contains	parentheses, additional	array elements
	       are created from	each matching substring	in the delimiter.

		    split(/([,-])/,"1-10,20");

	       produces	the array value

		    (1,'-',10,',',20)

	       The pattern /PATTERN/ may be replaced  with  an	expression  to
	       specify patterns	that vary at runtime.  (To do runtime compila-
	       tion only once, use /$variable/o.)  As a	special	case, specify-
	       ing  a space (' ') will split on	white space just as split with
	       no arguments does, but leading white space does NOT  produce  a
	       null  first  field.   Thus,  split(' ')	can be used to emulate
	       awk's default behavior, whereas split(/ /)  will	 give  you  as
	       many null initial fields	as there are leading spaces.

	       Example:

		    open(passwd, '/etc/passwd');
		    while (<passwd>) {
			 ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
			      =	split(/:/);
			 ...
		    }

	       (Note  that  $shell above will still have a newline on it.  See
	       chop().)	 See also join.

       sprintf(FORMAT,LIST)
	       Returns a string	formatted by  the  usual  printf  conventions.
	       The * character is not supported.

       sqrt(EXPR)

       sqrt EXPR
	       Return  the  square  root of EXPR.  If EXPR is omitted, returns
	       square root of $_.

       srand(EXPR)

       srand EXPR
	       Sets the	random number seed for the rand	operator.  If EXPR  is
	       omitted,	does srand(time).

       stat(FILEHANDLE)

       stat FILEHANDLE

       stat(EXPR)

       stat SCALARVARIABLE
	       Returns	a  13-element  array giving the	statistics for a file,
	       either the file	opened	via  FILEHANDLE,  or  named  by	 EXPR.
	       Returns	a null list if the stat	fails.	Typically used as fol-
	       lows:

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

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

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

	       (This  only  works  on  machines	for which the device number is
	       negative	under NFS.)

       study(SCALAR)

       study SCALAR

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

	       For example, here is  a	loop  which  inserts  index  producing
	       entries before any line containing a certain pattern:

		    while (<>) {
			 study;
			 print ".IX foo\n" if /\bfoo\b/;
			 print ".IX bar\n" if /\bbar\b/;
			 print ".IX blurfl\n" if /\bblurfl\b/;
			 ...
			 print;
		    }

	       In  searching  for  /\bfoo\b/,  only those locations in $_ that
	       contain 'f' will	be looked at, because 'f' is rarer  than  'o'.
	       In  general,  this  is  a big win except	in pathological	cases.
	       The only	question is whether it saves you  more	time  than  it
	       took to build the linked	list in	the first place.

	       Note  that  if you have to look for strings that	you don't know
	       till runtime, you can build an entire loop as a string and eval
	       that  to	 avoid	recompiling  all  your	patterns all the time.
	       Together	with undefining	 $/  to	 input	entire	files  as  one
	       record,	this  can  be very fast, often faster than specialized
	       programs	like fgrep.  The  following  scans  a  list  of	 files
	       (@files)	for a list of words (@words), and prints out the names
	       of those	files that contain a match:

		    $search = 'while (<>) { study;';
		    foreach $word (@words) {
			$search	.= "++\$seen{\$ARGV} if	/\\b$word\\b/;\n";
		    }
		    $search .= "}";
		    @ARGV = @files;
		    undef $/;
		    eval $search;	# this screams
		    $/ = "\n";		# put back to normal input delim
		    foreach $file (sort	keys(%seen)) {
			print $file, "\n";
		    }

       substr(EXPR,OFFSET,LEN)

       substr(EXPR,OFFSET)
	       Extracts	a substring out	of EXPR	and returns it.	 First charac-
	       ter is at offset	0, or whatever you've set $[ to.  If OFFSET is
	       negative, starts	that far from the end of the string.   If  LEN
	       is  omitted,  returns everything	to the end of the string.  You
	       can use the substr() function as	an lvalue, in which case  EXPR
	       must  be	 an lvalue.  If	you assign something shorter than LEN,
	       the string will shrink, and if you assign something longer than
	       LEN,  the  string  will	grow  to  accommodate it.  To keep the
	       string the same length you may need to pad or chop  your	 value
	       using sprintf().

       symlink(OLDFILE,NEWFILE)
	       Creates a new filename symbolically linked to the old filename.
	       Returns 1 for success, 0	otherwise.  On systems that don't sup-
	       port  symbolic  links,  produces	a fatal	error at run time.  To
	       check for that, use eval:

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

       syscall(LIST)

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

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

       sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)

       sysread(FILEHANDLE,SCALAR,LENGTH)
	       Attempts	to read	LENGTH bytes of	data into variable SCALAR from
	       the  specified  FILEHANDLE,  using the system call read(2).  It
	       bypasses	stdio, so mixing this with other kinds	of  reads  may
	       cause confusion.	 Returns the number of bytes actually read, or
	       undef if	there was an error.  SCALAR will be grown or shrunk to
	       the  length actually read.  An OFFSET may be specified to place
	       the read	data at	some other place than  the  beginning  of  the
	       string.

       system(LIST)

       system LIST
	       Does  exactly  the same thing as	"exec LIST" except that	a fork
	       is done first, and the  parent  process	waits  for  the	 child
	       process	to  complete.	Note  that  argument processing	varies
	       depending on the	number of arguments.  The return value is  the
	       exit  status of the program as returned by the wait() call.  To
	       get the actual exit value divide	by 256.	 See also exec.

       syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)

       syswrite(FILEHANDLE,SCALAR,LENGTH)
	       Attempts	to write LENGTH	bytes of data from variable SCALAR  to
	       the  specified  FILEHANDLE, using the system call write(2).  It
	       bypasses	stdio, so mixing this with prints may cause confusion.
	       Returns the number of bytes actually written, or	undef if there
	       was an error.  An OFFSET	may be specified  to  place  the  read
	       data at some other place	than the beginning of the string.

       tell(FILEHANDLE)

       tell FILEHANDLE

       tell    Returns	the  current file position for FILEHANDLE.  FILEHANDLE
	       may be an expression whose value	gives the name of  the	actual
	       filehandle.   If	 FILEHANDLE  is	omitted, assumes the file last
	       read.

       telldir(DIRHANDLE)

       telldir DIRHANDLE
	       Returns the current  position  of  the  readdir()  routines  on
	       DIRHANDLE.  Value may be	given to seekdir() to access a partic-
	       ular location in	a directory.  Has the same caveats about  pos-
	       sible  directory	compaction as the corresponding	system library
	       routine.

       time    Returns the number of non-leap seconds since 00:00:00 UTC, Jan-
	       uary  1,	 1970.	 Suitable  for	feeding	to gmtime() and	local-
	       time().

       times   Returns a four-element array giving the user and	system	times,
	       in seconds, for this process and	the children of	this process.

		   ($user,$system,$cuser,$csystem) = times;

       tr/SEARCHLIST/REPLACEMENTLIST/cds

       y/SEARCHLIST/REPLACEMENTLIST/cds
	       Translates  all	occurrences  of	 the  characters  found	in the
	       search list with	the corresponding character in the replacement
	       list.  It returns the number of characters replaced or deleted.
	       If no string is specified via the =~ or	!~  operator,  the  $_
	       string  is translated.  (The string specified with =~ must be a
	       scalar variable,	an array element, or an	assignment to  one  of
	       those,  i.e.  an	lvalue.)  For sed devotees, y is provided as a
	       synonym for tr.	If the SEARCHLIST is delimited	by  bracketing
	       quotes,	the  REPLACEMENTLIST has its own pair of quotes, which
	       may or may not be  bracketing  quotes,  e.g.   tr[A-Z][a-z]  or
	       tr(+-*/)/ABCD/.

	       If the c	modifier is specified, the SEARCHLIST character	set is
	       complemented.  If the d modifier	is specified,  any  characters
	       specified  by  SEARCHLIST that are not found in REPLACEMENTLIST
	       are deleted.  (Note that	this is	slightly  more	flexible  than
	       the  behavior  of  some tr programs, which delete anything they
	       find in the SEARCHLIST, period.)	 If the	s modifier  is	speci-
	       fied,  sequences	of characters that were	translated to the same
	       character are squashed down to 1	instance of the	character.

	       If the d	modifier  was  used,  the  REPLACEMENTLIST  is	always
	       interpreted  exactly  as	specified.  Otherwise, if the REPLACE-
	       MENTLIST	is shorter than	the SEARCHLIST,	the final character is
	       replicated  till	 it is long enough.  If	the REPLACEMENTLIST is
	       null, the SEARCHLIST is replicated.  This latter	is useful  for
	       counting	 characters  in	 a  class,  or for squashing character
	       sequences in a class.

	       Examples:

		   $ARGV[1] =~ y/A-Z/a-z/;   # canonicalize to lower case

		   $cnt	= tr/*/*/;	     # count the stars in $_

		   $cnt	= tr/0-9//;	     # count the digits	in $_

		   tr/a-zA-Z//s;	     # bookkeeper -> bokeper

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

		   y/a-zA-Z/ /cs;	     # change non-alphas to single space

		   tr/\200-\377/\0-\177/;    # delete 8th bit

       truncate(FILEHANDLE,LENGTH)

       truncate(EXPR,LENGTH)
	       Truncates the file opened on FILEHANDLE,	or named by  EXPR,  to
	       the specified length.  Produces a fatal error if	truncate isn't
	       implemented on your system.

       umask(EXPR)

       umask EXPR

       umask   Sets the	umask for the process and returns  the	old  one.   If
	       EXPR is omitted,	merely returns current umask.

       undef(EXPR)

       undef EXPR

       undef   Undefines the value of EXPR, which must be an lvalue.  Use only
	       on a scalar value, an entire array, or a	subroutine name	(using
	       &).  (Undef will	probably not do	what you expect	on most	prede-
	       fined variables or dbm array values.)  Always returns the unde-
	       fined  value.   You can omit the	EXPR, in which case nothing is
	       undefined, but you still	get an undefined value that you	could,
	       for instance, return from a subroutine.	Examples:

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

       unlink(LIST)

       unlink LIST
	       Deletes	a list of files.  Returns the number of	files success-
	       fully deleted.

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

	       Note: unlink will not delete directories	unless you  are	 supe-
	       ruser  and the -U flag is supplied to perl.  Even if these con-
	       ditions are met,	be  warned  that  unlinking  a	directory  can
	       inflict damage on your filesystem.  Use rmdir instead.

       unpack(TEMPLATE,EXPR)
	       Unpack does the reverse of pack:	it takes a string representing
	       a structure and expands it out into an array  value,  returning
	       the  array  value.  (In a scalar	context, it merely returns the
	       first value produced.)  The TEMPLATE has	the same format	as  in
	       the pack	function.  Here's a subroutine that does substring:

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

	       and then	there's

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

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

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

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

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

       utime(LIST)

       utime LIST
	       Changes	the  access  and  modification times on	each file of a
	       list of files.  The first two elements of the list must be  the
	       NUMERICAL   access  and	modification  times,  in  that	order.
	       Returns the number of files successfully	 changed.   The	 inode
	       modification  time  of  each  file  is set to the current time.
	       Example of a "touch" command:

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

       values(ASSOC_ARRAY)

       values ASSOC_ARRAY
	       Returns a normal	array consisting of  all  the  values  of  the
	       named  associative array.  The values are returned in an	appar-
	       ently random order, but it is the  same	order  as  either  the
	       keys() or each()	function would produce on the same array.  See
	       also keys() and each().

       vec(EXPR,OFFSET,BITS)
	       Treats a	string as a vector of unsigned integers,  and  returns
	       the  value of the bitfield specified.  May also be assigned to.
	       BITS must be a power of two from	1 to 32.

	       Vectors created with vec() can also  be	manipulated  with  the
	       logical	operators  |,  & and ^,	which will assume a bit	vector
	       operation is desired when  both	operands  are  strings.	  This
	       interpretation  is  not	enabled	 unless	 there is at least one
	       vec() in	your program, to protect older programs.

	       To transform a bit vector into a	string or  array  of  0's  and
	       1's, use	these:

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

	       If  you	know the exact length in bits, it can be used in place
	       of the *.

       wait    Waits for a child process to terminate and returns the  pid  of
	       the  deceased  process,	or -1 if there are no child processes.
	       The status is returned in $?.

       waitpid(PID,FLAGS)
	       Waits for a particular child process to terminate  and  returns
	       the  pid	 of  the  deceased  process, or	-1 if there is no such
	       child process.  The status is returned in $?.  If you say

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

	       then you	can do a non-blocking  wait  for  any  process.	  Non-
	       blocking	 wait  is only available on machines supporting	either
	       the waitpid (2) or wait4	(2) system  calls.   However,  waiting
	       for a particular	pid with FLAGS of 0 is implemented everywhere.
	       (Perl emulates the system call by remembering the status	values
	       of  processes  that  have exited	but have not been harvested by
	       the Perl	script yet.)

       wantarray
	       Returns true if the context of the currently executing  subrou-
	       tine  is	looking	for an array value.  Returns false if the con-
	       text is looking for a scalar.

		    return wantarray ? () : undef;

       warn(LIST)

       warn LIST
	       Produces	a message on STDERR just like "die", but doesn't exit.

       write(FILEHANDLE)

       write(EXPR)

       write   Writes a	formatted record (possibly multi-line) to  the	speci-
	       fied  file,  using  the	format	associated with	that file.  By
	       default the format for a	file is	the one	having the  same  name
	       is  the filehandle, but the format for the current output chan-
	       nel (see	select)	may be set explicitly by assigning the name of
	       the format to the $~ variable.

	       Top  of	form  processing is handled automatically: if there is
	       insufficient room on the	current	page for the formatted record,
	       the  page is advanced by	writing	a form feed, a special top-of-
	       page format is used to format the new page header, and then the
	       record  is  written.   By default the top-of-page format	is the
	       name of the filehandle with "_TOP"  appended,  but  it  may  be
	       dynamicallly  set to the	format of your choice by assigning the
	       name to the $^ variable while the filehandle is selected.   The
	       number  of  lines  remaining on the current page	is in variable
	       $-, which can be	set to 0 to force a new	page.

	       If FILEHANDLE  is  unspecified,	output	goes  to  the  current
	       default	output	channel, which starts out as STDOUT but	may be
	       changed by the select operator.	If the FILEHANDLE is an	 EXPR,
	       then  the  expression  is evaluated and the resulting string is
	       used to look up the name	of the FILEHANDLE at  run  time.   For
	       more on formats,	see the	section	on formats later on.

	       Note that write is NOT the opposite of read.

       Precedence

       Perl operators have the following associativity and precedence:

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

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

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

       but, because * is higher	precedence than	||:

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

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

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

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

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

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

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

       Also note that

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

       probably	doesn't	do what	you expect at first glance.

       Subroutines

       A subroutine may	be declared as follows:

	   sub NAME BLOCK

       Any arguments passed to the routine  come  in  as  array	 @_,  that  is
       ($_[0], $_[1], ...).  The array @_ is a local array, but	its values are
       references to the actual	scalar parameters.  The	return	value  of  the
       subroutine  is  the  value of the last expression evaluated, and	can be
       either an array value or	a scalar value.	 Alternately, a	return	state-
       ment may	be used	to specify the returned	value and exit the subroutine.
       To create local variables see the local operator.

       A subroutine is called using the	do operator or the & operator.

       Example:

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

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

       Example:

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

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

       Use array assignment to a local list to name your formal	arguments:

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

       This also has the effect	of  turning  call-by-reference	into  call-by-
       value, since the	assignment copies the values.

       Subroutines may be called recursively.  If a subroutine is called using
       the & form, the argument	list is	optional.  If omitted, no @_ array  is
       set up for the subroutine; the @_ array at the time of the call is vis-
       ible to subroutine instead.

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

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

       Passing By Reference

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

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

       Assignment to *name is currently	recommended  only  inside  a  local().
       You can actually	assign to *name	anywhere, but the previous referent of
       *name may be stranded forever.  This may	or may not bother you.

       Note that scalars are already passed by reference, so  you  can	modify
       scalar  arguments  without using	this mechanism by referring explicitly
       to the $_[nnn] in question.  You	can modify  all	 the  elements	of  an
       array by	passing	all the	elements as scalars, but you have to use the *
       mechanism to push, pop or change	the size of an array.  The * mechanism
       will probably be	more efficient in any case.

       Since  a	*name value contains unprintable binary	data, if it is used as
       an argument in a	print, or as a %s argument in a	printf or sprintf,  it
       then has	the value '*name', just	so it prints out pretty.

       Even if you don't want to modify	an array, this mechanism is useful for
       passing multiple	arrays in a single LIST, since normally	the LIST mech-
       anism will merge	all the	array values so	that you can't extract out the
       individual arrays.

       Regular Expressions

       The patterns used in pattern matching are regular expressions  such  as
       those  supplied	in  the	Version	8 regexp routines.  (In	fact, the rou-
       tines are derived from Henry Spencer's freely redistributable  reimple-
       mentation of the	V8 routines.)  In addition, \w matches an alphanumeric
       character (including "_") and \W	a  nonalphanumeric.   Word  boundaries
       may be matched by \b, and non-boundaries	by \B.	A whitespace character
       is matched by \s, non-whitespace	by \S.	A numeric character is matched
       by  \d,	non-numeric by \D.  You	may use	\w, \s and \d within character
       classes.	 Also, \n, \r, \f, \t and \NNN have their  normal  interpreta-
       tions.	Within character classes \b represents backspace rather	than a
       word boundary.  Alternatives may	be separated  by  |.   The  bracketing
       construct  ( ...	) may also be used, in which case \<digit> matches the
       digit'th	substring.  (Outside of	the pattern, always use	$ instead of \
       in  front  of  the  digit.   The	 scope of $<digit> (and	$`, $& and $')
       extends to the end of the enclosing BLOCK or eval  string,  or  to  the
       next  pattern  match  with subexpressions.  The \<digit>	notation some-
       times works outside the current	pattern,  but  should  not  be	relied
       upon.)  You may have as many parentheses	as you wish.  If you have more
       than 9 substrings, the variables	$10, $11, ... refer to the correspond-
       ing  substring.	 Within	the pattern, \10, \11, etc. refer back to sub-
       strings if there	have been at least that	many left  parens  before  the
       backreference.	Otherwise (for backward	compatibility) \10 is the same
       as \010,	a backspace, and \11 the same as \011, a tab.  And so on.  (\1
       through \9 are always backreferences.)

       $+  returns  whatever  the  last	bracket	match matched.	$& returns the
       entire matched string.  ($0 used	to return the same thing, but not  any
       more.)	$`  returns  everything	before the matched string.  $' returns
       everything after	the matched string.  Examples:

	    s/^([^ ]*) *([^ ]*)/$2 $1/;	  # swap first two words

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

       By default, the ^ character is only guaranteed to match at  the	begin-
       ning of the string, the $ character only	at the end (or before the new-
       line at the end)	and perl does certain optimizations with  the  assump-
       tion  that  the string contains only one	line.  The behavior of ^ and $
       on embedded newlines will be inconsistent.  You may, however,  wish  to
       treat a string as a multi-line buffer, such that	the ^ will match after
       any newline within the string, and $ will match before any newline.  At
       the  cost  of  a	 little	 more overhead,	you can	do this	by setting the
       variable	$* to 1.  Setting it back to 0 makes perl revert  to  its  old
       behavior.

       To facilitate multi-line	substitutions, the . character never matches a
       newline (even when $* is	0).  In	particular,  the  following  leaves  a
       newline on the $_ string:

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

       If the newline is unwanted, try one of

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

       Any  item  of a regular expression may be followed with digits in curly
       brackets	of the form {n,m}, where n gives the minimum number  of	 times
       to  match the item and m	gives the maximum.  The	form {n} is equivalent
       to {n,n}	and matches exactly n times.  The form {n,} matches n or  more
       times.	(If a curly bracket occurs in any other	context, it is treated
       as a regular character.)	 The * modifier	is equivalent to {0,},	the  +
       modifier	to {1,}	and the	? modifier to {0,1}.  There is no limit	to the
       size of n or m, but large numbers will chew up more memory.

       You will	note that all backslashed metacharacters in perl are  alphanu-
       meric,  such  as	\b, \w,	\n.  Unlike some other regular expression lan-
       guages, there are no backslashed	symbols	that aren't alphanumeric.   So
       anything	that looks like	\\, \(,	\), \<,	\>, \{,	or \} is always	inter-
       preted as a literal character, not a metacharacter.  This makes it sim-
       ple  to	quote a	string that you	want to	use for	a pattern but that you
       are afraid might	contain	metacharacters.	 Simply	 quote	all  the  non-
       alphanumeric characters:

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

       Formats

       Output  record  formats for use with the	write operator may declared as
       follows:

	   format NAME =
	   FORMLIST
	   .

       If name is omitted, format "STDOUT" is defined.	FORMLIST consists of a
       sequence	of lines, each of which	may be of one of three types:

       1.  A comment.

       2.  A "picture" line giving the format for one output line.

       3.  An argument line supplying values to	plug into a picture line.

       Picture	lines  are  printed  exactly  as they look, except for certain
       fields that substitute values into the line.  Each picture field	starts
       with  either  @	or  ^.	The @ field (not to be confused	with the array
       marker @) is the	normal case; ^	fields	are  used  to  do  rudimentary
       multi-line  text	block filling.	The length of the field	is supplied by
       padding out the field with multiple <, >, or | characters  to  specify,
       respectively,  left  justification,  right justification, or centering.
       As an alternate form of right justification, you	may also use # charac-
       ters  (with  an	optional  .)  to  specify  a numeric field.  (Use of ^
       instead of @ causes the field to	be blanked if undefined.)  If  any  of
       the  values supplied for	these fields contains a	newline, only the text
       up to the newline is printed.  The special field	@*  can	 be  used  for
       printing	multi-line values.  It should appear by	itself on a line.

       The  values  are	 specified on the following line, in the same order as
       the picture fields.  The	values should be separated by commas.

       Picture fields that begin with ^	rather than @ are  treated  specially.
       The value supplied must be a scalar variable name which contains	a text
       string.	Perl puts as much text as it can  into	the  field,  and  then
       chops off the front of the string so that the next time the variable is
       referenced, more	of the text can	be printed.  Normally you would	use  a
       sequence	 of  fields  in	a vertical stack to print out a	block of text.
       If you like, you	can end	the final field	with ..., which	will appear in
       the output if the text was too long to appear in	its entirety.  You can
       change which characters are legal to break on by	changing the  variable
       $: to a list of the desired characters.

       Since  use  of ^	fields can produce variable length records if the text
       to be formatted is short, you can suppress blank	lines by  putting  the
       tilde  (~) character anywhere in	the line.  (Normally you should	put it
       in the front if possible, for visibility.)  The tilde  will  be	trans-
       lated  to a space upon output.  If you put a second tilde contiguous to
       the first, the line will	be repeated until all the fields on  the  line
       are  exhausted.	 (If  you use a	field of the @ variety,	the expression
       you supply had better not give the same value every time	forever!)

       Examples:

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

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

       It is possible to intermix prints with writes on	the same output	 chan-
       nel, but	you'll have to handle $- (lines	left on	the page) yourself.

       If  you	are printing lots of fields that are usually blank, you	should
       consider	using the reset	operator between records.  Not only is it more
       efficient,  but it can prevent the bug of adding	another	field and for-
       getting to zero it.

       Interprocess Communication

       The IPC facilities of perl are built on the Berkeley socket  mechanism.
       If you don't have sockets, you can ignore this section.	The calls have
       the same	names as the corresponding system  calls,  but	the  arguments
       tend to differ, for two reasons.	 First,	perl file handles work differ-
       ently than C file descriptors.  Second, perl already knows  the	length
       of  its strings,	so you don't need to pass that information.  Here is a
       sample client (untested):

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

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

	    require 'sys/socket.ph';

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

	    ($name, $aliases, $proto) =	getprotobyname('tcp');
	    ($name, $aliases, $port) = getservbyname($port, 'tcp')
		 unless	$port =~ /^\d+$/;
	    ($name, $aliases, $type, $len, $thisaddr) =
				gethostbyname($hostname);
	    ($name, $aliases, $type, $len, $thataddr) =	gethostbyname($them);

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

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

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

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

       And here's a server:

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

	    require 'sys/socket.ph';

	    $sockaddr =	'S n a4	x8';

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

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

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

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

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

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

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

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

       Predefined Names

       The following names have	special	meaning	to perl.  I  could  have  used
       alphabetic  symbols  for	 some  of these, but I didn't want to take the
       chance that someone would say reset "a-zA-Z" and	 wipe  them  all  out.
       You'll  just  have  to  suffer along with these silly symbols.  Most of
       them have reasonable mnemonics, or analogues in one of the shells.

       $_      The default input and pattern-searching space.	The  following
	       pairs are equivalent:

		    while (<>) {...	# only equivalent in while!
		    while ($_ =	<>) {...

		    /^Subject:/
		    $_ =~ /^Subject:/

		    y/a-z/A-Z/
		    $_ =~ y/a-z/A-Z/

		    chop
		    chop($_)

	       (Mnemonic: underline is understood in certain operations.)

       $.      The  current  input line	number of the last filehandle that was
	       read.  Readonly.	 Remember that only an explicit	close  on  the
	       filehandle  resets  the	line  number.	Since <> never does an
	       explicit	close, line numbers increase across  ARGV  files  (but
	       see  examples  under  eof).   (Mnemonic:	many programs use . to
	       mean the	current	line number.)

       $/      The input record	separator, newline  by	default.   Works  like
	       awk's RS	variable, including treating blank lines as delimiters
	       if set to the null string.  You may set it to a	multicharacter
	       string to match a multi-character delimiter.  Note that setting
	       it to "\n\n" means something slightly different than setting it
	       to  "",	if the file contains consecutive blank lines.  Setting
	       it to ""	will treat two or more consecutive blank  lines	 as  a
	       single  blank  line.   Setting it to "\n\n" will	blindly	assume
	       that the	next input character belongs to	 the  next  paragraph,
	       even  if	 it's a	newline.  (Mnemonic: / is used to delimit line
	       boundaries when quoting poetry.)

       $,      The output field	separator for the print	operator.   Ordinarily
	       the print operator simply prints	out the	comma separated	fields
	       you specify.  In	order to get behavior more like	awk, set  this
	       variable	as you would set awk's OFS variable to specify what is
	       printed between fields.	(Mnemonic: what	is printed when	 there
	       is a , in your print statement.)

       $""     This is like $, except that it applies to array values interpo-
	       lated into  a  double-quoted  string  (or  similar  interpreted
	       string).	 Default is a space.  (Mnemonic: obvious, I think.)

       $\      The output record separator for the print operator.  Ordinarily
	       the print operator simply prints	out the	comma separated	fields
	       you  specify,  with  no	trailing  newline  or record separator
	       assumed.	 In order to get behavior  more	 like  awk,  set  this
	       variable	as you would set awk's ORS variable to specify what is
	       printed at the end of the print.	 (Mnemonic: you	set $\ instead
	       of  adding \n at	the end	of the print.  Also, it's just like /,
	       but it's	what you get "back" from perl.)

       $#      The output format for printed  numbers.	 This  variable	 is  a
	       half-hearted attempt to emulate awk's OFMT variable.  There are
	       times, however, when awk	and perl  have	differing  notions  of
	       what  is	 in  fact  numeric.   Also, the	initial	value is %.20g
	       rather than %.6g, so you	need to	set $# explicitly to get awk's
	       value.  (Mnemonic: # is the number sign.)

       $%      The  current page number	of the currently selected output chan-
	       nel.  (Mnemonic:	% is page number in nroff.)

       $=      The current page	length	(printable  lines)  of	the  currently
	       selected	output channel.	 Default is 60.	 (Mnemonic: = has hor-
	       izontal lines.)

       $-      The number of lines left	on the page of the currently  selected
	       output channel.	(Mnemonic: lines_on_page - lines_printed.)

       $~      The  name  of  the  current  report  format  for	 the currently
	       selected	output channel.	 Default is name  of  the  filehandle.
	       (Mnemonic: brother to $^.)

       $^      The  name  of  the current top-of-page format for the currently
	       selected	output channel.	 Default is  name  of  the  filehandle
	       with "_TOP" appended.  (Mnemonic: points	to top of page.)

       $|      If set to nonzero, forces a flush after every write or print on
	       the currently selected output channel.	Default	 is  0.	  Note
	       that STDOUT will	typically be line buffered if output is	to the
	       terminal	and block buffered otherwise.  Setting	this  variable
	       is  useful primarily when you are outputting to a pipe, such as
	       when you	are running a perl script under	rsh and	 want  to  see
	       the  output  as	it's happening.	 (Mnemonic: when you want your
	       pipes to	be piping hot.)

       $$      The process number of the perl running this script.  (Mnemonic:
	       same as shells.)

       $?      The  status returned by the last	pipe close, backtick (``) com-
	       mand or system operator.	 Note that this	 is  the  status  word
	       returned	 by  the  wait() system	call, so the exit value	of the
	       subprocess is actually ($? >> 8).  $? & 255 gives which signal,
	       if  any,	 the  process  died from, and whether there was	a core
	       dump.  (Mnemonic: similar to sh and ksh.)

       $&      The string matched by the last successful  pattern  match  (not
	       counting	 any matches hidden within a BLOCK or eval enclosed by
	       the current BLOCK).  (Mnemonic: like & in some editors.)

       $`      The string preceding whatever was matched by the	last  success-
	       ful  pattern  match  (not  counting any matches hidden within a
	       BLOCK or	eval enclosed by the  current  BLOCK).	 (Mnemonic:  `
	       often precedes a	quoted string.)

       $'      The  string following whatever was matched by the last success-
	       ful pattern match (not counting any  matches  hidden  within  a
	       BLOCK  or  eval	enclosed  by the current BLOCK).  (Mnemonic: '
	       often follows a quoted string.)	Example:

		    $_ = 'abcdefghi';
		    /def/;
		    print "$`:$&:$'\n";	     # prints abc:def:ghi

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

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

	       (Mnemonic: be positive and forward looking.)

       $*      Set to 1	to do multiline	matching within	a string,  0  to  tell
	       perl that it can	assume that strings contain a single line, for
	       the purpose of optimizing pattern matches.  Pattern matches  on
	       strings	containing  multiple  newlines	can  produce confusing
	       results when $* is 0.  Default is 0.  (Mnemonic:	* matches mul-
	       tiple  things.)	 Note  that  this variable only	influences the
	       interpretation of ^ and $.  A literal newline can  be  searched
	       for even	when $*	== 0.

       $0      Contains	 the name of the file containing the perl script being
	       executed.  Assigning to $0 modifies the argument	area that  the
	       ps(1) program sees.  (Mnemonic: same as sh and ksh.)

       $<digit>
	       Contains	the subpattern from the	corresponding set of parenthe-
	       ses in the last pattern matched,	not counting patterns  matched
	       in  nested  blocks  that	 have been exited already.  (Mnemonic:
	       like \digit.)

       $[      The index of the	first element in an array, and	of  the	 first
	       character  in  a	substring.  Default is 0, but you could	set it
	       to 1 to make perl behave	more like awk (or Fortran)  when  sub-
	       scripting  and  when  evaluating	the index() and	substr() func-
	       tions.  (Mnemonic: [ begins subscripts.)

       $]      The string printed out when you say "perl -v".  It can be  used
	       to  determine  at  the  beginning  of a script whether the perl
	       interpreter executing the script	is in the right	range of  ver-
	       sions.	If  used  in  a	numeric	context, returns the version +
	       patchlevel / 1000.  Example:

		    # see if getc is available
		       ($version,$patchlevel) =
			  $] =~	/(\d+\.\d+).*\nPatch level: (\d+)/;
		       print STDERR "(No filename completion available.)\n"
			  if $version *	1000 + $patchlevel < 2016;

	       or, used	numerically,

		    warn "No checksumming!\n" if $] < 3.019;

	       (Mnemonic: Is this version of perl in the right bracket?)

       $;      The subscript separator for multi-dimensional array  emulation.
	       If you refer to an associative array element as
		    $foo{$a,$b,$c}

	       it really means

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

	       But don't put

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

	       which means

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

	       Default	is  "\034",  the  same as SUBSEP in awk.  Note that if
	       your keys contain binary	data there might not be	any safe value
	       for  $;.	  (Mnemonic: comma (the	syntactic subscript separator)
	       is a semi-semicolon.  Yeah, I know, it's	pretty lame, but $, is
	       already taken for something more	important.)

       $!      If  used	 in  a	numeric	 context,  yields the current value of
	       errno, with all	the  usual  caveats.   (This  means  that  you
	       shouldn't  depend on the	value of $! to be anything in particu-
	       lar unless you've gotten	a specific error return	 indicating  a
	       system  error.)	If used	in a string context, yields the	corre-
	       sponding	system error string.  You can assign to	$! in order to
	       set  errno  if,	for instance, you want $! to return the	string
	       for error n, or you want	to set the  exit  value	 for  the  die
	       operator.  (Mnemonic: What just went bang?)

       $@      The  perl  syntax error message from the	last eval command.  If
	       null, the last eval parsed and executed correctly (although the
	       operations  you invoked may have	failed in the normal fashion).
	       (Mnemonic: Where	was the	syntax error "at"?)

       $<      The real	uid of this process.  (Mnemonic: it's the uid you came
	       FROM, if	you're running setuid.)

       $>      The effective uid of this process.  Example:

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

	       (Mnemonic: it's the uid you went	TO, if you're running setuid.)
	       Note: $<	and $> can only	 be  swapped  on  machines  supporting
	       setreuid().

       $(      The  real  gid  of  this	process.  If you are on	a machine that
	       supports	membership in multiple groups simultaneously, gives  a
	       space separated list of groups you are in.  The first number is
	       the one returned	by getgid(), and the subsequent	ones  by  get-
	       groups(),  one  of  which  may be the same as the first number.
	       (Mnemonic: parentheses are used to GROUP	things.	 The real  gid
	       is the group you	LEFT, if you're	running	setgid.)

       $)      The  effective  gid  of	this process.  If you are on a machine
	       that supports membership	 in  multiple  groups  simultaneously,
	       gives  a	 space separated list of groups	you are	in.  The first
	       number is the one returned by  getegid(),  and  the  subsequent
	       ones  by	getgroups(), one of which may be the same as the first
	       number.	(Mnemonic: parentheses are used	to GROUP things.   The
	       effective gid is	the group that's RIGHT for you,	if you're run-
	       ning setgid.)

	       Note: $<, $>, $(	and $) can only	be set on machines  that  sup-
	       port  the corresponding set[re][ug]id() routine.	 $( and	$) can
	       only be swapped on machines supporting setregid().

       $:      The current set of characters after which a string may be  bro-
	       ken  to fill continuation fields	(starting with ^) in a format.
	       Default	is  " \n-",  to	 break	on  whitespace	 or   hyphens.
	       (Mnemonic: a "colon" in poetry is a part	of a line.)

       $^D     The  current value of the debugging flags.  (Mnemonic: value of
	       -D switch.)

       $^F     The maximum system file descriptor, ordinarily 2.  System  file
	       descriptors  are	 passed	 to  subprocesses,  while  higher file
	       descriptors are not.  During an open, system  file  descriptors
	       are  preserved  even if the open	fails.	Ordinary file descrip-
	       tors are	closed before the open is attempted.

       $^I     The current value of the	inplace-edit extension.	 Use undef  to
	       disable inplace editing.	 (Mnemonic: value of -i	switch.)

       $^L     What formats output to perform a	formfeed.  Default is \f.

       $^P     The  internal  flag that	the debugger clears so that it doesn't
	       debug itself.  You could	conceivable disable debugging yourself
	       by clearing it.

       $^T     The  time  at  which the	script began running, in seconds since
	       the epoch.  The values returned by the -M , -A and -C filetests
	       are based on this value.

       $^W     The current value of the	warning	switch.	 (Mnemonic: related to
	       the -w switch.)

       $^X     The name	that Perl itself was executed as, from argv[0].

       $ARGV   contains	the name of the	current	file when reading from <>.

       @ARGV   The array ARGV contains the command line	arguments intended for
	       the  script.  Note that $#ARGV is the generally number of argu-
	       ments minus one,	since $ARGV[0] is the first argument, NOT  the
	       command name.  See $0 for the command name.

       @INC    The  array  INC	contains  the  list of places to look for perl
	       scripts to be  evaluated	 by  the  "do  EXPR"  command  or  the
	       "require"  command.   It	initially consists of the arguments to
	       any -I command line switches,  followed	by  the	 default  perl
	       library,	probably "/usr/share/perl", followed by	".", to	repre-
	       sent the	current	directory.

       %INC    The associative array INC contains entries  for	each  filename
	       that  has  been included	via "do" or "require".	The key	is the
	       filename	you specified, and the value is	the  location  of  the
	       file  actually found.  The "require" command uses this array to
	       determine whether a given file has already been included.

       $ENV{expr}
	       The associative array ENV contains  your	 current  environment.
	       Setting	a  value in ENV	changes	the environment	for child pro-
	       cesses.

       $SIG{expr}
	       The associative array SIG is used to set	 signal	 handlers  for
	       various signals.	 Example:

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

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

	       The SIG array only contains values for the signals actually set
	       within the perl script.

       Packages

       Perl provides a mechanism for alternate namespaces to protect  packages
       from  stomping  on  each	 others	 variables.  By	default, a perl	script
       starts compiling	into the package known as "main".  By use of the pack-
       age  declaration,  you can switch namespaces.  The scope	of the package
       declaration is from the declaration itself to the end of	the  enclosing
       block  (the same	scope as the local() operator).	 Typically it would be
       the first declaration in	a file to be included by the "require"	opera-
       tor.   You  can switch into a package in	more than one place; it	merely
       influences which	symbol table is	used by	the compiler for the  rest  of
       that  block.  You can refer to variables	and filehandles	in other pack-
       ages by prefixing the identifier	with the package  name	and  a	single
       quote.  If the package name is null, the	"main" package as assumed.

       Only  identifiers starting with letters are stored in the packages sym-
       bol table.  All other symbols are kept in package "main".  In addition,
       the  identifiers	STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC and SIG
       are forced to be	in package "main", even	when used for  other  purposes
       than  their built-in one.  Note also that, if you have a	package	called
       "m", "s"	or "y",	the you	can't use the qualified	form of	an  identifier
       since it	will be	interpreted instead as a pattern match,	a substitution
       or a translation.

       Eval'ed strings are compiled in the package in which the	eval was  com-
       piled  in.   (Assignments to $SIG{}, however, assume the	signal handler
       specified is in the main	package.  Qualify the signal handler  name  if
       you wish	to have	a signal handler in a package.)	 For an	example, exam-
       ine perldb.pl in	the perl library.  It initially	 switches  to  the  DB
       package	so  that  the debugger doesn't interfere with variables	in the
       script you are trying to	debug.	At various points, however, it	tempo-
       rarily  switches	 back  to the main package to evaluate various expres-
       sions in	the context of the main	package.

       The symbol table	for a package happens to be stored in the  associative
       array  of  that	name  prepended	with an	underscore.  The value in each
       entry of	the associative	array is what you are referring	 to  when  you
       use  the	 *name	notation.  In fact, the	following have the same	effect
       (in package main, anyway), though the first is more  efficient  because
       it does the symbol table	lookups	at compile time:

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

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

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

       Note that, even though the subroutine is	compiled in  package  dumpvar,
       the  name  of  the subroutine is	qualified so that its name is inserted
       into package "main".

       Style

       Each programmer will, of	course,	have his or  her  own  preferences  in
       regards	to formatting, but there are some general guidelines that will
       make your programs easier to read.

       1.  Just	because	you CAN	do something a	particular  way	 doesn't  mean
	   that	 you SHOULD do it that way.  Perl is designed to give you sev-
	   eral	ways to	do anything, so	consider  picking  the	most  readable
	   one.	 For instance

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

	   is better than

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

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

		print "Starting	analysis\n" if $verbose;

	   is better than

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

	   since the main point	isn't whether the user typed -v	or not.

	   Similarly, just because an operator lets you	assume	default	 argu-
	   ments  doesn't mean that you	have to	make use of the	defaults.  The
	   defaults are	there for lazy systems	programmers  writing  one-shot
	   programs.   If  you want your program to be readable, consider sup-
	   plying the argument.

	   Along the same lines, just because you can omit parentheses in many
	   places doesn't mean that you	ought to:

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

	   When	 in  doubt,  parenthesize.  At the very	least it will let some
	   poor	schmuck	bounce on the %	key in vi.

	   Even	if you aren't in doubt,	consider the  mental  welfare  of  the
	   person  who has to maintain the code	after you, and who will	proba-
	   bly put parens in the wrong place.

       2.  Don't go through silly contortions to exit a	loop at	the top	or the
	   bottom,  when  perl provides	the "last" operator so you can exit in
	   the middle.	Just outdent it	a little to make it more visible:

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

       3.  Don't be afraid to use loop labels--they're there to	enhance	 read-
	   ability  as	well  as  to  allow multi-level	loop breaks.  See last
	   example.

       4.  For portability, when using features	that may not be	implemented on
	   every  machine,  test  the construct	in an eval to see if it	fails.
	   If you know what version or patchlevel  a  particular  feature  was
	   implemented,	you can	test $]	to see if it will be there.

       5.  Choose mnemonic identifiers.

       6.  Be consistent.

       Debugging

       If  you	invoke	perl with a -d switch, your script will	be run under a
       debugging monitor.  It will halt	before the first executable  statement
       and ask you for a command, such as:

       h	   Prints out a	help message.

       T	   Stack trace.

       s	   Single  step.   Executes  until it reaches the beginning of
		   another statement.

       n	   Next.  Executes over	subroutine calls, until	it reaches the
		   beginning of	the next statement.

       f	   Finish.  Executes statements	until it has finished the cur-
		   rent	subroutine.

       c	   Continue.  Executes until the next breakpoint is reached.

       c line	   Continue to the specified line.   Inserts  a	 one-time-only
		   breakpoint at the specified line.

       <CR>	   Repeat last n or s.

       l min+incr  List	 incr+1	 lines	starting  at  min.  If min is omitted,
		   starts where	last listing left off.	If  incr  is  omitted,
		   previous value of incr is used.

       l min-max   List	lines in the indicated range.

       l line	   List	just the indicated line.

       l	   List	next window.

       -	   List	previous window.

       w line	   List	window around line.

       l subname   List	 subroutine.   If it's a long subroutine it just lists
		   the beginning.  Use "l" to list more.

       /pattern/   Regular expression search forward for pattern; the final  /
		   is optional.

       ?pattern?   Regular expression search backward for pattern; the final ?
		   is optional.

       L	   List	lines that have	breakpoints or actions.

       S	   Lists the names of all subroutines.

       t	   Toggle trace	mode on	or off.

       b line condition
		   Set a breakpoint.  If line is omitted, sets a breakpoint on
		   the	line  that is about to be executed.  If	a condition is
		   specified, it is  evaluated	each  time  the	 statement  is
		   reached  and	a breakpoint is	taken only if the condition is
		   true.  Breakpoints may only be set on lines that  begin  an
		   executable statement.

       b subname condition
		   Set breakpoint at first executable line of subroutine.

       d line	   Delete  breakpoint.	If line	is omitted, deletes the	break-
		   point on the	line that is about to be executed.

       D	   Delete all breakpoints.

       a line command
		   Set an action  for  line.   A  multi-line  command  may  be
		   entered by backslashing the newlines.

       A	   Delete all line actions.

       < command   Set	an  action  to happen before every debugger prompt.  A
		   multi-line command may be entered by	backslashing the  new-
		   lines.

       > command   Set	an  action to happen after the prompt when you've just
		   given a command to  return  to  executing  the  script.   A
		   multi-line  command may be entered by backslashing the new-
		   lines.

       V package   List	all variables in package.  Default is main package.

       ! number	   Redo	a debugging command.  If number	is omitted, redoes the
		   previous command.

       ! -number   Redo	the command that was that many commands	ago.

       H -number   Display  last  n  commands.	 Only commands longer than one
		   character are listed.  If number  is	 omitted,  lists  them
		   all.

       q or ^D	   Quit.

       command	   Execute  command  as	a perl statement.  A missing semicolon
		   will	be supplied.

       p expr	   Same	as "print DB'OUT  expr".   The	DB'OUT	filehandle  is
		   opened to /dev/tty, regardless of where STDOUT may be redi-
		   rected to.

       If you want to modify  the  debugger,  copy  perldb.pl  from  the  perl
       library	to your	current	directory and modify it	as necessary.  (You'll
       also have to put	-I. on your command line.)  You	can do some customiza-
       tion  by	 setting up a .perldb file which contains initialization code.
       For instance, you could make aliases like these:

	   $DB'alias{'len'} = 's/^len(.*)/p length($1)/';
	   $DB'alias{'stop'} = 's/^stop	(at|in)/b/';
	   $DB'alias{'.'} =
	     's/^\./p "\$DB\'sub(\$DB\'line):\t",\$DB\'line[\$DB\'line]/';

       Setuid Scripts

       Perl is designed	to make	it easy	to  write  secure  setuid  and	setgid
       scripts.	  Unlike  shells,  which  are  based  on multiple substitution
       passes on each line of the script, perl uses a more conventional	evalu-
       ation scheme with fewer hidden "gotchas".  Additionally,	since the lan-
       guage has more built-in functionality, it has to	rely less upon	exter-
       nal (and	possibly untrustworthy)	programs to accomplish its purposes.

       In  an unpatched	4.2 or 4.3bsd kernel, setuid scripts are intrinsically
       insecure, but this kernel feature can be	disabled.  If it is, perl  can
       emulate	the  setuid and	setgid mechanism when it notices the otherwise
       useless setuid/gid bits on perl scripts.	 If the	kernel	feature	 isn't
       disabled,  perl	will  complain loudly that your	setuid script is inse-
       cure.  You'll need to either disable the	kernel setuid script  feature,
       or put a	C wrapper around the script.

       When perl is executing a	setuid script, it takes	special	precautions to
       prevent you from	falling	into any obvious traps.	 (In some ways,	a perl
       script  is  more	secure than the	corresponding C	program.)  Any command
       line argument, environment variable, or input is	marked	as  "tainted",
       and  may	 not  be  used,	 directly  or  indirectly, in any command that
       invokes a subshell, or in any command that modifies files,  directories
       or  processes.	Any variable that is set within	an expression that has
       previously referenced a tainted value also becomes tainted (even	if  it
       is  logically  impossible  for the tainted value	to influence the vari-
       able).  For example:

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

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

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

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

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

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

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

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

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

       The taintedness is associated with each scalar value, so	some  elements
       of an array can be tainted, and others not.

       If  you try to do something insecure, you will get a fatal error	saying
       something like "Insecure	dependency" or "Insecure PATH".	 Note that you
       can still write an insecure system call or exec,	but only by explicitly
       doing something like the	last example above.  You can also  bypass  the
       tainting	 mechanism  by	referencing subpatterns--perl presumes that if
       you reference a substring using $1, $2, etc, you	 knew  what  you  were
       doing when you wrote the	pattern:

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

       This  is	 fairly	 secure	 since \w+ doesn't match shell metacharacters.
       Use of .+ would have been insecure, but perl doesn't check for that, so
       you must	be careful with	your patterns.	This is	the ONLY mechanism for
       untainting user supplied	filenames if you want to do file operations on
       them (unless you	make $>	equal to $<).

       It's also possible to get into trouble with other operations that don't
       care whether they use tainted values.  Make judicious use of  the  file
       tests  in  dealing with any user-supplied filenames.  When possible, do
       opens and such after setting $> = $<.  Perl doesn't  prevent  you  from
       opening	tainted	 filenames  for	 reading, so be	careful	what you print
       out.  The tainting mechanism is intended	to  prevent  stupid  mistakes,
       not to remove the need for thought.

ENVIRONMENT
       HOME	   Used	if chdir has no	argument.

       LOGDIR	   Used	if chdir has no	argument and HOME is not set.

       PATH	   Used	 in  executing subprocesses, and in finding the	script
		   if -S is used.

       PERLLIB	   A colon-separated list of directories in which to look  for
		   Perl	 library  files	before looking in the standard library
		   and the current directory.

       PERLDB	   The command used to get the debugger	code.  If unset, uses

			require	'perldb.pl'

       Apart from these, perl uses no other environment	variables,  except  to
       make  them  available  to  the script being executed, and to child pro-
       cesses.	However, scripts running setuid	would do well to  execute  the
       following lines before doing anything else, just	to keep	people honest:

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

AUTHOR
       Larry Wall <lwall@netlabs.com>
       MS-DOS port by Diomidis Spinellis <dds@cc.ic.ac.uk>

FILES
       /tmp/perl-eXXXXXX   temporary file for -e commands.

SEE ALSO
       a2p  awk	to perl	translator
       s2p  sed	to perl	translator

DIAGNOSTICS
       Compilation  errors will	tell you the line number of the	error, with an
       indication of the next token or token type that	was  to	 be  examined.
       (In  the	 case  of  a script passed to perl via -e switches, each -e is
       counted as one line.)

       Setuid scripts have additional constraints that can produce error  mes-
       sages  such  as	"Insecure  dependency".	  See  the  section  on	setuid
       scripts.

TRAPS
       Accustomed awk users should take	special	note of	the following:

       *   Semicolons are required after all simple statements in perl (except
	   at the end of a block).  Newline is not a statement delimiter.

       *   Curly brackets are required on ifs and whiles.

       *   Variables begin with	$ or @ in perl.

       *   Arrays  index  from 0 unless	you set	$[.  Likewise string positions
	   in substr() and index().

       *   You have to	decide	whether	 your  array  has  numeric  or	string
	   indices.

       *   Associative	array  values  do  not spring into existence upon mere
	   reference.

       *   You have to decide whether you want to use string or	 numeric  com-
	   parisons.

       *   Reading  an input line does not split it for	you.  You get to split
	   it yourself to an array.  And  the  split  operator	has  different
	   arguments.

       *   The	current	 input	line  is normally in $_, not $0.  It generally
	   does	not have the newline stripped.	($0 is the name	of the program
	   executed.)

       *   $<digit>  does not refer to fields--it refers to substrings matched
	   by the last match pattern.

       *   The print statement does not	add field and record separators	unless
	   you set $, and $\.

       *   You must open your files before you print to	them.

       *   The	range  operator	is "..", not comma.  (The comma	operator works
	   as in C.)

       *   The match operator is "=~", not "~".	 ("~" is the one's  complement
	   operator, as	in C.)

       *   The	exponentiation	operator  is  "**",  not "^".  ("^" is the XOR
	   operator, as	in C.)

       *   The concatenation operator is ".", not the null string.  (Using the
	   null	 string	would render "/pat/ /pat/" unparsable, since the third
	   slash would be interpreted as a division operator--the  tokener  is
	   in  fact slightly context sensitive for operators like /, ?,	and <.
	   And in fact,	. itself can be	the beginning of a number.)

       *   Next, exit and continue work	differently.

       *   The following variables work	differently

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

       *   When	in doubt, run the awk construct	through	a2p and	 see  what  it
	   gives you.

       Cerebral	C programmers should take note of the following:

       *   Curly brackets are required on ifs and whiles.

       *   You should use "elsif" rather than "else if"

       *   Break and continue become last and next, respectively.

       *   There's no switch statement.

       *   Variables begin with	$ or @ in perl.

       *   Printf does not implement *.

       *   Comments begin with #, not /*.

       *   You can't take the address of anything.

       *   ARGV	must be	capitalized.

       *   The	"system"  calls	 link, unlink, rename, etc. return nonzero for
	   success, not	0.

       *   Signal handlers deal	with signal names, not numbers.

       Seasoned	sed programmers	should take note of the	following:

       *   Backreferences in substitutions use $ rather	than \.

       *   The pattern matching	metacharacters (, ), and | do not  have	 back-
	   slashes in front.

       *   The range operator is .. rather than	comma.

       Sharp shell programmers should take note	of the following:

       *   The	backtick  operator does	variable interpretation	without	regard
	   to the presence of single quotes in the command.

       *   The backtick	operator does no  translation  of  the	return	value,
	   unlike csh.

       *   Shells  (especially	csh) do	several	levels of substitution on each
	   command line.  Perl does substitution only  in  certain  constructs
	   such	 as  double  quotes, backticks,	angle brackets and search pat-
	   terns.

       *   Shells interpret scripts a little bit at a time.  Perl compiles the
	   whole program before	executing it.

       *   The arguments are available via @ARGV, not $1, $2, etc.

       *   The environment is not automatically	made available as variables.

ERRATA AND ADDENDA
       The  Perl  book,	 Programming Perl  ,  has  the following omissions and
       goofs.

       On page 5, the examples which read

	    eval "/usr/bin/perl

       should read

	    eval "exec /usr/bin/perl

       On page 195, the	equivalent to the System V sum program only works  for
       very small files.  To do	larger files, use

	    undef $/;
	    $checksum =	unpack("%32C*",<>) % 32767;

       The  descriptions  of  alarm and	sleep refer to signal SIGALARM.	 These
       should refer to SIGALRM.

       The -0 switch to	set the	initial	value of $/ was	added  to  Perl	 after
       the book	went to	press.

       The -l switch now does automatic	line ending processing.

       The qx//	construct is now a synonym for backticks.

       $0 may now be assigned to set the argument displayed by ps (1).

       The new @###.## format was omitted accidentally from the	description on
       formats.

       It wasn't known at press	time that s///ee caused	 multiple  evaluations
       of the replacement expression.  This is to be construed as a feature.

       (LIST) x	$count now does	array replication.

       There is	now no limit on	the number of parentheses in a regular expres-
       sion.

       In double-quote context,	more escapes are supported: \e,	\a, \x1b, \c[,
       \l, \L, \u, \U, \E.  The	latter five control up/lower case translation.

       The $/ variable may now be set to a multi-character delimiter.

       There  is  now a	g modifier on ordinary pattern matching	that causes it
       to iterate through a string finding multiple matches.

       All of the $^X variables	are new	except for $^T.

       The default top-of-form format for  FILEHANDLE  is  now	FILEHANDLE_TOP
       rather than top.

       The eval	{} and sort {} constructs were added in	version	4.018.

       The  v  and V (little-endian) template options for pack and unpack were
       added in	4.019.

BUGS
       Perl is at the mercy of your machine's definitions  of  various	opera-
       tions such as type casting, atof() and sprintf().

       If  your	 stdio	requires  an seek or eof between reads and writes on a
       particular stream, so does perl.	 (This doesn't apply to	sysread()  and
       syswrite().)

       While  none  of	the built-in data types	have any arbitrary size	limits
       (apart from memory size), there are still a  few	 arbitrary  limits:  a
       given  identifier  may not be longer than 255 characters, and no	compo-
       nent of your PATH may be	longer than 255	if  you	 use  -S.   A  regular
       expression may not compile to more than 32767 bytes internally.

       Perl  actually  stands  for Pathologically Eclectic Rubbish Lister, but
       don't tell anyone I said	that.

3rd Berkeley Distribution					       PERL(1)

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | AUTHOR | FILES | SEE ALSO | DIAGNOSTICS | TRAPS | ERRATA AND ADDENDA | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=perl&manpath=FreeBSD+2.2.8-RELEASE>

home | help