1N/Aperlrun - how to execute the Perl interpreter
1N/AB<perl> S<[ B<-sTtuUWX> ]>
1N/A S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
1N/A S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
1N/A S<[ B<-x>[I<dir>] ]>
1N/A S<[ B<-i>[I<extension>] ]>
1N/A S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
1N/AThe normal way to run a Perl program is by making it directly
1N/Aexecutable, or else by passing the name of the source file as an
1N/Aargument on the command line. (An interactive Perl environment
1N/Ais also possible--see L<perldebug> for details on how to do that.)
1N/AUpon startup, Perl looks for your program in one of the following
1N/ASpecified line by line via B<-e> switches on the command line.
1N/AContained in the file specified by the first filename on the command line.
1N/A(Note that systems supporting the #! notation invoke interpreters this
1N/Away. See L<Location of Perl>.)
1N/APassed in implicitly via standard input. This works only if there are
1N/Ano filename arguments--to pass arguments to a STDIN-read program you
1N/Amust explicitly specify a "-" for the program name.
1N/AWith methods 2 and 3, Perl starts parsing the input file from the
1N/Abeginning, unless you've specified a B<-x> switch, in which case it
1N/Ascans for the first line starting with #! and containing the word
1N/A"perl", and starts there instead. This is useful for running a program
1N/Aembedded in a larger message. (In this case you would indicate the end
1N/Aof the program using the C<__END__> token.)
1N/AThe #! line is always examined for switches as the line is being
1N/Aparsed. Thus, if you're on a machine that allows only one argument
1N/Awith the #! line, or worse, doesn't even recognize the #! line, you
1N/Astill can get consistent switch behavior regardless of how Perl was
1N/Ainvoked, even if B<-x> was used to find the beginning of the program.
1N/ABecause historically some operating systems silently chopped off
1N/Akernel interpretation of the #! line after 32 characters, some
1N/Aswitches may be passed in on the command line, and some may not;
1N/Ayou could even get a "-" without its letter, if you're not careful.
1N/AYou probably want to make sure that all your switches fall either
1N/Abefore or after that 32-character boundary. Most switches don't
1N/Aactually care if they're processed redundantly, but getting a "-"
1N/Ainstead of a complete switch could cause Perl to try to execute
1N/Astandard input instead of your program. And a partial B<-I> switch
1N/Acould also cause odd results.
1N/ASome switches do care if they are processed twice, for instance
1N/Acombinations of B<-l> and B<-0>. Either put all the switches after
1N/Athe 32-character boundary (if applicable), or replace the use of
1N/AB<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>.
1N/AParsing of the #! switches starts wherever "perl" is mentioned in the line.
1N/AThe sequences "-*" and "- " are specifically ignored so that you could,
1N/Aif you were so inclined, say
1N/A eval 'exec perl -wS $0 ${1+"$@"}'
1N/A if $running_under_some_shell;
1N/Ato let Perl see the B<-p> switch.
1N/AA similar trick involves the B<env> program, if you have it.
1N/AThe examples above use a relative path to the perl interpreter,
1N/Agetting whatever version is first in the user's path. If you want
1N/Aa specific version of Perl, say, perl5.005_57, you should place
1N/Athat directly in the #! line's path.
1N/AIf the #! line does not contain the word "perl", the program named after
1N/Athe #! is executed instead of the Perl interpreter. This is slightly
1N/Abizarre, but it helps people on machines that don't do #!, because they
1N/Adispatch the program to the correct interpreter for them.
1N/AAfter locating your program, Perl compiles the entire program to an
1N/Ainternal form. If there are any compilation errors, execution of the
1N/Aprogram is not attempted. (This is unlike the typical shell script,
1N/Awhich might run part-way through before finding a syntax error.)
1N/AIf the program is syntactically correct, it is executed. If the program
1N/Aruns off the end without hitting an exit() or die() operator, an implicit
1N/AC<exit(0)> is provided to indicate successful completion.
1N/A=head2 #! and quoting on non-Unix systems
1N/AUnix's #! technique can be simulated on other systems:
1N/A extproc perl -S -your_switches
1N/Aas the first line in C<*.cmd> file (B<-S> due to a bug in
cmd.exe's
1N/ACreate a batch file to run your program, and codify it in
1N/AC<ALTERNATE_SHEBANG> (see the F<
dosish.h> file in the source
1N/Adistribution for more information).
1N/AThe
Win95/NT installation, when using the ActiveState installer for Perl,
1N/Awill modify the Registry to associate the F<.pl> extension with the perl
1N/Ainterpreter. If you install Perl by other means (including building from
1N/Athe sources), you may have to modify the Registry yourself. Note that
1N/Athis means you can no longer tell the difference between an executable
1N/APerl program and a Perl library file.
1N/AA Macintosh perl program will have the appropriate Creator and
1N/AType, so that double-clicking them will invoke the perl application.
1N/A $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
1N/A $ exit++ + ++$status != 0 and $exit = $status = undef;
1N/Aat the top of your program, where B<-mysw> are any command line switches you
1N/Awant to pass to Perl. You can now invoke the program directly, by saying
1N/AC<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly
1N/Avia F<DCL$PATH> by just using the name of the program).
1N/AThis incantation is a bit much to remember, but Perl will display it for
1N/Ayou if you say C<perl "-V:startperl">.
1N/ACommand-interpreters on non-Unix systems have rather different ideas
1N/Aon quoting than Unix shells. You'll need to learn the special
1N/Acharacters in your command-interpreter (C<*>, C<\> and C<"> are
1N/Acommon) and how to protect whitespace and these characters to run
1N/Aone-liners (see B<-e> below).
1N/AOn some systems, you may have to change single-quotes to double ones,
1N/Awhich you must I<not> do on Unix or Plan 9 systems. You might also
1N/Ahave to change a single % to a %%.
1N/A perl -e 'print "Hello world\n"'
1N/A perl -e "print \"Hello world\n\""
1N/A print "Hello world\n"
1N/A (then Run "Myscript" or Shift-Command-R)
1N/A perl -e "print ""Hello world\n"""
1N/AThe problem is that none of this is reliable: it depends on the
1N/Acommand and it is entirely possible neither works. If B<4DOS> were
1N/Athe command shell, this would probably work better:
1N/A perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
1N/AB<
CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in
1N/Awhen nobody was looking, but just try to find documentation for its
1N/AUnder the Macintosh, it depends which environment you are using. The MacPerl
1N/Ashell, or MPW, is much like Unix shells in its support for several
1N/Aquoting variants, except that it makes free use of the Macintosh's non-ASCII
1N/Acharacters as control characters.
1N/AThere is no general solution to all of this. It's just a mess.
1N/A=head2 Location of Perl
1N/AIt may seem obvious to say, but Perl is useful only when users can
1N/Athat can't be done, system administrators are strongly encouraged
1N/Ato put (symlinks to) perl and its accompanying utilities into a
1N/Adirectory typically found along a user's PATH, or in some other
1N/Aobvious and convenient place.
1N/Awill stand in for whatever method works on your system. You are
1N/Aadvised to use a specific path if you care about a specific version.
1N/Aor if you just want to be running at least version, place a statement
1N/Alike this at the top of your program:
1N/A=head2 Command Switches
1N/AAs with all standard commands, a single-character switch may be
1N/Aclustered with the following switch, if any.
1N/Aspecifies the input record separator (C<$/>) as an octal or
1N/Ahexadecimal number. If there are no digits, the null character is the
1N/Aseparator. Other switches may precede or follow the digits. For
1N/Aexample, if you have a version of B<find> which can print filenames
1N/Aterminated by the null character, you can say this:
1N/A find . -name '*.orig' -print0 | perl -n0e unlink
1N/AThe special value 00 will cause Perl to slurp files in paragraph mode.
1N/AThe value 0777 will cause Perl to slurp files whole because there is no
1N/Alegal byte with that value.
1N/AIf you want to specify any Unicode character, use the hexadecimal
1N/Aformat: C<-0xHHH...>, where the C<H> are valid hexadecimal digits.
1N/A(This means that you cannot use the C<-x> with a directory name that
1N/Aconsists of hexadecimal digits.)
1N/Aturns on autosplit mode when used with a B<-n> or B<-p>. An implicit
1N/Asplit command to the @F array is done as the first thing inside the
1N/Aimplicit while loop produced by the B<-n> or B<-p>.
1N/A perl -ane 'print pop(@F), "\n";'
1N/A print pop(@F), "\n";
1N/AAn alternate delimiter may be specified using B<-F>.
1N/AThe C<-C> flag controls some Unicode of the Perl Unicode features.
1N/AAs of 5.8.1, the C<-C> can be followed either by a number or a list
1N/Aof option letters. The letters, their numeric values, and effects
1N/Aare as follows; listing the letters is equal to summing the numbers.
1N/A I 1 STDIN is assumed to be in UTF-8
1N/A O 2 STDOUT will be in UTF-8
1N/A E 4 STDERR will be in UTF-8
1N/A i 8 UTF-8 is the default PerlIO layer for input streams
1N/A o 16 UTF-8 is the default PerlIO layer for output streams
1N/A A 32 the @ARGV elements are expected to be strings encoded in UTF-8
1N/A L 64 normally the "IOEioA" are unconditional,
1N/A the L makes them conditional on the locale environment
1N/A variables (the LC_ALL, LC_TYPE, and LANG, in the order
1N/A of decreasing precedence) -- if the variables indicate
1N/A UTF-8, then the selected "IOEioA" are in effect
1N/AFor example, C<-COE> and C<-C6> will both turn on UTF-8-ness on both
1N/ASTDOUT and STDERR. Repeating letters is just redundant, not cumulative
1N/AThe C<io> options mean that any subsequent open() (or similar I/O
1N/Aoperations) will have the C<:utf8> PerlIO layer implicitly applied
1N/Ato them, in other words, UTF-8 is expected from any input stream,
1N/Aand UTF-8 is produced to any output stream. This is just the default,
1N/Awith explicit layers in open() and with binmode() one can manipulate
1N/AC<-C> on its own (not followed by any number or option list), or the
1N/Aempty string C<""> for the C<PERL_UNICODE> environment variable, has the
1N/Asame effect as C<-CSDL>. In other words, the standard I/O handles and
1N/Athe default C<open()> layer are UTF-8-fied B<but> only if the locale
1N/Aenvironment variables indicate a UTF-8 locale. This behaviour follows
1N/Athe I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
1N/AYou can use C<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
1N/Adisable all the above Unicode features.
1N/AThe read-only magic variable C<${^UNICODE}> reflects the numeric value
1N/Aof this setting. This is variable is set during Perl startup and is
1N/Athereafter read-only. If you want runtime effects, use the three-arg
1N/Aand the C<open> pragma (see L<open>).
1N/A(In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch
1N/Athat enabled the use of Unicode-aware "wide system call" Win32 APIs.
1N/AThis feature was practically unused, however, and the command line
1N/Aswitch was therefore "recycled".)
1N/Acauses Perl to check the syntax of the program and then exit without
1N/Aexecuting it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and
1N/AC<use> blocks, because these are considered as occurring outside the
1N/Aexecution of your program. C<INIT> and C<END> blocks, however, will
1N/Aruns the program under the Perl debugger. See L<perldebug>.
1N/A=item B<-d:>I<foo[=bar,baz]>
1N/Aruns the program under the control of a debugging, profiling, or
1N/Atracing module installed as Devel::foo.
E.g., B<-d:DProf> executes
1N/Athe program using the Devel::DProf profiler. As with the B<-M>
1N/Aflag, options may be passed to the Devel::foo package where they
1N/Awill be received and interpreted by the Devel::foo::import routine.
1N/AThe comma-separated list of options must follow a C<=> character.
1N/A=item B<-D>I<letters>
1N/Asets debugging flags. To watch how it executes your program, use
1N/AB<-Dtls>. (This works only if debugging is compiled into your
1N/APerl.) Another nice value is B<-Dx>, which lists your compiled
1N/Asyntax tree. And B<-Dr> displays compiled regular expressions;
1N/Athe format of the output is explained in L<perldebguts>.
1N/AAs an alternative, specify a number instead of list of letters (
e.g.,
1N/AB<-D14> is equivalent to B<-Dtls>):
1N/A 1 p Tokenizing and parsing
1N/A with v, displays all stacks
1N/A 4 l Context (loop) stack processing
1N/A 16 o Method and overloading resolution
1N/A 64 P Print profiling info, preprocessor command for -P, source file input state
1N/A 128 m Memory allocation
1N/A 256 f Format processing
1N/A 512 r Regular expression parsing and execution
1N/A 1024 x Syntax tree dump
1N/A 2048 u Tainting checks
1N/A 4096 (Obsolete, previously used for LEAKTEST)
1N/A 8192 H Hash dump -- usurps values()
1N/A 16384 X Scratchpad allocation
1N/A 65536 S Thread synchronization
1N/A 262144 R Include reference counts of dumped variables (eg when using -Ds)
1N/A 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB
1N/A 1048576 v Verbose: use in conjunction with other flags
1N/A 2097152 C Copy On Write
1N/AAll these flags require B<-DDEBUGGING> when you compile the Perl
1N/Aexecutable (but see L<Devel::Peek>, L<re> which may change this).
1N/ASee the F<INSTALL> file in the Perl source distribution
1N/Afor how to do this. This flag is automatically set if you include B<-g>
1N/AIf you're just trying to get a print out of each line of Perl code
1N/Aas it executes, the way that C<sh -x> provides for shell scripts,
1N/Ayou can't use Perl's B<-D> switch. Instead do this
1N/A # If you have "env" utility
1N/A env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
1N/A # Bourne shell syntax
1N/A $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
1N/A % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
1N/ASee L<perldebug> for details and variations.
1N/A=item B<-e> I<commandline>
1N/Amay be used to enter one line of program. If B<-e> is given, Perl
1N/Awill not look for a filename in the argument list. Multiple B<-e>
1N/Acommands may be given to build up a multi-line script. Make sure
1N/Ato use semicolons where you would in a normal program.
1N/A=item B<-F>I<pattern>
1N/Aspecifies the pattern to split on if B<-a> is also in effect. The
1N/Apattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
1N/Aput in single quotes.
1N/Aprints a summary of the options.
1N/A=item B<-i>[I<extension>]
1N/Aspecifies that files processed by the C<E<lt>E<gt>> construct are to be
1N/Aedited in-place. It does this by renaming the input file, opening the
1N/Aoutput file by the original name, and selecting that output file as the
1N/Adefault for print() statements. The extension, if supplied, is used to
1N/Amodify the name of the old file to make a backup copy, following these
1N/AIf no extension is supplied, no backup is made and the current file is
1N/AIf the extension doesn't contain a C<*>, then it is appended to the
1N/Aend of the current filename as a suffix. If the extension does
1N/Acontain one or more C<*> characters, then each C<*> is replaced
1N/Awith the current filename. In Perl terms, you could think of this
1N/A ($backup = $extension) =~ s/\*/$file_name/g;
1N/AThis allows you to add a prefix to the backup file, instead of (or in
1N/Aaddition to) a suffix:
1N/A $ perl -pi'orig_*' -e '
s/bar/baz/' fileA # backup to 'orig_fileA'
1N/AOr even to place backup copies of the original files into another
1N/Adirectory (provided the directory already exists):
1N/AThese sets of one-liners are equivalent:
1N/A $ perl -pi'*' -e '
s/bar/baz/' fileA # overwrite current file
1N/AFrom the shell, saying
1N/Ais the same as using the program:
1N/Awhich is equivalent to
1N/A $extension = '.orig';
1N/A if ($ARGV ne $oldargv) {
1N/A if ($extension !~ /\*/) {
1N/A $backup = $ARGV . $extension;
1N/A ($backup = $extension) =~ s/\*/$ARGV/g;
1N/A rename($ARGV, $backup);
1N/A open(ARGVOUT, ">$ARGV");
1N/A print; # this prints to original filename
1N/Aexcept that the B<-i> form doesn't need to compare $ARGV to $oldargv to
1N/Aknow when the filename has changed. It does, however, use ARGVOUT for
1N/Athe selected filehandle. Note that STDOUT is restored as the default
1N/Aoutput filehandle after the loop.
1N/AAs shown above, Perl creates the backup file whether or not any output
1N/Ais actually changed. So this is just a fancy way to copy files:
1N/A $ perl -p -i'.orig' -e 1 file1 file2 file3...
1N/AYou can use C<eof> without parentheses to locate the end of each input
1N/Afile, in case you want to append to each file, or reset line numbering
1N/AIf, for a given file, Perl is unable to create the backup file as
1N/Aspecified in the extension then it will skip that file and continue on
1N/Awith the next one (if it exists).
1N/AFor a discussion of issues surrounding file permissions and B<-i>,
1N/Asee L<
perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?>.
1N/AYou cannot use B<-i> to create directories or to strip extensions from
1N/APerl does not expand C<~> in filenames, which is good, since some
1N/Afolks use it for their backup files:
1N/AFinally, the B<-i> switch does not impede execution when no
1N/Afiles are given on the command line. In this case, no backup is made
1N/A(the original file cannot, of course, be determined) and processing
1N/Aproceeds from STDIN to STDOUT as might be expected.
1N/A=item B<-I>I<directory>
1N/ADirectories specified by B<-I> are prepended to the search path for
1N/Amodules (C<@INC>), and also tells the C preprocessor where to search for
1N/Ainclude files. The C preprocessor is invoked with B<-P>; by default it
1N/A=item B<-l>[I<octnum>]
1N/Aenables automatic line-ending processing. It has two separate
1N/Aeffects. First, it automatically chomps C<$/> (the input record
1N/Aseparator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
1N/A(the output record separator) to have the value of I<octnum> so
1N/Athat any print statements will have that separator added back on.
1N/AIf I<octnum> is omitted, sets C<$\> to the current value of
1N/AC<$/>. For instance, to trim lines to 80 columns:
1N/A perl -lpe 'substr($_, 80) = ""'
1N/ANote that the assignment C<$\ = $/> is done when the switch is processed,
1N/Aso the input record separator can be different than the output record
1N/Aseparator if the B<-l> switch is followed by a B<-0> switch:
1N/A gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
1N/AThis sets C<$\> to newline and then sets C<$/> to the null character.
1N/A=item B<-m>[B<->]I<module>
1N/A=item B<-M>[B<->]I<module>
1N/A=item B<-M>[B<->]I<'module ...'>
1N/A=item B<-[mM]>[B<->]I<module=arg[,arg]...>
1N/AB<-m>I<module> executes C<use> I<module> C<();> before executing your
1N/AB<-M>I<module> executes C<use> I<module> C<;> before executing your
1N/Aprogram. You can use quotes to add extra code after the module name,
1N/AIf the first character after the B<-M> or B<-m> is a dash (C<->)
1N/Athen the 'use' is replaced with 'no'.
1N/AA little builtin syntactic sugar means you can also say
1N/AB<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for
1N/AC<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when
1N/Aimporting symbols. The actual code generated by B<-Mmodule=foo,bar> is
1N/AC<use module split(/,/,q{foo,bar})>. Note that the C<=> form
1N/Aremoves the distinction between B<-m> and B<-M>.
1N/Acauses Perl to assume the following loop around your program, which
1N/Amakes it iterate over filename arguments somewhat like B<sed -n> or
1N/A ... # your program goes here
1N/ANote that the lines are not printed by default. See B<-p> to have
1N/Alines printed. If a file named by an argument cannot be opened for
1N/Asome reason, Perl warns you about it and moves on to the next file.
1N/AHere is an efficient way to delete all files that haven't been modifed for
1N/A find . -mtime +7 -print | perl -nle unlink
1N/AThis is faster than using the B<-exec> switch of B<find> because you don't
1N/Ahave to start a process on every filename found. It does suffer from
1N/Athe bug of mishandling newlines in pathnames, which you can fix if
1N/Ayou follow the example under B<-0>.
1N/AC<BEGIN> and C<END> blocks may be used to capture control before or after
1N/Athe implicit program loop, just as in B<awk>.
1N/Acauses Perl to assume the following loop around your program, which
1N/Amakes it iterate over filename arguments somewhat like B<sed>:
1N/A ... # your program goes here
1N/A print or die "-p destination: $!\n";
1N/AIf a file named by an argument cannot be opened for some reason, Perl
1N/Awarns you about it, and moves on to the next file. Note that the
1N/Alines are printed automatically. An error occurring during printing is
1N/Atreated as fatal. To suppress printing use the B<-n> switch. A B<-p>
1N/Aoverrides a B<-n> switch.
1N/AC<BEGIN> and C<END> blocks may be used to capture control before or after
1N/Athe implicit loop, just as in B<awk>.
1N/AB<NOTE: Use of -P is strongly discouraged because of its inherent
1N/Aproblems, including poor portability.>
1N/AThis option causes your program to be run through the C preprocessor before
1N/Acompilation by Perl. Because both comments and B<cpp> directives begin
1N/Awith the # character, you should avoid starting comments with any words
1N/Arecognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">.
1N/AIf you're considering using C<-P>, you might also want to look at the
1N/AFilter::cpp module from CPAN.
1N/AThe problems of -P include, but are not limited to:
1N/AThe C<#!> line is stripped, so any switches there don't apply.
1N/AA C<-P> on a C<#!> line doesn't work.
1N/AB<All> lines that begin with (whitespace and) a C<#> but
1N/Ado not look like cpp commands, are stripped, including anything
1N/Ainside Perl strings, regular expressions, and here-docs .
1N/AIn some platforms the C preprocessor knows too much: it knows about
1N/Athe C++ -style until-end-of-line comments starting with C<"//">.
1N/AThis will cause problems with common Perl constructs like
1N/Abecause after -P this will became illegal code
1N/AThe workaround is to use some other quoting separator than C<"/">,
1N/Alike for example C<"!">:
1N/AIt requires not only a working C preprocessor but also a working
1N/AF<sed>. If not on UNIX, you are probably out of luck on this.
1N/AScript line numbers are not preserved.
1N/AThe C<-x> does not work with C<-P>.
1N/Aenables rudimentary switch parsing for switches on the command
1N/Aline after the program name but before any filename arguments (or before
1N/Aan argument of B<-->). This means you can have switches with two leading
1N/Adashes (B<--help>). Any switch found there is removed from @ARGV and sets the
1N/Acorresponding variable in the Perl program. The following program
1N/Aprints "1" if the program is invoked with a B<-xyz> switch, and "abc"
1N/Aif it is invoked with B<-xyz=abc>.
1N/A if ($xyz) { print "$xyz\n" }
1N/ADo note that B<--help> creates the variable ${-help}, which is not compliant
1N/Amakes Perl use the PATH environment variable to search for the
1N/Aprogram (unless the name of the program contains directory separators).
1N/AOn some platforms, this also makes Perl append suffixes to the
1N/Afilename while searching for it. For example, on Win32 platforms,
1N/Athe ".bat" and ".cmd" suffixes are appended if a lookup for the
1N/Aoriginal name fails, and if the name does not already end in one
1N/Aof those suffixes. If your Perl was compiled with DEBUGGING turned
1N/Aon, using the -Dp switch to Perl shows how the search progresses.
1N/ATypically this is used to emulate #! startup on platforms that
1N/Adon't support #!. This example works on many platforms that
1N/Ahave a shell compatible with Bourne shell:
1N/A if $running_under_some_shell;
1N/AThe system ignores the first line and feeds the program to F<
/bin/sh>,
1N/Awhich proceeds to try to execute the Perl program as a shell script.
1N/AThe shell executes the second line as a normal shell command, and thus
1N/Astarts up the Perl interpreter. On some systems $0 doesn't always
1N/Acontain the full pathname, so the B<-S> tells Perl to search for the
1N/Aprogram if necessary. After Perl locates the program, it parses the
1N/Alines and ignores them because the variable $running_under_some_shell
1N/Ais never true. If the program will be interpreted by csh, you will need
1N/Ato replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
1N/Aembedded spaces (and such) in the argument list. To start up sh rather
1N/Athan csh, some systems may have to replace the #! line with a line
1N/Acontaining just a colon, which will be politely ignored by Perl. Other
1N/Asystems can't control that, and need a totally devious construct that
1N/Awill work under any of B<csh>, B<sh>, or Perl, such as the following:
1N/A eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
1N/A if $running_under_some_shell;
1N/AIf the filename supplied contains directory separators (
i.e., is an
1N/Aabsolute or relative pathname), and if that file is not found,
1N/Aplatforms that append file extensions will do so and try to look
1N/Afor the file with those extensions added, one by one.
1N/AOn DOS-like platforms, if the program does not contain directory
1N/Aseparators, it will first be searched for in the current directory
1N/Abefore being searched for on the PATH. On Unix platforms, the
1N/Aprogram will be searched for strictly on the PATH.
1N/ALike B<-T>, but taint checks will issue warnings rather than fatal
1N/Aerrors. These warnings can be controlled normally with C<no warnings
1N/AB<NOTE: this is not a substitute for -T.> This is meant only to be
1N/Aused as a temporary development aid while securing legacy code:
1N/Afor real production code and for new secure code written from scratch
1N/Aalways use the real B<-T>.
1N/Aforces "taint" checks to be turned on so you can test them. Ordinarily
1N/Athese checks are done only when running setuid or setgid. It's a
1N/Agood idea to turn them on explicitly for programs that run on behalf
1N/Aof someone else whom you might not necessarily trust, such as CGI
1N/Aprograms or any internet servers you might write in Perl. See
1N/AL<perlsec> for details. For security reasons, this option must be
1N/Aseen by Perl quite early; usually this means it must appear early
1N/Aon the command line or in the #! line for systems which support
1N/AThis obsolete switch causes Perl to dump core after compiling your
1N/Aprogram. You can then in theory take this core dump and turn it
1N/Ainto an executable file by using the B<undump> program (not supplied).
1N/AThis speeds startup at the expense of some disk space (which you
1N/Acan minimize by stripping the executable). (Still, a "hello world"
1N/Aexecutable comes out to about 200K on my machine.) If you want to
1N/Aexecute a portion of your program before dumping, use the dump()
1N/Aoperator instead. Note: availability of B<undump> is platform
1N/Aspecific and may not be available for a specific port of Perl.
1N/AThis switch has been superseded in favor of the new Perl code
1N/Agenerator backends to the compiler. See L<B> and L<B::Bytecode>
1N/Aallows Perl to do unsafe operations. Currently the only "unsafe"
1N/Aoperations are the unlinking of directories while running as superuser,
1N/Aand running setuid programs with fatal taint checks turned into
1N/Awarnings. Note that the B<-w> switch (or the C<$^W> variable) must
1N/Abe used along with this option to actually I<generate> the
1N/Ataint-check warnings.
1N/Aprints the version and patchlevel of your perl executable.
1N/Aprints summary of the major perl configuration values and the current
1N/APrints to STDOUT the value of the named configuration variable.
1N/Awill provide strong clues about what your MANPATH variable should
1N/Abe set to in order to access the Perl documentation.
1N/Aprints warnings about dubious constructs, such as variable names
1N/Athat are mentioned only once and scalar variables that are used
1N/Abefore being set, redefined subroutines, references to undefined
1N/Afilehandles or filehandles opened read-only that you are attempting
1N/Ato write on, values used as a number that doesn't look like numbers,
1N/Ausing an array as though it were a scalar, if your subroutines
1N/Arecurse more than 100 deep, and innumerable other things.
1N/AThis switch really just enables the internal C<$^W> variable. You
1N/Acan disable or promote into fatal errors specific warnings using
1N/ASee also L<perldiag> and L<perltrap>. A new, fine-grained warning
1N/Afacility is also available if you want to manipulate entire classes
1N/Aof warnings; see L<warnings> or L<perllexwarn>.
1N/AEnables all warnings regardless of C<no warnings> or C<$^W>.
1N/ADisables all warnings regardless of C<use warnings> or C<$^W>.
1N/A=item B<-x> I<directory>
1N/Atells Perl that the program is embedded in a larger chunk of unrelated
1N/AASCII text, such as in a mail message. Leading garbage will be
1N/Adiscarded until the first line that starts with #! and contains the
1N/Astring "perl". Any meaningful switches on that line will be applied.
1N/AIf a directory name is specified, Perl will switch to that directory
1N/Abefore running the program. The B<-x> switch controls only the
1N/Adisposal of leading garbage. The program must be terminated with
1N/AC<__END__> if there is trailing garbage to be ignored (the program
1N/Acan process any or all of the trailing garbage via the DATA filehandle
1N/AUsed if chdir has no argument.
1N/AUsed if chdir has no argument and HOME is not set.
1N/AUsed in executing subprocesses, and in finding the program if B<-S> is
1N/AA list of directories in which to look for Perl library
1N/Afiles before looking in the standard library and the current
1N/Adirectory. Any architecture-specific directories under the specified
1N/Alocations are automatically included if they exist. If PERL5LIB is not
1N/Adefined, PERLLIB is used. Directories are separated (like in PATH) by
1N/Aa colon on unixish platforms and by a semicolon on Windows (the proper
1N/Apath separator being given by the command C<perl -V:path_sep>).
1N/AWhen running taint checks (either because the program was running setuid
1N/Aor setgid, or the B<-T> switch was used), neither variable is used.
1N/AThe program should instead say:
1N/ACommand-line options (switches). Switches in this variable are taken
1N/Aas if they were on every Perl command line. Only the B<-[DIMUdmtw]>
1N/Aswitches are allowed. When running taint checks (because the program
1N/Awas running setuid or setgid, or the B<-T> switch was used), this
1N/Avariable is ignored. If PERL5OPT begins with B<-T>, tainting will be
1N/Aenabled, and any subsequent options ignored.
1N/AA space (or colon) separated list of PerlIO layers. If perl is built
1N/Ato use PerlIO system for IO (the default) these layers effect perl's IO.
1N/AIt is conventional to start layer names with a colon
e.g. C<:perlio> to
1N/Aemphasise their similarity to variable "attributes". But the code that parses
1N/Alayer specification strings (which is also used to decode the PERLIO
1N/Aenvironment variable) treats the colon as a separator.
1N/AAn unset or empty PERLIO is equivalent to C<:stdio>.
1N/AThe list becomes the default for I<all> perl's IO. Consequently only built-in
1N/Alayers can appear in this list, as external layers (such as :encoding()) need
1N/AIO in order to load them!. See L<"open pragma"|open> for how to add external
1N/Aencodings as defaults.
1N/AThe layers that it makes sense to include in the PERLIO environment
1N/Avariable are briefly summarised below. For more details see L<PerlIO>.
1N/AA pseudolayer that turns I<off> the C<:utf8> flag for the layer below.
1N/AUnlikely to be useful on its own in the global PERLIO environment variable.
1N/AYou perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
1N/AA layer which does CRLF to "\n" translation distinguishing "text" and
1N/A"binary" files in the manner of MS-DOS and similar operating systems.
1N/A(It currently does I<not> mimic MS-DOS as far as treating of Control-Z
1N/Aas being an end-of-file marker.)
1N/AA layer which implements "reading" of files by using C<mmap()> to
1N/Amake (whole) file appear in the process's address space, and then
1N/Ausing that as PerlIO's "buffer".
1N/AThis is a re-implementation of "stdio-like" buffering written as a
1N/APerlIO "layer". As such it will call whatever layer is below it for
1N/Aits operations (typically C<:unix>).
1N/AAn experimental pseudolayer that removes the topmost layer.
1N/AUse with the same care as is reserved for nitroglycerin.
1N/AA pseudolayer that manipulates other layers. Applying the <:raw>
1N/Alayer is equivalent to calling C<binmode($fh)>. It makes the stream
1N/Apass each byte as-is without any translation. In particular CRLF
1N/Atranslation,
and/or :utf8 intuited from locale are disabled.
1N/AUnlike in the earlier versions of Perl C<:raw> is I<not>
1N/Ajust the inverse of C<:crlf> - other layers which would affect the
1N/Abinary nature of the stream are also removed or disabled.
1N/AThis layer provides PerlIO interface by wrapping system's ANSI C "stdio"
1N/Alibrary calls. The layer provides both buffering and IO.
1N/ANote that C<:stdio> layer does I<not> do CRLF translation even if that
1N/Ais platforms normal behaviour. You will need a C<:crlf> layer above it
1N/ALow level layer which calls C<read>, C<write> and C<lseek> etc.
1N/AA pseudolayer that turns on a flag on the layer below to tell perl
1N/Athat output should be in utf8 and that input should be regarded as
1N/Aalready in utf8 form. May be useful in PERLIO environment
1N/Avariable to make UTF-8 the default. (To turn off that behaviour
1N/Ause C<:bytes> layer.)
1N/AOn Win32 platforms this I<experimental> layer uses native "handle" IO
1N/Arather than unix-like numeric file descriptor layer. Known to be
1N/Abuggy in this release.
1N/AOn all platforms the default set of layers should give acceptable results.
1N/AFor UNIX platforms that will equivalent of "unix perlio" or "stdio".
1N/AConfigure is setup to prefer "stdio" implementation if system's library
1N/Aprovides for fast access to the buffer, otherwise it uses the "unix perlio"
1N/AOn Win32 the default in this release is "unix crlf". Win32's "stdio"
1N/Athe buffer avoids those issues and makes things more uniform.
1N/AThe C<crlf> layer provides CRLF
to/from "\n" conversion as well as
1N/AThis release uses C<unix> as the bottom layer on Win32 and so still uses C
1N/Acompiler's numeric file descriptor routines. There is an experimental native
1N/AC<win32> layer which is expected to be enhanced and should eventually be
1N/Athe default under Win32.
1N/AIf set to the name of a file or device then certain operations of PerlIO
1N/Asub-system will be logged to that file (opened as append). Typical uses
1N/Aand Win32 approximate equivalent:
1N/A set PERLIO_DEBUG=CON
1N/AA list of directories in which to look for Perl library
1N/Afiles before looking in the standard library and the current directory.
1N/AIf PERL5LIB is defined, PERLLIB is not used.
1N/AThe command used to load the debugger code. The default is:
1N/A=item PERL5SHELL (specific to the Win32 port)
1N/AMay be set to an alternative shell that perl must use internally for
1N/Aexecuting "backtick" commands or system(). Default is C<
cmd.exe /x/d/c>
1N/Aon WindowsNT and C<
command.com /c> on Windows95. The value is considered
1N/Ato be space-separated. Precede any character that needs to be protected
1N/A(like a space or backslash) with a backslash.
1N/ANote that Perl doesn't use COMSPEC for this purpose because
1N/ACOMSPEC has a high degree of variability among users, leading to
1N/Aportability concerns. Besides, perl can use a shell that may not be
1N/Afit for interactive use, and setting COMSPEC to such a shell may
1N/Ainterfere with the proper functioning of other programs (which usually
1N/Alook in COMSPEC to find a shell fit for interactive use).
1N/A=item PERL_DEBUG_MSTATS
1N/ARelevant only if perl is compiled with the malloc included with the perl
1N/Adistribution (that is, if C<perl -V:d_mymalloc> is 'define').
1N/AIf set, this causes memory statistics to be dumped after execution. If set
1N/Ato an integer greater than one, also causes memory statistics to be dumped
1N/A=item PERL_DESTRUCT_LEVEL
1N/ARelevant only if your perl executable was built with B<-DDEBUGGING>,
1N/Athis controls the behavior of global destruction of objects and other
1N/A=item PERL_DL_NONLAZY
1N/ASet to one to have perl resolve B<all> undefined symbols when it loads
1N/Aa dynamic library. The default behaviour is to resolve symbols when
1N/Athey are used. Setting this variable is useful during testing of
1N/Aextensions as it ensures that you get an error on misspelled function
1N/Anames even if the test suite doesn't call it.
1N/AIf using the C<encoding> pragma without an explicit encoding name, the
1N/APERL_ENCODING environment variable is consulted for an encoding name.
1N/A(Since Perl 5.8.1.) Used to randomise Perl's internal hash function.
1N/ATo emulate the pre-5.8.1 behaviour, set to an integer (zero means
1N/Aexactly the same order as 5.8.0). "Pre-5.8.1" means, among other
1N/Athings, that hash keys will be ordered the same between different runs
1N/AThe default behaviour is to randomise unless the PERL_HASH_SEED is set.
1N/AIf Perl has been compiled with C<-DUSE_HASH_SEED_EXPLICIT>, the default
1N/Abehaviour is B<not> to randomise unless the PERL_HASH_SEED is set.
1N/AIf PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses
1N/Athe pseudorandom seed supplied by the operating system and libraries.
1N/AThis means that each different run of Perl will have a different
1N/Aordering of the results of keys(), values(), and each().
1N/AB<Please note that the hash seed is sensitive information>. Hashes are
1N/Arandomized to protect against local and remote attacks against Perl
1N/Acode. By manually setting a seed this protection may be partially or
1N/ASee L<perlsec/"Algorithmic Complexity Attacks"> and
1N/AL</PERL_HASH_SEED_DEBUG> for more information.
1N/A=item PERL_HASH_SEED_DEBUG
1N/A(Since Perl 5.8.1.) Set to one to display (to STDERR) the value of
1N/Athe hash seed at the beginning of execution. This, combined with
1N/AL</PERL_HASH_SEED> is intended to aid in debugging nondeterministic
1N/Abehavior caused by hash randomization.
1N/AB<Note that the hash seed is sensitive information>: by knowing it one
1N/Acan craft a denial-of-service attack against Perl code, even remotely,
1N/Asee L<perlsec/"Algorithmic Complexity Attacks"> for more information.
1N/AB<Do not disclose the hash seed> to people who don't need to know it.
1N/ASee also hash_seed() of L<Hash::Util>.
1N/A=item PERL_ROOT (specific to the VMS port)
1N/AA translation concealed rooted logical name that contains perl and the
1N/Alogical device for the @INC path on VMS only. Other logical names that
1N/Aaffect perl on VMS include PERLSHR, PERL_ENV_TABLES, and
1N/ASYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in
1N/AIn Perls 5.8.1 and later. If set to C<unsafe> the pre-Perl-5.8.0
1N/Asignals behaviour (immediate but unsafe) is restored. If set to
1N/AC<safe> the safe (or deferred) signals are used.
1N/ASee L<perlipc/"Deferred Signals (Safe signals)">.
1N/AEquivalent to the B<-C> command-line switch. Note that this is not
1N/Aa boolean variable-- setting this to C<"1"> is not the right way to
1N/A"enable Unicode" (whatever that would mean). You can use C<"0"> to
1N/A"disable Unicode", though (or alternatively unset PERL_UNICODE in
1N/Ayour shell before starting Perl). See the description of the C<-C>
1N/Aswitch for more information.
1N/A=item SYS$LOGIN (specific to the VMS port)
1N/AUsed if chdir has no argument and HOME and LOGDIR are not set.
1N/APerl also has environment variables that control how Perl handles data
1N/Aspecific to particular natural languages. See L<perllocale>.
1N/AApart from these, Perl uses no other environment variables, except
1N/Ato make them available to the program being executed, and to child
1N/Aprocesses. However, programs running setuid would do well to execute
1N/Athe following lines before doing anything else, just to keep people
1N/A delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};