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  re-
       ports  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.)  Ex-
       pression	syntax corresponds quite closely to C expression syntax.   Un-
       like  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 ta-
       bles 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  De-
	    bugging.

       -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 be-
	    gin	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 un-
	    der	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  in-
	    stead.   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 op-
       erations	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  re-
       turn  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  re-
       turned  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 un-
       defined 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  as-
       signment	 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.)   As-
       signing 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 ar-
       ray 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 @ar-
       ray{LIST} only happens if array is referenced elsewhere in the  program
       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  al-
       ways  right.  If	it does	guess wrong, or	if you're just plain paranoid,
       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 ar-
       ray 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 in-
       terpreted  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  as-
       signment	 happens.  If (and only	if) the	input symbol is	the only thing
       inside the conditional of a while loop, the value is automatically  as-
       signed  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 in-
       put.  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  be-
       cause 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 un-
       der 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 en-
       closing 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  op-
       tional,	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	continued  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  im-
       plicitly	 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  ar-
       ray  (as	 opposed  to  an expression returning an array value), you can
       modify each element of the array	by modifying VAR inside	the loop.  Ex-
       amples:

	    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  al-
       ready  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  ex-
	       plicit 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 ex-
	       plicit 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 de-
	       pending	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	.. op-
	       erator 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, AF-
	       TER which the range operator becomes false again.  (It  doesn't
	       become  false  till  the	next time the range operator is	evalu-
	       ated.  It can test the right operand and	become	false  on  the
	       same  evaluation	 it  became true (as in	awk), but it still re-
	       turns true once.	 If you	don't want it to test the right	 oper-
	       and  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	operand	is not
	       evaluated while the operator  is	 in  the  "true"  state.   The
	       precedence  is  a  little  lower	than ||	and &&.	 The value re-
	       turned is either	the null string	for false, or a	sequence  num-
	       ber  (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 im-
	       plicitly	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 op-
	       erator 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  au-
       toincrement  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 in-
       terpolated 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  to-
       ken  on the same	line must be a left parenthesis.  (There may be	inter-
       vening 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 de-
       pending	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 un-
       defined value, and in an	array context by returning the null list.  Re-
       member  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  re-
       turn the	first value in the list.  Some operators return	the last value
       in the list.  Some operators return a count of  successful  operations.
       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 re-
	       sults.  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  ar-
	       ray.   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 ex-
	       its 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 re-
	       turns the value of the last expression evaluated	in SUBROUTINE.
	       If there	is no subroutine by that name, produces	a fatal	error.
	       (You may	use the	"defined" operator to determine	if  a  subrou-
	       tine  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 re-
	       quired 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  it-
	       erator  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 ex-
	       pression	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 de-
	       tect the	end of only the	last file.  Use	eof(ARGV) or eof with-
	       out 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 db-
	       mopen or	symlink) is implemented.  It is	also Perl's  exception
	       trapping	mechanism, where the die operator is used to raise ex-
	       ceptions.

	       If the code to be executed doesn't vary,	you may	use the	 eval-
	       BLOCK  form  to trap run-time errors without incurring the pen-
	       alty of recompiling each	time.  The error, if any, is still re-
	       turned  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 replace-
	       ment side of  a	substitution  is  considered  a	 single-quoted
	       string  when  you use the e modifier, the same optimization oc-
	       curs 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 di-
	       rectly 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 op-
	       erating 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  en-
	       vironment:

		    @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 LA-
	       BEL 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,  re-
	       turns 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 re-
	       turned.	If the match succeeds, but there were no  parentheses,
	       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  re-
	       turns a list of all the substrings matched by all the parenthe-
	       ses 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).  Re-
	       turns 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 be-
	       gins 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.)	 Open-
	       ing  '-'	 opens	STDIN and opening '>-' opens STDOUT.  Open re-
	       turns non-zero upon success, the	undefined value	otherwise.  If
	       the  open  involved  a pipe, the	return value happens to	be the
	       pid of the subprocess.  Examples:

		    $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,  un-
	       flushed 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 ar-
	       bitrary 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 ar-
	       ray context, and	any subroutine that you	call will have one  or
	       more of its expressions evaluated in an array context.  Also be
	       careful not to follow the print keyword with a left parenthesis
	       unless  you  want the corresponding right parenthesis to	termi-
	       nate 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 im-
	       plemented.  If not, gives a fatal error.	 If there is some sys-
	       tem 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 in-
	       nermost enclosing loop.	This command is	normally used by  pro-
	       grams 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 ex-
	       pression	evaluated.  That's the preferred method--use of	an ex-
	       plicit 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 el-
	       ement 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-in-
	       sensitive  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 re-
	       placement 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  re-
	       turned  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  op-
	       erations	 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  OP-
	       STRING.	 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 ma-
	       chine 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  AR-
	       RAY is omitted, shifts the @ARGV	array in the main program, and
	       the @_ array in subroutines.  (This is  determined  lexically.)
	       See also	unshift(), push() and pop().  Shift() and unshift() do
	       the same	thing to the left end of  an  array  that  push()  and
	       pop() do	to the right end.

       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  re-
	       member).	  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.   Re-
	       turns  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  un-
	       derline,	 no stat is done, but the current contents of the stat
	       structure from the last stat or filetest	are  returned.	 Exam-
	       ple:

		    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  en-
	       tries 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.  To-
	       gether 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 de-
	       pending 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  in-
	       terpreted  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 se-
	       quences 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  in-
	       flict 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, de-
	       pending 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.  Re-
	       turns the number	of files successfully changed.	The inode mod-
	       ification  time of each file is set to the current time.	 Exam-
	       ple 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  in-
	       terpretation  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 de-
	       fault the format	for a file is the one having the same name  is
	       the  filehandle,	 but the format	for the	current	output channel
	       (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  dy-
	       namicallly  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  de-
	       fault  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  re-
       fer  to all the objects of a particular name by prefixing the name with
       a star: *foo.  When evaluated, it produces a scalar value  that	repre-
       sents all the objects of	that name, including any filehandle, format or
       subroutine.  When assigned to within a local() operation, it causes the
       name  mentioned to refer	to whatever * value was	assigned to it.	 Exam-
       ple:

	    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  ar-
       ray  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 $') ex-
       tends to	the end	of the enclosing BLOCK or eval string, or to the  next
       pattern	match  with  subexpressions.   The \<digit> notation sometimes
       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 sub-
       strings,	the variables $10, $11,	... refer to  the  corresponding  sub-
       string.	Within the pattern, \10, \11, etc. refer back to substrings if
       there have been at least	that many left parens  before  the  backrefer-
       ence.   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 en-
       tire 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-al-
       phanumeric 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 ^ in-
       stead 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	print-
       ing 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 ex-
	       plicit 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 as-
	       sumed.  In order	to get behavior	more like awk, set this	 vari-
	       able  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  se-
	       lected  output channel.	Default	is 60.	(Mnemonic: = has hori-
	       zontal 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 se-
	       lected 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 re-
	       turned by the wait() system call, so the	exit value of the sub-
	       process 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: ` of-
	       ten 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: ' of-
	       ten 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 re-
	       sults when $* is	0.  Default is 0.  (Mnemonic: *	matches	multi-
	       ple  things.)   Note that this variable only influences the in-
	       terpretation 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 in-
	       terpreter 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 er-
	       rno,  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  op-
	       erator.	(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  se-
	       treuid().

       $(      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.	 (Mne-
	       monic: 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 de-
	       scriptors are not.  During an open, system file descriptors are
	       preserved  even	if  the	open fails.  Ordinary file descriptors
	       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  "re-
	       quire"  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 represent 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 en-
       try 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 in-
       stance.	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 re-
       gards  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 ex-
	   ample.

       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 im-
	   plemented, 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  en-
		   tered 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  li-
       brary  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 in-
       vokes a subshell, or in any command that	modifies files,	directories or
       processes.  Any variable	that is	set within an expression that has pre-
       viously referenced a tainted value also becomes tainted (even if	it  is
       logically  impossible for the tainted value to influence	the variable).
       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 do-
       ing 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  in-
	   dices.

       *   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  ar-
	   guments.

       *   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 op-
	   erator, 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,  un-
	   like	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  ex-
       pression	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