X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=a72c2c01f6a78d80df5c2348f92b9e4e0bbbf851;hb=584420f022db57225e9644b9c6668ff9f567984a;hp=a5260a976def86fb1b75becfe973574ceb1e5267;hpb=aefc56c5a86a8918fc9d52065e8cf4df301d4ee4;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrun.pod b/pod/perlrun.pod index a5260a9..a72c2c0 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -8,14 +8,13 @@ B S<[ B<-sTtuUWX> ]> S<[ B<-hv> ] [ B<-V>[:I] ]> S<[ B<-cw> ] [ B<-d>[B][:I] ] [ B<-D>[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<-A>[I][=I] ]> + S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]> S<[ B<-C [I] >]> S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I] ]> S<[ B<-i>[I] ]> - S<[ B<-e> I<'command'> ] [ B<--> ] [ I ] [ I ]...> + S<[ B<-eE> I<'command'> ] [ B<--> ] [ I ] [ I ]...> =head1 DESCRIPTION @@ -30,7 +29,7 @@ places: =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. @@ -110,6 +109,7 @@ runs off the end without hitting an exit() or die() operator, an implicit C is provided to indicate successful completion. =head2 #! and quoting on non-Unix systems +X X<#!> Unix's #! technique can be simulated on other systems: @@ -206,6 +206,7 @@ characters as control characters. There is no general solution to all of this. It's just a mess. =head2 Location of Perl +X It may seem obvious to say, but Perl is useful only when users can easily find it. When possible, it's good for both F @@ -227,6 +228,7 @@ like this at the top of your program: use 5.005_54; =head2 Command Switches +X X As with all standard commands, a single-character switch may be clustered with the following switch, if any. @@ -238,6 +240,7 @@ Switches include: =over 5 =item B<-0>[I] +X<-0> X<$/> specifies the input record separator (C<$/>) as an octal or hexadecimal number. If there are no digits, the null character is the @@ -256,19 +259,8 @@ 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][=I]> - -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 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 and L. - =item B<-a> +X<-a> X turns on autosplit mode when used with a B<-n> or B<-p>. An implicit split command to the @F array is done as the first thing inside the @@ -286,6 +278,7 @@ is equivalent to An alternate delimiter may be specified using B<-F>. =item B<-C [I]> +X<-C> The C<-C> flag controls some Unicode of the Perl Unicode features. @@ -307,6 +300,15 @@ are as follows; listing the letters is equal to summing the numbers. 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 @@ -341,14 +343,16 @@ This feature was practically unused, however, and the command line switch was therefore "recycled".) =item B<-c> +X<-c> causes Perl to check the syntax of the program and then exit without -executing it. Actually, it I execute C, C, and -C blocks, because these are considered as occurring outside the -execution of your program. C and C blocks, however, will -be skipped. +executing it. Actually, it I execute C, C, +C, and C blocks, because these are considered as occurring +outside the execution of your program. C and C blocks, +however, will be skipped. =item B<-d> +X<-d> X<-dt> =item B<-dt> @@ -357,6 +361,7 @@ If B is specified, it indicates to the debugger that threads will be used in the code being debugged. =item B<-d:>I +X<-d> X<-dt> =item B<-dt:>I @@ -371,6 +376,7 @@ will be used in the code being debugged. See L. =item B<-D>I +X<-D> X X<-DDEBUGGING> =item B<-D>I @@ -430,34 +436,44 @@ you can't use Perl's B<-D> switch. Instead do this See L for details and variations. =item B<-e> I +X<-e> may be used to enter one line of program. If B<-e> is given, Perl will not look for a filename in the argument list. Multiple B<-e> 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 +X<-E> + +behaves just like B<-e>, except that it implicitly enables all +optional features (in the main compilation unit). See L. + =item B<-f> +X<-f> -Disable executing F<$Config{siteperl}/sitecustomize.pl> at -startup. +Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup. Perl can be built so that it by default will try to execute -F<$Config{siteperl}/sitecustomize.pl> at startup. This is a hook that +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. =item B<-F>I +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. +put in single quotes. You can't use literal whitespace in the pattern. =item B<-h> +X<-h> prints a summary of the options. =item B<-i>[I] +X<-i> X specifies that files processed by the CE> construct are to be edited in-place. It does this by renaming the input file, opening the @@ -569,6 +585,7 @@ files are given on the command line. In this case, no backup is made proceeds from STDIN to STDOUT as might be expected. =item B<-I>I +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 @@ -576,6 +593,7 @@ include files. The C preprocessor is invoked with B<-P>; by default it searches /usr/include and /usr/lib/perl. =item B<-l>[I] +X<-l> X<$/> X<$\> enables automatic line-ending processing. It has two separate effects. First, it automatically chomps C<$/> (the input record @@ -596,6 +614,7 @@ separator if the B<-l> switch is followed by a B<-0> switch: This sets C<$\> to newline and then sets C<$/> to the null character. =item B<-m>[B<->]I +X<-m> X<-M> =item B<-M>[B<->]I @@ -620,7 +639,12 @@ importing symbols. The actual code generated by B<-Mmodule=foo,bar> is C. Note that the C<=> form removes the distinction between B<-m> and B<-M>. +A consequence of this is that B<-MFoo=number> never does a version check +(unless C itself is set up to do a version check, which +could happen for example if Foo inherits from Exporter.) + =item B<-n> +X<-n> causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like B or @@ -649,6 +673,7 @@ C and C blocks may be used to capture control before or after the implicit program loop, just as in B. =item B<-p> +X<-p> causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like B: @@ -671,6 +696,7 @@ C and C blocks may be used to capture control before or after the implicit loop, just as in B. =item B<-P> +X<-P> B @@ -736,11 +762,11 @@ 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>. @@ -748,11 +774,12 @@ 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. 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> makes Perl use the PATH environment variable to search for the program (unless the name of the program contains directory separators). @@ -805,6 +832,7 @@ before being searched for on the PATH. On Unix platforms, the program will be searched for strictly on the PATH. =item B<-t> +X<-t> Like B<-T>, but taint checks will issue warnings rather than fatal errors. These warnings can be controlled normally with C. =item B<-T> +X<-T> forces "taint" checks to be turned on so you can test them. Ordinarily these checks are done only when running setuid or setgid. It's a @@ -828,6 +857,7 @@ on the command line or in the #! line for systems which support that construct. =item B<-u> +X<-u> This obsolete switch causes Perl to dump core after compiling your program. You can then in theory take this core dump and turn it @@ -844,19 +874,22 @@ generator backends to the compiler. See L and L 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 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 the +taint-check warnings. =item B<-v> +X<-v> prints the version and patchlevel of your perl executable. =item B<-V> +X<-V> prints summary of the major perl configuration values and the current values of @INC. @@ -902,6 +935,7 @@ below, the PERL_API params are returned in alphabetical order. building_on 'linux' '5' '1' '9' now =item B<-w> +X<-w> prints warnings about dubious constructs, such as variable names that are mentioned only once and scalar variables that are used @@ -919,16 +953,19 @@ facility is also available if you want to manipulate entire classes of warnings; see L or L. =item B<-W> +X<-W> Enables all warnings regardless of C or C<$^W>. See L. =item B<-X> +X<-X> Disables all warnings regardless of C or C<$^W>. See L. =item B<-x> +X<-x> =item B<-x> I @@ -946,48 +983,58 @@ if desired). =back =head1 ENVIRONMENT +X =over 12 =item HOME +X Used if chdir has no argument. =item LOGDIR +X Used if chdir has no argument and HOME is not set. =item PATH +X Used in executing subprocesses, and in finding the program if B<-S> is used. =item PERL5LIB +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. 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). +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). 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"; =item PERL5OPT +X Command-line options (switches). Switches in this variable are taken -as if they were on every Perl command line. Only the B<-[DIMUdmtw]> +as if they were on every Perl command line. Only the B<-[CDIMUdmtwA]> 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 +X 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. @@ -997,7 +1044,9 @@ 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>. +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 perl's IO. Consequently only built-in layers can appear in this list, as external layers (such as :encoding()) need @@ -1010,12 +1059,14 @@ variable are briefly summarised below. For more details see L. =over 8 =item :bytes +X<: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 +X<:crlf> A layer which does CRLF to "\n" translation distinguishing "text" and "binary" files in the manner of MS-DOS and similar operating systems. @@ -1023,23 +1074,27 @@ A layer which does CRLF to "\n" translation distinguishing "text" and as being an end-of-file marker.) =item :mmap +X<: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". =item :perlio +X<:perlio> 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>). =item :pop +X<:pop> An experimental pseudolayer that removes the topmost layer. Use with the same care as is reserved for nitroglycerin. =item :raw +X<:raw> A pseudolayer that manipulates other layers. Applying the C<:raw> layer is equivalent to calling C. It makes the stream @@ -1051,6 +1106,7 @@ just the inverse of C<:crlf> - other layers which would affect the binary nature of the stream are also removed or disabled. =item :stdio +X<:stdio> This layer provides PerlIO interface by wrapping system's ANSI C "stdio" library calls. The layer provides both buffering and IO. @@ -1059,10 +1115,12 @@ is platforms normal behaviour. You will need a C<:crlf> layer above it to do that. =item :unix +X<:unix> Low level layer which calls C, C and C etc. =item :utf8 +X<:utf8> 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 @@ -1071,6 +1129,7 @@ variable to make UTF-8 the default. (To turn off that behaviour use C<:bytes> layer.) =item :win32 +X<:win32> On Win32 platforms this I layer uses native "handle" IO rather than unix-like numeric file descriptor layer. Known to be @@ -1098,6 +1157,7 @@ C layer which is expected to be enhanced and should eventually be the default under Win32. =item PERLIO_DEBUG +X 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 @@ -1114,23 +1174,27 @@ This functionality is disabled for setuid scripts and for scripts run with B<-T>. =item PERLLIB +X 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 PERL5DB +X The command used to load the debugger code. The default is: BEGIN { require 'perl5db.pl' } =item PERL5DB_THREADED +X If set to a true value, indicates to the debugger that the code being debugged uses threads. =item PERL5SHELL (specific to the Win32 port) +X May be set to an alternative shell that perl must use internally for executing "backtick" commands or system(). Default is C @@ -1146,6 +1210,7 @@ interfere with the proper functioning of other programs (which usually look in COMSPEC to find a shell fit for interactive use). =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port) +X Set to 1 to allow the use of non-IFS compatible LSP's. Perl normally searches for an IFS-compatible LSP because this is required @@ -1160,6 +1225,7 @@ Guardian's LSP actually plays some other games which allow applications requiring IFS compatibility to work). =item PERL_DEBUG_MSTATS +X Relevant only if perl is compiled with the malloc included with the perl distribution (that is, if C is 'define'). @@ -1168,12 +1234,14 @@ to an integer greater than one, also causes memory statistics to be dumped after compilation. =item PERL_DESTRUCT_LEVEL +X Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other references. See L for more information. =item PERL_DL_NONLAZY +X Set to one to have perl resolve B undefined symbols when it loads a dynamic library. The default behaviour is to resolve symbols when @@ -1182,11 +1250,13 @@ 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 +X 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 +X (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 @@ -1212,6 +1282,7 @@ See L and L for more information. =item PERL_HASH_SEED_DEBUG +X (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 @@ -1225,6 +1296,7 @@ B to people who don't need to know it. See also hash_seed() of L. =item PERL_ROOT (specific to the VMS port) +X A translation concealed rooted logical name that contains perl and the logical device for the @INC path on VMS only. Other logical names that @@ -1233,6 +1305,7 @@ SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in L and in F in the Perl source distribution. =item PERL_SIGNALS +X 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 @@ -1240,6 +1313,7 @@ C the safe (or deferred) signals are used. See L. =item PERL_UNICODE +X 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 @@ -1249,6 +1323,7 @@ your shell before starting Perl). See the description of the C<-C> switch for more information. =item SYS$LOGIN (specific to the VMS port) +X Used if chdir has no argument and HOME and LOGDIR are not set.