X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=f90e642d40642efb71bea560be3d644991749b25;hb=1e422769b80038b1bfc4f5af33438b87cc1c7a22;hp=fe8a154c395f2a0e9217f9c341331c4b5f70bb44;hpb=a77489aad1511753fbfe951d1291deb8ecb1aa54;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrun.pod b/pod/perlrun.pod index fe8a154..f90e642 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -4,10 +4,16 @@ perlrun - how to execute the Perl interpreter =head1 SYNOPSIS -B [B<-acdhnpPsSTuUvw>] [B<-0[octal>]] [B<-D[number/list]>] - [B<-F regexp>] [B<-i[extension>]] [B<-Idir>] - [B<-l[octal]>] [B<-x[dir]>] - [programfile | B<-e command>] [argument ...] +B S<[ B<-sTuU> ]> + S<[ B<-hv> ] [ B<-V>[:I] ]> + S<[ B<-cw> ] [ B<-d>[:I] ] [ B<-D>[I] ]> + S<[ B<-pna> ] [ B<-F>I ] [ B<-l>[I] ] [ B<-0>[I] ]> + S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ]> + S<[ B<-P> ]> + S<[ B<-S> ]> + S<[ B<-x>[I] ]> + S<[ B<-i>[I] ]> + S<[ B<-e> I<'command'> ] [ B<--> ] [ I ] [ I ]...> =head1 DESCRIPTION @@ -27,7 +33,7 @@ Contained in the file specified by the first filename on the command line. =item 3. -Passed in implicitly via standard input. This only works if there are +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. @@ -40,11 +46,11 @@ scans for the first line starting with #! and containing the word 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. +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 @@ -61,8 +67,8 @@ 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; + eval 'exec /usr/bin/perl $0 -S ${1+"$@"}' + if $running_under_some_shell; to let Perl see the B<-p> switch. @@ -92,9 +98,9 @@ Switches include: =over 5 -=item B<-0>I +=item B<-0>[I] -specifies the record separator (C<$/>) as an octal number. If there are +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 which can print filenames terminated by the null character, you @@ -103,7 +109,7 @@ 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 +The value 0777 will cause Perl to slurp files whole because there is no legal character with that value. =item B<-a> @@ -127,14 +133,14 @@ An alternate delimiter may be specified using B<-F>. causes Perl to check the syntax of the script and then exit without executing it. Actually, it I execute C, C, and C blocks, -since these are considered as occurring outside the execution of +because these are considered as occurring outside the execution of your program. =item B<-d> runs the script under the Perl debugger. See L. -=item B<-d:foo> +=item B<-d:>I 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 @@ -145,10 +151,10 @@ Devel::DProf profiler. See L. =item B<-D>I sets debugging flags. To watch how it executes your script, use -B<-D14>. (This only works if debugging is compiled into your +B<-D14>. (This works only 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 +alternative specify a list of letters instead of numbers (e.g., B<-D14> is equivalent to B<-Dtls>): 1 p Tokenizing and Parsing @@ -177,12 +183,17 @@ 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 +=item B<-F>I -specifies a regular expression to split on if B<-a> is also in effect. -If regexp has C around it, the slashes will be ignored. +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<-i>I +=item B<-h> + +prints a summary of the options. + +=item B<-i>[I] specifies that files processed by the CE> construct are to be edited in-place. It does this by renaming the input file, opening the output @@ -226,16 +237,18 @@ example in L). =item B<-I>I -may be used in conjunction with B<-P> to tell the C preprocessor where -to look for include files. By default /usr/include and /usr/lib/perl -are searched. +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 +=item B<-l>[I] 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 so that -any print statements will have that line terminator added back on. If +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 so that +any print statements will have that separator added back on. If I is omitted, sets "C<$\>" to the current value of "C<$/>". For instance, to trim lines to 80 columns: @@ -247,11 +260,15 @@ 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. +This sets C<$\> to newline and then sets C<$/> to the null character. + +=item B<-m>[B<->]I + +=item B<-M>[B<->]I -=item B<-m>I +=item B<-M>[B<->]I<'module ...'> -=item B<-M>I +=item B<-[mM]>[B<->]I C<-m>I executes C I C<();> before executing your script. @@ -260,9 +277,14 @@ C<-M>I executes C I 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> or C<-Mmodule=foo> as a shortcut for -C<-M'module qw(foo)'>. Note that using the C<=> form +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. Note that the C<=> form removes the distinction between C<-m> and C<-M>. =item B<-n> @@ -308,9 +330,9 @@ 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 +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".) +recognized by the C preprocessor such as "if", "else", or "define".) =item B<-s> @@ -331,7 +353,7 @@ 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 $*" + eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' if $running_under_some_shell; The system ignores the first line and feeds the script to /bin/sh, @@ -343,15 +365,15 @@ 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 +the script is being interpreted by csh. 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: +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; + if $running_under_some_shell; =item B<-T> @@ -388,33 +410,102 @@ prints the version and patchlevel of your Perl executable. prints summary of the major perl configuration values and the current value of @INC. -=item B<-V:name> +=item B<-V:>I Prints to STDOUT the value of the named configuration variable. =item B<-w> -prints warnings about identifiers that are mentioned only once, and +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 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 and L. +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 and L. See also L and L. =item B<-x> I 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 +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 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 PERL_DEBUG_MSTATS + +Relevant only if your perl executable was built with B<-DDEBUGGING_MSTATS>, +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. + +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 defined $ENV{'SHELL'}; + $ENV{'IFS'} = '' if defined $ENV{'IFS'}; +