diff options
author | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
commit | e5c6e6d9c56fbfc54508fa2c32b03a5a870b7553 (patch) | |
tree | 40fcc93aa383c1e45d31ddc42d03f15cbada7076 /Master/tlpkg/tlperl/lib/pods/perlrun.pod | |
parent | 300c1eb6d37d46078d448d6d58938d5a80cd68ff (diff) |
oops, remove 5.16 tlperl files
git-svn-id: svn://tug.org/texlive/trunk@33649 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlrun.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlrun.pod | 1353 |
1 files changed, 0 insertions, 1353 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlrun.pod b/Master/tlpkg/tlperl/lib/pods/perlrun.pod deleted file mode 100644 index 6ddc608d4f4..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlrun.pod +++ /dev/null @@ -1,1353 +0,0 @@ -=head1 NAME - -perlrun - how to execute the Perl interpreter - -=head1 SYNOPSIS - -B<perl> S<[ B<-sTtuUWX> ]> - S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]> - S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]> - S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]> - S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]> - S<[ B<-C [I<number/list>] >]> - S<[ B<-S> ]> - S<[ B<-x>[I<dir>] ]> - S<[ B<-i>[I<extension>] ]> - S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...> - -=head1 DESCRIPTION - -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<perldebug> 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> 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 C<#!> notation invoke interpreters this -way. See L<Location of Perl>.) - -=item 3. - -Passed in implicitly via standard input. This works only if there are -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 C<#!> and containing the word -"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 program using the C<__END__> token.) - -The C<#!> 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 C<#!> line, or worse, doesn't even recognize the C<#!> line, you -still can get consistent switch behaviour regardless of how Perl was -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 C<#!> 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<digits> by C<BEGIN{ $/ = "\0digits"; }>. - -Parsing of the C<#!> 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-*- - eval 'exec perl -x -wS $0 ${1+"$@"}' - if 0; - -to let Perl see the B<-p> switch. - -A similar trick involves the I<env> 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 C<#!> line's path. - -If the C<#!> line does not contain the word "perl" nor the word "indir" -the program named after the C<#!> is executed instead of the Perl -interpreter. This is slightly bizarre, but it helps people on machines -that don't do C<#!>, because they can tell a program that their SHELL is -F</usr/bin/perl>, and Perl will then dispatch the program to the correct -interpreter for them. - -After locating your program, Perl compiles the entire program to an -internal form. If there are any compilation errors, execution of the -program is not attempted. (This is unlike the typical shell script, -which might run part-way through before finding a syntax error.) - -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<exit(0)> is provided to indicate successful completion. - -=head2 #! and quoting on non-Unix systems -X<hashbang> X<#!> - -Unix's C<#!> technique can be simulated on other systems: - -=over 4 - -=item OS/2 - -Put - - extproc perl -S -your_switches - -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 program, and codify it in -C<ALTERNATE_SHEBANG> (see the F<dosish.h> file in the source -distribution for more information). - -=item Win95/NT - -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 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<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly -via F<DCL$PATH> 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<perl "-V:startperl">. - -=back - -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 L<-e|/-e commandline> below). - -On some systems, you may have to change single-quotes to double ones, -which you must I<not> do on Unix or Plan 9 systems. You might also -have to change a single % to a %%. - -For example: - - # Unix - perl -e 'print "Hello world\n"' - - # MS-DOS, etc. - perl -e "print \"Hello world\n\"" - - # 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 I<4DOS> were -the command shell, this would probably work better: - - perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" - -B<CMD.EXE> 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. - -There is no general solution to all of this. It's just a mess. - -=head2 Location of Perl -X<perl, location of interpreter> - -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</usr/bin/perl> -and F</usr/local/bin/perl> 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. - -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/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<perl, command switches> X<command switches> - -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<octal/hexadecimal>] -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 -separator. Other switches may precede or follow the digits. For -example, if you have a version of I<find> which can print filenames -terminated by the null character, you can say this: - - find . -name '*.orig' -print0 | perl -n0e unlink - -The special value 00 will cause Perl to slurp files in paragraph mode. -Any value 0400 or above will cause Perl to slurp files whole, but by convention -the value 0777 is the one normally used for this purpose. - -You can also specify the separator character using hexadecimal notation: -B<-0xI<HHH...>>, where the C<I<H>> are valid hexadecimal digits. Unlike -the octal form, this one may be used to specify any Unicode character, even -those beyond 0xFF. So if you I<really> want a record separator of 0777, -specify it as B<-0x1FF>. (This means that you cannot use the B<-x> option -with a directory name that consists of hexadecimal digits, or else Perl -will think you have specified a hex number to B<-0>.) - -=item B<-a> -X<-a> X<autosplit> - -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 -implicit while loop produced by the B<-n> or B<-p>. - - perl -ane 'print pop(@F), "\n";' - -is equivalent to - - while (<>) { - @F = split(' '); - print pop(@F), "\n"; - } - -An alternate delimiter may be specified using B<-F>. - -=item B<-C [I<number/list>]> -X<-C> - -The B<-C> flag controls some of the Perl Unicode features. - -As of 5.8.1, the B<-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, B<-COE> and B<-C6> will both turn on UTF-8-ness on both -STDOUT and STDERR. Repeating letters is just redundant, not cumulative -nor toggling. - -The C<io> options mean that any subsequent open() (or similar I/O -operations) in the current file scope 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. - -B<-C> on its own (not followed by any number or option list), or the -empty string C<""> for the C<PERL_UNICODE> environment variable, has the -same effect as B<-CSDL>. In other words, the standard I/O handles and -the default C<open()> layer are UTF-8-fied I<but> only if the locale -environment variables indicate a UTF-8 locale. This behaviour follows -the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0. -(See L<perl581delta/UTF-8 no longer default under UTF-8 locales>.) - -You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly -disable all the above Unicode features. - -The read-only magic variable C<${^UNICODE}> reflects the numeric value -of this setting. This variable is set during Perl startup and is -thereafter read-only. If you want runtime effects, use the three-arg -open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>), -and the C<open> pragma (see L<open>). - -(In Perls earlier than 5.8.1 the B<-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".) - -B<Note:> Since perl 5.10.1, if the B<-C> option is used on the C<#!> line, -it must be specified on the command line as well, since the standard streams -are already set up at this point in the execution of the perl interpreter. -You can also use binmode() to set the encoding of an I/O stream. - -=item B<-c> -X<-c> - -causes Perl to check the syntax of the program and then exit without -executing it. Actually, it I<will> execute and C<BEGIN>, C<UNITCHECK>, -or C<CHECK> blocks and any C<use> statements: these are considered as -occurring outside the execution of your program. C<INIT> and C<END> -blocks, however, will be skipped. - -=item B<-d> -X<-d> X<-dt> - -=item B<-dt> - -runs the program under the Perl debugger. See L<perldebug>. -If B<t> is specified, it indicates to the debugger that threads -will be used in the code being debugged. - -=item B<-d:>I<MOD[=bar,baz]> -X<-d> X<-dt> - -=item B<-dt:>I<MOD[=bar,baz]> - -runs the program under the control of a debugging, profiling, or tracing -module installed as C<Devel::I<MOD>>. E.g., B<-d:DProf> executes the -program using the C<Devel::DProf> profiler. As with the B<-M> flag, options -may be passed to the C<Devel::I<MOD>> package where they will be received -and interpreted by the C<Devel::I<MOD>::import> routine. Again, like B<-M>, -use -B<-d:-I<MOD>> to call C<Devel::I<MOD>::unimport> instead of import. The -comma-separated list of options must follow a C<=> character. If B<t> is -specified, it indicates to the debugger that threads will be used in the -code being debugged. See L<perldebug>. - -=item B<-D>I<letters> -X<-D> X<DEBUGGING> X<-DDEBUGGING> - -=item B<-D>I<number> - -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<perldebguts>. - -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, source file input state - 128 m Memory and SV 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 - 131072 T Tokenizing - 262144 R Include reference counts of dumped variables (eg when - using -Ds) - 524288 J show s,t,P-debug (don't Jump over) on 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 - 16777216 M trace smart match resolution - 33554432 B dump suBroutine definitions, including special Blocks - like BEGIN - -All these flags require B<-DDEBUGGING> when you compile the Perl -executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode> -which may change this). -See the F<INSTALL> file in the Perl source distribution -for how to do this. This flag is automatically set if you include B<-g> -option when C<Configure> 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<sh -x> 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<perldebug> for details and variations. - -=item B<-e> I<commandline> -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<commandline> -X<-E> - -behaves just like B<-e>, except that it implicitly enables all -optional features (in the main compilation unit). See L<feature>. - -=item B<-f> -X<-f> X<sitecustomize> X<sitecustomize.pl> - -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 (in a BEGIN block). -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. - -Perl actually inserts the following code: - - BEGIN { - do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; } - && do "$Config{sitelib}/sitecustomize.pl"; - } - -Since it is an actual C<do> (not a C<require>), F<sitecustomize.pl> -doesn't need to return a true value. The code is run in package C<main>, -in its own lexical scope. However, if the script dies, C<$@> will not -be set. - -The value of C<$Config{sitelib}> is also determined in C code and not -read from C<Config.pm>, which is not loaded. - -The code is executed I<very> early. For example, any changes made to -C<@INC> will show up in the output of `perl -V`. Of course, C<END> -blocks will be likewise executed very late. - -To determine at runtime if this capability has been compiled in your -perl, you can check the value of C<$Config{usesitecustomize}>. - -=item B<-F>I<pattern> -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. You can't use literal whitespace in the pattern. - -=item B<-h> -X<-h> - -prints a summary of the options. - -=item B<-i>[I<extension>] -X<-i> X<in-place> - -specifies that files processed by the C<E<lt>E<gt>> 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' - -Or even to place backup copies of the original files into another -directory (provided the directory already exists): - - $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to - # 'old/fileA.orig' - -These sets of one-liners are equivalent: - - $ 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 - $extension = '.orig'; - LINE: while (<>) { - if ($ARGV ne $oldargv) { - if ($extension !~ /\*/) { - $backup = $ARGV . $extension; - } - else { - ($backup = $extension) =~ s/\*/$ARGV/g; - } - rename($ARGV, $backup); - open(ARGVOUT, ">$ARGV"); - select(ARGVOUT); - $oldargv = $ARGV; - } - s/foo/bar/; - } - continue { - print; # this prints to original filename - } - select(STDOUT); - -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. - -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<eof> 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<perlfunc/eof>). - -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). - -For a discussion of issues surrounding file permissions and B<-i>, -see L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?>. - -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<directory> -X<-I> X<@INC> - -Directories specified by B<-I> are prepended to the search path for -modules (C<@INC>). - -=item B<-l>[I<octnum>] -X<-l> X<$/> X<$\> - -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<octnum> so -that any print statements will have that separator added back on. -If I<octnum> is omitted, sets C<$\> to the current value of -C<$/>. For instance, to trim lines to 80 columns: - - perl -lpe 'substr($_, 80) = ""' - -Note that the assignment C<$\ = $/> is done when the switch is processed, -so the input record separator can be different than the output record -separator if the B<-l> switch is followed by a B<-0> switch: - - gnufind / -print0 | perl -ln0e 'print "found $_" if -p' - -This sets C<$\> to newline and then sets C<$/> to the null character. - -=item B<-m>[B<->]I<module> -X<-m> X<-M> - -=item B<-M>[B<->]I<module> - -=item B<-M>[B<->]I<'module ...'> - -=item B<-[mM]>[B<->]I<module=arg[,arg]...> - -B<-m>I<module> executes C<use> I<module> C<();> before executing your -program. - -B<-M>I<module> executes C<use> I<module> C<;> before executing your -program. You can use quotes to add extra code after the module name, -e.g., C<'-MI<MODULE> qw(foo bar)'>. - -If the first character after the B<-M> or B<-m> is a dash (B<->) -then the 'use' is replaced with 'no'. - -A little builtin syntactic sugar means you can also say -B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for -B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when -importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is -C<use module split(/,/,q{foo,bar})>. Note that the C<=> form -removes the distinction between B<-m> and B<-M>. - -A consequence of this is that B<-MI<MODULE>=number> never does a version check, -unless C<I<MODULE>::import()> itself is set up to do a version check, which -could happen for example if I<MODULE> inherits from L<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 I<sed -n> or -I<awk>: - - LINE: - while (<>) { - ... # your program goes here - } - -Note that the lines are not printed by default. See L</-p> to have -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. - -Also note that C<< <> >> passes command line arguments to -L<perlfunc/open>, which doesn't necessarily interpret them as file names. -See L<perlop> for possible security implications. - -Here is an efficient way to delete all files that haven't been modified for -at least a week: - - find . -mtime +7 -print | perl -nle unlink - -This is faster than using the B<-exec> switch of I<find> 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<BEGIN> and C<END> blocks may be used to capture control before or after -the implicit program loop, just as in I<awk>. - -=item B<-p> -X<-p> - -causes Perl to assume the following loop around your program, which -makes it iterate over filename arguments somewhat like I<sed>: - - - LINE: - while (<>) { - ... # your program goes here - } continue { - print or die "-p destination: $!\n"; - } - -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<BEGIN> and C<END> blocks may be used to capture control before or after -the implicit loop, just as in I<awk>. - -=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<-->). 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 "$xyz\n" } - -Do note that a switch like B<--help> creates the variable C<${-help}>, which is not compliant -with C<use strict "refs">. 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 path 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 C<DEBUGGING> turned -on, using the B<-Dp> switch to Perl shows how the search progresses. - -Typically this is used to emulate C<#!> startup on platforms that don't -support C<#!>. It's also convenient when debugging a script that uses C<#!>, -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 -wS $0 ${1+"$@"}' - if $running_under_some_shell; - -The system ignores the first line and feeds the program to F</bin/sh>, -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 -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. 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 I<sh> rather -than I<csh>, some systems may have to replace the C<#!> 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 I<csh>, I<sh>, or Perl, such as the following: - - eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' - & eval 'exec /usr/bin/perl -wS $0 $argv:q' - if $running_under_some_shell; - -If the filename supplied contains directory separators (and so 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. - -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<-t> -X<-t> - -Like B<-T>, but taint checks will issue warnings rather than fatal -errors. These warnings can now be controlled normally with C<no warnings -qw(taint)>. - -B<Note: This is not a substitute for C<-T>!> This is meant to be -used I<only> 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> - -turns on "taint" 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<perlsec> 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 C<#!> line for systems which support -that construct. - -=item B<-u> -X<-u> - -This 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 I<undump> 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 I<undump> is platform -specific and may not be available for a specific port of Perl. - -=item B<-U> -X<-U> - -allows Perl to do unsafe operations. Currently the only "unsafe" -operations are attempting to unlink directories while running as superuser -and running setuid programs with fatal taint checks turned into warnings. -Note that warnings must be enabled along with this option to actually -I<generate> 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. - -=item B<-V:>I<configvar> - -Prints to STDOUT the value of the named configuration variable(s), -with multiples when your C<I<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) - - $ echo "goodvfork="`./perl -Ilib -V::usevfork` - goodvfork=false; - -Leading and trailing colons can be used together if you need -positional parameter values without the names. Note that in the case -below, the C<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 -mentioned only once and scalar variables used -before being set; redefined subroutines; references to undefined -filehandles; filehandles opened read-only that you are attempting -to write on; values used as a number that don't I<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 global C<$^W> variable; normally, -the lexically scoped C<use warnings> pragma is preferred. You -can disable or promote into fatal errors specific warnings using -C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. -See also L<perldiag> and L<perltrap>. A fine-grained warning -facility is also available if you want to manipulate entire classes -of warnings; see L<warnings> or L<perllexwarn>. - -=item B<-W> -X<-W> - -Enables all warnings regardless of C<no warnings> or C<$^W>. -See L<perllexwarn>. - -=item B<-X> -X<-X> - -Disables all warnings regardless of C<use warnings> or C<$^W>. -See L<perllexwarn>. - -=item B<-x> -X<-x> - -=item B<-x>I<directory> - -tells Perl that the program is embedded in a larger chunk of unrelated -text, such as in a mail message. Leading garbage will be -discarded until the first line that starts with C<#!> and contains the -string "perl". Any meaningful switches on that line will be applied. - -All references to line numbers by the program (warnings, errors, ...) -will treat the C<#!> line as the first line. -Thus a warning on the 2nd line of the program, which is on the 100th -line in the file will be reported as line 2, not as line 100. -This can be overridden by using the C<#line> directive. -(See L<perlsyn/"Plain Old Comments (Not!)">) - -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 C<DATA> filehandle -if desired. - -The directory, if specified, must appear immediately following the B<-x> -with no intervening whitespace. - -=back - -=head1 ENVIRONMENT -X<perl, environment variables> - -=over 12 - -=item HOME -X<HOME> - -Used if C<chdir> has no argument. - -=item LOGDIR -X<LOGDIR> - -Used if C<chdir> has no argument and HOME is not set. - -=item PATH -X<PATH> - -Used in executing subprocesses, and in finding the program if B<-S> is -used. - -=item PERL5LIB -X<PERL5LIB> - -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, with this lookup -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<perl --V:I<path_sep>>). - -When running taint checks, either because the program was running setuid or -setgid, or the B<-T> or B<-t> switch was specified, neither PERL5LIB nor -PERLLIB is consulted. The program should instead say: - - use lib "/my/directory"; - -=item PERL5OPT -X<PERL5OPT> - -Command-line options (switches). Switches in this variable are treated -as if they were on every Perl command line. Only the B<-[CDIMUdmtwW]> -switches are allowed. When running taint checks (either because the -program was running setuid or setgid, or because the B<-T> or B<-t> -switch was used), this variable is ignored. If PERL5OPT begins with -B<- T>, tainting will be enabled and subsequent options ignored. If -PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot -removed from @INC, and subsequent options honored. - -=item PERLIO -X<PERLIO> - -A space (or colon) separated list of PerlIO layers. If perl is built -to use PerlIO system for IO (the default) these layers affect Perl's IO. - -It is conventional to start layer names with a colon (for example, C<:perlio>) to -emphasize 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<all> Perl's IO. Consequently only built-in -layers can appear in this list, as external layers (such as C<:encoding()>) need -IO in order to load them!. See L<"open pragma"|open> for how to add external -encodings as defaults. - -Layers it makes sense to include in the PERLIO environment -variable are briefly summarized below. For more details see L<PerlIO>. - -=over 8 - -=item :bytes -X<:bytes> - -A pseudolayer that turns the C<:utf8> flag I<off> 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 C<"\n"> translation distinguishing "text" and -"binary" files in the manner of MS-DOS and similar operating systems. -(It currently does I<not> mimic MS-DOS as far as treating of Control-Z -as being an end-of-file marker.) - -=item :mmap -X<:mmap> - -A layer that implements "reading" of files by using I<mmap>(2) to -make an entire 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 nitroglycerine. - -=item :raw -X<:raw> - -A pseudolayer that manipulates other layers. Applying the C<:raw> -layer is equivalent to calling C<binmode($fh)>. It makes the stream -pass each byte as-is without translation. In particular, both CRLF -translation and intuiting C<:utf8> from the locale are disabled. - -Unlike in earlier versions of Perl, C<:raw> is I<not> -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 a PerlIO interface by wrapping system's ANSI C "stdio" -library calls. The layer provides both buffering and IO. -Note that the C<:stdio> layer does I<not> do CRLF translation even if that -is the platform's normal behaviour. You will need a C<:crlf> layer above it -to do that. - -=item :unix -X<:unix> - -Low-level layer that calls C<read>, C<write>, C<lseek>, etc. - -=item :utf8 -X<:utf8> - -A pseudolayer that enables a flag in the layer below to tell Perl -that output should be in utf8 and that input should be regarded as -already in valid utf8 form. B<WARNING: It does not check for validity and as such -should be handled with extreme caution for input, because security violations -can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(utf8)> is -the best option when reading UTF-8 encoded data. - -=item :win32 -X<:win32> - -On Win32 platforms this I<experimental> layer uses native "handle" IO -rather than a Unix-like numeric file descriptor layer. Known to be -buggy in this release (5.14). - -=back - -The default set of layers should give acceptable results on all platforms - -For Unix platforms that will be the equivalent of "unix perlio" or "stdio". -Configure is set up to prefer the "stdio" implementation if the system's library -provides for fast access to the buffer; otherwise, it uses the "unix perlio" -implementation. - -On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio" -has a number of bugs/mis-features for Perl IO which are somewhat depending -on the version and vendor of the C compiler. Using our own C<crlf> layer as -the buffer avoids those issues and makes things more uniform. The C<crlf> -layer provides CRLF conversion as well as buffering. - -This release (5.14) uses C<unix> as the bottom layer on Win32, and so still -uses the C compiler's numeric file descriptor routines. There is an -experimental native C<win32> layer, which is expected to be enhanced and -should eventually become the default under Win32. - -The PERLIO environment variable is completely ignored when Perl -is run in taint mode. - -=item PERLIO_DEBUG -X<PERLIO_DEBUG> - -If set to the name of a file or device, certain operations of PerlIO -subsystem will be logged to that file, which is opened in append mode -Typical uses are in Unix: - - % env PERLIO_DEBUG=/dev/tty perl script ... - -and under Win32, the approximately equivalent: - - > set PERLIO_DEBUG=CON - perl script ... - -This functionality is disabled for setuid scripts and for scripts run -with B<-T>. - -=item PERLLIB -X<PERLLIB> - -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. - -The PERLLIB environment variable is completely ignored when Perl -is run in taint mode. - -=item PERL5DB -X<PERL5DB> - -The command used to load the debugger code. The default is: - - BEGIN { require "perl5db.pl" } - -The PERL5DB environment variable is only used when Perl is started with -a bare B<-d> switch. - -=item PERL5DB_THREADED -X<PERL5DB_THREADED> - -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<PERL5SHELL> - -On Win32 ports only, may be set to an alternative shell that Perl must use -internally for executing "backtick" commands or system(). Default is -C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The -value is considered space-separated. Precede any character that -needs to be protected, like a space or backslash, with another 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). - -Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked -when running external commands. It is recommended that -you explicitly set (or delete) C<$ENV{PERL5SHELL}> when running -in taint mode under Windows. - -=item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port) -X<PERL_ALLOW_NON_IFS_LSP> - -Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers). -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 I<McAfee Guardian>, which requires -that all applications use its LSP but 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 I<McAfee Guardian> -happy--and in that particular case Perl still works too because I<McAfee -Guardian>'s LSP actually plays other games which allow applications -requiring IFS compatibility to work. - -=item PERL_DEBUG_MSTATS -X<PERL_DEBUG_MSTATS> - -Relevant only if Perl is compiled with the C<malloc> included with the Perl -distribution; that is, if C<perl -V:d_mymalloc> is "define". - -If set, this dumps out memory statistics after execution. If set -to an integer greater than one, also dumps out memory statistics -after compilation. - -=item PERL_DESTRUCT_LEVEL -X<PERL_DESTRUCT_LEVEL> - -Relevant only if your Perl executable was built with B<-DDEBUGGING>, -this controls the behaviour of global destruction of objects and other -references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information. - -=item PERL_DL_NONLAZY -X<PERL_DL_NONLAZY> - -Set to C<"1"> to have Perl resolve I<all> 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 them. - -=item PERL_ENCODING -X<PERL_ENCODING> - -If using the C<use encoding> pragma without an explicit encoding name, the -PERL_ENCODING environment variable is consulted for an encoding name. - -=item PERL_HASH_SEED -X<PERL_HASH_SEED> - -(Since Perl 5.8.1.) Used to randomize Perl's internal hash function. -To emulate the pre-5.8.1 behaviour, set to an integer; C<"0"> means -exactly the same order as in 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 by default return elements in the same order as in Perl 5.8.0. -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 randomize unless the PERL_HASH_SEED is set. -If Perl has been compiled with B<-DUSE_HASH_SEED_EXPLICIT>, the default -behaviour is I<not> to randomize 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<PLEASE NOTE: The hash seed is sensitive information>. 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<perlsec/"Algorithmic Complexity Attacks"> and -L</PERL_HASH_SEED_DEBUG> for more information. - -=item PERL_HASH_SEED_DEBUG -X<PERL_HASH_SEED_DEBUG> - -(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) the value of -the hash seed at the beginning of execution. This, combined with -L</PERL_HASH_SEED> is intended to aid in debugging nondeterministic -behaviour caused by hash randomization. - -B<Note that the hash seed is sensitive information>: by knowing it, one -can craft a denial-of-service attack against Perl code, even remotely; -see L<perlsec/"Algorithmic Complexity Attacks"> for more information. -B<Do not disclose the hash seed> to people who don't need to know it. -See also hash_seed() in L<Hash::Util>. - -=item PERL_MEM_LOG -X<PERL_MEM_LOG> - -If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting -the environment variable C<PERL_MEM_LOG> enables logging debug -messages. The value has the form C<< <I<number>>[m][s][t] >>, where -C<I<number>> is the file descriptor number you want to write to (2 is -default), and the combination of letters specifies that you want -information about (m)emory and/or (s)v, optionally with -(t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all -information to stdout. You can write to other opened file descriptors -in a variety of ways: - - $ 3>foo3 PERL_MEM_LOG=3m perl ... - -=item PERL_ROOT (specific to the VMS port) -X<PERL_ROOT> - -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<perlvms> and in F<README.vms> in the Perl source distribution. - -=item PERL_SIGNALS -X<PERL_SIGNALS> - -Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0 -signal behaviour (which is immediate but unsafe) is restored. If set -to C<safe>, then safe (but deferred) signals are used. See -L<perlipc/"Deferred Signals (Safe Signals)">. - -=item PERL_UNICODE -X<PERL_UNICODE> - -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 B<-C> -switch for more information. - -=item SYS$LOGIN (specific to the VMS port) -X<SYS$LOGIN> - -Used if chdir has no argument and HOME and LOGDIR are not set. - -=back - -Perl also has environment variables that control how Perl handles data -specific to particular natural languages; see L<perllocale>. - -Perl and its various modules and components, including its test frameworks, -may sometimes make use of certain other environment variables. Some of -these are specific to a particular platform. Please consult the -appropriate module documentation and any documentation for your platform -(like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for -variables peculiar to those specific situations. - -Perl makes all environment variables available to the program being -executed, and passes these along to any child processes it starts. -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{SHELL} = "/bin/sh" if exists $ENV{SHELL}; - delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; |