Contained in the file specified by the first filename on the command line.
(Note that systems supporting the C<#!> notation invoke interpreters this
-way. See L<Location of Perl>.)
+way. See L</Location of Perl>.)
=item 3.
a specific version of Perl, say, perl5.14.1, you should place
that directly in the C<#!> line's path.
-If the C<#!> line does not contain the word "perl" nor the word "indir"
+If the C<#!> line does not contain the word "perl" nor the word "indir",
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
#!/usr/bin/perl -spi.orig # same as -s -p -i.orig
+A C<--> signals the end of options and disables further option processing. Any
+arguments after the C<--> are treated as filenames and arguments.
+
Switches include:
=over 5
An alternate delimiter may be specified using B<-F>.
+B<-a> implicitly sets B<-n>.
+
=item B<-C [I<number/list>]>
X<-C>
in UTF-8
L 64 normally the "IOEioA" are unconditional, the L makes
them conditional on the locale environment variables
- (the LC_ALL, LC_TYPE, and LANG, in the order of
+ (the LC_ALL, LC_CTYPE, 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
=item B<-D>I<number>
-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;
-the format of the output is explained in L<perldebguts>.
+sets debugging flags. This switch is enabled only if your perl binary has
+been built with debugging enabled: normal production perls won't have
+been.
+
+For example, to watch how perl executes your program, use B<-Dtls>.
+Another nice value is B<-Dx>, which lists your compiled 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 (with v, displays parse stack)
- 2 s Stack snapshots (with v, displays all stacks)
- 4 l Context (loop) stack processing
- 8 t Trace execution
- 16 o Method and overloading resolution
- 32 c String/numeric conversions
- 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
- 2048 u Tainting checks
- 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 Op slab allocation
- 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
- 2097152 C Copy On Write
- 4194304 A Consistency checks on internal structures
- 8388608 q quiet - currently only suppresses the "EXECUTING"
- message
- 16777216 M trace smart match resolution
- 33554432 B dump suBroutine definitions, including special Blocks
- like BEGIN
+ 1 p Tokenizing and parsing (with v, displays parse
+ stack)
+ 2 s Stack snapshots (with v, displays all stacks)
+ 4 l Context (loop) stack processing
+ 8 t Trace execution
+ 16 o Method and overloading resolution
+ 32 c String/numeric conversions
+ 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
+ 2048 u Tainting checks
+ 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 Op slab allocation
+ 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
+ 2097152 C Copy On Write
+ 4194304 A Consistency checks on internal structures
+ 8388608 q quiet - currently only suppresses the "EXECUTING"
+ message
+ 16777216 M trace smart match resolution
+ 33554432 B dump suBroutine definitions, including special
+ Blocks like BEGIN
+ 67108864 L trace Locale-related info; what gets output is very
+ subject to change
+ 134217728 i trace PerlIO layer processing. Set PERLIO_DEBUG to
+ the filename to trace to.
All these flags require B<-DDEBUGGING> when you compile the Perl
executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode>
which may change this).
See the F<INSTALL> file in the Perl source distribution
-for how to do this. This flag is automatically set if you include B<-g>
-option when C<Configure> asks you about optimizer/debugger flags.
+for how to do this.
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,
=item B<-F>I<pattern>
X<-F>
-specifies the pattern to split on if B<-a> is also in effect. The
-pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
-put in single quotes. You can't use literal whitespace in the pattern.
+specifies the pattern to split on for B<-a>. The pattern may be
+surrounded by C<//>, C<"">, or C<''>, otherwise it will be put in single
+quotes. You can't use literal whitespace in the pattern.
+
+B<-F> implicitly sets both B<-a> and B<-n>.
=item B<-h>
X<-h>
modify the name of the old file to make a backup copy, following these
rules:
-If no extension is supplied, no backup is made and the current file is
-overwritten.
+If no extension is supplied, and your system supports it, the original
+I<file> is kept open without a name while the output is redirected to
+a new file with the original I<filename>. When perl exits, cleanly or not,
+the original I<file> is unlinked.
If the extension doesn't contain a C<*>, then it is appended to the
end of the current filename as a suffix. If the extension does
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>,
-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?>.
+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?>.
You cannot use B<-i> to create directories or to strip extensions from
files.
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>.
+removes the distinction between B<-m> and B<-M>; that is,
+B<-mI<MODULE>=foo,bar> is the same as B<-MI<MODULE>=foo,bar>.
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
find . -mtime +7 -print | perl -nle unlink
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>.
+have to start a process on every filename found (but it's not faster
+than using the B<-delete> switch available in newer versions of I<find>.
+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 I<awk>.
#!/usr/bin/perl -s
if ($xyz) { print "$xyz\n" }
-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.
+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>
C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
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>.
+of warnings; see L<warnings>.
=item B<-W>
X<-W>
Enables all warnings regardless of C<no warnings> or C<$^W>.
-See L<perllexwarn>.
+See L<warnings>.
=item B<-X>
X<-X>
Disables all warnings regardless of C<use warnings> or C<$^W>.
-See L<perllexwarn>.
+See L<warnings>.
=item B<-x>
X<-x>
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, with this lookup
-done at interpreter startup time.
+directory. Any architecture-specific and version-specific directories,
+such as F<version/archname/>, F<version/>, or F<archname/> under the
+specified locations are automatically included if they exist, with this
+lookup done at interpreter startup time. In addition, any directories
+matching the entries in C<$Config{inc_version_list}> are added.
+(These typically would be for older compatible perl versions installed
+in the same directory tree.)
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
=item PERLIO_DEBUG
X<PERLIO_DEBUG>
-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:
+If set to the name of a file or device when Perl is run with the
+B<-Di> command-line switch, the logging of certain operations of
+the PerlIO subsystem will be redirected to the specified file rather
+than going to stderr, which is the default. The file is opened in append
+mode. Typical uses are in Unix:
- % env PERLIO_DEBUG=/dev/tty perl script ...
+ % env PERLIO_DEBUG=/tmp/perlio.log perl -Di script ...
and under Win32, the approximately equivalent:
> set PERLIO_DEBUG=CON
- perl script ...
+ perl -Di script ...
-This functionality is disabled for setuid scripts and for scripts run
-with B<-T>.
+This functionality is disabled for setuid scripts, for scripts run
+with B<-T>, and for scripts run on a Perl built without C<-DDEBUGGING>
+support.
=item PERLLIB
X<PERLLIB>
=item PERL_HASH_SEED
X<PERL_HASH_SEED>
-(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.
+(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override
+the randomization of Perl's internal hash function. The value is expressed
+in hexadecimal, and may include a leading 0x. Truncated patterns
+are treated as though they are suffixed with sufficient 0's as required.
-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 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
-the pseudorandom seed supplied by the operating system and libraries.
+If the option is provided, and C<PERL_PERTURB_KEYS> is NOT set, then
+a value of '0' implies C<PERL_PERTURB_KEYS=0> and any other value
+implies C<PERL_PERTURB_KEYS=2>.
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
completely lost.
-See L<perlsec/"Algorithmic Complexity Attacks"> and
+See L<perlsec/"Algorithmic Complexity Attacks">, L</PERL_PERTURB_KEYS>, and
L</PERL_HASH_SEED_DEBUG> for more information.
+=item PERL_PERTURB_KEYS
+X<PERL_PERTURB_KEYS>
+
+(Since Perl 5.18.0) Set to C<"0"> or C<"NO"> then traversing keys
+will be repeatable from run to run for the same PERL_HASH_SEED.
+Insertion into a hash will not change the order, except to provide
+for more space in the hash. When combined with setting PERL_HASH_SEED
+this mode is as close to pre 5.18 behavior as you can get.
+
+When set to C<"1"> or C<"RANDOM"> then traversing keys will be randomized.
+Every time a hash is inserted into the key order will change in a random
+fashion. The order may not be repeatable in a following program run
+even if the PERL_HASH_SEED has been specified. This is the default
+mode for perl.
+
+When set to C<"2"> or C<"DETERMINISTIC"> then inserting keys into a hash
+will cause the key order to change, but in a way that is repeatable
+from program run to program run.
+
+B<NOTE:> Use of this option is considered insecure, and is intended only
+for debugging non-deterministic behavior in Perl's hash function. Do
+not use it in production.
+
+See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_HASH_SEED>
+and L</PERL_HASH_SEED_DEBUG> for more information. You can get and set the
+key traversal mask for a specific hash by using the C<hash_traversal_mask()>
+function from L<Hash::Util>.
+
=item PERL_HASH_SEED_DEBUG
X<PERL_HASH_SEED_DEBUG>
-(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
-behaviour caused by hash randomization.
+(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) information
+about the hash function, seed, and what type of key traversal
+randomization is in effect at the beginning of execution. This, combined
+with L</PERL_HASH_SEED> and L</PERL_PERTURB_KEYS> is intended to aid in
+debugging nondeterministic behaviour caused by hash randomization.
+
+B<Note> that any information about the hash function, especially the hash
+seed is B<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 C<hash_seed()> and
+C<key_traversal_mask()> in L<Hash::Util>.
+
+An example output might be:
-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() in L<Hash::Util>.
+ HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
=item PERL_MEM_LOG
X<PERL_MEM_LOG>