Unused 'cv'

[perl5.git] / pod / perlrun.pod

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 246d5b3..c3b30c8 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -10,11 +10,10 @@ B<perl>     S<[ B<-sTtuUWX> ]>
        S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]>
        S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
        S<[ B<-C [I<number/list>] >]>
        S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]>
        S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
        S<[ B<-C [I<number/list>] >]>

-       S<[ B<-P> ]>

        S<[ B<-S> ]>
        S<[ B<-x>[I<dir>] ]>
        S<[ B<-i>[I<extension>] ]>
        S<[ B<-S> ]>
        S<[ B<-x>[I<dir>] ]>
        S<[ B<-i>[I<extension>] ]>

-       S<[ B<-eE> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+       S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -78,9 +77,10 @@ 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
 
 The sequences "-*" and "- " are specifically ignored so that you could,
 if you were so inclined, say
 

-    #!/bin/sh -- # -*- perl -*- -p
-    eval 'exec perl -wS $0 ${1+"$@"}'
-        if $running_under_some_shell;
+    #!/bin/sh
+    #! -*-perl-*-
+    eval 'exec perl -x -wS $0 ${1+"$@"}'
+        if 0;

 
 to let Perl see the B<-p> switch.
 
 
 to let Perl see the B<-p> switch.
 


@@ -280,7 +280,7 @@ An alternate delimiter may be specified using B<-F>.
 =item B<-C [I<number/list>]>
 X<-C>
 
 =item B<-C [I<number/list>]>
 X<-C>
 

-The C<-C> flag controls some Unicode of the Perl Unicode features.
+The C<-C> flag controls some of the Perl Unicode features.

 
 As of 5.8.1, the C<-C> can be followed either by a number or a list
 of option letters.  The letters, their numeric values, and effects
 
 As of 5.8.1, the C<-C> can be followed either by a number or a list
 of option letters.  The letters, their numeric values, and effects


@@ -342,6 +342,11 @@ that enabled the use of Unicode-aware "wide system call" Win32 APIs.
 This feature was practically unused, however, and the command line
 switch was therefore "recycled".)
 
 This feature was practically unused, however, and the command line
 switch was therefore "recycled".)
 

+B<Note:> Since perl 5.10.0, the -C option can no longer be used
+on the #! line. It wasn't working there anyway, since the standard streams
+are already set up at this point in the execution of the perl interpreter.
+You can use binmode() instead to get the desired behaviour.
+

 =item B<-c>
 X<-c>
 
 =item B<-c>
 X<-c>
 


@@ -395,8 +400,8 @@ B<-D14> is 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 profiling info, preprocessor command for -P, source file input state
-      128  m  Memory allocation
+       64  P  Print profiling info, source file input state
+      128  m  Memory and SV allocation

       256  f  Format processing
       512  r  Regular expression parsing and execution
      1024  x  Syntax tree dump
       256  f  Format processing
       512  r  Regular expression parsing and execution
      1024  x  Syntax tree dump


@@ -405,7 +410,6 @@ B<-D14> is equivalent to B<-Dtls>):
      8192  H  Hash dump -- usurps values()
     16384  X  Scratchpad allocation
     32768  D  Cleaning up
      8192  H  Hash dump -- usurps values()
     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)
    524288  J  Do not s,t,P-debug (Jump over) opcodes within package DB
    131072  T  Tokenising
    262144  R  Include reference counts of dumped variables (eg when using -Ds)
    524288  J  Do not s,t,P-debug (Jump over) opcodes within package DB


@@ -455,10 +459,10 @@ X<-f>
 Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup.
 
 Perl can be built so that it by default will try to execute
 Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup.
 
 Perl can be built so that it by default will try to execute

-F<$Config{sitelib}/sitecustomize.pl> at startup.  This is a hook that
-allows the sysadmin to customize how perl behaves.  It can for
-instance be used to add entries to the @INC array to make perl find
-modules in non-standard locations.
+F<$Config{sitelib}/sitecustomize.pl> at startup (in a BEGIN block).
+This is a hook that allows the sysadmin to customize how perl behaves.
+It can for instance be used to add entries to the @INC array to make perl
+find modules in non-standard locations.

 
 =item B<-F>I<pattern>
 X<-F>
 
 =item B<-F>I<pattern>
 X<-F>


@@ -588,9 +592,7 @@ proceeds from STDIN to STDOUT as might be expected.
 X<-I> X<@INC>
 
 Directories specified by B<-I> are prepended to the search path for
 X<-I> X<@INC>
 
 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.
+modules (C<@INC>).

 
 =item B<-l>[I<octnum>]
 X<-l> X<$/> X<$\>
 
 =item B<-l>[I<octnum>]
 X<-l> X<$/> X<$\>


@@ -659,6 +661,10 @@ 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.
 
 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.
 

+Also note that C<< <> >> passes command line arguments to
+L<perlfunc/open>, which doesn't necessarily interpret them as file names.
+See  L<perlop> for possible security implications.
+

 Here is an efficient way to delete all files that haven't been modified for
 at least a week:
 
 Here is an efficient way to delete all files that haven't been modified for
 at least a week:
 


@@ -695,72 +701,6 @@ 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 B<awk>.
 
 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>
-X<-P>
-
-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 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>
 X<-s>
 
 =item B<-s>
 X<-s>
 


@@ -869,10 +809,6 @@ execute a portion of your program 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.
 
 operator instead.  Note: availability of B<undump> is platform
 specific and may not be available for a specific port of Perl.
 

-This switch has been superseded in favor of the new Perl code
-generator backends to the compiler.  See L<B> and L<B::Bytecode>
-for details.
-

 =item B<-U>
 X<-U>
 
 =item B<-U>
 X<-U>
 


@@ -967,12 +903,20 @@ See L<perllexwarn>.
 =item B<-x>
 X<-x>
 
 =item B<-x>
 X<-x>
 

-=item B<-x> I<directory>
+=item B<-x>I<directory>

 
 tells Perl that the program is embedded in a larger chunk of unrelated
 ASCII text, such as in a mail 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.
 
 tells Perl that the program is embedded in a larger chunk of unrelated
 ASCII text, such as in a mail 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.

+
+All references to line numbers by the program (warnings, errors, ...)
+will treat the #! line as the first line.
+Thus a warning on the 2nd line of the program (which is on the 100th
+line in the file) will be reported as line 2, and not as line 100.
+This can be overridden by using the #line directive.
+(See L<perlsyn/"Plain-Old-Comments-(Not!)">)
+

 If a directory name is specified, Perl will switch to that directory
 before running the program.  The B<-x> switch controls only the
 disposal of leading garbage.  The program must be terminated with
 If a directory name is specified, Perl will switch to that directory
 before running the program.  The B<-x> switch controls only the
 disposal of leading garbage.  The program must be terminated with


@@ -980,6 +924,9 @@ C<__END__> if there is trailing garbage to be ignored (the program
 can process any or all of the trailing garbage via the DATA filehandle
 if desired).
 
 can process any or all of the trailing garbage via the DATA filehandle
 if desired).
 

+The directory, if specified, must appear immediately following the B<-x>
+with no intervening whitespace.
+

 =back
 
 =head1 ENVIRONMENT
 =back
 
 =head1 ENVIRONMENT


@@ -1027,7 +974,7 @@ is used. The program should instead say:
 X<PERL5OPT>
 
 Command-line options (switches).  Switches in this variable are taken
 X<PERL5OPT>
 
 Command-line options (switches).  Switches in this variable are taken

-as if they were on every Perl command line.  Only the B<-[CDIMUdmtwA]>
+as if they were on every Perl command line.  Only the B<-[CDIMUdmtwW]>

 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


@@ -1124,9 +1071,9 @@ X<:utf8>
 
 A pseudolayer that turns on a flag on the layer below to tell perl
 that output should be in utf8 and that input should be regarded as
 
 A pseudolayer that turns on a flag on the layer below to tell perl
 that output should be in utf8 and that input should be regarded as

-already in utf8 form.  May be useful in PERLIO environment
-variable to make UTF-8 the default. (To turn off that behaviour
-use C<:bytes> layer.)
+already in valid utf8 form. It does not check for validity and as such
+should be handled with caution for input. Generally C<:encoding(utf8)> is
+the best option when reading UTF-8 encoded data.

 
 =item :win32
 X<:win32>
 
 =item :win32
 X<:win32>


@@ -1156,6 +1103,9 @@ compiler's numeric file descriptor routines. There is an experimental native
 C<win32> layer which is expected to be enhanced and should eventually be
 the default under Win32.
 
 C<win32> layer which is expected to be enhanced and should eventually be
 the default under Win32.
 

+The PERLIO environment variable is completely ignored when perl
+is run in taint mode.
+

 =item PERLIO_DEBUG
 X<PERLIO_DEBUG>
 
 =item PERLIO_DEBUG
 X<PERLIO_DEBUG>
 


@@ -1180,6 +1130,9 @@ A 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.
 
 files before looking in the standard library and the current directory.
 If PERL5LIB is defined, PERLLIB is not used.
 

+The PERLLIB environment variable is completely ignored when perl
+is run in taint mode.
+

 =item PERL5DB
 X<PERL5DB>
 
 =item PERL5DB
 X<PERL5DB>
 


@@ -1187,6 +1140,9 @@ The command used to load the debugger code.  The default is:
 
        BEGIN { require 'perl5db.pl' }
 
 
        BEGIN { require 'perl5db.pl' }
 

+The PERL5DB environment variable only used when perl is started with
+a bare B<-d> switch.
+

 =item PERL5DB_THREADED
 X<PERL5DB_THREADED>
 
 =item PERL5DB_THREADED
 X<PERL5DB_THREADED>
 


@@ -1209,6 +1165,11 @@ 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).
 
 interfere with the proper functioning of other programs (which usually
 look in COMSPEC to find a shell fit for interactive use).
 

+Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked
+when running external commands.  It is recommended that
+you explicitly set (or delete) C<$ENV{PERL5SHELL}> when running
+in taint mode under Windows.
+

 =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
 X<PERL_ALLOW_NON_IFS_LSP>
 
 =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
 X<PERL_ALLOW_NON_IFS_LSP>
 


@@ -1258,20 +1219,23 @@ PERL_ENCODING environment variable is consulted for an encoding name.
 =item PERL_HASH_SEED
 X<PERL_HASH_SEED>
 
 =item PERL_HASH_SEED
 X<PERL_HASH_SEED>
 

-(Since Perl 5.8.1.)  Used to randomise Perl's internal hash function.
+(Since Perl 5.8.1.)  Used to randomise perl's internal hash function.

 To emulate the pre-5.8.1 behaviour, set to an integer (zero means
 exactly the same order as 5.8.0).  "Pre-5.8.1" means, among other
 To emulate the pre-5.8.1 behaviour, set to an integer (zero means
 exactly the same order as 5.8.0).  "Pre-5.8.1" means, among other

-things, that hash keys will be ordered the same between different runs
-of Perl.
+things, that hash keys will always have the same ordering between
+different runs of perl.
+
+Most hashes return elements in the same order as Perl 5.8.0 by default.
+On a hash by hash basis, if pathological data is detected during a hash
+key insertion, then that hash will switch to an alternative random hash
+seed.

 
 The default behaviour is to randomise unless the PERL_HASH_SEED is set.
 
 The default behaviour is to randomise unless the PERL_HASH_SEED is set.

-If Perl has been compiled with C<-DUSE_HASH_SEED_EXPLICIT>, the default
+If perl has been compiled with C<-DUSE_HASH_SEED_EXPLICIT>, the default

 behaviour is B<not> to randomise unless the PERL_HASH_SEED is set.
 
 behaviour is B<not> to randomise unless the PERL_HASH_SEED is set.
 

-If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses
+If PERL_HASH_SEED is unset or set to a non-numeric string, perl uses

 the pseudorandom seed supplied by the operating system and libraries.
 the pseudorandom seed supplied by the operating system and libraries.

-This means that each different run of Perl will have a different
-ordering of the results of keys(), values(), and each().

 
 B<Please note that the hash seed is sensitive information>. Hashes are
 randomized to protect against local and remote attacks against Perl
 
 B<Please note that the hash seed is sensitive information>. Hashes are
 randomized to protect against local and remote attacks against Perl