X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/5d170f3a2f1aec382dd58400cc2a2fe1d00859b9..48b971ca150628f9bfd4a49abb4675434cdd71df:/pod/perlrun.pod diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 0e3017f..043ab5d 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -4,16 +4,18 @@ perlrun - how to execute the Perl interpreter =head1 SYNOPSIS -B S<[ B<-CsTuUWX> ]> +B S<[ B<-sTtuUWX> ]> S<[ B<-hv> ] [ B<-V>[:I] ]> S<[ B<-cw> ] [ B<-d>[:I] ] [ B<-D>[I] ]> - S<[ B<-pna> ] [ B<-F>I ] [ B<-l>[I] ] [ B<-0>[I] ]> + S<[ B<-pna> ] [ B<-F>I ] [ B<-l>[I] ] [ B<-0>[I] ]> S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ]> S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I] ]> S<[ B<-i>[I] ]> S<[ B<-e> I<'command'> ] [ B<--> ] [ I ] [ I ]...> + S<[ B<-A [I] >]> + S<[ B<-C [I] >]> =head1 DESCRIPTION @@ -81,7 +83,7 @@ if you were so inclined, say eval 'exec perl -wS $0 ${1+"$@"}' if $running_under_some_shell; -to let Perl see the B<-p> switch. +to let Perl see the B<-p> switch. A similar trick involves the B program, if you have it. @@ -166,7 +168,7 @@ common) and how to protect whitespace and these characters to run one-liners (see B<-e> below). On some systems, you may have to change single-quotes to double ones, -which you must I do on Unix or Plan9 systems. You might also +which you must I do on Unix or Plan 9 systems. You might also have to change a single % to a %%. For example: @@ -233,19 +235,30 @@ Switches include: =over 5 -=item B<-0>[I] +=item B<-0>[I] -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 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 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 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]> + +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. =item B<-a> @@ -264,13 +277,59 @@ is equivalent to An alternate delimiter may be specified using B<-F>. -=item B<-C> - -enables Perl to use the native wide character APIs on the target system. -The magic variable C<${^WIDE_SYSTEM_CALLS}> reflects the state of -this switch. See L. - -This feature is currently only implemented on the Win32 platform. +=item B<-C [I]> + +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. 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 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<$ENV{PERL_UNICODE}, has the same effect +as <-CSDL>. In other words, the standard I/O handles and the default +C layer are UTF-8-fied B only if the locale environment +variables indicate a UTF-8 locale. This behaviour follows the +I (and problematic) UTF-8 behaviour of Perl 5.8.0. + +You can use C<-C0> (or C<"0"> for $ENV{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), the two-arg binmode() (see L), +and the C pragma (see L). + +(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. +This feature was practically unused, however, and the command line +switch was therefore "recycled".) =item B<-c> @@ -301,38 +360,48 @@ See L. 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. As an -alternative, specify a number instead of list of letters (e.g., B<-D14> is -equivalent to B<-Dtls>): +syntax tree. And B<-Dr> displays compiled regular expressions; +the format of the output is explained in L. + +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 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 preprocessor command for -P, source file input state + 64 P Print profiling info, preprocessor command for -P, 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 L Memory leaks (needs -DLEAKTEST when compiling Perl) + 4096 (Obsolete, previously used for LEAKTEST) 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 + 1048576 v Verbose: use in conjunction with other flags + 2097152 C Copy On Write All these flags require B<-DDEBUGGING> when you compile the Perl -executable. See the F file in the Perl source distribution +executable (but see L, L which may change this). +See the F file in the Perl source distribution for how to do this. This flag is automatically set if you include B<-g> option when C asks you about optimizer/debugger flags. If you're just trying to get a print out of each line of Perl code as it executes, the way that C provides for shell scripts, -you can't use Perl's B<-D> switch. Instead do this +you can't use Perl's B<-D> switch. Instead do this + + # If you have "env" utility + env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program # Bourne shell syntax $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program @@ -438,9 +507,9 @@ output filehandle after the loop. As shown above, Perl creates the backup file whether or not any output is actually changed. So this is just a fancy way to copy files: - $ perl -p -i '/some/file/path/*' -e 1 file1 file2 file3... + $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3... or - $ perl -p -i '.orig' -e 1 file1 file2 file3... + $ perl -p -i'.orig' -e 1 file1 file2 file3... You can use C without parentheses to locate the end of each input file, in case you want to append to each file, or reset line numbering @@ -540,7 +609,7 @@ Here is an efficient way to delete all files older than a week: This is faster than using the B<-exec> switch of B 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 +you follow the example under B<-0>. C and C blocks may be used to capture control before or after the implicit program loop, just as in B. @@ -569,12 +638,39 @@ the implicit loop, just as in B. =item B<-P> -causes your program to be run through the C preprocessor before +B + +This option causes your program to be run through the C preprocessor before compilation by Perl. Because both comments and B 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">. -Also, in some platforms the C preprocessor knows too much: it knows -about the C++ -style until-end-of-line comments starting with C<"//">. + +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 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//; @@ -588,6 +684,23 @@ like for example C<"!">: s!foo!!; + + +=item * + +It requires not only a working C preprocessor but also a working +F. 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> enables rudimentary switch parsing for switches on the command @@ -653,6 +766,17 @@ separators, it will first be searched for in the current directory before being searched for on the PATH. On Unix platforms, the program will be searched for strictly on the PATH. +=item B<-t> + +Like B<-T>, but taint checks will issue warnings rather than fatal +errors. These warnings can be controlled normally with C. + +B 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 +always use the real B<-T>. + =item B<-T> forces "taint" checks to be turned on so you can test them. Ordinarily @@ -702,7 +826,7 @@ values of @INC. =item B<-V:>I Prints to STDOUT the value of the named configuration variable. -For example, +For example, $ perl -V:man.dir @@ -719,7 +843,7 @@ to write on, values used as a number that doesn'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. -This switch really just enables the internal C<^$W> variable. You +This switch really just enables the internal C<$^W> variable. You can disable or promote into fatal errors specific warnings using C<__WARN__> hooks, as described in L and L. See also L and L. A new, fine-grained warning @@ -770,11 +894,13 @@ used. =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). When running taint checks (either because the program was running setuid or setgid, or the B<-T> switch was used), neither variable is used. @@ -785,15 +911,160 @@ The program should instead say: =item PERL5OPT Command-line options (switches). Switches in this variable are taken -as if they were on every Perl command line. Only the B<-[DIMUdmw]> +as if they were on every Perl command line. Only the B<-[DIMUdmtw]> 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. +=item 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. + +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. + +An unset or empty PERLIO is equivalent to C<:stdio>. + +The list becomes the default for I 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. + +=over 8 + +=item :bytes + +A pseudolayer that turns I 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. + +=item :mmap + +A layer which implements "reading" of files by using C to +make (whole) file appear in the process's address space, and then +using that as PerlIO's "buffer". This I 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-able revert to behaving like the C<:perlio> +layer. Writes also behave like C<:perlio> layer as C 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. + +=item :perlio + +A from scratch implementation of buffering for PerlIO. Provides fast +access to the buffer for C which implements perl's readline/EE +and in general attempts to minimize data copying. + +C<:perlio> will insert a C<:unix> layer below itself to do low level IO. + +=item :pop + +An experimental pseudolayer that removes the topmost layer. +Use with the same care as is reserved for nitroglyserin. + +=item :raw + +A pseudolayer that manipulates other layers. Applying the <:raw> +layer is equivalent to calling C. It makes the stream +pass each byte as-is without any translation. In particular CRLF +translation, and/or :utf8 intuited from locale are disabled. + +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. + +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. + +=item :stdio + +This layer provides 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 do CRLF translation even if that +is platforms normal behaviour. You will need a C<:crlf> layer above it +to do that. + +=item :unix + +Lowest level layer which provides basic PerlIO operations in terms of +UNIX/POSIX numeric file descriptor calls +C + +=item :utf8 + +A pseudolayer that 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.) + +=item :win32 + +On Win32 platforms this I layer uses native "handle" IO +rather than unix-like numeric file descriptor layer. Known to be +buggy in this release. + +=back + +On all platforms the default set of layers should give acceptable results. + +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" +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 layer as +the buffer avoids those issues and makes things more uniform. +The C layer provides CRLF to/from "\n" conversion as well as +buffering. + +This release uses C as the bottom layer on Win32 and so still uses C +compiler's numeric file descriptor routines. There is an experimental native +C layer which is expected to be enhanced and should eventually replace +the C layer. + +=item 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: + + PERLIO_DEBUG=/dev/tty perl script ... + +and Win32 approximate equivalent: + + set PERLIO_DEBUG=CON + perl script ... + + =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. @@ -806,7 +1077,7 @@ The command used to load the debugger code. The default is: =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 +executing "backtick" commands or system(). Default is C on WindowsNT and 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. @@ -837,14 +1108,55 @@ references. See L for more information. If using the C 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. + +The default behaviour is B to randomise if the PERL_HASH_SEED is +unset. If Perl has been compiled with C<-DUSE_HASH_SEED>, the default +behaviour B to randomise. If Perl hash been compiled with +C<-DNO_HASH_SEED>, the hash randomisation is completely disabled. + +If PERL_HASH_SEED is set to a numeric (positive integer) string, +that is used as the seed. + +If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses +the pseudorandom seed supplied by the operating system and libraries. + +The seed being set means that each different run of Perl will have +a different ordering of the results of keys(), values(), and each(). + +See L for more information. + +=item PERL_HASH_SEED_DEBUG + +(Since Perl 5.8.1.) Set to "1" to display (to STDERR) the value of +the hash seed at the beginning of execution. + =item PERL_ROOT (specific to the VMS port) 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 and in F in the Perl source distribution. +=item PERL_SIGNALS + +In Perls 5.8.1 and later. If set to C the pre-Perl-5.8.0 +signals behaviour (immediate but unsafe) is restored. If set to +C the safe (or deferred) signals are used. +See L. + +=item PERL_UNICODE + +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) Used if chdir has no argument and HOME and LOGDIR are not set.