diff options
Diffstat (limited to 'contrib/perl5/pod/perlrun.pod')
| -rw-r--r-- | contrib/perl5/pod/perlrun.pod | 731 |
1 files changed, 731 insertions, 0 deletions
diff --git a/contrib/perl5/pod/perlrun.pod b/contrib/perl5/pod/perlrun.pod new file mode 100644 index 000000000000..a0c85b917b30 --- /dev/null +++ b/contrib/perl5/pod/perlrun.pod @@ -0,0 +1,731 @@ +=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. See L<Location of Perl>.) + +=item 3. + +Passed in implicitly via standard input. This works only 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 C<__END__> token.) + +The #! line is always examined for switches as the line is being +parsed. Thus, if you're on a machine that allows only 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. + +Some switches do care if they are processed twice, for instance combinations +of B<-l> and B<-0>. Either put all the switches after the 32 character +boundary (if applicable), or replace the use of B<-0>I<digits> by +C<BEGIN{ $/ = "\0digits"; }>. + +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 /usr/bin/perl -wS $0 ${1+"$@"}' + if $running_under_some_shell; + +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 part-way 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 #! and quoting on non-Unix systems + +Unix's #! technique can be simulated on other systems: + +=over 4 + +=item OS/2 + +Put + + extproc perl -S -your_switches + +as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's +`extproc' handling). + +=item MS-DOS + +Create a batch file to run your script, and codify it in +C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source +distribution for more information). + +=item Win95/NT + +The Win95/NT installation, when using the Activeware port of Perl, +will modify the Registry to associate the F<.pl> extension with the perl +interpreter. If you install another port of Perl, including the one +in the Win32 directory of the Perl distribution, then you'll have to +modify the Registry yourself. Note that this means you can no +longer tell the difference between an executable Perl program +and a Perl library file. + +=item Macintosh + +Macintosh perl scripts will have the appropriate Creator and +Type, so that double-clicking them will invoke the perl application. + +=back + +Command-interpreters on non-Unix systems have rather different ideas +on quoting than Unix shells. You'll need to learn the special +characters in your command-interpreter (C<*>, C<\> and C<"> are +common) and how to protect whitespace and these characters to run +one-liners (see C<-e> below). + +On some systems, you may have to change single-quotes to double ones, +which you must I<NOT> do on Unix or Plan9 systems. You might also +have to change a single % to a %%. + +For example: + + # Unix + perl -e 'print "Hello world\n"' + + # MS-DOS, etc. + perl -e "print \"Hello world\n\"" + + # Macintosh + print "Hello world\n" + (then Run "Myscript" or Shift-Command-R) + + # VMS + perl -e "print ""Hello world\n""" + +The problem is that none of this is reliable: it depends on the command +and it is entirely possible neither works. If 4DOS was the command shell, this would +probably work better: + + perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" + +CMD.EXE in Windows NT slipped a lot of standard Unix functionality in +when nobody was looking, but just try to find documentation for its +quoting rules. + +Under the Macintosh, it depends which environment you are using. The MacPerl +shell, or MPW, is much like Unix shells in its support for several +quoting variants, except that it makes free use of the Macintosh's non-ASCII +characters as control characters. + +There is no general solution to all of this. It's just a mess. + +=head2 Location of Perl + +It may seem obvious to say, but Perl is useful only when users can +easily find it. When possible, it's good for both B</usr/bin/perl> and +B</usr/local/bin/perl> to be symlinks to the actual binary. If that +can't be done, system administrators are strongly encouraged to put +(symlinks to) perl and its accompanying utilities, such as perldoc, into +a directory typically found along a user's PATH, or in another obvious +and convenient place. + +In this documentation, C<#!/usr/bin/perl> on the first line of the script +will stand in for whatever method works on your system. + +=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 input 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 because 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, +because 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<letters> + +=item B<-D>I<number> + +sets debugging flags. To watch how it executes your script, use +B<-Dtls>. (This works only if debugging is compiled into your +Perl.) Another nice value is B<-Dx>, which lists your compiled +syntax tree. And B<-Dr> displays compiled regular expressions. As an +alternative, specify a number instead of list of letters (e.g., B<-D14> is +equivalent to B<-Dtls>): + + 1 p Tokenizing and parsing + 2 s Stack snapshots + 4 l Context (loop) stack processing + 8 t Trace execution + 16 o Method and overloading resolution + 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 and execution + 1024 x Syntax tree dump + 2048 u Tainting checks + 4096 L Memory leaks (needs C<-DLEAKTEST> when compiling Perl) + 8192 H Hash dump -- usurps values() + 16384 X Scratchpad allocation + 32768 D Cleaning up + 65536 S Thread synchronization + +All these flags require C<-DDEBUGGING> when you compile the Perl +executable. This flag is automatically set if you include C<-g> +option when C<Configure> asks you about optimizer/debugger flags. + +=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 used to +modify the name of the old file to make a backup copy, following these +rules: + +If no extension is supplied, no backup is made and the current file is +overwritten. + +If the extension doesn't contain a C<*> then it is appended to the end +of the current filename as a suffix. + +If the extension does contain one or more C<*> characters, then each C<*> +is replaced with the current filename. In perl terms you could think of +this as: + + ($backup = $extension) =~ s/\*/$file_name/g; + +This allows you to add a prefix to the backup file, instead of (or in +addition to) a suffix: + + $ perl -pi'bak_*' -e 's/bar/baz/' fileA # backup to 'bak_fileA' + +Or even to place backup copies of the original files into another +directory (provided the directory already exists): + + $ perl -pi'old/*.bak' -e 's/bar/baz/' fileA # backup to 'old/fileA.bak' + +These sets of one-liners are equivalent: + + $ perl -pi -e 's/bar/baz/' fileA # overwrite current file + $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file + + $ perl -pi'.bak' -e 's/bar/baz/' fileA # backup to 'fileA.bak' + $ perl -pi'*.bak' -e 's/bar/baz/' fileA # backup to 'fileA.bak' + +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 + $extension = '.bak'; + while (<>) { + if ($ARGV ne $oldargv) { + if ($extension !~ /\*/) { + $backup = $ARGV . $extension; + } + else { + ($backup = $extension) =~ s/\*/$ARGV/g; + } + rename($ARGV, $backup); + 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. + +As shown above, Perl creates the backup file whether or not any output +is actually changed. So this is just a fancy way to copy files: + + $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3... + or + $ perl -p -i'.bak' -e 1 file1 file2 file3... + +You can use C<eof> without parentheses 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>). + +If, for a given file, Perl is unable to create the backup file as +specified in the extension then it will skip that file and continue on +with the next one (if it exists). + +For a discussion of issues surrounding file permissions and C<-i>, see +L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?>. + +You cannot use B<-i> to create directories or to strip extensions from +files. + +Perl does not expand C<~>, so don't do that. + +Finally, note that the B<-i> switch does not impede execution when no +files are given on the command line. In this case, no backup is made +(the original file cannot, of course, be determined) and processing +proceeds from STDIN to STDOUT as might be expected. + +=item B<-I>I<directory> + +Directories specified by B<-I> are prepended to the search path for +modules (C<@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 "C<$/>" (the input record separator) when used +with B<-n> or B<-p>, and second, it assigns "C<$\>" +(the output record separator) to have the value of I<octnum> so that +any print statements will have that separator 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 C<$\> to newline and then sets C<$/> 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 builtin 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. If a file named by an argument cannot be opened for +some reason, Perl warns you about it, and moves on to the next file. + +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 or die "-p destination: $!\n"; + } + +If a file named by an argument cannot be opened for some reason, Perl +warns you about it, and moves on to the next file. Note that the +lines are printed automatically. An error occuring during printing is +treated as fatal. 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. (Because 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 contains directory separators). +On some platforms, this also makes Perl append suffixes to the +filename while searching for it. For example, on Win32 platforms, +the ".bat" and ".cmd" suffixes are appended if a lookup for the +original name fails, and if the name does not already end in one +of those suffixes. If your Perl was compiled with DEBUGGING turned +on, using the -Dp switch to Perl shows how the search progresses. + +If the filename supplied contains directory separators (i.e. it is an +absolute or relative pathname), and if the file is not found, +platforms that append file extensions will do so and try to look +for the file with those extensions added, one by one. + +On DOS-like platforms, if the script does not contain directory +separators, it will first be searched for in the current directory +before being searched for on the PATH. On Unix platforms, the +script will be searched for strictly on the PATH. + +Typically this is used to emulate #! startup on platforms that +don't support #!. This example works on many platforms that +have a shell compatible with Bourne shell: + + #!/usr/bin/perl + eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}' + 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. If the script will be interpreted by csh, you will need +to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand +embedded spaces (and such) in the argument list. 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 -wS $0 ${1+"$@"}' + & eval 'exec /usr/bin/perl -wS $0 $argv:q' + if $running_under_some_shell; + +=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>. Note that (for security reasons) +this option must be seen by Perl quite early; usually this means it must +appear early on the command line or in the #! line (for systems which +support that). + +=item B<-u> + +causes Perl to dump core after compiling your script. You can then +in theory 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. It has been superseded by the new perl-to-C compiler, which is more +portable, even though it's still only considered beta. + +=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. Note that the B<-w> switch (or the C<$^W> variable) must +be used along with this option to actually B<generate> the +taint-check 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 variable names 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 read-only 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. + +You can disable specific warnings using C<__WARN__> hooks, as described +in L<perlvar> and L<perlfunc/warn>. See also 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. If a directory name is specified, Perl will switch to +that directory before running the script. The B<-x> switch controls +only 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 + +=head1 ENVIRONMENT + +=over 12 + +=item HOME + +Used if chdir has no argument. + +=item LOGDIR + +Used if chdir has no argument and HOME is not set. + +=item PATH + +Used in executing subprocesses, and in finding the script if B<-S> is +used. + +=item PERL5LIB + +A colon-separated list of directories in which to look for Perl library +files before looking in the standard library and the current +directory. If PERL5LIB is not defined, PERLLIB is used. When running +taint checks (because the script was running setuid or setgid, or the +B<-T> switch was used), neither variable is used. The script should +instead say + + use lib "/my/directory"; + +=item PERL5OPT + +Command-line options (switches). Switches in this variable are taken +as if they were on every Perl command line. Only the B<-[DIMUdmw]> +switches are allowed. When running taint checks (because the script +was running setuid or setgid, or the B<-T> switch was used), this +variable is ignored. + +=item 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. +If PERL5LIB is defined, PERLLIB is not used. + +=item PERL5DB + +The command used to load the debugger code. The default is: + + BEGIN { require 'perl5db.pl' } + +=item PERL5SHELL (specific to WIN32 port) + +May be set to an alternative shell that perl must use internally for +executing "backtick" commands or system(). Default is C<cmd.exe /x/c> +on WindowsNT and C<command.com /c> on Windows95. The value is considered +to be space delimited. Precede any character that needs to be protected +(like a space or backslash) with a backslash. + +Note that Perl doesn't use COMSPEC for this purpose because +COMSPEC has a high degree of variability among users, leading to +portability concerns. Besides, perl can use a shell that may not be +fit for interactive use, and setting COMSPEC to such a shell may +interfere with the proper functioning of other programs (which usually +look in COMSPEC to find a shell fit for interactive use). + +=item PERL_DEBUG_MSTATS + +Relevant only if perl is compiled with the malloc included with the perl +distribution (that is, if C<perl -V:d_mymalloc> is 'define'). +If set, this causes memory statistics to be dumped after execution. If set +to an integer greater than one, also causes memory statistics to be dumped +after compilation. + +=item PERL_DESTRUCT_LEVEL + +Relevant only if your perl executable was built with B<-DDEBUGGING>, +this controls the behavior of global destruction of objects and other +references. + +=back + +Perl also has environment variables that control how Perl handles data +specific to particular natural languages. See L<perllocale>. + +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 anything else, just to keep people +honest: + + $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need + $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL}; + delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; + |