S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[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<-A>[I<module>][=I<assertions>] ]>
S<[ B<-C [I<number/list>] >]>
- S<[ B<-P> ]>
S<[ B<-S> ]>
S<[ B<-x>[I<dir>] ]>
S<[ B<-i>[I<extension>] ]>
- S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+ S<[ B<-eE> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
=head1 DESCRIPTION
=item 1.
-Specified line by line via B<-e> switches on the command line.
+Specified line by line via B<-e> or B<-E> switches on the command line.
=item 2.
(This means that you cannot use the C<-x> with a directory name that
consists of hexadecimal digits.)
-=item B<-A[I<module>][=I<assertions>]>
-X<-A>
-
-Activates the assertions given after the equal sign as a comma-separated
-list of assertion names or regular expressions. If no assertion name
-is given, activates all assertions.
-
-The module L<assertions::activate> is used by default to activate the
-selected assertions. An alternate module may be specified including
-its name between the switch and the equal sign.
-
-See L<assertions> and L<assertions::activate>.
-
=item B<-a>
X<-a> X<autosplit>
=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
variables (the LC_ALL, LC_TYPE, and LANG, in the order
of decreasing precedence) -- if the variables indicate
UTF-8, then the selected "IOEioA" are in effect
+ a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching code in
+ debugging mode.
+
+=for documenting_the_underdocumented
+perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */"
+
+=for todo
+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
STDOUT and STDERR. Repeating letters is just redundant, not cumulative
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<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 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.
=item B<-d>
X<-d> X<-dt>
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
+ 64 P Print profiling info, source file input state
128 m Memory allocation
256 f Format processing
512 r Regular expression parsing and execution
1024 x Syntax tree dump
2048 u Tainting checks
- 4096 (Obsolete, previously used for LEAKTEST)
+ 4096 U Unofficial, User hacking (reserved for private, unreleased use)
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
commands may be given to build up a multi-line script. Make sure
to use semicolons where you would in a normal program.
+=item B<-E> I<commandline>
+X<-E>
+
+behaves just like B<-e>, except that it implicitly enables all
+optional features (in the main compilation unit). See L<feature>.
+
=item B<-f>
X<-f>
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>
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<$\>
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>
enables rudimentary switch parsing for switches on the command
line after the program name but before any filename arguments (or before
-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
+an argument of B<-->). 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
+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
warnings enabled you may get a lot of spurious "used only once" warnings.
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>
allows Perl to do unsafe operations. Currently the only "unsafe"
-operations are the unlinking of 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 the B<-w> switch (or the C<$^W> variable)
+must be used along with this option to actually I<generate> the
+taint-check warnings.
=item B<-v>
X<-v>
=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.
+
+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
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
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. 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>).
+locations are automatically included if they exist (this lookup
+being 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>).
When running taint checks (either because the program was running setuid
-or setgid, or the B<-T> switch was used), neither variable is used.
-The program should instead say:
+or setgid, or the B<-T> or B<-t> switch was specified), neither variable
+is used. The program should instead say:
use lib "/my/directory";
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<-[CDIMUdmtw]>
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
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 C<:stdio>.
+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
+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
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 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
-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.
-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.
-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.
-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