Anton Berezin did more reading and the uid setting story

[perl5.git] / pod / perlrun.pod

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 5cc1969..7c56788 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -4,7 +4,7 @@ perlrun - how to execute the Perl interpreter
 
 =head1 SYNOPSIS
 
 
 =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>] ]>
        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>] ]>


@@ -284,11 +284,15 @@ be skipped.
 
 runs the program under the Perl debugger.  See L<perldebug>.
 
 
 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
 
 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>
 
 
 =item B<-D>I<letters>
 


@@ -297,9 +301,11 @@ the program using the Devel::DProf profiler.  See L<perldebug>.
 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
 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
 
         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
         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
       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
     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 
 
 All these flags require B<-DDEBUGGING> when you compile the Perl
 executable.  See the F<INSTALL> 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<sh -x> provides for shell scripts,
 you can't use Perl's B<-D> switch.  Instead do this 
 
 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
 
   # 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>,
 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.
 
 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<awk>.
 
 =item B<-P>
 
 
 =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
 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
 
 =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>.
 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" }
 
     #!/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
 =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.
 
 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
 =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<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
 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 B<-W>
 


@@ -763,7 +845,7 @@ The program should instead say:
 =item PERL5OPT
 
 Command-line options (switches).  Switches in this variable are taken
 =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
 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
 
 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
 
 
 =back