B<perl> S<[ B<-sTtuUWX> ]>
S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
- S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+ S<[ B<-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...'> ]>
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<-C [I<number/list>] >]> ]>
+ S<[ B<-A [I<assertions>] >]>
+ S<[ B<-C [I<number/list>] >]>
=head1 DESCRIPTION
=item MS-DOS
Create a batch file to run your program, and codify it in
-C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source
+C<ALTERNATE_SHEBANG> (see the F<dosish.h> file in the source
distribution for more information).
=item Win95/NT
=over 5
-=item B<-0>[I<digits>]
+=item B<-0>[I<octal/hexadecimal>]
-specifies the input record separator (C<$/>) as an octal 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 terminated by the null character, you
-can say this:
+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
+terminated by the null character, you can say this:
find . -name '*.orig' -print0 | perl -n0e unlink
The special value 00 will cause Perl to slurp files in paragraph mode.
The value 0777 will cause Perl to slurp files whole because there is no
-legal character with that value.
+legal byte with that value.
+
+If you want to specify any Unicode character, use the hexadecimal
+format: C<-0xHHH...>, where the C<H> are valid hexadecimal digits.
+(This means that you cannot use the C<-x> with a directory name that
+consists of hexadecimal digits.)
+
+=item B<-A [I<assertions>]>
+
+Activates the assertions given after the switch as a comma-separated
+list of assertion names. If no assertion name is given, activates all
+assertions. See L<assertions>.
=item B<-a>
The C<-C> flag controls some Unicode 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.
-
- I 0x0001 STDIN is assumed to be in UTF-8
- O 0x0002 STDOUT will be in UTF-8
- E 0x0004 STDERR will be in UTF-8
- S 0x0007 I + O + E
- i 0x0008 the default input layer expects UTF-8
- o 0x0010 the default output layer enforces UTF-8
- D 0x0018 i + o
- A 0x0020 the @ARGV elements are supposed to be in UTF-8
- L 0x0040 normally the IOEio (SD) are unconditional,
- the L makes them conditional on the locale environment
- variables (the LC_ALL, LC_TYPE, and LANG; in the order
- of decreasing precedence)
-
-The C<-C> on its own (not followed by any number or option list) has
-the same effect as <-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
-environment variables indicate a UTF-8 locale. This behavior follows
-the I<implicit> behaviour of Perl 5.8.0.
-
-You can use C<-C0> to explicitly disable all the above Unicode features.
-
-See L<perluniintro>, L<perlfunc/open>, and L<open> for more information.
-
-The magic variable C<${^UNICODE}> reflects the state of this setting,
-see L<perlvar/"${^UNICODE}">. (Another way of setting this variable
-is to set the environment variable PERL_UNICODE.)
+of option letters. The letters, their numeric values, and effects
+are as follows; listing the letters is equal to summing the numbers.
+
+ I 1 STDIN is assumed to be in UTF-8
+ O 2 STDOUT will be in UTF-8
+ E 4 STDERR will be in UTF-8
+ S 7 I + O + E
+ i 8 UTF-8 is the default PerlIO layer for input streams
+ o 16 UTF-8 is the default PerlIO layer for output streams
+ D 24 i + o
+ A 32 the @ARGV elements are expected to be strings encoded
+ 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 decreasing precedence) -- if the variables indicate
+ UTF-8, then the selected "IOEioA" are in effect
+
+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
+nor toggling.
+
+The C<io> options mean that any subsequent open() (or similar I/O
+operations) will have the C<:utf8> PerlIO layer implicitly applied
+to them, in other words, UTF-8 is expected from any input stream,
+and UTF-8 is produced to any output stream. This is just 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
+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
+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
+disable all the above Unicode features.
+
+The read-only magic variable C<${^UNICODE}> reflects the numeric value
+of this setting. This is variable is set during Perl startup and is
+thereafter read-only. If you want runtime effects, use the three-arg
+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
that enabled the use of Unicode-aware "wide system call" Win32 APIs.
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
+ 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
524288 J Do not s,t,P-debug (Jump over) 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 suppressed the "EXECUTING" message
All these flags require B<-DDEBUGGING> when you compile the Perl
executable (but see L<Devel::Peek>, L<re> which may change this).
This allows you to add a prefix to the backup file, instead of (or in
addition to) a suffix:
- $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
+ $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
Or even to place backup copies of the original files into another
directory (provided the directory already exists):
- $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
+ $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
These sets of one-liners are equivalent:
$ perl -pi -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file
+ $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
- $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
From the shell, saying
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.
-Here is an efficient way to delete all files older than a week:
+Here is an efficient way to delete all files that haven't been modifed for
+at least a week:
find . -mtime +7 -print | perl -nle unlink
=item PERL5LIB
-A colon-separated list of directories in which to look for Perl library
+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.
+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.
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>.
+
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
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 summarised below. For more details see L<PerlIO>.
+variable are
briefly summarised below. For more details see L<PerlIO>.
=over 8
=item :bytes
-Turns I<off> the C<:utf8> flag for the layer below.
-Unlikely to be useful in global PERLIO environment variable.
+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.
+You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
=item :crlf
-A layer that implements DOS/Windows like CRLF line endings.
-On read converts pairs of CR,LF to a single "\n" newline character.
-On write converts each "\n" to a CR,LF pair.
-Based on the C<:perlio> layer.
+A layer which does CRLF to "\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.)
=item :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
-using that as PerlIO's "buffer". This I<may> be faster in certain
-circumstances for large files, and may result in less physical memory
-use when multiple processes are reading the same file.
-
-Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
-layer. Writes also behave like C<:perlio> layer as C<mmap()> for write
-needs extra house-keeping (to extend the file) which negates any advantage.
-
-The C<:mmap> layer will not exist if platform does not support C<mmap()>.
+using that as PerlIO's "buffer".
=item :perlio
-A from scratch implementation of buffering for PerlIO. Provides fast
-access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt>
-and in general attempts to minimize data copying.
+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>).
-C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
+=item :pop
-=item :raw
+An experimental pseudolayer that removes the topmost layer.
+Use with the same care as is reserved for nitroglycerin.
-Applying the <: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 inuited from locale
-are disabled.
+=item :raw
-Arranges for all accesses go straight to the lowest buffered layer provided
-by the configration. That is it strips off any layers above that layer.
+A pseudolayer that manipulates other layers. Applying the <: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.
-In Perl 5.6 and some books the C<:raw> layer (previously sometimes also
-referred to as a "discipline") is documented as the inverse of the
-C<:crlf> layer. That is no longer the case - other layers which would
-alter binary nature of the stream are also disabled. If you want UNIX
-line endings on a platform that normally does CRLF translation, but still
-want UTF-8 or encoding defaults the appropriate thing to do is to add
-C<:perlio> to PERLIO environment variable.
+Unlike in the 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
=item :unix
-Lowest level layer which provides basic PerlIO operations in terms of
-UNIX/POSIX numeric file descriptor calls
-C<open(), read(), write(), lseek(), close()>
+Low level layer which calls C<read>, C<write> and C<lseek> etc.
=item :utf8
-Turns on a flag on the layer below to tell perl that data sent to the
-stream should be converted to perl internal "utf8" form and that data from the
-stream should be considered as so encoded. On ASCII based platforms the
-encoding is UTF-8 and on EBCDIC platforms UTF-EBCDIC.
-May be useful in PERLIO environment variable to make UTF-8 the
-default. (To turn off that behaviour use C<:bytes> layer.)
+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.)
=item :win32
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 replace
-the C<unix> layer.
+C<win32> layer which is expected to be enhanced and should eventually be
+the default under Win32.
=item PERLIO_DEBUG
=item PERLLIB
-A colon-separated list of directories in which to look for Perl library
+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.
=item PERL5SHELL (specific to the Win32 port)
May be set to an alternative shell that perl must use internally for
-executing "backtick" commands or system(). Default is C<cmd.exe /x/c>
+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.
this controls the behavior of global destruction of objects and other
references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
+=item PERL_DL_NONLAZY
+
+Set to one to have perl resolve B<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.
+
=item PERL_ENCODING
If using the C<encoding> pragma without an explicit encoding name, the
PERL_ENCODING environment variable is consulted for an encoding name.
+=item PERL_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
+things, that hash keys will be ordered the same between different runs
+of Perl.
+
+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.
+
+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
+code. By manually setting a seed this protection may be partially or
+completely lost.
+
+See L<perlsec/"Algorithmic Complexity Attacks"> and
+L</PERL_HASH_SEED_DEBUG> for more information.
+
+=item PERL_HASH_SEED_DEBUG
+
+(Since Perl 5.8.1.) Set to one 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.
+
+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>.
+
=item PERL_ROOT (specific to the VMS port)
A translation concealed rooted logical name that contains perl and the
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
+
+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)">.
+
=item PERL_UNICODE
-Equivalent to the B<-C> command-line switch.
+Equivalent to the B<-C> command-line switch. Note that this is not
+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>
+switch for more information.
=item SYS$LOGIN (specific to the VMS port)
https://perl5.git.perl.org / perl5.git / blobdiff