X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=ee35b11bb05422e689612872121585986bf48da9;hb=bc82975d259d743626ad1b4a960b4b1f13c7a816;hp=71af29ceb113cc27f2f1ce0d2c45044b41bde310;hpb=a4d9c8a6ca8341547c15d831d9aa888263f7fce2;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 71af29c..ee35b11 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -8,14 +8,14 @@ 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] >]> + S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]> + S<[ B<-A>[I][=I] ]> 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 +30,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 +110,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 +207,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 +229,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 +241,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,13 +260,21 @@ 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]> +=item B<-A[I][=I]> +X<-A> -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. +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 @@ -280,6 +292,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. @@ -335,6 +348,7 @@ 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 @@ -343,6 +357,7 @@ execution of your program. C and C blocks, however, will be skipped. =item B<-d> +X<-d> X<-dt> =item B<-dt> @@ -351,6 +366,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 @@ -365,6 +381,7 @@ will be used in the code being debugged. See L. =item B<-D>I +X<-D> X X<-DDEBUGGING> =item B<-D>I @@ -424,34 +441,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 @@ -563,6 +590,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 @@ -570,6 +598,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 @@ -590,6 +619,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 @@ -614,7 +644,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 @@ -643,6 +678,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: @@ -665,6 +701,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 @@ -730,11 +767,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>. @@ -742,11 +779,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). @@ -799,6 +837,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 @@ -822,6 +862,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 @@ -838,19 +879,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. @@ -896,6 +940,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 @@ -913,16 +958,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 @@ -940,23 +988,28 @@ 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 @@ -973,15 +1026,17 @@ 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. @@ -1004,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. @@ -1017,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 @@ -1045,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. @@ -1053,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 @@ -1065,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 @@ -1092,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 @@ -1108,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 @@ -1140,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 @@ -1154,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'). @@ -1162,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 @@ -1176,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 @@ -1206,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 @@ -1219,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 @@ -1227,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 @@ -1234,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 @@ -1243,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.