X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/3c0facb21e91c63c42bcfc1031a2f001e59d479c..c8d2171d9a4e444fcbc15a9762adc552285c7cab:/pod/perlrun.pod diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 5cc1969..7c56788 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -4,7 +4,7 @@ perlrun - how to execute the Perl interpreter =head1 SYNOPSIS -B S<[ B<-CsTuUWX> ]> +B S<[ B<-CsTtuUWX> ]> 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] ]> @@ -284,11 +284,15 @@ be skipped. runs the program under the Perl debugger. See L. -=item B<-d:>I +=item B<-d:>I runs the program under the control of a debugging, profiling, or tracing module installed as Devel::foo. E.g., B<-d:DProf> executes -the program using the Devel::DProf profiler. See L. +the program using the Devel::DProf profiler. As with the B<-M> +flag, options may be passed to the Devel::foo package where they +will be received and interpreted by the Devel::foo::import routine. +The comma-separated list of options must follow a C<=> character. +See L. =item B<-D>I @@ -297,9 +301,11 @@ the program using the Devel::DProf profiler. See L. sets debugging flags. To watch how it executes your program, 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>): +syntax tree. And B<-Dr> displays compiled regular expressions; +the format of the output is explained in L. + +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 @@ -307,7 +313,7 @@ equivalent to B<-Dtls>): 8 t Trace execution 16 o Method and overloading resolution 32 c String/numeric conversions - 64 P Print preprocessor command for -P + 64 P Print preprocessor command for -P, source file input state 128 m Memory allocation 256 f Format processing 512 r Regular expression parsing and execution @@ -318,6 +324,8 @@ equivalent to B<-Dtls>): 16384 X Scratchpad allocation 32768 D Cleaning up 65536 S Thread synchronization + 131072 T Tokenising + 262144 R Include reference counts of dumped variables (eg when using -Ds) All these flags require B<-DDEBUGGING> when you compile the Perl executable. See the F file in the Perl source distribution @@ -328,6 +336,9 @@ If you're just trying to get a print out of each line of Perl code as it executes, the way that C provides for shell scripts, you can't use Perl's B<-D> switch. Instead do this + # If you have "env" utility + env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program + # Bourne shell syntax $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program @@ -445,8 +456,7 @@ 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 B<-i>, -see L. +see L. You cannot use B<-i> to create directories or to strip extensions from files. @@ -564,16 +574,75 @@ the implicit loop, just as in B. =item B<-P> -causes your program to be run through the C preprocessor before -compilation by Perl. (Because both comments and B directives begin +B + +This option causes your program to be run through the C preprocessor before +compilation by Perl. Because both comments and B 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 C<"if">, C<"else">, or C<"define">. + +If you're considering using C<-P>, you might also want to look at the +Filter::cpp module from CPAN. + +The problems of -P include, but are not limited to: + +=over 10 + +=item * + +The C<#!> line is stripped, so any switches there don't apply. + +=item * + +A C<-P> on a C<#!> line doesn't work. + +=item * + +B lines that begin with (whitespace and) a C<#> but +do not look like cpp commands, are stripped, including anything +inside Perl strings, regular expressions, and here-docs . + +=item * + +In some platforms the C preprocessor knows too much: it knows about +the C++ -style until-end-of-line comments starting with C<"//">. +This will cause problems with common Perl constructs like + + s/foo//; + +because after -P this will became illegal code + + s/foo + +The workaround is to use some other quoting separator than C<"/">, +like for example C<"!">: + + s!foo!!; + + + +=item * + +It requires not only a working C preprocessor but also a working +F. If not on UNIX, you are probably out of luck on this. + +=item * + +Script line numbers are not preserved. + +=item * + +The C<-x> does not work with C<-P>. + +=back =item B<-s> enables rudimentary switch parsing for switches on the command line after the program name but before any filename arguments (or before -a B<-->). Any switch found there is removed from @ARGV and sets the +an argument of B<-->). This means you can have switches with two leading +dashes (B<--help>). Any switch found there is removed from @ARGV and sets the corresponding variable in the Perl program. The following program prints "1" if the program is invoked with a B<-xyz> switch, and "abc" if it is invoked with B<-xyz=abc>. @@ -581,6 +650,9 @@ if it is invoked with B<-xyz=abc>. #!/usr/bin/perl -s if ($xyz) { print "$xyz\n" } +Do note that B<--help> creates the variable ${-help}, which is not compliant +with C. + =item B<-S> makes Perl use the PATH environment variable to search for the @@ -630,6 +702,17 @@ separators, it will first be searched for in the current directory before being searched for on the PATH. On Unix platforms, the program will be searched for strictly on the PATH. +=item B<-t> + +Like B<-T>, but taint checks will issue warnings rather than fatal +errors. These warnings can be controlled normally with C. + +B This is meant only to be +used as a temporary development aid while securing legacy code: +for real production code and for new secure code written from scratch +always use the real B<-T>. + =item B<-T> forces "taint" checks to be turned on so you can test them. Ordinarily @@ -701,8 +784,7 @@ can disable or promote into fatal errors specific warnings using C<__WARN__> hooks, as described in L and L. See also L and L. A new, fine-grained warning facility is also available if you want to manipulate entire classes -of warnings; see L (or better yet, its source code) about -that. +of warnings; see L or L. =item B<-W> @@ -763,7 +845,7 @@ The program should instead say: =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]> +as if they were on every Perl command line. Only the B<-[DIMUdmtw]> switches are allowed. When running taint checks (because the program was running setuid or setgid, or the B<-T> switch was used), this variable is ignored. If PERL5OPT begins with B<-T>, tainting will be @@ -808,7 +890,24 @@ after compilation. Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other -references. +references. See L for more information. + +=item PERL_ENCODING + +If using the C pragma without an explicit encoding name, the +PERL_ENCODING environment variable is consulted for an encoding name. + +=item PERL_ROOT (specific to the VMS port) + +A translation concealed rooted logical name that contains perl and the +logical device for the @INC path on VMS only. Other logical names that +affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and +SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in +L and in F in the Perl source distribution. + +=item SYS$LOGIN (specific to the VMS port) + +Used if chdir has no argument and HOME and LOGDIR are not set. =back