X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=3eca0e9e4283c960d362c0d3b25f9e0cbd6ee793;hb=d74e8afc9309529cf5c6c4390fc311850865d506;hp=36e331dbdc5034525202a6b5dd786241f7bde6b3;hpb=e4af53b035442614d6967aeb0941ba0a0e6238a0;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 36e331d..3eca0e9 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -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 @@ -257,6 +261,7 @@ format: C<-0xHHH...>, where the C are valid hexadecimal digits. consists of hexadecimal digits.) =item B<-A[I][=I]> +X<-A> Activates the assertions given after the equal sign as a comma-separated list of assertion names or regular expressions. If no assertion name @@ -269,6 +274,7 @@ 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 +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. @@ -341,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 @@ -349,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> @@ -357,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 @@ -371,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 @@ -430,6 +441,7 @@ 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> @@ -437,6 +449,7 @@ 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<-f> +X<-f> Disable executing F<$Config{siteperl}/sitecustomize.pl> at startup. @@ -448,16 +461,19 @@ 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 @@ -625,6 +644,7 @@ A consequence of this is that B<-MFoo=number> never does a version check 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 @@ -653,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: @@ -675,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 @@ -740,6 +762,7 @@ 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 @@ -757,6 +780,7 @@ 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). @@ -809,6 +833,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 @@ -832,6 +858,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 @@ -848,6 +875,7 @@ 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, @@ -857,10 +885,12 @@ 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. @@ -906,6 +936,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 @@ -923,16 +954,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 @@ -950,23 +984,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 @@ -983,6 +1022,7 @@ 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<-[CDIMUdmtwA]> @@ -992,6 +1032,7 @@ 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. @@ -1014,12 +1055,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. @@ -1027,23 +1070,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 @@ -1055,6 +1102,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. @@ -1063,10 +1111,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 @@ -1075,6 +1125,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 @@ -1102,6 +1153,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 @@ -1118,23 +1170,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 @@ -1150,6 +1206,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 @@ -1164,6 +1221,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'). @@ -1172,12 +1230,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 @@ -1186,11 +1246,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 @@ -1216,6 +1278,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 @@ -1229,6 +1292,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 @@ -1237,6 +1301,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 @@ -1244,6 +1309,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 @@ -1253,6 +1319,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.