perl 4.0.00: (no release announcement available)perl-4.0.00

So far, 4.0 is still a beta test version.  For the last production
version, look in pub/perl.3.0/kits@44.

1 files changed, 0 insertions, 1188 deletions

diff --git a/perl.man.2 b/perl.man.2
deleted file mode 100644
index a6ab6a1a86..0000000000
--- a/perl.man.2
+++ /dev/null
@@ -1,1188 +0,0 @@
-''' Beginning of part 2
-''' $Header: perl_man.2,v 3.0.1.11 91/01/11 18:17:08 lwall Locked $
-'''
-''' $Log:	perl.man.2,v $
-''' Revision 3.0.1.11  91/01/11  18:17:08  lwall
-''' patch42: fixed some man page entries
-''' 
-''' Revision 3.0.1.10  90/11/10  01:46:29  lwall
-''' patch38: random cleanup
-''' patch38: added alarm function
-''' 
-''' Revision 3.0.1.9  90/10/15  18:17:37  lwall
-''' patch29: added caller
-''' patch29: index and substr now have optional 3rd args
-''' patch29: added SysV IPC
-''' 
-''' Revision 3.0.1.8  90/08/13  22:21:00  lwall
-''' patch28: documented that you can't interpolate $) or $| in pattern
-''' 
-''' Revision 3.0.1.7  90/08/09  04:27:04  lwall
-''' patch19: added require operator
-''' 
-''' Revision 3.0.1.6  90/08/03  11:15:29  lwall
-''' patch19: Intermediate diffs for Randal
-''' 
-''' Revision 3.0.1.5  90/03/27  16:15:17  lwall
-''' patch16: MSDOS support
-''' 
-''' Revision 3.0.1.4  90/03/12  16:46:02  lwall
-''' patch13: documented behavior of @array = /noparens/
-''' 
-''' Revision 3.0.1.3  90/02/28  17:55:58  lwall
-''' patch9: grep now returns number of items matched in scalar context
-''' patch9: documented in-place modification capabilites of grep
-''' 
-''' Revision 3.0.1.2  89/11/17  15:30:16  lwall
-''' patch5: fixed some manual typos and indent problems
-''' 
-''' Revision 3.0.1.1  89/11/11  04:43:10  lwall
-''' patch2: made some line breaks depend on troff vs. nroff
-''' patch2: example of unshift had args backwards
-''' 
-''' Revision 3.0  89/10/18  15:21:37  lwall
-''' 3.0 baseline
-''' 
-'''
-.PP
-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 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.
-.Ip "/PATTERN/" 8 4
-See m/PATTERN/.
-.Ip "?PATTERN?" 8 4
-This is just like the /pattern/ search, except that it matches only once between
-calls to the
-.I 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.
-.Ip "accept(NEWSOCKET,GENERICSOCKET)" 8 2
-Does the same thing that the accept system call does.
-Returns true if it succeeded, false otherwise.
-See example in section on Interprocess Communication.
-.Ip "alarm(SECONDS)" 8 4
-.Ip "alarm SECONDS" 8
-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.
-.Ip "atan2(Y,X)" 8 2
-Returns the arctangent of Y/X in the range
-.if t \-\(*p to \(*p.
-.if n \-PI to PI.
-.Ip "bind(SOCKET,NAME)" 8 2
-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.
-.Ip "binmode(FILEHANDLE)" 8 4
-.Ip "binmode FILEHANDLE" 8 4
-Arranges for the file to be read in \*(L"binary\*(R" 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.
-.Ip "caller(EXPR)"
-.Ip "caller"
-Returns the context of the current subroutine call:
-.nf
-
-	($package,$filename,$line) = caller;
-
-.fi
-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.
-.Ip "chdir(EXPR)" 8 2
-.Ip "chdir EXPR" 8 2
-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
-.IR die .
-.Ip "chmod(LIST)" 8 2
-.Ip "chmod LIST" 8 2
-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.
-.nf
-
-.ne 2
-	$cnt = chmod 0755, \'foo\', \'bar\';
-	chmod 0755, @executables;
-
-.fi
-.Ip "chop(LIST)" 8 7
-.Ip "chop(VARIABLE)" 8
-.Ip "chop VARIABLE" 8
-.Ip "chop" 8
-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/\en// because it neither scans nor copies
-the string.
-If VARIABLE is omitted, chops $_.
-Example:
-.nf
-
-.ne 5
-	while (<>) {
-		chop;	# avoid \en on last field
-		@array = split(/:/);
-		.\|.\|.
-	}
-
-.fi
-You can actually chop anything that's an lvalue, including an assignment:
-.nf
-
-	chop($cwd = \`pwd\`);
-	chop($answer = <STDIN>);
-
-.fi
-If you chop a list, each element is chopped.
-Only the value of the last chop is returned.
-.Ip "chown(LIST)" 8 2
-.Ip "chown LIST" 8 2
-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.
-.nf
-
-.ne 2
-	$cnt = chown $uid, $gid, \'foo\', \'bar\';
-	chown $uid, $gid, @filenames;
-
-.fi
-.ne 23
-Here's an example of looking up non-numeric uids:
-.nf
-
-	print "User: ";
-	$user = <STDIN>;
-	chop($user);
-	print "Files: "
-	$pattern = <STDIN>;
-	chop($pattern);
-.ie t \{\
-	open(pass, \'/etc/passwd\') || die "Can't open passwd: $!\en";
-'br\}
-.el \{\
-	open(pass, \'/etc/passwd\')
-		|| die "Can't open passwd: $!\en";
-'br\}
-	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;
-	}
-
-.fi
-.Ip "chroot(FILENAME)" 8 5
-.Ip "chroot FILENAME" 8
-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 $_.
-.Ip "close(FILEHANDLE)" 8 5
-.Ip "close FILEHANDLE" 8
-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
-.IR open .)
-However, an explicit close on an input file resets the line counter ($.), while
-the implicit close done by
-.I 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:
-.nf
-
-.ne 4
-	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
-
-.fi
-FILEHANDLE may be an expression whose value gives the real filehandle name.
-.Ip "closedir(DIRHANDLE)" 8 5
-.Ip "closedir DIRHANDLE" 8
-Closes a directory opened by opendir().
-.Ip "connect(SOCKET,NAME)" 8 2
-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.
-.Ip "cos(EXPR)" 8 6
-.Ip "cos EXPR" 8 6
-Returns the cosine of EXPR (expressed in radians).
-If EXPR is omitted takes cosine of $_.
-.Ip "crypt(PLAINTEXT,SALT)" 8 6
-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.
-.Ip "dbmclose(ASSOC_ARRAY)" 8 6
-.Ip "dbmclose ASSOC_ARRAY" 8
-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.
-.Ip "dbmopen(ASSOC,DBNAME,MODE)" 8 6
-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 only have one
-dbmopen in your program.
-If your system has neither dbm nor ndbm, calling dbmopen produces a fatal
-error.
-.Sp
-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.
-.Sp
-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.
-.Sp
-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:
-.nf
-
-.ne 6
-	# print out history file offsets
-	dbmopen(HIST,'/usr/lib/news/history',0666);
-	while (($key,$val) = each %HIST) {
-		print $key, ' = ', unpack('L',$val), "\en";
-	}
-	dbmclose(HIST);
-
-.fi
-.Ip "defined(EXPR)" 8 6
-.Ip "defined EXPR" 8
-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:
-.nf
-
-.ne 7
-	print if defined $switch{'D'};
-	print "$val\en" 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"; }
-
-.fi
-See also undef.
-.Ip "delete $ASSOC{KEY}" 8 6
-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.
-.Sp
-The following deletes all the values of an associative array:
-.nf
-
-.ne 3
-	foreach $key (keys %ARRAY) {
-		delete $ARRAY{$key};
-	}
-
-.fi
-(But it would be faster to use the
-.I reset
-command.
-Saying undef %ARRAY is faster yet.)
-.Ip "die(LIST)" 8
-.Ip "die LIST" 8
-Outside of an eval, prints the value of LIST to
-.I 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.
-.Sp
-Equivalent examples:
-.nf
-
-.ne 3
-.ie t \{\
-	die "Can't cd to spool: $!\en" unless chdir \'/usr/spool/news\';
-'br\}
-.el \{\
-	die "Can't cd to spool: $!\en"
-		unless chdir \'/usr/spool/news\';
-'br\}
-
-	chdir \'/usr/spool/news\' || die "Can't cd to spool: $!\en" 
-
-.fi
-.Sp
-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 \*(L", stopped\*(R" to your message will cause it to make
-better sense when the string \*(L"at foo line 123\*(R" is appended.
-Suppose you are running script \*(L"canasta\*(R".
-.nf
-
-.ne 7
-	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.
-
-.fi
-See also
-.IR exit .
-.Ip "do BLOCK" 8 4
-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.)
-.Ip "do SUBROUTINE (LIST)" 8 3
-Executes a SUBROUTINE declared by a
-.I 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 \*(L"defined\*(R" 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.)
-SUBROUTINE may be a scalar variable, in which case the variable contains
-the name of the subroutine to execute.
-The parentheses are required to avoid confusion with the \*(L"do EXPR\*(R"
-form.
-.Sp
-As an alternate 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.
-.Ip "do EXPR" 8 3
-Uses the value of EXPR as a filename and executes the contents of the file
-as a
-.I perl
-script.
-Its primary use is to include subroutines from a
-.I perl
-subroutine library.
-.nf
-
-	do \'stat.pl\';
-
-is just like
-
-	eval \`cat stat.pl\`;
-
-.fi
-except that it's more efficient, more concise, keeps track of the current
-filename for error messages, and searches all the
-.B \-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 \*(L";#\*(R" for standalone comments.)
-Note that the following are NOT equivalent:
-.nf
-
-.ne 2
-	do $foo;	# eval a file
-	do $foo();	# call a subroutine
-
-.fi
-Note that inclusion of library routines is better done with
-the \*(L"require\*(R" operator.
-.Ip "dump LABEL" 8 6
-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.
-.Sp
-Example:
-.nf
-
-.ne 16
-	#!/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');
-
-.fi
-.Ip "each(ASSOC_ARRAY)" 8 6
-.Ip "each ASSOC_ARRAY" 8
-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:
-.nf
-
-.ne 3
-	while (($key,$value) = each %ENV) {
-		print "$key=$value\en";
-	}
-
-.fi
-See also keys() and values().
-.Ip "eof(FILEHANDLE)" 8 8
-.Ip "eof()" 8
-.Ip "eof" 8
-Returns 1 if the next read on FILEHANDLE will return end of file, or if
-FILEHANDLE is not open.
-FILEHANDLE may be an expression whose value gives the real filehandle name.
-(Note that this function actually reads a character and then ungetc's it,
-so it is not very useful in an interactive context.)
-An eof without an argument returns the eof status for the last file read.
-Empty parentheses () may be used to indicate the pseudo file formed of the
-files listed on the command line, i.e. eof() is reasonable to use inside
-a while (<>) loop to detect the end of only the last file.
-Use eof(ARGV) or eof without the parentheses to test EACH file in a while (<>) loop.
-Examples:
-.nf
-
-.ne 7
-	# insert dashes just before last line of last file
-	while (<>) {
-		if (eof()) {
-			print "\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\en";
-		}
-		print;
-	}
-
-.ne 7
-	# reset line numbering on each input file
-	while (<>) {
-		print "$.\et$_";
-		if (eof) {	# Not eof().
-			close(ARGV);
-		}
-	}
-
-.fi
-.Ip "eval(EXPR)" 8 6
-.Ip "eval EXPR" 8 6
-EXPR is parsed and executed as if it were a little
-.I perl
-program.
-It is executed in the context of the current
-.I 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.
-.Sp
-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, where the die operator is
-used to raise exceptions.
-.Ip "exec(LIST)" 8 8
-.Ip "exec LIST" 8 6
-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 \*(L"/bin/sh \-c\*(R" 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:
-.nf
-
-	exec \'/bin/echo\', \'Your arguments are: \', @ARGV;
-	exec "sort $outfile | uniq";
-
-.fi
-.Sp
-If you don't really want to execute the first argument, but want to lie
-to the program you are executing about its own name, you can specify
-the program you actually want to run by assigning that to a variable and
-putting the name of the 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:
-.nf
-
-.ne 2
-	$shell = '/bin/csh';
-	exec $shell '-sh';		# pretend it's a login shell
-
-.fi
-.Ip "exit(EXPR)" 8 6
-.Ip "exit EXPR" 8
-Evaluates EXPR and exits immediately with that value.
-Example:
-.nf
-
-.ne 2
-	$ans = <STDIN>;
-	exit 0 \|if \|$ans \|=~ \|/\|^[Xx]\|/\|;
-
-.fi
-See also
-.IR die .
-If EXPR is omitted, exits with 0 status.
-.Ip "exp(EXPR)" 8 3
-.Ip "exp EXPR" 8
-Returns
-.I e
-to the power of EXPR.
-If EXPR is omitted, gives exp($_).
-.Ip "fcntl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
-Implements the fcntl(2) function.
-You'll probably have to say
-.nf
-
-	require "fcntl.ph";	# probably /usr/local/lib/perl/fcntl.ph
-
-.fi
-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).
-.Ip "fileno(FILEHANDLE)" 8 4
-.Ip "fileno FILEHANDLE" 8 4
-Returns the file descriptor for a filehandle.
-Useful for constructing bitmaps for select().
-If FILEHANDLE is an expression, the value is taken as the name of
-the filehandle.
-.Ip "flock(FILEHANDLE,OPERATION)" 8 4
-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.
-.nf
-
-.ne 20
-	$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,"\en\en";
-	do unlock();
-
-.fi
-.Ip "fork" 8 4
-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.
-.Ip "getc(FILEHANDLE)" 8 4
-.Ip "getc FILEHANDLE" 8
-.Ip "getc" 8
-Returns the next character from the input file attached to FILEHANDLE, or
-a null string at EOF.
-If FILEHANDLE is omitted, reads from STDIN.
-.Ip "getlogin" 8 3
-Returns the current login from /etc/utmp, if any.
-If null, use getpwuid.
-
-	$login = getlogin || (getpwuid($<))[0] || "Somebody";
-
-.Ip "getpeername(SOCKET)" 8 3
-Returns the packed sockaddr address of other end of the SOCKET connection.
-.nf
-
-.ne 4
-	# An internet sockaddr
-	$sockaddr = 'S n a4 x8';
-	$hersockaddr = getpeername(S);
-.ie t \{\
-	($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
-'br\}
-.el \{\
-	($family, $port, $heraddr) =
-			unpack($sockaddr,$hersockaddr);
-'br\}
-
-.fi
-.Ip "getpgrp(PID)" 8 4
-.Ip "getpgrp PID" 8
-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.
-.Ip "getppid" 8 4
-Returns the process id of the parent process.
-.Ip "getpriority(WHICH,WHO)" 8 4
-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).
-.Ip "getpwnam(NAME)" 8
-.Ip "getgrnam(NAME)" 8
-.Ip "gethostbyname(NAME)" 8
-.Ip "getnetbyname(NAME)" 8
-.Ip "getprotobyname(NAME)" 8
-.Ip "getpwuid(UID)" 8
-.Ip "getgrgid(GID)" 8
-.Ip "getservbyname(NAME,PROTO)" 8
-.Ip "gethostbyaddr(ADDR,ADDRTYPE)" 8
-.Ip "getnetbyaddr(ADDR,ADDRTYPE)" 8
-.Ip "getprotobynumber(NUMBER)" 8
-.Ip "getservbyport(PORT,PROTO)" 8
-.Ip "getpwent" 8
-.Ip "getgrent" 8
-.Ip "gethostent" 8
-.Ip "getnetent" 8
-.Ip "getprotoent" 8
-.Ip "getservent" 8
-.Ip "setpwent" 8
-.Ip "setgrent" 8
-.Ip "sethostent(STAYOPEN)" 8
-.Ip "setnetent(STAYOPEN)" 8
-.Ip "setprotoent(STAYOPEN)" 8
-.Ip "setservent(STAYOPEN)" 8
-.Ip "endpwent" 8
-.Ip "endgrent" 8
-.Ip "endhostent" 8
-.Ip "endnetent" 8
-.Ip "endprotoent" 8
-.Ip "endservent" 8
-These routines perform the same functions as their counterparts in the
-system library.
-The return values from the various get routines are as follows:
-.nf
-
-	($name,$passwd,$uid,$gid,
-	   $quota,$comment,$gcos,$dir,$shell) = getpw.\|.\|.
-	($name,$passwd,$gid,$members) = getgr.\|.\|.
-	($name,$aliases,$addrtype,$length,@addrs) = gethost.\|.\|.
-	($name,$aliases,$addrtype,$net) = getnet.\|.\|.
-	($name,$aliases,$proto) = getproto.\|.\|.
-	($name,$aliases,$port,$proto) = getserv.\|.\|.
-
-.fi
-The $members value returned by getgr.\|.\|. is a space separated list
-of the login names of the members of the group.
-.Sp
-The @addrs value returned by the gethost.\|.\|. functions 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:
-.nf
-
-	($a,$b,$c,$d) = unpack('C4',$addr[0]);
-
-.fi
-.Ip "getsockname(SOCKET)" 8 3
-Returns the packed sockaddr address of this end of the SOCKET connection.
-.nf
-
-.ne 4
-	# An internet sockaddr
-	$sockaddr = 'S n a4 x8';
-	$mysockaddr = getsockname(S);
-.ie t \{\
-	($family, $port, $myaddr) = unpack($sockaddr,$mysockaddr);
-'br\}
-.el \{\
-	($family, $port, $myaddr) =
-			unpack($sockaddr,$mysockaddr);
-'br\}
-
-.fi
-.Ip "getsockopt(SOCKET,LEVEL,OPTNAME)" 8 3
-Returns the socket option requested, or undefined if there is an error.
-.Ip "gmtime(EXPR)" 8 4
-.Ip "gmtime EXPR" 8
-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:
-.nf
-
-.ne 3
-.ie t \{\
-    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time);
-'br\}
-.el \{\
-    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
-						gmtime(time);
-'br\}
-
-.fi
-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).
-.Ip "goto LABEL" 8 6
-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
-.IR sed -to- perl
-translator easier.
-I may change its semantics at any time, consistent with support for translated
-.I sed
-scripts.
-Use it at your own risk.
-Better yet, don't use it at all.
-.Ip "grep(EXPR,LIST)" 8 4
-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.
-.nf
-
-	@foo = grep(!/^#/, @bar);    # weed out comments
-
-.fi
-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.
-.Ip "hex(EXPR)" 8 4
-.Ip "hex EXPR" 8
-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 $_.
-.Ip "index(STR,SUBSTR,POSITION)" 8 4
-.Ip "index(STR,SUBSTR)" 8 4
-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.
-.Ip "int(EXPR)" 8 4
-.Ip "int EXPR" 8
-Returns the integer portion of EXPR.
-If EXPR is omitted, uses $_.
-.Ip "ioctl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
-Implements the ioctl(2) function.
-You'll probably have to say
-.nf
-
-	require "ioctl.ph";	# probably /usr/local/lib/perl/ioctl.ph
-
-.fi
-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.
-.nf
-
-.ne 9
-	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: $!";
-	}
-
-.fi
-The return value of ioctl (and fcntl) is as follows:
-.nf
-
-.ne 4
-	if OS returns:\h'|3i'perl returns:
-	  -1\h'|3i'  undefined value
-	  0\h'|3i'  string "0 but true"
-	  anything else\h'|3i'  that number
-
-.fi
-Thus perl returns true on success and false on failure, yet you can still
-easily determine the actual value returned by the operating system:
-.nf
-
-	($retval = ioctl(...)) || ($retval = -1);
-	printf "System returned %d\en", $retval;
-.fi
-.Ip "join(EXPR,LIST)" 8 8
-.Ip "join(EXPR,ARRAY)" 8
-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:
-.nf
-    
-.ie t \{\
-    $_ = join(\|\':\', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
-'br\}
-.el \{\
-    $_ = join(\|\':\',
-		$login,$passwd,$uid,$gid,$gcos,$home,$shell);
-'br\}
-
-.fi
-See
-.IR split .
-.Ip "keys(ASSOC_ARRAY)" 8 6
-.Ip "keys ASSOC_ARRAY" 8
-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:
-.nf
-
-.ne 5
-	@keys = keys %ENV;
-	@values = values %ENV;
-	while ($#keys >= 0) {
-		print pop(@keys), \'=\', pop(@values), "\en";
-	}
-
-or how about sorted by key:
-
-.ne 3
-	foreach $key (sort(keys %ENV)) {
-		print $key, \'=\', $ENV{$key}, "\en";
-	}
-
-.fi
-.Ip "kill(LIST)" 8 8
-.Ip "kill LIST" 8 2
-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.
-.nf
-
-	$cnt = kill 1, $child1, $child2;
-	kill 9, @goners;
-
-.fi
-If the signal is negative, kills process groups instead of processes.
-(On System V, a negative \fIprocess\fR number will also kill process groups,
-but that's not portable.)
-You may use a signal name in quotes.
-.Ip "last LABEL" 8 8
-.Ip "last" 8
-The
-.I last
-command is like the
-.I 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
-.I continue
-block, if any, is not executed:
-.nf
-
-.ne 4
-	line: while (<STDIN>) {
-		last line if /\|^$/;	# exit when done with header
-		.\|.\|.
-	}
-
-.fi
-.Ip "length(EXPR)" 8 4
-.Ip "length EXPR" 8
-Returns the length in characters of the value of EXPR.
-If EXPR is omitted, returns length of $_.
-.Ip "link(OLDFILE,NEWFILE)" 8 2
-Creates a new filename linked to the old filename.
-Returns 1 for success, 0 otherwise.
-.Ip "listen(SOCKET,QUEUESIZE)" 8 2
-Does the same thing that the listen system call does.
-Returns true if it succeeded, false otherwise.
-See example in section on Interprocess Communication.
-.Ip "local(LIST)" 8 4
-Declares the listed variables to be local to the enclosing block,
-subroutine, eval or \*(L"do\*(R".
-All the listed elements must be legal lvalues.
-This operator works by saving the current values of those variables in LIST
-on a hidden stack and 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:
-.nf
-
-.ne 13
-	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;
-	}
-
-.ne 6
-	if ($sw eq \'-v\') {
-	    # init local array with global array
-	    local(@ARGV) = @ARGV;
-	    unshift(@ARGV,\'echo\');
-	    system @ARGV;
-	}
-	# @ARGV restored
-
-.ne 6
-	# temporarily add to digits associative array
-	if ($base12) {
-		# (NOTE: not claiming this is efficient!)
-		local(%digits) = (%digits,'t',10,'e',11);
-		do parse_num();
-	}
-
-.fi
-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.
-.Ip "localtime(EXPR)" 8 4
-.Ip "localtime EXPR" 8
-Converts a time as returned by the time function to a 9-element array with
-the time analyzed for the local timezone.
-Typically used as follows:
-.nf
-
-.ne 3
-.ie t \{\
-    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
-'br\}
-.el \{\
-    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
-						localtime(time);
-'br\}
-
-.fi
-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).
-.Ip "log(EXPR)" 8 4
-.Ip "log EXPR" 8
-Returns logarithm (base
-.IR e )
-of EXPR.
-If EXPR is omitted, returns log of $_.
-.Ip "lstat(FILEHANDLE)" 8 6
-.Ip "lstat FILEHANDLE" 8
-.Ip "lstat(EXPR)" 8
-.Ip "lstat SCALARVARIABLE" 8
-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.
-.Ip "m/PATTERN/io" 8 4
-.Ip "/PATTERN/io" 8
-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.
-.Sp
-If / is the delimiter then the initial \*(L'm\*(R' is optional.
-With the \*(L'm\*(R' you can use any pair of non-alphanumeric characters
-as delimiters.
-This is particularly useful for matching Unix path names that contain \*(L'/\*(R'.
-If the final delimiter is followed by the optional letter \*(L'i\*(R', 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 like end-of-string tests.)
-If you want such a pattern to be compiled only once, add an \*(L"o\*(R" 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.
-.Sp
-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.
-.Sp
-Examples:
-.nf
-
-.ne 4
-    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#;
-
-.ne 5
-    # poor man's grep
-    $arg = shift;
-    while (<>) {
-	    print if /$arg/o;	# compile only once
-    }
-
-    if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
-
-.fi
-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.
-.Ip "mkdir(FILENAME,MODE)" 8 3
-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).
-.Ip "msgctl(ID,CMD,ARG)" 8 4
-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.
-.Ip "msgget(KEY,FLAGS)" 8 4
-Calls the System V IPC function msgget.  Returns the message queue id,
-or the undefined value if there is an error.
-.Ip "msgsnd(ID,MSG,FLAGS)" 8 4
-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.
-.Ip "msgrcv(ID,VAR,SIZE,TYPE,FLAGS)" 8 4
-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.