Front page | perl.perl5.porters |
Postings from May 2011
Re: [perl #89486] PATCH: perlrun.pod
Thread Previous
From:
Jesse Vincent
Date:
May 2, 2011 07:05
Subject:
Re: [perl #89486] PATCH: perlrun.pod
Message ID:
20110502140512.GK9931@puppy
Thanks. Applied to jesse/tchrist-doc-patches for review and merge after
maint-5.14 branches.
On Thu 28.Apr'11 at 10:03:59 -0700, tchrist1 wrote:
> # New Ticket Created by tchrist1
> # Please include the string: [perl #89486]
> # in the subject line of all future correspondence about this issue.
> # <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=89486 >
>
>
> This patch is aagainst the "blead du moment". It fixes various
> things, but does not address the "this version" != 5.14 and the
> perlio issues. I believe that these at least should be addressed
> as soon as possible (I don't know whether that means 5.14;
> probably not). It has to either say the particular version that
> applies. We can't keep releasing things that say this version:
> they are not trustable.
>
> --tom
>
> --- pod/perlrun.pod 2011-04-25 19:40:47.000000000 -0600
> +++ /tmp/perlrun.pod 2011-04-28 11:00:39.000000000 -0600
> @@ -33,7 +33,7 @@
> =item 2.
>
> Contained in the file specified by the first filename on the command line.
> -(Note that systems supporting the #! notation invoke interpreters this
> +(Note that systems supporting the C<#!> notation invoke interpreters this
> way. See L<Location of Perl>.)
>
> =item 3.
> @@ -46,19 +46,19 @@
>
> With methods 2 and 3, Perl starts parsing the input file from the
> beginning, unless you've specified a B<-x> switch, in which case it
> -scans for the first line starting with #! and containing the word
> +scans for the first line starting with C<#!> and containing the word
> "perl", and starts there instead. This is useful for running a program
> embedded in a larger message. (In this case you would indicate the end
> of the program using the C<__END__> token.)
>
> -The #! line is always examined for switches as the line is being
> +The C<#!> 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
> +with the C<#!> line, or worse, doesn't even recognize the C<#!> line, you
> +still can get consistent switch behaviour regardless of how Perl was
> invoked, even if B<-x> was used to find the beginning of the program.
>
> Because historically some operating systems silently chopped off
> -kernel interpretation of the #! line after 32 characters, some
> +kernel interpretation of the C<#!> line after 32 characters, some
> switches may be passed in on the command line, and some may not;
> you could even get a "-" without its letter, if you're not careful.
> You probably want to make sure that all your switches fall either
> @@ -73,7 +73,7 @@
> the 32-character boundary (if applicable), or replace the use of
> B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>.
>
> -Parsing of the #! switches starts wherever "perl" is mentioned in the line.
> +Parsing of the C<#!> 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
>
> @@ -84,18 +84,18 @@
>
> to let Perl see the B<-p> switch.
>
> -A similar trick involves the B<env> program, if you have it.
> +A similar trick involves the I<env> program, if you have it.
>
> #!/usr/bin/env perl
>
> The examples above use a relative path to the perl interpreter,
> getting whatever version is first in the user's path. If you want
> a specific version of Perl, say, perl5.005_57, you should place
> -that directly in the #! line's path.
> +that directly in the C<#!> line's path.
>
> -If the #! line does not contain the word "perl", the program named after
> -the #! is executed instead of the Perl interpreter. This is slightly
> -bizarre, but it helps people on machines that don't do #!, because they
> +If the C<#!> line does not contain the word "perl", the program named after
> +the C<#!> is executed instead of the Perl interpreter. This is slightly
> +bizarre, but it helps people on machines that don't do C<#!>, because they
> can tell a program that their SHELL is F</usr/bin/perl>, and Perl will then
> dispatch the program to the correct interpreter for them.
>
> @@ -111,7 +111,7 @@
> =head2 #! and quoting on non-Unix systems
> X<hashbang> X<#!>
>
> -Unix's #! technique can be simulated on other systems:
> +Unix's C<#!> technique can be simulated on other systems:
>
> =over 4
>
> @@ -178,7 +178,7 @@
> perl -e "print ""Hello world\n"""
>
> The problem is that none of this is reliable: it depends on the
> -command and it is entirely possible neither works. If B<4DOS> were
> +command and it is entirely possible neither works. If I<4DOS> were
> the command shell, this would probably work better:
>
> perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
> @@ -229,7 +229,7 @@
> specifies the input record separator (C<$/>) as an octal or
> hexadecimal 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<find> which can print filenames
> +example, if you have a version of I<find> which can print filenames
> terminated by the null character, you can say this:
>
> find . -name '*.orig' -print0 | perl -n0e unlink
> @@ -239,11 +239,12 @@
> the value 0777 is the one normally used for this purpose.
>
> You can also specify the separator character using hexadecimal notation:
> -C<-0xHHH...>, where the C<H> are valid hexadecimal digits. Unlike the octal
> -form, this one may be used to specify any Unicode character, even those beyond
> -0xFF.
> -(This means that you cannot use the C<-x> with a directory name that
> -consists of hexadecimal digits.)
> +B<-0xI<HHH...>>, where the C<I<H>> are valid hexadecimal digits. Unlike
> +the octal form, this one may be used to specify any Unicode character, even
> +those beyond 0xFF. So if you I<really> want a record separator of 0777,
> +specify it as B<-0x1FF>. (This means that you cannot use the B<-x> option
> +with a directory name that consists of hexadecimal digits, or else Perl
> +will think you have specified a hex number to B<-0>.)
>
> =item B<-a>
> X<-a> X<autosplit>
> @@ -266,9 +267,9 @@
> =item B<-C [I<number/list>]>
> X<-C>
>
> -The C<-C> flag controls some of the Perl Unicode features.
> +The B<-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
> +As of 5.8.1, the B<-C> can be followed either by a number or a list
> of option letters. The letters, their numeric values, and effects
> are as follows; listing the letters is equal to summing the numbers.
>
> @@ -296,7 +297,7 @@
> perltodo mentions Unicode in %ENV and filenames. I guess that these will be
> options e and f (or F).
>
> -For example, C<-COE> and C<-C6> will both turn on UTF-8-ness on both
> +For example, B<-COE> and B<-C6> will both turn on UTF-8-ness on both
> STDOUT and STDERR. Repeating letters is just redundant, not cumulative
> nor toggling.
>
> @@ -307,14 +308,14 @@
> the default, with explicit layers in open() and with binmode() one can
> manipulate streams as usual.
>
> -C<-C> on its own (not followed by any number or option list), or the
> +B<-C> on its own (not followed by any number or option list), or the
> empty string C<""> for the C<PERL_UNICODE> environment variable, has the
> -same effect as C<-CSDL>. In other words, the standard I/O handles and
> -the default C<open()> layer are UTF-8-fied B<but> only if the locale
> +same effect as B<-CSDL>. In other words, the standard I/O handles and
> +the default C<open()> layer are UTF-8-fied I<but> only if the locale
> environment variables indicate a UTF-8 locale. This behaviour follows
> the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
>
> -You can use C<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
> +You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
> disable all the above Unicode features.
>
> The read-only magic variable C<${^UNICODE}> reflects the numeric value
> @@ -323,13 +324,13 @@
> open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>),
> and the C<open> pragma (see L<open>).
>
> -(In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch
> +(In Perls earlier than 5.8.1 the B<-C> switch was a Win32-only switch
> 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".)
>
> -B<Note:> Since perl 5.10.1, if the -C option is used on the #! line, it
> -must be specified on the command line as well, since the standard streams
> +B<Note:> Since perl 5.10.1, if the B<-C> option is used on the C<#!> line,
> +it must be specified on the command line as well, since the standard streams
> are already set up at this point in the execution of the perl interpreter.
> You can also use binmode() to set the encoding of an I/O stream.
>
> @@ -337,10 +338,10 @@
> X<-c>
>
> causes Perl to check the syntax of the program and then exit without
> -executing it. Actually, it I<will> execute C<BEGIN>, C<UNITCHECK>,
> -C<CHECK>, and C<use> blocks, because these are considered as occurring
> -outside the execution of your program. C<INIT> and C<END> blocks,
> -however, will be skipped.
> +executing it. Actually, it I<will> execute and C<BEGIN>, C<UNITCHECK>,
> +or C<CHECK> blocks and any C<use> statements: these are considered as
> +occurring outside the execution of your program. C<INIT> and C<END>
> +blocks, however, will be skipped.
>
> =item B<-d>
> X<-d> X<-dt>
> @@ -351,21 +352,20 @@
> If B<t> is specified, it indicates to the debugger that threads
> will be used in the code being debugged.
>
> -=item B<-d:>I<foo[=bar,baz]>
> +=item B<-d:>I<MOD[=bar,baz]>
> X<-d> X<-dt>
>
> -=item B<-dt:>I<foo[=bar,baz]>
> +=item B<-dt:>I<MOD[=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. 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.
> -Again, like B<-M>, use -d:-foo to call Devel::foo::unimport instead of import.
> -The comma-separated list of options must follow a C<=> character.
> -If B<t> is specified, it indicates to the debugger that threads
> -will be used in the code being debugged.
> -See L<perldebug>.
> +runs the program under the control of a debugging, profiling, or tracing
> +module installed as C<Devel::I<MOD>>. E.g., B<-d:DProf> executes the
> +program using the C<Devel::DProf> profiler. As with the B<-M> flag, options
> +may be passed to the C<Devel::I<MOD>> package where they will be received
> +and interpreted by the C<Devel::I<MOD>::import> routine. Again, like B<-M>,
> +use -B<-d:-I<MOD>> to call C<Devel::I<MOD>::unimport> instead of import. The
> +comma-separated list of options must follow a C<=> character. If B<t> is
> +specified, it indicates to the debugger that threads will be used in the
> +code being debugged. See L<perldebug>.
>
> =item B<-D>I<letters>
> X<-D> X<DEBUGGING> X<-DDEBUGGING>
> @@ -397,7 +397,7 @@
> 8192 H Hash dump -- usurps values()
> 16384 X Scratchpad allocation
> 32768 D Cleaning up
> - 131072 T Tokenising
> + 131072 T Tokenizing
> 262144 R Include reference counts of dumped variables (eg when using -Ds)
> 524288 J show s,t,P-debug (don't Jump over) on opcodes within package DB
> 1048576 v Verbose: use in conjunction with other flags
> @@ -450,8 +450,8 @@
>
> Perl can be built so that it by default will try to execute
> 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
> +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.
>
> Perl actually inserts the following code:
> @@ -469,7 +469,7 @@
> The value of C<$Config{sitelib}> is also determined in C code and not
> read from C<Config.pm>, which is not loaded.
>
> -The code is executed B<very> early. For example, any changes made to
> +The code is executed I<very> early. For example, any changes made to
> C<@INC> will show up in the output of `perl -V`. Of course, C<END>
> blocks will be likewise executed very late.
>
> @@ -641,28 +641,28 @@
>
> B<-M>I<module> executes C<use> I<module> C<;> before executing your
> program. You can use quotes to add extra code after the module name,
> -e.g., C<'-Mmodule qw(foo bar)'>.
> +e.g., C<'-MI<MODULE> qw(foo bar)'>.
>
> -If the first character after the B<-M> or B<-m> is a dash (C<->)
> +If the first character after the B<-M> or B<-m> is a dash (B<->)
> then the 'use' is replaced with 'no'.
>
> A little builtin syntactic sugar means you can also say
> -B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for
> -C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when
> -importing symbols. The actual code generated by B<-Mmodule=foo,bar> is
> +B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for
> +B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when
> +importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is
> C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
> removes the distinction between B<-m> and B<-M>.
>
> -A consequence of this is that B<-MFoo=number> never does a version check
> -(unless C<Foo::import()> itself is set up to do a version check, which
> -could happen for example if Foo inherits from Exporter.)
> +A consequence of this is that B<-MI<MODULE>=number> never does a version check,
> +unless C<I<MODULE>::import()> itself is set up to do a version check, which
> +could happen for example if I<MODULE> inherits from L<Exporter>.
>
> =item B<-n>
> X<-n>
>
> causes Perl to assume the following loop around your program, which
> -makes it iterate over filename arguments somewhat like B<sed -n> or
> -B<awk>:
> +makes it iterate over filename arguments somewhat like I<sed -n> or
> +I<awk>:
>
> LINE:
> while (<>) {
> @@ -682,19 +682,19 @@
>
> find . -mtime +7 -print | perl -nle unlink
>
> -This is faster than using the B<-exec> switch of B<find> because you don't
> +This is faster than using the B<-exec> switch of I<find> because you don't
> have to start a process on every filename found. It does suffer from
> the bug of mishandling newlines in pathnames, which you can fix if
> you follow the example under B<-0>.
>
> C<BEGIN> and C<END> blocks may be used to capture control before or after
> -the implicit program loop, just as in B<awk>.
> +the implicit program loop, just as in I<awk>.
>
> =item B<-p>
> X<-p>
>
> causes Perl to assume the following loop around your program, which
> -makes it iterate over filename arguments somewhat like B<sed>:
> +makes it iterate over filename arguments somewhat like I<sed>:
>
>
> LINE:
> @@ -711,7 +711,7 @@
> 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>.
> +the implicit loop, just as in I<awk>.
>
> =item B<-s>
> X<-s>
> @@ -726,25 +726,25 @@
> #!/usr/bin/perl -s
> if ($xyz) { print "$xyz\n" }
>
> -Do note that a switch like B<--help> creates the variable ${-help}, which is not compliant
> -with C<strict refs>. Also, when using this option on a script with
> +Do note that a switch like B<--help> creates the variable C<${-help}>, which is not compliant
> +with C<use strict "refs">. Also, when using this option on a script with
> warnings enabled you may get a lot of spurious "used only once" warnings.
>
> =item B<-S>
> X<-S>
>
> makes Perl use the PATH environment variable to search for the
> -program (unless the name of the program contains directory separators).
> +program unless the name of the program contains path separators.
>
> On some platforms, this also makes Perl append suffixes to the
> filename while searching for it. For example, on Win32 platforms,
> the ".bat" and ".cmd" suffixes are appended if a lookup for the
> original name fails, and if the name does not already end in one
> -of those suffixes. If your Perl was compiled with DEBUGGING turned
> -on, using the -Dp switch to Perl shows how the search progresses.
> +of those suffixes. If your Perl was compiled with C<DEBUGGING> turned
> +on, using the B<-Dp> switch to Perl shows how the search progresses.
>
> -Typically this is used to emulate #! startup on platforms that don't
> -support #!. Its also convenient when debugging a script that uses #!,
> +Typically this is used to emulate C<#!> startup on platforms that don't
> +support C<#!>. It's also convenient when debugging a script that uses C<#!>,
> and is thus normally found by the shell's $PATH search mechanism.
>
> This example works on many platforms that have a shell compatible with
> @@ -763,17 +763,17 @@
> lines and ignores them because the variable $running_under_some_shell
> is never true. If the program will be interpreted by csh, you will need
> to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
> -embedded spaces (and such) in the argument list. To start up sh rather
> -than csh, some systems may have to replace the #! line with a line
> +embedded spaces (and such) in the argument list. To start up I<sh> rather
> +than I<csh>, some systems may have to replace the C<#!> 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 B<csh>, B<sh>, or Perl, such as the following:
> +will work under any of I<csh>, I<sh>, or Perl, such as the following:
>
> eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
> & eval 'exec /usr/bin/perl -wS $0 $argv:q'
> if $running_under_some_shell;
>
> -If the filename supplied contains directory separators (i.e., is an
> +If the filename supplied contains directory separators (and so is an
> absolute or relative pathname), and if that file is not found,
> platforms that append file extensions will do so and try to look
> for the file with those extensions added, one by one.
> @@ -787,49 +787,48 @@
> X<-t>
>
> Like B<-T>, but taint checks will issue warnings rather than fatal
> -errors. These warnings can be controlled normally with C<no warnings
> +errors. These warnings can now 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
> +B<Note: This is not a substitute for C<-T>!> This is meant to be
> +used I<only> 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>
> X<-T>
>
> -forces "taint" checks to be turned on so you can test them. Ordinarily
> +turns on "taint" so you can test them. Ordinarily
> these checks are done only when running setuid or setgid. It's a
> good idea to turn them on explicitly for programs that run on behalf
> of someone else whom you might not necessarily trust, such as CGI
> programs or any internet servers you might write in Perl. See
> L<perlsec> for details. For security reasons, this option must be
> seen by Perl quite early; usually this means it must appear early
> -on the command line or in the #! line for systems which support
> +on the command line or in the C<#!> line for systems which support
> that construct.
>
> =item B<-u>
> X<-u>
>
> -This obsolete switch causes Perl to dump core after compiling your
> +This switch causes Perl to dump core after compiling your
> program. You can then in theory take this core dump and turn it
> -into an executable file by using the B<undump> program (not supplied).
> +into an executable file by using the I<undump> program (not supplied).
> This speeds startup at the expense of some disk space (which you
> can minimize by stripping the executable). (Still, a "hello world"
> executable comes out to about 200K on my machine.) If you want to
> execute a portion of your program before dumping, use the dump()
> -operator instead. Note: availability of B<undump> is platform
> +operator instead. Note: availability of I<undump> is platform
> specific and may not be available for a specific port of Perl.
>
> =item B<-U>
> X<-U>
>
> allows Perl to do unsafe operations. Currently the only "unsafe"
> -operations are attempting to unlink directories while running as
> -superuser, and running setuid programs with fatal taint checks turned
> -into warnings. Note that the B<-w> switch (or the C<$^W> variable)
> -must be used along with this option to actually I<generate> the
> -taint-check warnings.
> +operations are attempting to unlink directories while running as superuser
> +and running setuid programs with fatal taint checks turned into warnings.
> +Note that warnings must be enabled along with this option to actually
> +I<generate> the taint-check warnings.
>
> =item B<-v>
> X<-v>
> @@ -845,7 +844,7 @@
> =item B<-V:>I<configvar>
>
> Prints to STDOUT the value of the named configuration variable(s),
> -with multiples when your configvar argument looks like a regex (has
> +with multiples when your C<I<configvar>> argument looks like a regex (has
> non-letters). For example:
>
> $ perl -V:libc
> @@ -862,14 +861,14 @@
> ....
>
> Additionally, extra colons can be used to control formatting. A
> -trailing colon suppresses the linefeed and terminator ';', allowing
> +trailing colon suppresses the linefeed and terminator ";", allowing
> you to embed queries into shell commands. (mnemonic: PATH separator
> -':'.)
> +":".)
>
> $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
> compression-vars: zcat='' zip='zip' are here !
>
> -A leading colon removes the 'name=' part of the response, this allows
> +A leading colon removes the "name=" part of the response, this allows
> you to map to the name you need. (mnemonic: empty label)
>
> $ echo "goodvfork="`./perl -Ilib -V::usevfork`
> @@ -877,7 +876,7 @@
>
> Leading and trailing colons can be used together if you need
> positional parameter values without the names. Note that in the case
> -below, the PERL_API params are returned in alphabetical order.
> +below, the C<PERL_API> params are returned in alphabetical order.
>
> $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
> building_on 'linux' '5' '1' '9' now
> @@ -886,17 +885,18 @@
> X<-w>
>
> prints warnings about dubious constructs, such as variable names
> -that are mentioned only once and scalar variables that are used
> -before being set, redefined subroutines, references to undefined
> -filehandles or filehandles opened read-only that you are attempting
> -to write on, values used as a number that don'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.
> +mentioned only once and scalar variables used
> +before being set; redefined subroutines; references to undefined
> +filehandles; filehandles opened read-only that you are attempting
> +to write on; values used as a number that don't I<look> like numbers;
> +using an array as though it were a scalar; if your subroutines
> +recurse more than 100 deep; and innumerable other things.
>
> -This switch really just enables the internal C<$^W> variable. You
> +This switch really just enables the global C<$^W> variable; normally,
> +the lexically scoped C<use warnings> pragma is preferred. You
> 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
> +See also L<perldiag> and L<perltrap>. A fine-grained warning
> facility is also available if you want to manipulate entire classes
> of warnings; see L<warnings> or L<perllexwarn>.
>
> @@ -918,23 +918,23 @@
> =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
> +text, such as in a mail message. Leading garbage will be
> +discarded until the first line that starts with C<#!> 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.
> +will treat the C<#!> 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, not as line 100.
> +This can be overridden by using the C<#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
> -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).
> +C<__END__> if there is trailing garbage to be ignored; the program
> +can process any or all of the trailing garbage via the C<DATA> filehandle
> +if desired.
>
> The directory, if specified, must appear immediately following the B<-x>
> with no intervening whitespace.
> @@ -949,12 +949,12 @@
> =item HOME
> X<HOME>
>
> -Used if chdir has no argument.
> +Used if C<chdir> has no argument.
>
> =item LOGDIR
> X<LOGDIR>
>
> -Used if chdir has no argument and HOME is not set.
> +Used if C<chdir> has no argument and HOME is not set.
>
> =item PATH
> X<PATH>
> @@ -968,66 +968,68 @@
> A list of directories in which to look for Perl library
> files before looking in the standard library and the current
> directory. Any architecture-specific directories under the specified
> -locations are automatically included if they exist (this lookup
> -being done at interpreter startup time.)
> +locations are automatically included if they exist, with this lookup
> +done at interpreter startup time.
>
> If PERL5LIB is not defined, PERLLIB is used. Directories are separated
> (like in PATH) by a colon on Unixish platforms and by a semicolon on
> Windows (the proper path separator being given by the command C<perl
> --V:path_sep>).
> +-V:I<path_sep>>).
>
> -When running taint checks (either because the program was running setuid
> -or setgid, or the B<-T> or B<-t> switch was specified), neither variable
> -is used. The program should instead say:
> +When running taint checks, either because the program was running setuid or
> +setgid, or the B<-T> or B<-t> switch was specified, neither PERL5LIB nor
> +PERLLIB is consulted. The program should instead say:
>
> use lib "/my/directory";
>
> =item PERL5OPT
> X<PERL5OPT>
>
> -Command-line options (switches). Switches in this variable are taken
> +Command-line options (switches). Switches in this variable are treated
> 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
> -enabled, and any subsequent options ignored.
> +switches are allowed. When running taint checks (either because the
> +program was running setuid or setgid, or because the B<-T> or B<-t>
> +switch was used), this variable is ignored. If PERL5OPT begins with
> +B<- T>, tainting will be enabled and subsequent options ignored. If
> +PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot
> +removed from @INC, and subsequent options honored.
>
> =item PERLIO
> X<PERLIO>
>
> A space (or colon) separated list of PerlIO layers. If perl is built
> -to use PerlIO system for IO (the default) these layers effect perl's IO.
> +to use PerlIO system for IO (the default) these layers affect Perl's IO.
>
> -It is conventional to start layer names with a colon e.g. C<:perlio> to
> -emphasise their similarity to variable "attributes". But the code that parses
> -layer specification strings (which is also used to decode the PERLIO
> -environment variable) treats the colon as a separator.
> +It is conventional to start layer names with a colon (for example, C<:perlio>) to
> +emphasize their similarity to variable "attributes". But the code that parses
> +layer specification strings, which is also used to decode the PERLIO
> +environment variable, treats the colon as a separator.
>
> An unset or empty PERLIO is equivalent to the default set of layers for
> -your platform, for example C<:unix:perlio> on Unix-like systems
> +your platform; for example, C<:unix:perlio> on Unix-like systems
> and C<:unix:crlf> on Windows and other DOS-like systems.
>
> -The list becomes the default for I<all> perl's IO. Consequently only built-in
> -layers can appear in this list, as external layers (such as :encoding()) need
> +The list becomes the default for I<all> Perl's IO. Consequently only built-in
> +layers can appear in this list, as external layers (such as C<:encoding()>) need
> IO in order to load them!. See L<"open pragma"|open> for how to add external
> encodings as defaults.
>
> -The layers that it makes sense to include in the PERLIO environment
> -variable are briefly summarised below. For more details see L<PerlIO>.
> +Layers it makes sense to include in the PERLIO environment
> +variable are briefly summarized below. For more details see L<PerlIO>.
>
> =over 8
>
> =item :bytes
> X<:bytes>
>
> -A pseudolayer that turns I<off> the C<:utf8> flag for the layer below.
> -Unlikely to be useful on its own in the global PERLIO environment variable.
> +A pseudolayer that turns the C<:utf8> flag I<off> for the layer below;
> +unlikely to be useful on its own in the global PERLIO environment variable.
> You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
>
> =item :crlf
> X<:crlf>
>
> -A layer which does CRLF to "\n" translation distinguishing "text" and
> +A layer which does CRLF to C<"\n"> translation distinguishing "text" and
> "binary" files in the manner of MS-DOS and similar operating systems.
> (It currently does I<not> mimic MS-DOS as far as treating of Control-Z
> as being an end-of-file marker.)
> @@ -1035,101 +1037,101 @@
> =item :mmap
> X<:mmap>
>
> -A layer which implements "reading" of files by using C<mmap()> to
> -make (whole) file appear in the process's address space, and then
> +A layer that implements "reading" of files by using I<mmap>(2) to
> +make an entire file appear in the process's address space, and then
> using that as PerlIO's "buffer".
>
> =item :perlio
> X<:perlio>
>
> -This is a re-implementation of "stdio-like" buffering written as a
> -PerlIO "layer". As such it will call whatever layer is below it for
> -its operations (typically C<:unix>).
> +This is a re-implementation of stdio-like buffering written as a
> +PerlIO layer. As such it will call whatever layer is below it for
> +its operations, typically C<:unix>.
>
> =item :pop
> X<:pop>
>
> An experimental pseudolayer that removes the topmost layer.
> -Use with the same care as is reserved for nitroglycerin.
> +Use with the same care as is reserved for nitroglycerine.
>
> =item :raw
> X<:raw>
>
> A pseudolayer that manipulates other layers. Applying the C<:raw>
> layer is equivalent to calling C<binmode($fh)>. It makes the stream
> -pass each byte as-is without any translation. In particular CRLF
> -translation, and/or :utf8 intuited from locale are disabled.
> +pass each byte as-is without translation. In particular, both CRLF
> +translation and intuiting C<:utf8> from the locale are disabled.
>
> -Unlike in the earlier versions of Perl C<:raw> is I<not>
> -just the inverse of C<:crlf> - other layers which would affect the
> +Unlike in earlier versions of Perl, C<:raw> is I<not>
> +just the inverse of C<:crlf>: other layers which would affect the
> binary nature of the stream are also removed or disabled.
>
> =item :stdio
> X<:stdio>
>
> -This layer provides PerlIO interface by wrapping system's ANSI C "stdio"
> +This layer provides a PerlIO interface by wrapping system's ANSI C "stdio"
> library calls. The layer provides both buffering and IO.
> -Note that C<:stdio> layer does I<not> do CRLF translation even if that
> -is platforms normal behaviour. You will need a C<:crlf> layer above it
> +Note that the C<:stdio> layer does I<not> do CRLF translation even if that
> +is the platform's normal behaviour. You will need a C<:crlf> layer above it
> to do that.
>
> =item :unix
> X<:unix>
>
> -Low level layer which calls C<read>, C<write> and C<lseek> etc.
> +Low-level layer that calls C<read>, C<write>, C<lseek>, etc.
>
> =item :utf8
> X<:utf8>
>
> -A pseudolayer that turns on a flag on the layer below to tell perl
> +A pseudolayer that enables a flag in the layer below to tell Perl
> that output should be in utf8 and that input should be regarded as
> -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
> +already in valid utf8 form. B<WARNING: It does not check for validity and as such
> +should be handled with extreme caution for input, because security violations
> +can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(utf8)> is
> the best option when reading UTF-8 encoded data.
>
> =item :win32
> X<:win32>
>
> On Win32 platforms this I<experimental> layer uses native "handle" IO
> -rather than unix-like numeric file descriptor layer. Known to be
> -buggy in this release.
> +rather than a Unix-like numeric file descriptor layer. Known to be
> +buggy in this release (5.14).
>
> =back
>
> -On all platforms the default set of layers should give acceptable results.
> +The default set of layers should give acceptable results on all platforms
>
> -For Unix platforms that will equivalent of "unix perlio" or "stdio".
> -Configure is setup to prefer "stdio" implementation if system's library
> -provides for fast access to the buffer, otherwise it uses the "unix perlio"
> +For Unix platforms that will be the equivalent of "unix perlio" or "stdio".
> +Configure is set up to prefer the "stdio" implementation if the system's library
> +provides for fast access to the buffer; otherwise, it uses the "unix perlio"
> implementation.
>
> -On Win32 the default in this release is "unix crlf". Win32's "stdio"
> -has a number of bugs/mis-features for perl IO which are somewhat
> -C compiler vendor/version dependent. Using our own C<crlf> layer as
> -the buffer avoids those issues and makes things more uniform.
> -The C<crlf> layer provides CRLF to/from "\n" conversion as well as
> -buffering.
> -
> -This release uses C<unix> as the bottom layer on Win32 and so still uses C
> -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.
> +On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio"
> +has a number of bugs/mis-features for Perl IO which are somewhat depending
> +on the version and vendor of the C compiler. Using our own C<crlf> layer as
> +the buffer avoids those issues and makes things more uniform. The C<crlf>
> +layer provides CRLF conversion as well as buffering.
> +
> +This release (5.14) uses C<unix> as the bottom layer on Win32, and so still
> +uses the C compiler's numeric file descriptor routines. There is an
> +experimental native C<win32> layer, which is expected to be enhanced and
> +should eventually become the default under Win32.
>
> -The PERLIO environment variable is completely ignored when perl
> +The PERLIO environment variable is completely ignored when Perl
> is run in taint mode.
>
> =item PERLIO_DEBUG
> X<PERLIO_DEBUG>
>
> -If set to the name of a file or device then certain operations of PerlIO
> -sub-system will be logged to that file (opened as append). Typical uses
> -are Unix:
> +If set to the name of a file or device, certain operations of PerlIO
> +subsystem will be logged to that file, which is opened in append mode
> +Typical uses are in Unix:
>
> - PERLIO_DEBUG=/dev/tty perl script ...
> + % env PERLIO_DEBUG=/dev/tty perl script ...
>
> -and Win32 approximate equivalent:
> +and under Win32, the approximately equivalent:
>
> - set PERLIO_DEBUG=CON
> + > set PERLIO_DEBUG=CON
> perl script ...
>
> This functionality is disabled for setuid scripts and for scripts run
> @@ -1142,7 +1144,7 @@
> 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
> +The PERLLIB environment variable is completely ignored when Perl
> is run in taint mode.
>
> =item PERL5DB
> @@ -1150,9 +1152,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
> +The PERL5DB environment variable is only used when Perl is started with
> a bare B<-d> switch.
>
> =item PERL5DB_THREADED
> @@ -1164,15 +1166,15 @@
> =item PERL5SHELL (specific to the Win32 port)
> X<PERL5SHELL>
>
> -May be set to an alternative shell that perl must use internally for
> -executing "backtick" commands or system(). Default is C<cmd.exe /x/d/c>
> -on WindowsNT and C<command.com /c> on Windows95. The value is considered
> -to be space-separated. Precede any character that needs to be protected
> -(like a space or backslash) with a backslash.
> +On Win32 ports only, may be set to an alternative shell that Perl must use
> +internally for executing "backtick" commands or system(). Default is
> +C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The
> +value is considered space-separated. Precede any character that
> +needs to be protected, like a space or backslash, with another backslash.
>
> Note that Perl doesn't use COMSPEC for this purpose because
> COMSPEC has a high degree of variability among users, leading to
> -portability concerns. Besides, perl can use a shell that may not be
> +portability concerns. Besides, Perl can use a shell that may not be
> 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).
> @@ -1185,73 +1187,75 @@
> =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
> X<PERL_ALLOW_NON_IFS_LSP>
>
> -Set to 1 to allow the use of non-IFS compatible LSP's.
> +Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers).
> Perl normally searches for an IFS-compatible LSP because this is required
> for its emulation of Windows sockets as real filehandles. However, this may
> -cause problems if you have a firewall such as McAfee Guardian which requires
> -all applications to use its LSP which is not IFS-compatible, because clearly
> +cause problems if you have a firewall such as I<McAfee Guardian>, which requires
> +that all applications use its LSP but which is not IFS-compatible, because clearly
> Perl will normally avoid using such an LSP.
> +
> Setting this environment variable to 1 means that Perl will simply use the
> -first suitable LSP enumerated in the catalog, which keeps McAfee Guardian
> -happy (and in that particular case Perl still works too because McAfee
> -Guardian's LSP actually plays some other games which allow applications
> -requiring IFS compatibility to work).
> +first suitable LSP enumerated in the catalog, which keeps I<McAfee Guardian>
> +happy--and in that particular case Perl still works too because I<McAfee
> +Guardian>'s LSP actually plays other games which allow applications
> +requiring IFS compatibility to work.
>
> =item PERL_DEBUG_MSTATS
> X<PERL_DEBUG_MSTATS>
>
> -Relevant only if perl is compiled with the malloc included with the perl
> -distribution (that is, if C<perl -V:d_mymalloc> is 'define').
> -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
> +Relevant only if Perl is compiled with the C<malloc> included with the Perl
> +distribution; that is, if C<perl -V:d_mymalloc> is "define".
> +
> +If set, this dumps out memory statistics after execution. If set
> +to an integer greater than one, also dumps out memory statistics
> after compilation.
>
> =item PERL_DESTRUCT_LEVEL
> X<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
> +Relevant only if your Perl executable was built with B<-DDEBUGGING>,
> +this controls the behaviour of global destruction of objects and other
> references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information.
>
> =item PERL_DL_NONLAZY
> X<PERL_DL_NONLAZY>
>
> -Set to one to have perl resolve B<all> undefined symbols when it loads
> +Set to C<"1"> to have Perl resolve I<all> undefined symbols when it loads
> a dynamic library. The default behaviour is to resolve symbols when
> they are used. Setting this variable is useful during testing of
> -extensions as it ensures that you get an error on misspelled function
> -names even if the test suite doesn't call it.
> +extensions, as it ensures that you get an error on misspelled function
> +names even if the test suite doesn't call them.
>
> =item PERL_ENCODING
> X<PERL_ENCODING>
>
> -If using the C<encoding> pragma without an explicit encoding name, the
> +If using the C<use encoding> pragma without an explicit encoding name, the
> PERL_ENCODING environment variable is consulted for an encoding name.
>
> =item PERL_HASH_SEED
> X<PERL_HASH_SEED>
>
> -(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
> +(Since Perl 5.8.1.) Used to randomize Perl's internal hash function.
> +To emulate the pre-5.8.1 behaviour, set to an integer; C<"0"> means
> +exactly the same order as in 5.8.0. "Pre-5.8.1" means, among other
> things, that hash keys will always have the same ordering between
> -different runs of perl.
> +different runs of Perl.
>
> -Most hashes return elements in the same order as Perl 5.8.0 by default.
> +Most hashes by default return elements in the same order as in Perl 5.8.0.
> 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.
> -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.
> +The default behaviour is to randomize unless the PERL_HASH_SEED is set.
> +If Perl has been compiled with B<-DUSE_HASH_SEED_EXPLICIT>, the default
> +behaviour is I<not> to randomize 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.
>
> -B<Please note that the hash seed is sensitive information>. Hashes are
> +B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are
> randomized to protect against local and remote attacks against Perl
> -code. By manually setting a seed this protection may be partially or
> +code. By manually setting a seed, this protection may be partially or
> completely lost.
>
> See L<perlsec/"Algorithmic Complexity Attacks"> and
> @@ -1260,48 +1264,48 @@
> =item PERL_HASH_SEED_DEBUG
> X<PERL_HASH_SEED_DEBUG>
>
> -(Since Perl 5.8.1.) Set to one to display (to STDERR) the value of
> +(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) the value of
> the hash seed at the beginning of execution. This, combined with
> L</PERL_HASH_SEED> is intended to aid in debugging nondeterministic
> -behavior caused by hash randomization.
> +behaviour caused by hash randomization.
>
> -B<Note that the hash seed is sensitive information>: by knowing it one
> -can craft a denial-of-service attack against Perl code, even remotely,
> +B<Note that the hash seed is sensitive information>: by knowing it, one
> +can craft a denial-of-service attack against Perl code, even remotely;
> see L<perlsec/"Algorithmic Complexity Attacks"> for more information.
> B<Do not disclose the hash seed> to people who don't need to know it.
> -See also hash_seed() of L<Hash::Util>.
> +See also hash_seed() in L<Hash::Util>.
>
> =item PERL_MEM_LOG
> X<PERL_MEM_LOG>
>
> -If your perl was configured with C<-Accflags=-DPERL_MEM_LOG>, setting
> +If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting
> the environment variable C<PERL_MEM_LOG> enables logging debug
> -messages. The value has the form C<< <number>[m][s][t] >>, where
> -C<number> is the filedescriptor number you want to write to (2 is
> +messages. The value has the form C<< <I<number>>[m][s][t] >>, where
> +C<I<number>> is the file descriptor number you want to write to (2 is
> default), and the combination of letters specifies that you want
> information about (m)emory and/or (s)v, optionally with
> -(t)imestamps. For example C<PERL_MEM_LOG=1mst> will log all
> -information to stdout. You can write to other opened filedescriptors
> -too, in a variety of ways;
> +(t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all
> +information to stdout. You can write to other opened file descriptors
> +in a variety of ways:
>
> - bash$ 3>foo3 PERL_MEM_LOG=3m perl ...
> + $ 3>foo3 PERL_MEM_LOG=3m perl ...
>
> =item PERL_ROOT (specific to the VMS port)
> X<PERL_ROOT>
>
> -A translation concealed rooted logical name that contains perl and the
> +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
> +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 PERL_SIGNALS
> X<PERL_SIGNALS>
>
> -In Perls 5.8.1 and later. If set to C<unsafe> the pre-Perl-5.8.0
> -signals behaviour (immediate but unsafe) is restored. If set to
> -C<safe> the safe (or deferred) signals are used.
> -See L<perlipc/"Deferred Signals (Safe Signals)">.
> +Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0
> +signal behaviour (which is immediate but unsafe) is restored. If set
> +to C<safe>, then safe (but deferred) signals are used. See
> +L<perlipc/"Deferred Signals (Safe Signals)">.
>
> =item PERL_UNICODE
> X<PERL_UNICODE>
> @@ -1310,7 +1314,7 @@
> a boolean variable. Setting this to C<"1"> is not the right way to
> "enable Unicode" (whatever that would mean). You can use C<"0"> to
> "disable Unicode", though (or alternatively unset PERL_UNICODE in
> -your shell before starting Perl). See the description of the C<-C>
> +your shell before starting Perl). See the description of the B<-C>
> switch for more information.
>
> =item SYS$LOGIN (specific to the VMS port)
> @@ -1321,14 +1325,21 @@
> =back
>
> Perl also has environment variables that control how Perl handles data
> -specific to particular natural languages. See L<perllocale>.
> +specific to particular natural languages; see L<perllocale>.
>
> -Apart from these, Perl uses no other environment variables, except
> -to make them available to the program being executed, and to child
> -processes. However, programs running setuid would do well to execute
> -the following lines before doing anything else, just to keep people
> -honest:
> +Perl and its various modules and components, including its test frameworks,
> +may sometimes make use of certain other environment variables. Some of
> +these are specific to a particular platform. Please consult the
> +appropriate module documentation and any documentation for your platform
> +(like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for
> +variables peculiar to those specific situations.
> +
> +Perl makes all environment variables available to the program being
> +executed, and passes these along to any child processes it starts.
> +However, programs 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 exists $ENV{SHELL};
> + $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need
> + $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
> delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
> +
Thread Previous