X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=4f9afdf6bfea98d5b2bb76244aa117c16c30da20;hb=d360a069d6bdc55d9bfda16507abbff2168bf4f7;hp=f668d531784f651b67dd70b32e49abd943f37a03;hpb=7d30b5c4c60a798b772f5d7bd3b85d21016359c7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrun.pod b/pod/perlrun.pod index f668d53..4f9afdf 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -4,7 +4,7 @@ perlrun - how to execute the Perl interpreter =head1 SYNOPSIS -B S<[ B<-sTuUWX> ]> +B S<[ B<-CsTtuUWX> ]> 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] ]> @@ -81,7 +81,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. @@ -130,13 +130,12 @@ distribution for more information). =item Win95/NT -The Win95/NT installation, when using the Activeware port of Perl, +The Win95/NT installation, when using the ActiveState installer for Perl, will modify the Registry to associate the F<.pl> extension with the perl -interpreter. If you install another port of Perl, including the one -in the Win32 directory of the Perl distribution, then you'll have to -modify the Registry yourself. Note that this means you can no -longer tell the difference between an executable Perl program -and a Perl library file. +interpreter. If you install Perl by other means (including building from +the sources), you may have to modify the Registry yourself. Note that +this means you can no longer tell the difference between an executable +Perl program and a Perl library file. =item Macintosh @@ -167,7 +166,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: @@ -265,6 +264,14 @@ 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> causes Perl to check the syntax of the program and then exit without @@ -277,11 +284,15 @@ be skipped. runs the program under the Perl debugger. See L. -=item B<-d:>I +=item B<-d:>I 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. See L. +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. +The comma-separated list of options must follow a C<=> character. +See L. =item B<-D>I @@ -290,9 +301,11 @@ the program using the Devel::DProf profiler. 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 @@ -300,7 +313,7 @@ equivalent to B<-Dtls>): 8 t Trace execution 16 o Method and overloading resolution 32 c String/numeric conversions - 64 P Print preprocessor command for -P + 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 @@ -311,15 +324,22 @@ equivalent to B<-Dtls>): 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 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,8 +458,7 @@ 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. +see L. You cannot use B<-i> to create directories or to strip extensions from files. @@ -528,7 +547,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. @@ -557,21 +576,84 @@ the implicit loop, just as in B. =item B<-P> -causes your program to be run through the C preprocessor before -compilation by Perl. (Because both comments and B directives begin +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 "if", "else", or "define".) +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 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. 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 line after the program name but before any filename arguments (or before -a B<-->). Any switch found there is removed from @ARGV and sets the +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 corresponding variable in the Perl program. The following program -prints "true" if and only if the program is invoked with a B<-xyz> switch. +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 "true\n" } + if ($xyz) { print "$xyz\n" } + +Do note that B<--help> creates the variable ${-help}, which is not compliant +with C. =item B<-S> @@ -622,6 +704,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 @@ -671,7 +764,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 @@ -693,17 +786,16 @@ 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 facility is also available if you want to manipulate entire classes -of warnings; see L (or better yet, its source code) about -that. +of warnings; see L or L. =item B<-W> -Enables all warnings regardless of +Enables all warnings regardless of C or C<$^W>. See L. =item B<-X> -Disables all warnings regardless of +Disables all warnings regardless of C or C<$^W>. See L. =item B<-x> I @@ -755,12 +847,148 @@ 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. + +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 + +Turns I the C<:utf8> flag for the layer below. +Unlikely to be useful in global PERLIO environment variable. + +=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 :raw + +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 inuited 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 + +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 @@ -800,7 +1028,24 @@ after compilation. Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other -references. +references. See L for more information. + +=item PERL_ENCODING + +If using the C pragma without an explicit encoding name, the +PERL_ENCODING environment variable is consulted for an encoding name. + +=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 +L and in F in the Perl source distribution. + +=item SYS$LOGIN (specific to the VMS port) + +Used if chdir has no argument and HOME and LOGDIR are not set. =back