X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=06649b815ecd9c321328ef1bad51980eeb40d97b;hb=60c1ee52655d31d7d03b4d8c0645113f2b5117e9;hp=de7116d939afcd09215b277ed5a3638424dbc5fb;hpb=174c211a66516a872d3a421681076bee9a56fa2b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrun.pod b/pod/perlrun.pod index de7116d..06649b8 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -4,90 +4,112 @@ perlrun - how to execute the Perl interpreter =head1 SYNOPSIS -B S<[ B<-sTuU> ]> +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<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ]> + 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...'> ] [ 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 -Upon startup, Perl looks for your script in one of the following +The normal way to run a Perl program is by making it directly +executable, or else by passing the name of the source file as an +argument on the command line. (An interactive Perl environment +is also possible--see L for details on how to do that.) +Upon startup, Perl looks for your program in one of the following places: =over 4 =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. Contained in the file specified by the first filename on the command line. -(Note that systems supporting the #! notation invoke interpreters this way.) +(Note that systems supporting the #! notation invoke interpreters this +way. See L.) =item 3. Passed in implicitly via standard input. This works only if there are -no filename arguments--to pass arguments to a STDIN script you -must explicitly specify a "-" for the script name. +no filename arguments--to pass arguments to a STDIN-read program you +must explicitly specify a "-" for the program name. =back With methods 2 and 3, Perl starts parsing the input file from the beginning, unless you've specified a B<-x> switch, in which case it scans for the first line starting with #! and containing the word -"perl", and starts there instead. This is useful for running a script +"perl", and starts there instead. This is useful for running a program embedded in a larger message. (In this case you would indicate the end -of the script using the C<__END__> token.) +of the program using the C<__END__> token.) The #! line is always examined for switches as the line is being parsed. Thus, if you're on a machine that allows only one argument with the #! line, or worse, doesn't even recognize the #! line, you still can get consistent switch behavior regardless of how Perl was -invoked, even if B<-x> was used to find the beginning of the script. - -Because many operating systems silently chop off kernel interpretation of -the #! line after 32 characters, some switches may be passed in on the -command line, and some may not; you could even get a "-" without its -letter, if you're not careful. You probably want to make sure that all -your switches fall either before or after that 32 character boundary. -Most switches don't actually care if they're processed redundantly, but -getting a - instead of a complete switch could cause Perl to try to -execute standard input instead of your script. And a partial B<-I> switch +invoked, even if B<-x> was used to find the beginning of the program. + +Because historically some operating systems silently chopped off +kernel interpretation of the #! line after 32 characters, some +switches may be passed in on the command line, and some may not; +you could even get a "-" without its letter, if you're not careful. +You probably want to make sure that all your switches fall either +before or after that 32-character boundary. Most switches don't +actually care if they're processed redundantly, but getting a "-" +instead of a complete switch could cause Perl to try to execute +standard input instead of your program. And a partial B<-I> switch could also cause odd results. +Some switches do care if they are processed twice, for instance +combinations of B<-l> and B<-0>. Either put all the switches after +the 32-character boundary (if applicable), or replace the use of +B<-0>I by C. + Parsing of the #! switches starts wherever "perl" is mentioned in the line. The sequences "-*" and "- " are specifically ignored so that you could, if you were so inclined, say #!/bin/sh -- # -*- perl -*- -p - eval 'exec /usr/bin/perl $0 -S ${1+"$@"}' + eval 'exec perl -wS $0 ${1+"$@"}' if $running_under_some_shell; to let Perl see the B<-p> switch. +A similar trick involves the B program, if you have it. + + #!/usr/bin/env perl + +The examples above use a relative path to the perl interpreter, +getting whatever version is first in the user's path. If you want +a specific version of Perl, say, perl5.005_57, you should place +that directly in the #! line's path. + If the #! line does not contain the word "perl", the program named after the #! is executed instead of the Perl interpreter. This is slightly bizarre, but it helps people on machines that don't do #!, because they -can tell a program that their SHELL is /usr/bin/perl, and Perl will then +can tell a program that their SHELL is F, and Perl will then dispatch the program to the correct interpreter for them. -After locating your script, Perl compiles the entire script to an +After locating your program, Perl compiles the entire program to an internal form. If there are any compilation errors, execution of the -script is not attempted. (This is unlike the typical shell script, +program is not attempted. (This is unlike the typical shell script, which might run part-way through before finding a syntax error.) -If the script is syntactically correct, it is executed. If the script +If the program is syntactically correct, it is executed. If the program 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: @@ -99,27 +121,45 @@ Put extproc perl -S -your_switches -as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's +as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's `extproc' handling). =item MS-DOS -Create a batch file to run your script, and codify it in -C (see the F file in the source +Create a batch file to run your program, and codify it in +C (see the F file in the source distribution for more information). =item Win95/NT -The Win95/NT installation, when using the Activeware port of Perl, -will modify the Registry to associate the .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. +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 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 -Macintosh perl scripts will have the appropriate Creator and -Type, so that double-clicking them will invoke the perl application. +Under "Classic" MacOS, a perl program will have the appropriate Creator and +Type, so that double-clicking them will invoke the MacPerl application. +Under Mac OS X, clickable apps can be made from any C<#!> script using Wil +Sanchez' DropScript utility: http://www.wsanchez.net/software/ . + +=item VMS + +Put + + $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' ! + $ exit++ + ++$status != 0 and $exit = $status = undef; + +at the top of your program, where B<-mysw> are any command line switches you +want to pass to Perl. You can now invoke the program directly, by saying +C, or as a DCL procedure, by saying C<@program> (or implicitly +via F by just using the name of the program). + +This incantation is a bit much to remember, but Perl will display it for +you if you say C. =back @@ -127,10 +167,10 @@ Command-interpreters on non-Unix systems have rather different ideas on quoting than Unix shells. You'll need to learn the special characters in your command-interpreter (C<*>, C<\> and C<"> are common) and how to protect whitespace and these characters to run -one-liners (see C<-e> below). +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: @@ -148,13 +188,13 @@ For example: # VMS perl -e "print ""Hello world\n""" -The problem is that none of this is reliable: it depends on the command -and it is entirely possible neither works. If 4DOS was the command shell, this would -probably work better: +The problem is that none of this is reliable: it depends on the +command and it is entirely possible neither works. If B<4DOS> were +the command shell, this would probably work better: perl -e "print "Hello world\n"" -CMD.EXE in Windows NT slipped a lot of standard Unix functionality in +B in Windows NT slipped a lot of standard Unix functionality in when nobody was looking, but just try to find documentation for its quoting rules. @@ -165,32 +205,62 @@ characters as control characters. There is no general solution to all of this. It's just a mess. -=head2 Switches +=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 +and F to be symlinks to the actual binary. If +that can't be done, system administrators are strongly encouraged +to put (symlinks to) perl and its accompanying utilities into a +directory typically found along a user's PATH, or in some other +obvious and convenient place. -A single-character switch may be combined with the following switch, if -any. +In this documentation, C<#!/usr/bin/perl> on the first line of the program +will stand in for whatever method works on your system. You are +advised to use a specific path if you care about a specific version. - #!/usr/bin/perl -spi.bak # same as -s -p -i.bak + #!/usr/local/bin/perl5.00554 + +or if you just want to be running at least version, place a statement +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. + + #!/usr/bin/perl -spi.orig # same as -s -p -i.orig Switches include: =over 5 -=item B<-0>[I] +=item B<-0>[I] +X<-0> X<$/> -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 '*.bak' -print0 | perl -n0e unlink + 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> +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 @@ -207,92 +277,262 @@ 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. + +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 + 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 +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 environment variable, has the +same effect as C<-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 C) 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> +X<-c> -causes Perl to check the syntax of the script 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. +causes Perl to check the syntax of the program and then exit without +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> + +runs the program under the Perl debugger. See L. +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> -runs the script under the Perl debugger. See L. +=item B<-dt:>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. 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. +If B is specified, it indicates to the debugger that threads +will be used in the code being debugged. +See L. -runs the script under the control of a debugging or tracing module -installed as Devel::foo. E.g., B<-d:DProf> executes the script using the -Devel::DProf profiler. See L. +=item B<-D>I +X<-D> X X<-DDEBUGGING> =item B<-D>I -=item B<-D>I - -sets debugging flags. To watch how it executes your script, use -B<-D14>. (This works only if debugging is compiled into your -Perl.) Another nice value is B<-D1024>, which lists your compiled -syntax tree. And B<-D512> displays compiled regular expressions. As an -alternative specify a list of letters instead of numbers (e.g., B<-D14> is -equivalent to B<-Dtls>): - - 1 p Tokenizing and Parsing - 2 s Stack Snapshots - 4 l Label Stack Processing - 8 t Trace Execution - 16 o Operator Node Construction - 32 c String/Numeric Conversions - 64 P Print Preprocessor Command for -P - 128 m Memory Allocation - 256 f Format Processing - 512 r Regular Expression Parsing - 1024 x Syntax Tree Dump - 2048 u Tainting Checks - 4096 L Memory Leaks (not supported anymore) - 8192 H Hash Dump -- usurps values() - 16384 X Scratchpad Allocation - 32768 D Cleaning Up +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; +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 (with v, displays parse stack) + 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 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 U Unofficial, User hacking (reserved for private, unreleased use) + 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 + 4194304 A Consistency checks on internal structures + 8388608 q quiet - currently only suppresses the "EXECUTING" message + +All these flags require B<-DDEBUGGING> when you compile the Perl +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 + + # 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 + + # csh syntax + % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program) + +See L for details and variations. =item B<-e> I +X<-e> -may be used to enter one line of script. -If B<-e> is given, Perl -will not look for a script 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. +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{sitelib}/sitecustomize.pl> at startup. + +Perl can be built so that it by default will try to execute +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 +output file by the original name, and selecting that output file as the +default for print() statements. The extension, if supplied, is used to +modify the name of the old file to make a backup copy, following these +rules: + +If no extension is supplied, no backup is made and the current file is +overwritten. + +If the extension doesn't contain a C<*>, then it is appended to the +end of the current filename as a suffix. If the extension does +contain one or more C<*> characters, then each C<*> is replaced +with the current filename. In Perl terms, you could think of this +as: + + ($backup = $extension) =~ s/\*/$file_name/g; + +This allows you to add a prefix to the backup file, instead of (or in +addition to) a suffix: + + $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA' -specifies that files processed by the CE> construct are to be edited -in-place. It does this by renaming the input file, opening the output -file by the original name, and selecting that output file as the default -for print() statements. The extension, if supplied, is added to the name -of the old file to make a backup copy. If no extension is supplied, no -backup is made. From the shell, saying +Or even to place backup copies of the original files into another +directory (provided the directory already exists): - $ perl -p -i.bak -e "s/foo/bar/; ... " + $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig' -is the same as using the script: +These sets of one-liners are equivalent: - #!/usr/bin/perl -pi.bak + $ perl -pi -e 's/bar/baz/' fileA # overwrite current file + $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file + + $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' + $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' + +From the shell, saying + + $ perl -p -i.orig -e "s/foo/bar/; ... " + +is the same as using the program: + + #!/usr/bin/perl -pi.orig s/foo/bar/; which is equivalent to #!/usr/bin/perl - while (<>) { + $extension = '.orig'; + LINE: while (<>) { if ($ARGV ne $oldargv) { - rename($ARGV, $ARGV . '.bak'); + if ($extension !~ /\*/) { + $backup = $ARGV . $extension; + } + else { + ($backup = $extension) =~ s/\*/$ARGV/g; + } + rename($ARGV, $backup); open(ARGVOUT, ">$ARGV"); select(ARGVOUT); $oldargv = $ARGV; @@ -306,14 +546,46 @@ which is equivalent to except that the B<-i> form doesn't need to compare $ARGV to $oldargv to know when the filename has changed. It does, however, use ARGVOUT for -the selected filehandle. Note that STDOUT is restored as the -default output filehandle after the loop. +the selected filehandle. Note that STDOUT is restored as the default +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... +or + $ 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 +(see example in L). + +If, for a given file, Perl is unable to create the backup file as +specified in the extension then it will skip that file and continue on +with the next one (if it exists). -You can use C without parenthesis to locate the end of each input file, -in case you want to append to each file, or reset line numbering (see -example in L). +For a discussion of issues surrounding file permissions and B<-i>, +see L. + +You cannot use B<-i> to create directories or to strip extensions from +files. + +Perl does not expand C<~> in filenames, which is good, since some +folks use it for their backup files: + + $ perl -pi~ -e 's/foo/bar/' file1 file2 file3... + +Note that because B<-i> renames or deletes the original file before +creating a new file of the same name, UNIX-style soft and hard links will +not be preserved. + +Finally, the B<-i> switch does not impede execution when no +files are given on the command line. In this case, no backup is made +(the original file cannot, of course, be determined) and processing +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 @@ -321,14 +593,15 @@ 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 effects: first, -it automatically chomps "C<$/>" (the input record separator) when used -with B<-n> or B<-p>, and second, it assigns "C<$\>" -(the output record separator) to have the value of I so that -any print statements will have that separator added back on. If -I is omitted, sets "C<$\>" to the current value of "C<$/>". For -instance, to trim lines to 80 columns: +enables automatic line-ending processing. It has two separate +effects. First, it automatically chomps C<$/> (the input record +separator) when used with B<-n> or B<-p>. Second, it assigns C<$\> +(the output record separator) to have the value of I so +that any print statements will have that separator added back on. +If I is omitted, sets C<$\> to the current value of +C<$/>. For instance, to trim lines to 80 columns: perl -lpe 'substr($_, 80) = ""' @@ -341,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 @@ -348,248 +622,713 @@ This sets C<$\> to newline and then sets C<$/> to the null character. =item B<-[mM]>[B<->]I -C<-m>I executes C I C<();> before executing your -script. +B<-m>I executes C I C<();> before executing your +program. -C<-M>I executes C I C<;> before executing your -script. You can use quotes to add extra code after the module name, -e.g., C<-M'module qw(foo bar)'>. +B<-M>I executes C I C<;> before executing your +program. You can use quotes to add extra code after the module name, +e.g., C<'-Mmodule qw(foo bar)'>. -If the first character after the C<-M> or C<-m> is a dash (C<->) +If the first character after the B<-M> or B<-m> is a dash (C<->) then the 'use' is replaced with 'no'. A little builtin syntactic sugar means you can also say -C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for -C<-M'module qw(foo bar)'>. This avoids the need to use quotes when -importing symbols. The actual code generated by C<-Mmodule=foo,bar> is +B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for +C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when +importing symbols. The actual code generated by B<-Mmodule=foo,bar> is C. Note that the C<=> form -removes the distinction between C<-m> and C<-M>. +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 script, which +causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like B or B: + LINE: while (<>) { - ... # your script goes here + ... # your program goes here } Note that the lines are not printed by default. See B<-p> to have -lines printed. Here is an efficient way to delete all files older than -a week: +lines printed. If a file named by an argument cannot be opened for +some reason, Perl warns you about it and moves on to the next file. - find . -mtime +7 -print | perl -nle 'unlink;' +Here is an efficient way to delete all files that haven't been modified for +at least a week: -This is faster than using the C<-exec> switch of B because you don't -have to start a process on every filename found. + find . -mtime +7 -print | perl -nle unlink + +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 follow the example under B<-0>. C and C blocks may be used to capture control before or after -the implicit loop, just as in B. +the implicit program loop, just as in B. =item B<-p> +X<-p> -causes Perl to assume the following loop around your script, which +causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like B: + LINE: while (<>) { - ... # your script goes here + ... # your program goes here } continue { - print; + print or die "-p destination: $!\n"; } -Note that the lines are printed automatically. To suppress printing -use the B<-n> switch. A B<-p> overrides a B<-n> switch. +If a file named by an argument cannot be opened for some reason, Perl +warns you about it, and moves on to the next file. Note that the +lines are printed automatically. An error occurring during printing is +treated as fatal. To suppress printing use the B<-n> switch. A B<-p> +overrides a B<-n> switch. C and C blocks may be used to capture control before or after -the implicit loop, just as in awk. +the implicit loop, just as in B. =item B<-P> +X<-P> -causes your script to be run through the C preprocessor before -compilation by Perl. (Because both comments and cpp 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> +X<-s> -enables some rudimentary switch parsing for switches on the command -line after the script name but before any filename arguments (or before -a B<-->). Any switch found there is removed from @ARGV and sets the -corresponding variable in the Perl script. The following script -prints "true" if and only if the script is invoked with a B<-xyz> switch. +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<-->). 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>. #!/usr/bin/perl -s - if ($xyz) { print "true\n"; } + if ($xyz) { print "$xyz\n" } + +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 -script (unless the name of the script starts with a slash). Typically -this is used to emulate #! startup on machines that don't support #!, -in the following manner: +program (unless the name of the program contains directory separators). + +On some platforms, this also makes Perl append suffixes to the +filename while searching for it. For example, on Win32 platforms, +the ".bat" and ".cmd" suffixes are appended if a lookup for the +original name fails, and if the name does not already end in one +of those suffixes. If your Perl was compiled with DEBUGGING turned +on, using the -Dp switch to Perl shows how the search progresses. + +Typically this is used to emulate #! startup on platforms that don't +support #!. Its also convenient when debugging a script that uses #!, +and is thus normally found by the shell's $PATH search mechanism. + +This example works on many platforms that have a shell compatible with +Bourne shell: #!/usr/bin/perl - eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' + eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}' if $running_under_some_shell; -The system ignores the first line and feeds the script to /bin/sh, -which proceeds to try to execute the Perl script as a shell script. +The system ignores the first line and feeds the program to F, +which proceeds to try to execute the Perl program as a shell script. The shell executes the second line as a normal shell command, and thus starts up the Perl interpreter. On some systems $0 doesn't always contain the full pathname, so the B<-S> tells Perl to search for the -script if necessary. After Perl locates the script, it parses the +program if necessary. After Perl locates the program, it parses the lines and ignores them because the variable $running_under_some_shell -is never true. A better construct than C<$*> would be C<${1+"$@"}>, which -handles embedded spaces and such in the filenames, but doesn't work if -the script is being interpreted by csh. To start up sh rather +is never true. If the program will be interpreted by csh, you will need +to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand +embedded spaces (and such) in the argument list. To start up sh rather than csh, some systems may have to replace the #! line with a line containing just a colon, which will be politely ignored by Perl. Other systems can't control that, and need a totally devious construct that -will work under any of csh, sh, or Perl, such as the following: +will work under any of B, B, or Perl, such as the following: - eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' - & eval 'exec /usr/bin/perl -S $0 $argv:q' + eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' + & eval 'exec /usr/bin/perl -wS $0 $argv:q' if $running_under_some_shell; -=item B<-T> +If the filename supplied contains directory separators (i.e., is an +absolute or relative pathname), and if that file is not found, +platforms that append file extensions will do so and try to look +for the file with those extensions added, one by one. -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 good idea to turn -them on explicitly for programs run on another's behalf, such as CGI -programs. See L. +On DOS-like platforms, if the program does not contain directory +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<-u> +=item B<-t> +X<-t> -causes Perl to dump core after compiling your script. You can then -take this core dump and turn it into an executable file by using the -B program (not supplied). This speeds startup at the expense of -some disk space (which you can minimize by stripping the executable). -(Still, a "hello world" executable comes out to about 200K on my -machine.) If you want to execute a portion of your script before dumping, -use the dump() operator instead. Note: availability of B is -platform specific and may not be available for a specific port of -Perl. +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> +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 +good idea to turn them on explicitly for programs that run on behalf +of someone else whom you might not necessarily trust, such as CGI +programs or any internet servers you might write in Perl. See +L for details. For security reasons, this option must be +seen by Perl quite early; usually this means it must appear early +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 +into an executable file by using the B program (not supplied). +This speeds startup at the expense of some disk space (which you +can minimize by stripping the executable). (Still, a "hello world" +executable comes out to about 200K on my machine.) If you want to +execute a portion of your program before dumping, use the dump() +operator instead. Note: availability of B is platform +specific and may not be available for a specific port of Perl. + +This switch has been superseded in favor of the new Perl code +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. +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. +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 -value of @INC. +values of @INC. + +=item B<-V:>I + +Prints to STDOUT the value of the named configuration variable(s), +with multiples when your configvar argument looks like a regex (has +non-letters). For example: + + $ perl -V:libc + libc='/lib/libc-2.2.4.so'; + $ perl -V:lib. + libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc'; + libc='/lib/libc-2.2.4.so'; + $ perl -V:lib.* + libpth='/usr/local/lib /lib /usr/lib'; + libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc'; + lib_ext='.a'; + libc='/lib/libc-2.2.4.so'; + libperl='libperl.a'; + .... + +Additionally, extra colons can be used to control formatting. A +trailing colon suppresses the linefeed and terminator ';', allowing +you to embed queries into shell commands. (mnemonic: PATH separator +':'.) + + $ echo "compression-vars: " `perl -V:z.*: ` " are here !" + compression-vars: zcat='' zip='zip' are here ! + +A leading colon removes the 'name=' part of the response, this allows +you to map to the name you need. (mnemonic: empty label) -=item B<-V:>I + $ echo "goodvfork="`./perl -Ilib -V::usevfork` + goodvfork=false; -Prints to STDOUT the value of the named configuration variable. +Leading and trailing colons can be used together if you need +positional parameter values without the names. Note that in the case +below, the PERL_API params are returned in alphabetical order. + + $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now + 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 +before being set, redefined subroutines, references to undefined +filehandles or filehandles opened read-only that you are attempting +to write on, values used as a number that don'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 +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 L. + +=item B<-W> +X<-W> + +Enables all warnings regardless of C or C<$^W>. +See L. -prints warnings about variable names that are mentioned only once, and -scalar variables that are used before being set. Also warns about -redefined subroutines, and references to undefined filehandles or -filehandles opened read-only that you are attempting to write on. Also -warns you if you use values 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. +=item B<-X> +X<-X> -You can disable specific warnings using C<__WARN__> hooks, as described -in L and L. See also L and L. +Disables all warnings regardless of C or C<$^W>. +See L. + +=item B<-x> +X<-x> =item B<-x> I -tells Perl that the script is embedded in a message. Leading -garbage will be discarded until the first line that starts with #! and -contains the string "perl". Any meaningful switches on that line will -be applied. If a directory name is specified, Perl will switch to -that directory before running the script. The B<-x> switch controls -only the disposal of leading garbage. The script must be -terminated with C<__END__> if there is trailing garbage to be ignored (the -script can process any or all of the trailing garbage via the DATA -filehandle if desired). +tells Perl that the program is embedded in a larger chunk of unrelated +ASCII text, such as in a mail message. Leading garbage will be +discarded until the first line that starts with #! and contains the +string "perl". Any meaningful switches on that line will be applied. +If a directory name is specified, Perl will switch to that directory +before running the program. The B<-x> switch controls only the +disposal of leading garbage. The program must be terminated with +C<__END__> if there is trailing garbage to be ignored (the program +can process any or all of the trailing garbage via the DATA filehandle +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 script if B<-S> is +Used in executing subprocesses, and in finding the program if B<-S> is used. =item PERL5LIB +X -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 not defined, PERLLIB is used. When running -taint checks (because the script was running setuid or setgid, or the -B<-T> switch was used), neither variable is used. The script should -instead say +directory. Any architecture-specific directories under the specified +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> 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<-[DIMUdmw]> -switches are allowed. When running taint checks (because the script +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. +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. + +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 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 +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 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. +(It currently does I mimic MS-DOS as far as treating of Control-Z +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 +pass each byte as-is without any translation. In particular CRLF +translation, and/or :utf8 intuited from locale are disabled. + +Unlike in the earlier versions of Perl C<:raw> is I +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. +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 +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 +already in utf8 form. May be useful in PERLIO environment +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 +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 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 +are UNIX: + + PERLIO_DEBUG=/dev/tty perl script ... + +and Win32 approximate equivalent: + + set PERLIO_DEBUG=CON + perl script ... + +This functionality is disabled for setuid scripts and for scripts run +with B<-T>. =item PERLLIB +X -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. =item PERL5DB +X The command used to load the debugger code. The default is: BEGIN { require 'perl5db.pl' } -=item PERL5SHELL (specific to WIN32 port) +=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(). Perl doesn't use COMSPEC -for this purpose because COMSPEC has a high degree of variability -among users, leading to portability concerns. Besides, perl can use -a shell that may not be fit for interactive use, and setting COMSPEC -to such a shell may interfere with the proper functioning of other -programs (which usually look in COMSPEC to find a shell fit for -interactive use). +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. + +Note that Perl doesn't use COMSPEC for this purpose because +COMSPEC has a high degree of variability among users, leading to +portability concerns. Besides, perl can use a shell that may not be +fit for interactive use, and setting COMSPEC to such a shell may +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 +for its emulation of Windows sockets as real filehandles. However, this may +cause problems if you have a firewall such as McAfee Guardian which requires +all applications to use its LSP which is not IFS-compatible, because clearly +Perl will normally avoid using such an LSP. +Setting this environment variable to 1 means that Perl will simply use the +first suitable LSP enumerated in the catalog, which keeps McAfee Guardian +happy (and in that particular case Perl still works too because McAfee +Guardian's LSP actually plays some other games which allow applications +requiring IFS compatibility to work). =item PERL_DEBUG_MSTATS +X -Relevant only if your perl executable was built with B<-DDEBUGGING_MSTATS>, -if set, this causes memory statistics to be dumped after execution. If set +Relevant only if perl is compiled with the malloc included with the perl +distribution (that is, if C is 'define'). +If set, this causes memory statistics to be dumped after execution. If set 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. +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 +they are used. Setting this variable is useful during testing of +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 +exactly the same order as 5.8.0). "Pre-5.8.1" means, among other +things, that hash keys will always have the same ordering between +different runs of perl. + +Most hashes return elements in the same order as Perl 5.8.0 by default. +On a hash by hash basis, if pathological data is detected during a hash +key insertion, then that hash will switch to an alternative random hash +seed. + +The default behaviour is to randomise unless the PERL_HASH_SEED is set. +If perl has been compiled with C<-DUSE_HASH_SEED_EXPLICIT>, the default +behaviour is B to randomise unless the PERL_HASH_SEED is set. + +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. + +B. Hashes are +randomized to protect against local and remote attacks against Perl +code. By manually setting a seed this protection may be partially or +completely lost. + +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 +L is intended to aid in debugging nondeterministic +behavior caused by hash randomization. + +B: by knowing it one +can craft a denial-of-service attack against Perl code, even remotely, +see L for more information. +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 +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 +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 +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 +"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) +X + +Used if chdir has no argument and HOME and LOGDIR are not set. =back @@ -597,12 +1336,11 @@ Perl also has environment variables that control how Perl handles data specific to particular natural languages. See L. Apart from these, Perl uses no other environment variables, except -to make them available to the script being executed, and to child -processes. However, scripts running setuid would do well to execute +to make them available to the program being executed, and to child +processes. However, programs running setuid would do well to execute the following lines before doing anything else, just to keep people honest: - $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need + $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL}; delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; -