Import of Perl 5.003 into the tree. Makefile.bsd-wrapper and

config.sh.OpenBSD are the only local changes.

1 files changed, 441 insertions, 0 deletions

diff --git a/gnu/usr.bin/perl/pod/perlrun.pod b/gnu/usr.bin/perl/pod/perlrun.pod
new file mode 100644
index 00000000000..4f6294cc69b
--- /dev/null
+++ b/gnu/usr.bin/perl/pod/perlrun.pod
@@ -0,0 +1,441 @@
+=head1 NAME
+
+perlrun - how to execute the Perl interpreter
+
+=head1 SYNOPSIS
+
+B<perl>	S<[ B<-sTuU> ]>
+	S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+	S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+	S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+	S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
+	S<[ B<-P> ]>
+	S<[ B<-S> ]>
+	S<[ B<-x>[I<dir>] ]>
+	S<[ B<-i>[I<extension>] ]>
+	S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+
+=head1 DESCRIPTION
+
+Upon startup, Perl looks for your script in one of the following
+places:
+
+=over 4
+
+=item 1.
+
+Specified line by line via B<-e> switches on the command line.
+
+=item 2.
+
+Contained in the file specified by the first filename on the command line.
+(Note that systems supporting the #! notation invoke interpreters this way.)
+
+=item 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.
+
+=back
+
+With methods 2 and 3, Perl starts parsing the input file from the
+beginning, unless you've specified a B<-x> switch, in which case it
+scans for the first line starting with #! and containing the word
+"perl", and starts there instead.  This is useful for running a script
+embedded in a larger message.  (In this case you would indicate the end
+of the script using the __END__ token.)
+
+As of Perl 5, the #! line is always examined for switches as the line is
+being parsed.  Thus, if you're on a machine that only allows one argument
+with the #! line, or worse, doesn't even recognize the #! line, you still
+can get consistent switch behavior regardless of how Perl was invoked,
+even if B<-x> was used to find the beginning of the script.
+
+Because many operating systems silently chop off kernel interpretation of
+the #! line after 32 characters, some switches may be passed in on the
+command line, and some may not; you could even get a "-" without its
+letter, if you're not careful.  You probably want to make sure that all
+your switches fall either before or after that 32 character boundary.
+Most switches don't actually care if they're processed redundantly, but
+getting a - instead of a complete switch could cause Perl to try to
+execute standard input instead of your script.  And a partial B<-I> switch
+could also cause odd results.
+
+Parsing of the #! switches starts wherever "perl" is mentioned in the line.
+The sequences "-*" and "- " are specifically ignored so that you could,
+if you were so inclined, say
+
+    #!/bin/sh -- # -*- perl -*- -p
+    eval 'exec perl $0 -S ${1+"$@"}'
+	if 0;
+
+to let Perl see the B<-p> switch.
+
+If the #! line does not contain the word "perl", the program named after
+the #! is executed instead of the Perl interpreter.  This is slightly
+bizarre, but it helps people on machines that don't do #!, because they
+can tell a program that their SHELL is /usr/bin/perl, and Perl will then
+dispatch the program to the correct interpreter for them.
+
+After locating your script, Perl compiles the entire script to an
+internal form.  If there are any compilation errors, execution of the
+script is not attempted.  (This is unlike the typical shell script,
+which might run partway through before finding a syntax error.)
+
+If the script is syntactically correct, it is executed.  If the script
+runs off the end without hitting an exit() or die() operator, an implicit
+C<exit(0)> is provided to indicate successful completion.
+
+=head2 Switches
+
+A single-character switch may be combined with the following switch, if
+any.
+
+    #!/usr/bin/perl -spi.bak	# same as -s -p -i.bak
+
+Switches include:
+
+=over 5
+
+=item B<-0>[I<digits>]
+
+specifies the record separator (C<$/>) 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
+B<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.
+
+=item B<-a>
+
+turns on autosplit mode when used with a B<-n> or B<-p>.  An implicit
+split command to the @F array is done as the first thing inside the
+implicit while loop produced by the B<-n> or B<-p>.
+
+    perl -ane 'print pop(@F), "\n";'
+
+is equivalent to
+
+    while (<>) {
+	@F = split(' ');
+	print pop(@F), "\n";
+    }
+
+An alternate delimiter may be specified using B<-F>.
+
+=item B<-c>
+
+causes Perl to check the syntax of the script and then exit without
+executing it.  Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks,
+since these are considered as occurring outside the execution of 
+your program.
+
+=item B<-d>
+
+runs the script under the Perl debugger.  See L<perldebug>.
+
+=item B<-d:>I<foo>
+
+runs the script under the control of a debugging or tracing module
+installed as Devel::foo. E.g., B<-d:DProf> executes the script using the
+Devel::DProf profiler.  See L<perldebug>.
+
+=item B<-D>I<number>
+
+=item B<-D>I<list>
+
+sets debugging flags.  To watch how it executes your script, use
+B<-D14>.  (This only works if debugging is compiled into your
+Perl.)  Another nice value is B<-D1024>, which lists your compiled
+syntax tree.  And B<-D512> displays compiled regular expressions. As an
+alternative specify a list of letters instead of numbers (e.g. B<-D14> is
+equivalent to B<-Dtls>):
+
+        1  p  Tokenizing and Parsing
+        2  s  Stack Snapshots
+        4  l  Label Stack Processing
+        8  t  Trace Execution
+       16  o  Operator Node Construction
+       32  c  String/Numeric Conversions
+       64  P  Print Preprocessor Command for -P
+      128  m  Memory Allocation
+      256  f  Format Processing
+      512  r  Regular Expression Parsing
+     1024  x  Syntax Tree Dump
+     2048  u  Tainting Checks
+     4096  L  Memory Leaks (not supported anymore)
+     8192  H  Hash Dump -- usurps values()
+    16384  X  Scratchpad Allocation
+    32768  D  Cleaning Up
+
+=item B<-e> I<commandline>
+
+may be used to enter one line of script.  
+If B<-e> is given, Perl
+will not look for a script filename in the argument list.  
+Multiple B<-e> commands may
+be given to build up a multi-line script.  
+Make sure to use semicolons where you would in a normal program.
+
+=item B<-F>I<pattern>
+
+specifies the pattern to split on if B<-a> is also in effect.  The
+pattern may be surrounded by C<//>, C<""> or C<''>, otherwise it will be
+put in single quotes.
+
+=item B<-h>
+
+prints a summary of the options.
+
+=item B<-i>[I<extension>]
+
+specifies that files processed by the C<E<lt>E<gt>> construct are to be edited
+in-place.  It does this by renaming the input file, opening the output
+file by the original 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.  From the shell, 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 B<-i> form doesn't need to compare $ARGV to $oldargv to
+know when the filename has changed.  It does, however, use ARGVOUT for
+the selected filehandle.  Note that STDOUT is restored as the
+default output filehandle after the loop.
+
+You can use C<eof> without parenthesis to locate the end of each input file, 
+in case you want to append to each file, or reset line numbering (see 
+example in L<perlfunc/eof>).
+
+=item B<-I>I<directory>
+
+Directories specified by B<-I> are prepended to the search path for
+modules (@INC), and also tells the C preprocessor where to search for
+include files.  The C preprocessor is invoked with B<-P>; by default it
+searches /usr/include and /usr/lib/perl.
+
+=item B<-l>[I<octnum>]
+
+enables automatic line-ending processing.  It has two effects:  first,
+it automatically chomps the line terminator when used with B<-n> or
+B<-p>, and second, it assigns "C<$\>" to have the value of I<octnum> so that
+any print statements will have that line terminator added back on.  If
+I<octnum> is omitted, sets "C<$\>" to the current value of "C<$/>".  For
+instance, to trim lines to 80 columns:
+
+    perl -lpe 'substr($_, 80) = ""'
+
+Note that the assignment C<$\ = $/> is done when the switch is processed,
+so the input record separator can be different than the output record
+separator if the B<-l> switch is followed by a B<-0> switch:
+
+    gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
+
+This sets $\ to newline and then sets $/ to the null character.
+
+=item B<-m>[B<->]I<module>
+
+=item B<-M>[B<->]I<module>
+
+=item B<-M>[B<->]I<'module ...'>
+
+=item B<-[mM]>[B<->]I<module=arg[,arg]...>
+
+C<-m>I<module> executes C<use> I<module> C<();> before executing your
+script.
+
+C<-M>I<module> executes C<use> I<module> C<;> before executing your
+script.  You can use quotes to add extra code after the module name,
+e.g., C<-M'module qw(foo bar)'>.
+
+If the first character after the C<-M> or C<-m> is a dash (C<->)
+then the 'use' is replaced with 'no'.
+
+A little built-in syntactic sugar means you can also say
+C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for
+C<-M'module qw(foo bar)'>.  This avoids the need to use quotes when
+importing symbols.  The actual code generated by C<-Mmodule=foo,bar> is
+C<use module split(/,/,q{foo,bar})>.  Note that the C<=> form
+removes the distinction between C<-m> and C<-M>.
+
+=item B<-n>
+
+causes Perl to assume the following loop around your script, which
+makes it iterate over filename arguments somewhat like B<sed -n> or
+B<awk>:
+
+    while (<>) {
+	...		# your script goes here
+    }
+
+Note that the lines are not printed by default.  See B<-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 C<-exec> switch of B<find> because you don't
+have to start a process on every filename found.
+
+C<BEGIN> and C<END> blocks may be used to capture control before or after
+the implicit loop, just as in B<awk>.
+
+=item B<-p>
+
+causes Perl to assume the following loop around your script, which
+makes it iterate over filename arguments somewhat like B<sed>:
+
+
+    while (<>) {
+	...		# your script goes here
+    } continue {
+	print;
+    }
+
+Note that the lines are printed automatically.  To suppress printing
+use the B<-n> switch.  A B<-p> overrides a B<-n> switch.
+
+C<BEGIN> and C<END> blocks may be used to capture control before or after
+the implicit loop, just as in awk.
+
+=item B<-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".)
+
+=item B<-s>
+
+enables some rudimentary switch parsing for switches on the command
+line after the script name but before any filename arguments (or before
+a B<-->).  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 B<-xyz> switch.
+
+    #!/usr/bin/perl -s
+    if ($xyz) { print "true\n"; }
+
+=item B<-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 B<-S> tells Perl to search for the
+script if necessary.  After Perl locates the script, it parses the
+lines and ignores them because the variable $running_under_some_shell
+is never true.  A better construct than C<$*> would be C<${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;
+
+=item B<-T>
+
+forces "taint" checks to be turned on so you can test them.  Ordinarily these checks are
+done only when running setuid or setgid.  It's a good idea to turn
+them on explicitly for programs run on another's behalf, such as CGI
+programs.  See L<perlsec>.
+
+=item B<-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
+B<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 want to execute a portion of your script before dumping,
+use the dump() operator instead.  Note: availability of B<undump> is
+platform specific and may not be available for a specific port of
+Perl.
+
+=item B<-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.
+
+=item B<-v>
+
+prints the version and patchlevel of your Perl executable.
+
+=item B<-V>
+
+prints summary of the major perl configuration values and the current
+value of @INC.
+
+=item B<-V:>I<name>
+
+Prints to STDOUT the value of the named configuration variable.
+
+=item B<-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 values as a number that doesn't look like numbers, using
+an array as though it were a scalar, if
+your subroutines recurse more than 100 deep, and innumerable other things.
+See L<perldiag> and L<perltrap>.
+
+=item B<-x> I<directory>
+
+tells Perl that the script is embedded in a message.  Leading
+garbage will be discarded until the first line that starts with #! and
+contains the string "perl".  Any meaningful switches on that line will
+be applied (but only one group of switches, as with normal #!
+processing).  If a directory name is specified, Perl will switch to
+that directory before running the script.  The B<-x> switch only
+controls the the disposal of leading garbage.  The script must be
+terminated with C<__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).
+
+
+=back