=head1 SYNOPSIS
-B<perl> S<[ B<-CsTuUWX> ]>
+B<perl> S<[ B<-CsTtuUWX> ]>
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>] ]>
runs the program under the Perl debugger. See L<perldebug>.
-=item B<-d:>I<foo>
+=item B<-d:>I<foo[=bar,baz]>
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<perldebug>.
+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<perldebug>.
=item B<-D>I<letters>
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<perldebguts>.
+
+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
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
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<INSTALL> file in the Perl source distribution
as it executes, the way that C<sh -x> 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
with the next one (if it exists).
For a discussion of issues surrounding file permissions and B<-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?>.
+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.
=item B<-P>
-causes your program to be run through the C preprocessor before
-compilation by Perl. (Because both comments and B<cpp> directives begin
+B<NOTE: Use of -P is strongly discouraged because of its inherent
+problems, including poor portability.>
+
+This option causes your program to be run through the C preprocessor before
+compilation by Perl. Because both comments and B<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 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<All> 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<sed>. 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>.
#!/usr/bin/perl -s
if ($xyz) { print "$xyz\n" }
+Do note that B<--help> creates the variable ${-help}, which is not compliant
+with C<strict refs>.
+
=item B<-S>
makes Perl use the PATH environment variable to search for the
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<no warnings
+qw(taint)>.
+
+B<NOTE: this is not a substitute for -T.> 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
C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
See also L<perldiag> and L<perltrap>. A new, fine-grained warning
facility is also available if you want to manipulate entire classes
-of warnings; see L<warnings> (or better yet, its source code) about
-that.
+of warnings; see L<warnings> or L<perllexwarn>.
=item B<-W>
=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
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<perlhack/PERL_DESTRUCT_LEVEL> for more information.
+
+=item PERL_ENCODING
+
+If using the C<encoding> 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<perlvms> and in F<README.vms> 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
https://perl5.git.perl.org / perl5.git / blobdiff