


		     Printed August 7, 1992
PERL(1)



NAME
     perl - Practical Extraction and Report Language

SYNOPSIS
     perl [options] filename args

DESCRIPTION
     Perl is an	interpreted language optimized for scanning
     arbitrary text files, extracting information from those text
     files, and	printing reports based on that information.  It's
     also a good language for many system management tasks.  The
     language is intended to be	practical (easy	to use,
     efficient,	complete) rather than beautiful	(tiny, elegant,
     minimal).	It combines (in	the author's opinion, anyway)
     some of the best features of C, sed, awk, and sh, so people
     familiar with those languages should have little difficulty
     with it.  (Language historians will also note some	vestiges
     of	csh, Pascal, and even BASIC-PLUS.)  Expression syntax
     corresponds quite closely to C expression syntax.	Unlike
     most Unix utilities, perl does not	arbitrarily limit the
     size of your data--if you've got the memory, perl can slurp
     in	your whole file	as a single string.  Recursion is of
     unlimited depth.  And the hash tables used	by associative
     arrays grow as necessary to prevent degraded performance.
     Perl uses sophisticated pattern matching techniques to scan
     large amounts of data very	quickly.  Although optimized for
     scanning 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
     capabilities 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 command 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.



Page 1				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 without executing it.



Page 2				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

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

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

	  which	is equivalent to

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

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



Page 3				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  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 processed, 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.




Page 4				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     -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 printing use	the -n switch.	A -p overrides a
	  -n switch.

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

     -s	  enables some rudimentary switch parsing for switches on
	  the command 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 following 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).  Typically 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	command, 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



Page 5				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  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 control
	  that,	and need a totally devious construct that will
	  work under any of csh, sh or perl, such as the
	  following:

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


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

     -U	  allows perl to do unsafe operations.	Currently the
	  only "unsafe"	operations are the unlinking of
	  directories while running as superuser, 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 filehandles 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



Page 6				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  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 normal #!
	  processing).	If a directory name is specified, Perl
	  will switch to that directory	before running the
	  script.  The -x switch only controls the 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 associative arrays by string.

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

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

     References	to scalar variables always begin with '$', even
     when referring 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 '@':




Page 7				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

     and entire	associative arrays are denoted by '%':

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

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

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

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


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

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

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

     Multi-dimensional arrays are not directly supported, but see
     the discussion of the $; variable later for a means of
     emulating multiple	subscripts with	an associative array.



Page 8				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 conflict, use the same name for a scalar variable,
     an	array, an associative 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,
     however, which don't have an initial special character.
     Hint: you could say open(LOG,'logfile') rather than
     open(log,'logfile').  Using uppercase filehandles also
     improves readability and protects you from	conflict 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



Page 9				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  \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 $" variable, space by default.  (Since in
     versions of perl prior to 3.0 the @ character was not a
     metacharacter in double-quoted strings, the interpolation of
     @array, $array[EXPR], @array[LIST], $array{EXPR}, or



Page 10				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     @array{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 expression) or as /${foo[bar]}/ (where
     [bar] is the subscript to array @foo)?  If	@foo doesn't
     otherwise exist, then it's	obviously a character class.  If
     @foo exists, perl takes a good guess about	[bar], and is
     almost always right.  If it does guess wrong, or if you're
     just plain	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 whitespace) 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




Page 11				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  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 literal is the value	of the final element, as in the	C
     comma operator.  For example,

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

     assigns the entire	array value to array foo, but

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

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

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

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

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

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

	  (@foo,@bar,&SomeSub)

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

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



Page 12				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     Examples:

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


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

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

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

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

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

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

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

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

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

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


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



Page 13				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     in	any of the shells, single quotes do not	hide variable
     names in the command from interpretation.	To pass	a $
     through to	the shell you need to hide it with a backslash.

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

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

     The filehandles STDIN, STDOUT and STDERR are predefined.
     (The filehandles 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 behavior of sed and awk.  Input from <> comes either
     from standard input, or from each file listed on the command
     line.  Here's how it works: the first time	<> is evaluated,
     the ARGV array is checked,	and if it is null, $ARGV[0] is
     set to '-', which when opened gives you standard input.  The
     ARGV array	is then	processed as a list of filenames.  The
     loop

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









Page 14				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     is	equivalent to the following Perl-like pseudo code:

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

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

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

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

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

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

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

     If	the string inside angle	brackets is not	a filehandle, it
     is	interpreted 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 $



Page 15				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 interpretation 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 declarations.  All
     uninitialized user-created	objects	are assumed to start with
     a null or 0 value until they are defined by some explicit
     operation 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 explicitly 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



Page 16				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     extend to the end of the line.  If	you attempt to use /* */
     C comments, it will be interpreted	either as division or
     pattern matching, depending on the	context.  So don't do
     that.

     Compound statements

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

     The following compound commands may be used to control flow:

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

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

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


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

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



Page 17				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     (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 iteration.

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

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

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

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

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






Page 18				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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


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

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

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

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

     or

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

     or

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

     or	even






Page 19				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  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 structure, 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 semicolon, 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 evaluated.
     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,



Page 20				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 behavior of using == for either
	     string or numeric equality	based on the current form
	     of	the comparands,	beware!	 You must be explicit
	     here.)

     ne	     String inequality (!= is numeric inequality).

     lt	     String less than.

     gt	     String greater than.

     le	     String less than or equal.

     ge	     String greater than or equal.

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

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

     =~	     Certain operations	search or modify the string "$_"
	     by	default.  This operator	makes that kind	of
	     operation work on some other string.  The right
	     argument is a search pattern, substitution, or
	     translation.  The left argument is	what is	supposed
	     to	be searched, substituted, or translated	instead
	     of	the default "$_".  The return value indicates the
	     success of	the operation.	(If the	right argument is
	     an	expression other than a	search pattern,
	     substitution, or translation, it is interpreted as	a
	     search pattern at run time.  This is less efficient



Page 21				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     than an explicit search, since the	pattern	must be
	     compiled every time the expression	is evaluated.)
	     The precedence of this operator is	lower than unary
	     minus and autoincrement/decrement,	but higher than
	     everything	else.

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

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

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

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

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


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

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

	     In	a scalar context, .. returns a boolean value.
	     The operator is bistable, like a flip-flop, and
	     emulates the line-range (comma) operator of sed,
	     awk, and various editors.	Each ..	operator
	     maintains its own boolean state.  It is false as
	     long as its left operand is false.	 Once the left
	     operand is	true, the range	operator stays true until
	     the right operand is true,	AFTER which the	range
	     operator becomes false again.  (It	doesn't	become
	     false till	the next time the range	operator is
	     evaluated.	 It can	test the right operand and become
	     false on the same evaluation it became true (as in
	     awk), but it still	returns	true once.  If you don't
	     want it to	test the right operand 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



Page 22				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     the "true"	state.	The precedence is a little lower
	     than || and &&.  The value	returned is either the
	     null string for false, or a sequence number
	     (beginning	with 1)	for true.  The sequence	number is
	     reset for each range encountered.	The final
	     sequence number in	a range	has the	string 'E0'
	     appended to it, which doesn't affect its numeric
	     value, but	gives you something to search for if you
	     want to exclude the endpoint.  You	can exclude the
	     beginning point by	waiting	for the	sequence number
	     to	be greater than	1.  If either operand of scalar
	     ..	is static, that	operand	is implicitly compared to
	     the $. variable, the current line number.	Examples:

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

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

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

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

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


     -x	     A file test.  This	unary operator takes one
	     argument, either a	filename or a filehandle, and
	     tests the associated file to see if something is
	     true about	it.  If	the argument is	omitted, tests
	     $_, except	for -t,	which tests STDIN.  It returns 1
	     for true and '' for false,	or the undefined value if
	     the file doesn't exist.  Precedence is higher than
	     logical and relational operators, but lower than
	     arithmetic	operators.  The	operator may be	any of:
		  -r   File is readable	by effective uid/gid.
		  -w   File is writable	by effective uid/gid.
		  -x   File is executable by effective uid/gid.
		  -o   File is owned by	effective uid.
		  -R   File is readable	by real	uid/gid.
		  -W   File is writable	by real	uid/gid.
		  -X   File is executable by real uid/gid.
		  -O   File is owned by	real uid.
		  -e   File exists.
		  -z   File has	zero size.
		  -s   File has	non-zero size (returns size).
		  -f   File is a plain file.
		  -d   File is a directory.
		  -l   File is a symbolic link.



Page 23				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



		  -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 letters 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	control	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 current 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.




Page 24				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     If	any of the file	tests (or either stat operator)	are given
     the special 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	symbolic 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 concatenation 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 variable 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:




Page 25				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

     The autodecrement is not magical.

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

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

     to	get all	the letters of the alphabet, or

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

     to	get a hexadecimal digit, or

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

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

     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 values	will be
     included in the list as if	each individual	element	were
     interpolated at that point	in the list, forming a longer
     single-dimensional	array value.  Elements of the LIST should
     be	separated by commas.  If an operation is listed	both with
     and without parentheses around its	arguments, it means you
     can either	use it as a unary operator or as a function call.
     To	use it as a function call, the next token on the same
     line must be a left parenthesis.  (There may be intervening
     white space.)  Such a function then has highest precedence,
     as	you would expect from a	function.  If any token	other
     than a left parenthesis follows, then it is a unary



Page 26				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     operator, with a precedence depending only	on whether it is
     a LIST operator or	not.  LIST operators have lowest
     precedence.  All other unary operators have a precedence
     greater than relational operators but less	than arithmetic
     operators.	 See the section on Precedence.

     For operators that	can be used in either a	scalar or array
     context, failure is generally indicated in	a scalar context
     by	returning the undefined	value, and in an array context by
     returning the null	list.  Remember	though that THERE IS NO
     GENERAL RULE FOR CONVERTING A LIST	INTO A SCALAR.	Each
     operator decides which sort of scalar it would be most
     appropriate to return.  Some operators return the length of
     the list that would have been returned in an array	context.
     Some operators return the first value in the list.	 Some
     operators return the last value in	the list.  Some	operators
     return a count of successful 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 useful 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)



Page 27				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 section 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 translated to LF	on input
	     and LF translated to CR LF	on output.  Binmode has
	     no	effect under Unix.  If FILEHANDLE is an
	     expression, 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;



Page 28				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     chop(LIST)

     chop(VARIABLE)

     chop VARIABLE

     chop    Chops off the last	character of a string and returns
	     the character 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;
















Page 29				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 omitted, 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



Page 30				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 package 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 passwords.	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.




Page 31				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 setting 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.  Example:

		  # 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, uninitialized
	     variable, system error and	such.  This function
	     allows you	to distinguish between an undefined null
	     string and	a defined null string with operations
	     that might	return a real null string, in particular
	     referencing elements of an	array.	You may	also
	     check to see if arrays or subroutines exist.  Use on
	     predefined	variables is not guaranteed to produce
	     intuitive results.	 Examples:

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




Page 32				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     See also undef.

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

	     The following deletes all the values of an
	     associative array:

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

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

     die(LIST)

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

	     Equivalent	examples:

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

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


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








Page 33				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



		  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 commands indicated by BLOCK.  When
	     modified by a loop	modifier, executes the BLOCK once
	     before testing the	loop condition.	 (On other
	     statements	the loop modifiers test	the conditional
	     first.)

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

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

	     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 parentheses.	 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';



Page 34				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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,	however, 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 standalone 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
	     executed 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 program is reincarnated, with possible
	     resulting confusion on the	part of	perl.  See also
	     -u.

	     Example:














Page 35				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

		 QUICKSTART:
		  do Getopt('f');


     each(ASSOC_ARRAY)

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

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

	     See also keys() and values().

     eof(FILEHANDLE)

     eof()

     eof     Returns 1 if the next read	on FILEHANDLE will return
	     end of file, or if	FILEHANDLE is not open.
	     FILEHANDLE	may be an expression whose value gives
	     the real filehandle name.	(Note that this	function



Page 36				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     actually reads a character	and then ungetc's it, so
	     it	is not very useful in an interactive context.)
	     An	eof without an argument	returns	the eof	status
	     for the last file read.  Empty parentheses	() may be
	     used to indicate the pseudo file formed of	the files
	     listed on the command line, i.e. eof() is reasonable
	     to	use inside a while (<>)	loop to	detect the end of
	     only the last file.  Use eof(ARGV)	or eof without
	     the parentheses to	test EACH file in a while (<>)
	     loop.  Examples:

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

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


     eval(EXPR)

     eval EXPR

     eval BLOCK
	     EXPR is parsed and	executed as if it were a little
	     perl program.  It is executed in the context of the
	     current perl program, so that any variable	settings,
	     subroutine	or format definitions 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 useful for determining whether a particular
	     feature (such as dbmopen or symlink) is implemented.
	     It	is also	Perl's exception trapping mechanism,



Page 37				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     where the die operator is used to raise exceptions.

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

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

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

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

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


     exec(LIST)

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

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


	     If	you don't really want to execute the first
	     argument, but want	to lie to the program you are
	     executing about its own name, you can specify the



Page 38				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     program you actually want to run by assigning that
	     to	a variable and putting the name	of the variable
	     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
	     processing	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	constructing bitmaps for select().  If



Page 39				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     FILEHANDLE	is an expression, 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.



Page 40				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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)





Page 41				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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...



Page 42				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



		  ($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 undefined 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 supported 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 system
	     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.



Page 43				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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.  Typically 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 {} construct.  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
	     $_.






Page 44				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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
	     character 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: $!";
		  }




Page 45				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

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

     join(EXPR,LIST)

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

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

	     See split.

     keys(ASSOC_ARRAY)

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

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

	     or	how about sorted by key:

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






Page 46				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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	processes.  (On	System V, a negative
	     process number will also kill process groups, but
	     that's not	portable.)  You	may use	a signal name in
	     quotes.

     last LABEL

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

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


     length(EXPR)

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

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

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

     local(LIST)
	     Declares the listed variables to be local to the
	     enclosing block, subroutine, eval or "do".	 All the
	     listed elements must be legal lvalues.  This



Page 47				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     operator works by saving the current values of those
	     variables in LIST on a hidden stack and restoring
	     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 variables.  (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



Page 48				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     local timezone.  Typically	used as	follows:

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

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

     log(EXPR)

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

     lstat(FILEHANDLE)

     lstat FILEHANDLE

     lstat(EXPR)

     lstat SCALARVARIABLE
	     Does the same thing as the	stat() function, but
	     stats a symbolic 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 !~ operator,	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-insensitive	manner.	 PATTERN may
	     contain references	to scalar variables, 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



Page 49				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     like end-of-string	tests.)	 If you	want such a
	     pattern to	be compiled only once, add an "o" after
	     the trailing delimiter.  This avoids expensive run-
	     time recompilations, and is useful	when the value
	     you are interpolating won't change	over the life of
	     the script.  If the PATTERN evaluates to a	null
	     string, the most recent successful	regular
	     expression	is used	instead.

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



Page 50				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 general, however,
	     you should	be using s///g for such	modifications.)
	     Examples:

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

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


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

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

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

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





Page 51				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

     next LABEL

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

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

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

     oct(EXPR)

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

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

	     If	EXPR is	omitted, uses $_.

     open(FILEHANDLE,EXPR)

     open(FILEHANDLE)

     open FILEHANDLE
	     Opens the file whose filename is given by EXPR, and
	     associates	it with	FILEHANDLE.  If	FILEHANDLE is an
	     expression, its value is used as the name of the
	     real filehandle wanted.  If EXPR is omitted, the
	     scalar variable of	the same name as the FILEHANDLE
	     contains the filename.  If	the filename begins with
	     "<" or nothing, the file is opened	for input.  If
	     the filename begins with ">", the file is opened for
	     output.  If the filename begins with ">>",	the file



Page 52				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     is	opened for appending.  (You can	put a '+' in
	     front of the '>' or '<' to	indicate that you want
	     both read and write access	to the file.)  If the
	     filename begins with "|", the filename is
	     interpreted as a command to which output is to be
	     piped, and	if the filename	ends with a "|", the
	     filename is interpreted as	command	which pipes input
	     to	us.  (You may not have a command that pipes both
	     in	and out.)  Opening '-' opens STDIN and opening
	     '>-' opens	STDOUT.	 Open returns non-zero upon
	     success, the undefined value 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



Page 53				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 command gets executed, such as when you are
	     running setuid, and don't want to have to scan shell
	     commands for metacharacters.  The following pairs
	     are more or less equivalent:








Page 54				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

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

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


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

     ord(EXPR)

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

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

		  A    An ascii	string,	will be	space padded.
		  a    An ascii	string,	will be	null padded.
		  c    A signed	char value.
		  C    An unsigned char	value.
		  s    A signed	short value.
		  S    An unsigned short value.
		  i    A signed	integer	value.
		  I    An unsigned integer value.
		  l    A signed	long value.



Page 55				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



		  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 spaces and nulls, but
	     "a" does not.)  Likewise, the "b" and "B" fields
	     pack a string that	many bits long.	 The "h" and "H"
	     fields pack a string that many nybbles long.  Real
	     numbers (floats and doubles) are in the native
	     machine format only; due to the multiplicity of
	     floating formats around, and the lack of a	standard
	     "network" representation, no facility for
	     interchange has been made.	 This means that packed
	     floating point data written on one	machine	may not
	     be	readable on another - even if both use IEEE
	     floating point arithmetic (as the endian-ness of the
	     memory representation is not part of the IEEE spec).
	     Note that perl uses doubles internally for	all
	     numeric calculation, and converting from double ->
	     float -> double will lose precision (i.e.
	     unpack("f", pack("f", $foo)) will not in general
	     equal $foo).
	     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);



Page 56				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



		  # 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,	deadlock can occur unless
	     you are very careful.  In addition, note that perl's
	     pipes use stdio buffering,	so you may need	to set $|
	     to	flush your WRITEHANDLE after each command,
	     depending on the application.  [Requires version 3.0
	     patchlevel	9.]

     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.










Page 57				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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
	     filehandle, thus introducing one level of
	     indirection.  (NOTE: If FILEHANDLE	is a variable and
	     the next token is a term, it may be misinterpreted
	     as	an operator unless you interpose a + or	put
	     parens around the arguments.)  If FILEHANDLE is
	     omitted, prints by	default	to standard output (or to
	     the last selected output channel--see select()).  If
	     LIST is also omitted, prints $_ to	STDOUT.	 To set
	     the default output	channel	to something other than
	     STDOUT use	the select operation.  Note that, because
	     print takes a LIST, anything in the LIST is
	     evaluated in an array context, and	any subroutine
	     that you call will	have one or more of its
	     expressions evaluated in an array context.	 Also be
	     careful not to follow the print keyword with a left
	     parenthesis unless	you want the corresponding right
	     parenthesis to terminate the arguments to the
	     print--interpose a	+ or put parens	around all the
	     arguments.

     printf(FILEHANDLE LIST)

     printf(LIST)

     printf FILEHANDLE LIST

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

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

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




Page 58				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 operator a
	     generalized double	quote.	The qx operator	is a
	     generalized 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
	     corresponding closing bracket or parenthesis.
	     (Embedded occurrences of the closing bracket need to
	     be	backslashed as usual.)	Examples:

		  $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 sysread.





Page 59				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     readdir(DIRHANDLE)

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

     readlink(EXPR)

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

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

     redo LABEL

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

















Page 60				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



		  # 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 otherwise.  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 subroutine:

		  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;
		  }




Page 61				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     Note that the file	will not be included twice under
	     the same specified	name.  The file	must return true
	     as	the last statement 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	beginning with
	     one of those letters are reset to their pristine
	     state.  If	the expression is omitted, one-match
	     searches (?pattern?) are reset to match again.  Only
	     resets variables or searches in the current package.
	     Always returns 1.	Examples:

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

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

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

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

     reverse(LIST)

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





Page 62				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 specified, returns the last
	     occurrence	at or before that position.

     rmdir(FILENAME)

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

     s/PATTERN/REPLACEMENT/gieo
	     Searches a	string for a pattern, and if found,
	     replaces that pattern with	the replacement	text and
	     returns the number	of substitutions made.	Otherwise
	     it	returns	false (0).  The	"g" is optional, and if
	     present, indicates	that all occurrences of	the
	     pattern are to be replaced.  The "i" is also
	     optional, and if present, indicates that matching is
	     to	be done	in a case-insensitive manner.  The "e" is
	     likewise optional,	and if present,	indicates that
	     the replacement string is to be evaluated as an
	     expression	rather than just as a double-quoted
	     string.  Any non-alphanumeric delimiter may replace
	     the slashes; if single quotes are used, no
	     interpretation is done on the replacement string
	     (the e modifier overrides this, however); if
	     backquotes	are used, the replacement string is a
	     command to	execute	whose output will be used as the
	     actual replacement	text.  If 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 !~	operator,
	     the $_ string is searched and modified.  (The string
	     specified with =~ must be a scalar	variable, an
	     array element, or an assignment to	one of those,
	     i.e. an lvalue.)  If the pattern contains a $ that
	     looks like	a variable rather than an end-of-string
	     test, the variable	will be	interpolated into the



Page 63				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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
	     successful	regular	expression is used instead.  See
	     also the section 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 section 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	DIRHANDLE.  POS	must be	a value	returned by
	     telldir().	 Has the same caveats about possible
	     directory compaction as the corresponding 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	variables related
	     to	output will refer to this output channel.  For
	     example, if you have to set the top of form format



Page 64				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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	specified, is in seconds, which	may be
	     fractional.  NOTE:	not all	implementations	are
	     capable of	returning the $timeleft.  If not, they



Page 65				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     always return $timeleft equal to the supplied
	     $timeout.

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

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

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

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

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

     send(SOCKET,MSG,FLAGS,TO)

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

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

     setpriority(WHICH,WHO,PRIORITY)
	     Sets the current priority for a process, a	process
	     group, or a user.	(See setpriority(2).)  Will



Page 66				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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, shortening the	array by 1 and moving everything
	     down.  If there are no elements in	the array,
	     returns the undefined value.  If ARRAY is omitted,
	     shifts the	@ARGV array in the main	program, and the
	     @_	array in subroutines.  (This is	determined
	     lexically.)  See also unshift(), push() and pop().
	     Shift() and unshift() do the same thing to	the left
	     end of an array that push() and pop() do to the
	     right end.

     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



Page 67				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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	filehandle SOCKET.  DOMAIN, TYPE and PROTOCOL are
	     specified the same	as for the system call of the
	     same name.	 You may need to run h2ph on sys/socket.h
	     to	get the	proper values handy in a perl library
	     file.  Return true	if successful.	See the	example
	     in	the section on Interprocess Communication.

     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	unimplemented, 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 SUBROUTINE is
	     specified,	gives the name of a subroutine that
	     returns an	integer	less than, equal to, or	greater
	     than 0, depending on how the elements of the array



Page 68				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     are to be ordered.	 (The <=> and cmp operators are
	     extremely useful in such routines.)  SUBROUTINE may
	     be	a scalar variable name,	in which case the value
	     provides the name of the subroutine to use.  In
	     place of a	SUBROUTINE name, you can provide a BLOCK
	     as	an anonymous, in-line sort subroutine.

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

	     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







Page 69				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 everything 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	whitespace (/[ \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



Page 70				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     (though it	may split into fewer).	If LIMIT is
	     unspecified, trailing null	fields are stripped
	     (which potential users of pop() would do well to
	     remember).	 A pattern matching the	null string (not
	     to	be confused with a null	pattern	//, which is just
	     one member	of the set of patterns matching	a null
	     string) will split	the value of EXPR into separate
	     characters	at each	point it matches that way.  For
	     example:

		  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 compilation	only once, use
	     /$variable/o.)  As	a special case,	specifying a
	     space (' ') will split on white space just	as split
	     with no arguments does, but leading white space does
	     NOT produce a null	first field.  Thus, split(' ')
	     can be used to emulate awk's default behavior,
	     whereas split(/ /)	will give you as many null
	     initial fields as there are leading spaces.

	     Example:





Page 71				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

     sqrt(EXPR)

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

     srand(EXPR)

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

     stat(FILEHANDLE)

     stat FILEHANDLE

     stat(EXPR)

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

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

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

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




Page 72				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

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

	     Note that if you have to look for strings that you
	     don't know	till runtime, you can build an entire



Page 73				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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


     substr(EXPR,OFFSET,LEN)

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

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

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







Page 74				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 context,	you may	need to	add 0 to them to
	     force them	to look	like numbers.

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


     sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)

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

     system(LIST)

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

     syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)







Page 75				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 particular location in a
	     directory.	 Has the same caveats about possible
	     directory compaction as the corresponding system
	     library routine.

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

     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



Page 76				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 specified, sequences of characters that
	     were translated to	the same character are squashed
	     down to 1 instance	of the character.

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

	     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.





Page 77				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 predefined
	     variables or dbm array values.)  Always returns the
	     undefined value.  You can omit the	EXPR, in which
	     case nothing is undefined,	but you	still get an
	     undefined value that you could, for instance, return
	     from a subroutine.	 Examples:

		  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 successfully	deleted.

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

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

     unpack(TEMPLATE,EXPR)
	     Unpack does the reverse of	pack: it takes a string
	     representing a structure and expands it out into an
	     array value, returning the	array value.  (In a
	     scalar context, it	merely returns the first value



Page 78				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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	indicate that you want a <number>-bit checksum of
	     the items instead of the items themselves.	 Default
	     is	a 16-bit checksum.  For	example, the following
	     computes the same number as the System V sum
	     program:

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


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

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


     utime(LIST)

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

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





Page 79				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 apparently random order, but it is
	     the same order as either the keys() or each()
	     function would produce on the same	array.	See also
	     keys() and	each().

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

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

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

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

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

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

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

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

	     then you can do a non-blocking wait for any process.
	     Non-blocking wait is only available on machines
	     supporting	either the waitpid (2) or wait4	(2)
	     system calls.  However, waiting for a particular pid
	     with FLAGS	of 0 is	implemented everywhere.	 (Perl



Page 80				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 subroutine is looking for an array value.
	     Returns false if the context 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 specified file, using the format associated with
	     that file.	 By default the	format for a file is the
	     one having	the same name is the filehandle, but the
	     format for	the current output channel (see	select)
	     may be set	explicitly by assigning	the name of the
	     format to the $~ variable.

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

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



Page 81				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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)



Page 82				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  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 operators tend to gobble	up all the
     arguments that follow them, and then act like a simple term
     with regard to the	preceding expression.  Note that you have
     to	be careful with	parens:

	  # 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 statement
     may be used to specify the	returned value and exit	the
     subroutine.  To create local variables see	the local
     operator.




Page 83				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 @_



Page 84				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     array at the time of the call is visible to subroutine
     instead.

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

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


     Passing By	Reference

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

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

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

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

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




Page 85				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 mechanism 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 routines are derived from	Henry
     Spencer's freely redistributable reimplementation 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
     interpretations.  Within character	classes	\b represents
     backspace rather than a word boundary.  Alternatives may be
     separated by |.  The bracketing construct ( ... ) may also
     be	used, in which case \<digit> matches the digit'th
     substring.	 (Outside of the pattern, always use $ instead of
     \ in front	of the digit.  The scope of $<digit> (and $`, $&
     and $') extends to	the end	of the enclosing BLOCK or eval
     string, or	to the next pattern match with subexpressions.
     The \<digit> notation 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
     substrings, the variables $10, $11, ... refer to the
     corresponding substring.  Within the pattern, \10,	\11, etc.
     refer back	to substrings if there have been at least that
     many left parens before the backreference.	 Otherwise (for
     backward compatibilty) \10	is the same as \010, a backspace,
     and \11 the same as \011, a tab.  And so on.  (\1 through \9
     are always	backreferences.)

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

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

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




Page 86				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     By	default, the ^ character is only guaranteed to match at
     the beginning of the string, the $	character only at the end
     (or before	the newline at the end)	and perl does certain
     optimizations with	the assumption that the	string contains
     only one line.  The behavior of ^ and $ on	embedded newlines
     will be inconsistent.  You	may, however, wish to treat a
     string as a multi-line buffer, such that the ^ will match
     after any newline within the string, and $	will match before
     any newline.  At the cost of a little more	overhead, you can
     do	this by	setting	the variable $*	to 1.  Setting it back to
     0 makes 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 alphanumeric, such as \b, \w, \n.  Unlike some	other
     regular expression	languages, there are no	backslashed
     symbols that aren't alphanumeric.	So anything that looks
     like \\, \(, \), \<, \>, \{, or \}	is always interpreted as
     a literal character, not a	metacharacter.	This makes it
     simple to quote a string that you want to use for a pattern
     but that you are afraid might contain metacharacters.
     Simply quote all the non-alphanumeric characters:

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





Page 87				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 # characters (with an	optional .) to specify a
     numeric field.  (Use of ^ instead of @ causes the field to
     be	blanked	if undefined.)	If any of the values supplied for
     these fields contains a newline, only the text up to the
     newline is	printed.  The special field @* can be used for
     printing multi-line values.  It should appear by itself on	a
     line.

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

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



Page 88				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 translated to a space
     upon output.  If you put a	second tilde contiguous	to the
     first, the	line will be repeated until all	the fields on the
     line are exhausted.  (If you use a	field of the @ variety,
     the expression you	supply had better not give the same value
     every time	forever!)

     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
     .




























Page 89				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     # 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 channel, 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 forgetting 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 differently than C
     file descriptors.	Second,	perl already knows the length of
     its strings, so you don't need to pass that information.
     Here is a sample client (untested):

	  ($them,$port)	= @ARGV;



Page 90				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  $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')



Page 91				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	       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($_)



Page 92				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     (Mnemonic:	underline is understood	in certain
	     operations.)

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

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

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

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

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

     $#	     The output	format for printed numbers.  This
	     variable is a half-hearted	attempt	to emulate awk's



Page 93				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     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 channel.  (Mnemonic: % is page number in
	     nroff.)

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

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

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

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

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

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

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






Page 94				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     $&	     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 successful pattern match (not	counting any
	     matches hidden within a BLOCK or eval enclosed by
	     the current BLOCK).  (Mnemonic: ` often precedes a
	     quoted string.)

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

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


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

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

	     (Mnemonic:	be positive and	forward	looking.)

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

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

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




Page 95				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     $[	     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	subscripting and when
	     evaluating	the index() and	substr() functions.
	     (Mnemonic:	[ begins subscripts.)

     $]	     The string	printed	out when you say "perl -v".  It
	     can be used to determine at the beginning of a
	     script whether the	perl interpreter executing the
	     script is in the right range of versions.	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.)




Page 96				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

     $>	     The effective uid of this process.	 Example:

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

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

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

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

	     Note: $<, $>, $( and $) can only be set on	machines



Page 97				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	     that support 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 broken to fill continuation	fields (starting
	     with ^) in	a format.  Default is "	\n-", to break on
	     whitespace	or hyphens.  (Mnemonic:	a "colon" in
	     poetry is a part of a line.)

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

     $^F     The maximum system	file descriptor, ordinarily 2.
	     System file descriptors are passed	to subprocesses,
	     while higher file descriptors are not.  During an
	     open, system file descriptors are preserved even if
	     the open fails.  Ordinary file 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 arguments minus one, since
	     $ARGV[0] is the first argument, NOT the command
	     name.  See	$0 for the command name.





Page 98				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     @INC    The array INC contains the	list of	places to look
	     for perl scripts to be evaluated by the "do EXPR"
	     command or	the "require" command.	It initially
	     consists of the arguments to any -I command line
	     switches, followed	by the default perl library,
	     probably "/usr/local/lib/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 processes.

     $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 package declaration, you can
     switch namespaces.	 The scope of the package declaration is
     from the declaration itself to the	end of the enclosing
     block (the	same scope as the local() operator).  Typically
     it	would be the first declaration in a file to be included



Page 99				  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     by	the "require" operator.	 You can switch	into a package in
     more than one place; it merely influences which symbol table
     is	used by	the compiler for the rest of that block.  You can
     refer to variables	and filehandles	in other packages 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 symbol 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 compiled in.  (Assignments to $SIG{}, however,
     assume the	signal handler specified is in the main	package.
     Qualify the signal	handler	name if	you wish to have a signal
     handler in	a package.)  For an example, examine perldb.pl in
     the perl library.	It initially switches to the DB	package
     so	that the debugger doesn't interfere with variables in the
     script you	are trying to debug.  At various points, however,
     it	temporarily switches back to the main package to evaluate
     various expressions in the	context	of the main package.

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

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

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











Page 100			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	  package dumpvar;

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

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

     Style

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

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

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

	 is better than

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




Page 101			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



	 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 arguments doesn't mean	that you have to make use
	 of the	defaults.  The defaults	are there for lazy
	 systems programmers writing one-shot programs.	 If you
	 want your program to be readable, consider supplying the
	 argument.

	 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 probably 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 readability as	well as	to allow multi-level loop
	 breaks.  See last example.




Page 102			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

     5.	 Choose	mnemonic identifiers.

     6.	 Be consistent.

     Debugging

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

     h		 Prints	out a help message.

     T		 Stack trace.

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

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

     f		 Finish.  Executes statements until it has
		 finished the current 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.






Page 103			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 breakpoint	on the line that is about to be
		 executed.

     D		 Delete	all breakpoints.

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

     A		 Delete	all line actions.

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

     > 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	newlines.




Page 104			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 redirected	to.

     If	you want to modify the debugger, copy perldb.pl	from the
     perl library to your current directory and	modify it as
     necessary.	 (You'll also have to put -I. on your command
     line.)  You can do	some customization 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 evaluation scheme with fewer hidden
     "gotchas".	 Additionally, since the language has more
     built-in functionality, it	has to rely less upon external
     (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,



Page 105			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     perl will complain	loudly that your setuid	script is
     insecure.	You'll need to either disable the kernel setuid
     script feature, or	put a C	wrapper	around the script.

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




Page 106			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

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

ENVIRONMENT
     HOME	 Used if chdir has no argument.

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

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

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

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

		      require 'perldb.pl'


     Apart from	these, perl uses no other environment variables,
     except to make them available to the script being executed,
     and to child processes.  However, scripts running setuid
     would do well to execute the following lines before doing



Page 107			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     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 messages such as "Insecure dependency".  See	the
     section on	setuid scripts.

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

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

     *	 Curly brackets	are required on	ifs and	whiles.

     *	 Variables begin with $	or @ in	perl.

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

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

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

     *	 You have to decide whether you	want to	use string or
	 numeric comparisons.



Page 108			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



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

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

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

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

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

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

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

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

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

     *	 Next, exit and	continue work differently.

     *	 The following variables work differently

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



Page 109			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     *	 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 backslashes in front.

     *	 The range operator is .. rather than comma.

     Sharp shell programmers should take note of the following:

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

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

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




Page 110			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     *	 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



Page 111			  Nixdorf TARGON Operating System






		     Printed August 7, 1992
PERL(1)



     regular expression.

     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 operations	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 component of your PATH may be longer
     than 255 if you use -S.  A	regular	expression may not
     compile to	more than 32767	bytes internally.

     Perl actually stands for Pathologically Eclectic Rubbish
     Lister, but don't tell anyone I said that.












Page 112			  Nixdorf TARGON Operating System



