748 lines
26 KiB
Plaintext
748 lines
26 KiB
Plaintext
=head1 NAME
|
|
|
|
perlrun - how to execute the Perl interpreter
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<perl> S<[ B<-sTuU> ]>
|
|
S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
|
|
S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
|
|
S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
|
|
S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
|
|
S<[ B<-P> ]>
|
|
S<[ B<-S> ]>
|
|
S<[ B<-x>[I<dir>] ]>
|
|
S<[ B<-i>[I<extension>] ]>
|
|
S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Upon startup, Perl looks for your script in one of the following
|
|
places:
|
|
|
|
=over 4
|
|
|
|
=item 1.
|
|
|
|
Specified line by line via B<-e> switches on the command line.
|
|
|
|
=item 2.
|
|
|
|
Contained in the file specified by the first filename on the command line.
|
|
(Note that systems supporting the #! notation invoke interpreters this
|
|
way. 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 script you
|
|
must explicitly specify a "-" for the script name.
|
|
|
|
=back
|
|
|
|
With methods 2 and 3, Perl starts parsing the input file from the
|
|
beginning, unless you've specified a B<-x> switch, in which case it
|
|
scans for the first line starting with #! and containing the word
|
|
"perl", and starts there instead. This is useful for running a script
|
|
embedded in a larger message. (In this case you would indicate the end
|
|
of the script using the C<__END__> token.)
|
|
|
|
The #! line is always examined for switches as the line is being
|
|
parsed. Thus, if you're on a machine that allows only one argument
|
|
with the #! line, or worse, doesn't even recognize the #! line, you
|
|
still can get consistent switch behavior regardless of how Perl was
|
|
invoked, even if B<-x> was used to find the beginning of the script.
|
|
|
|
Because many operating systems silently chop off kernel interpretation of
|
|
the #! line after 32 characters, some switches may be passed in on the
|
|
command line, and some may not; you could even get a "-" without its
|
|
letter, if you're not careful. You probably want to make sure that all
|
|
your switches fall either before or after that 32 character boundary.
|
|
Most switches don't actually care if they're processed redundantly, but
|
|
getting a - instead of a complete switch could cause Perl to try to
|
|
execute standard input instead of your script. And a partial B<-I> switch
|
|
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 #! switches starts wherever "perl" is mentioned in the line.
|
|
The sequences "-*" and "- " are specifically ignored so that you could,
|
|
if you were so inclined, say
|
|
|
|
#!/bin/sh -- # -*- perl -*- -p
|
|
eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
|
|
if $running_under_some_shell;
|
|
|
|
to let Perl see the B<-p> switch.
|
|
|
|
If the #! line does not contain the word "perl", the program named after
|
|
the #! is executed instead of the Perl interpreter. This is slightly
|
|
bizarre, but it helps people on machines that don't do #!, because they
|
|
can tell a program that their SHELL is /usr/bin/perl, and Perl will then
|
|
dispatch the program to the correct interpreter for them.
|
|
|
|
After locating your script, Perl compiles the entire script to an
|
|
internal form. If there are any compilation errors, execution of the
|
|
script is not attempted. (This is unlike the typical shell script,
|
|
which might run part-way through before finding a syntax error.)
|
|
|
|
If the script is syntactically correct, it is executed. If the script
|
|
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
|
|
|
|
Unix's #! 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 (C<-S> due to a bug in cmd.exe's
|
|
`extproc' handling).
|
|
|
|
=item MS-DOS
|
|
|
|
Create a batch file to run your script, and codify it in
|
|
C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source
|
|
distribution for more information).
|
|
|
|
=item Win95/NT
|
|
|
|
The Win95/NT installation, when using the Activeware port of Perl,
|
|
will modify the Registry to associate the F<.pl> extension with the perl
|
|
interpreter. If you install another port of Perl, including the one
|
|
in the Win32 directory of the Perl distribution, then you'll have to
|
|
modify the Registry yourself. Note that this means you can no
|
|
longer tell the difference between an executable Perl program
|
|
and a Perl library file.
|
|
|
|
=item Macintosh
|
|
|
|
Macintosh perl scripts will have the appropriate Creator and
|
|
Type, so that double-clicking them will invoke the perl application.
|
|
|
|
=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 script, where C<-mysw> are any command line switches you
|
|
want to pass to Perl. You can now invoke the script directly, by saying
|
|
C<perl script>, or as a DCL procedure, by saying C<@script> (or implicitly
|
|
via F<DCL$PATH> by just using the name of the script).
|
|
|
|
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 C<-e> below).
|
|
|
|
On some systems, you may have to change single-quotes to double ones,
|
|
which you must I<NOT> do on Unix or Plan9 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\""
|
|
|
|
# Macintosh
|
|
print "Hello world\n"
|
|
(then Run "Myscript" or Shift-Command-R)
|
|
|
|
# VMS
|
|
perl -e "print ""Hello world\n"""
|
|
|
|
The problem is that none of this is reliable: it depends on the command
|
|
and it is entirely possible neither works. If 4DOS was the command shell, this would
|
|
probably work better:
|
|
|
|
perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
|
|
|
|
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.
|
|
|
|
Under the Macintosh, it depends which environment you are using. The MacPerl
|
|
shell, or MPW, is much like Unix shells in its support for several
|
|
quoting variants, except that it makes free use of the Macintosh's non-ASCII
|
|
characters as control characters.
|
|
|
|
There is no general solution to all of this. It's just a mess.
|
|
|
|
=head2 Location of Perl
|
|
|
|
It may seem obvious to say, but Perl is useful only when users can
|
|
easily find it. When possible, it's good for both B</usr/bin/perl> and
|
|
B</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, such as perldoc, into
|
|
a directory typically found along a user's PATH, or in another obvious
|
|
and convenient place.
|
|
|
|
In this documentation, C<#!/usr/bin/perl> on the first line of the script
|
|
will stand in for whatever method works on your system.
|
|
|
|
=head2 Switches
|
|
|
|
A single-character switch may be combined with the following switch, if
|
|
any.
|
|
|
|
#!/usr/bin/perl -spi.bak # same as -s -p -i.bak
|
|
|
|
Switches include:
|
|
|
|
=over 5
|
|
|
|
=item B<-0>[I<digits>]
|
|
|
|
specifies the input record separator (C<$/>) as an octal number. If there are
|
|
no digits, the null character is the separator. Other switches may
|
|
precede or follow the digits. For example, if you have a version of
|
|
B<find> which can print filenames terminated by the null character, you
|
|
can say this:
|
|
|
|
find . -name '*.bak' -print0 | perl -n0e unlink
|
|
|
|
The special value 00 will cause Perl to slurp files in paragraph mode.
|
|
The value 0777 will cause Perl to slurp files whole because there is no
|
|
legal character with that value.
|
|
|
|
=item B<-a>
|
|
|
|
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>
|
|
|
|
causes Perl to check the syntax of the script and then exit without
|
|
executing it. Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks,
|
|
because these are considered as occurring outside the execution of
|
|
your program.
|
|
|
|
=item B<-d>
|
|
|
|
runs the script under the Perl debugger. See L<perldebug>.
|
|
|
|
=item B<-d:>I<foo>
|
|
|
|
runs the script under the control of a debugging or tracing module
|
|
installed as Devel::foo. E.g., B<-d:DProf> executes the script using the
|
|
Devel::DProf profiler. See L<perldebug>.
|
|
|
|
=item B<-D>I<letters>
|
|
|
|
=item B<-D>I<number>
|
|
|
|
sets debugging flags. To watch how it executes your script, 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. 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
|
|
2 s Stack snapshots
|
|
4 l Context (loop) stack processing
|
|
8 t Trace execution
|
|
16 o Method and overloading resolution
|
|
32 c String/numeric conversions
|
|
64 P Print preprocessor command for -P
|
|
128 m Memory allocation
|
|
256 f Format processing
|
|
512 r Regular expression parsing and execution
|
|
1024 x Syntax tree dump
|
|
2048 u Tainting checks
|
|
4096 L Memory leaks (needs C<-DLEAKTEST> when compiling Perl)
|
|
8192 H Hash dump -- usurps values()
|
|
16384 X Scratchpad allocation
|
|
32768 D Cleaning up
|
|
65536 S Thread synchronization
|
|
|
|
All these flags require C<-DDEBUGGING> when you compile the Perl
|
|
executable. This flag is automatically set if you include C<-g>
|
|
option when C<Configure> asks you about optimizer/debugger flags.
|
|
|
|
=item B<-e> I<commandline>
|
|
|
|
may be used to enter one line of script.
|
|
If B<-e> is given, Perl
|
|
will not look for a script filename in the argument list.
|
|
Multiple B<-e> commands may
|
|
be given to build up a multi-line script.
|
|
Make sure to use semicolons where you would in a normal program.
|
|
|
|
=item B<-F>I<pattern>
|
|
|
|
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.
|
|
|
|
=item B<-h>
|
|
|
|
prints a summary of the options.
|
|
|
|
=item B<-i>[I<extension>]
|
|
|
|
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'bak_*' -e 's/bar/baz/' fileA # backup to 'bak_fileA'
|
|
|
|
Or even to place backup copies of the original files into another
|
|
directory (provided the directory already exists):
|
|
|
|
$ perl -pi'old/*.bak' -e 's/bar/baz/' fileA # backup to 'old/fileA.bak'
|
|
|
|
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'.bak' -e 's/bar/baz/' fileA # backup to 'fileA.bak'
|
|
$ perl -pi'*.bak' -e 's/bar/baz/' fileA # backup to 'fileA.bak'
|
|
|
|
From the shell, saying
|
|
|
|
$ perl -p -i.bak -e "s/foo/bar/; ... "
|
|
|
|
is the same as using the script:
|
|
|
|
#!/usr/bin/perl -pi.bak
|
|
s/foo/bar/;
|
|
|
|
which is equivalent to
|
|
|
|
#!/usr/bin/perl
|
|
$extension = '.bak';
|
|
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'.bak' -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 C<-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<~>, so don't do that.
|
|
|
|
Finally, note that 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>
|
|
|
|
Directories specified by B<-I> are prepended to the search path for
|
|
modules (C<@INC>), and also tells the C preprocessor where to search for
|
|
include files. The C preprocessor is invoked with B<-P>; by default it
|
|
searches /usr/include and /usr/lib/perl.
|
|
|
|
=item B<-l>[I<octnum>]
|
|
|
|
enables automatic line-ending processing. It has two effects: first,
|
|
it automatically chomps "C<$/>" (the input record separator) when used
|
|
with B<-n> or B<-p>, and second, it assigns "C<$\>"
|
|
(the output record separator) to have the value of I<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>
|
|
|
|
=item B<-M>[B<->]I<module>
|
|
|
|
=item B<-M>[B<->]I<'module ...'>
|
|
|
|
=item B<-[mM]>[B<->]I<module=arg[,arg]...>
|
|
|
|
C<-m>I<module> executes C<use> I<module> C<();> before executing your
|
|
script.
|
|
|
|
C<-M>I<module> executes C<use> I<module> C<;> before executing your
|
|
script. You can use quotes to add extra code after the module name,
|
|
e.g., C<-M'module qw(foo bar)'>.
|
|
|
|
If the first character after the C<-M> or C<-m> is a dash (C<->)
|
|
then the 'use' is replaced with 'no'.
|
|
|
|
A little builtin syntactic sugar means you can also say
|
|
C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for
|
|
C<-M'module qw(foo bar)'>. This avoids the need to use quotes when
|
|
importing symbols. The actual code generated by C<-Mmodule=foo,bar> is
|
|
C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
|
|
removes the distinction between C<-m> and C<-M>.
|
|
|
|
=item B<-n>
|
|
|
|
causes Perl to assume the following loop around your script, which
|
|
makes it iterate over filename arguments somewhat like B<sed -n> or
|
|
B<awk>:
|
|
|
|
while (<>) {
|
|
... # your script goes here
|
|
}
|
|
|
|
Note that the lines are not printed by default. See B<-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.
|
|
|
|
Here is an efficient way to delete all files older than a week:
|
|
|
|
find . -mtime +7 -print | perl -nle 'unlink;'
|
|
|
|
This is faster than using the C<-exec> switch of B<find> because you don't
|
|
have to start a process on every filename found.
|
|
|
|
C<BEGIN> and C<END> blocks may be used to capture control before or after
|
|
the implicit loop, just as in B<awk>.
|
|
|
|
=item B<-p>
|
|
|
|
causes Perl to assume the following loop around your script, which
|
|
makes it iterate over filename arguments somewhat like B<sed>:
|
|
|
|
|
|
while (<>) {
|
|
... # your script 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 awk.
|
|
|
|
=item B<-P>
|
|
|
|
causes your script to be run through the C preprocessor before
|
|
compilation by Perl. (Because both comments and cpp directives begin
|
|
with the # character, you should avoid starting comments with any words
|
|
recognized by the C preprocessor such as "if", "else", or "define".)
|
|
|
|
=item B<-s>
|
|
|
|
enables some rudimentary switch parsing for switches on the command
|
|
line after the script name but before any filename arguments (or before
|
|
a B<-->). Any switch found there is removed from @ARGV and sets the
|
|
corresponding variable in the Perl script. The following script
|
|
prints "true" if and only if the script is invoked with a B<-xyz> switch.
|
|
|
|
#!/usr/bin/perl -s
|
|
if ($xyz) { print "true\n"; }
|
|
|
|
=item B<-S>
|
|
|
|
makes Perl use the PATH environment variable to search for the
|
|
script (unless the name of the script contains directory separators).
|
|
On some platforms, this also makes Perl append suffixes to the
|
|
filename while searching for it. For example, on Win32 platforms,
|
|
the ".bat" and ".cmd" suffixes are appended if a lookup for the
|
|
original name fails, and if the name does not already end in one
|
|
of those suffixes. If your Perl was compiled with DEBUGGING turned
|
|
on, using the -Dp switch to Perl shows how the search progresses.
|
|
|
|
If the filename supplied contains directory separators (i.e. it is an
|
|
absolute or relative pathname), and if the 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 script 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
|
|
script will be searched for strictly on the PATH.
|
|
|
|
Typically this is used to emulate #! startup on platforms that
|
|
don't support #!. 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 script to /bin/sh,
|
|
which proceeds to try to execute the Perl script as a shell script.
|
|
The shell executes the second line as a normal shell command, and thus
|
|
starts up the Perl interpreter. On some systems $0 doesn't always
|
|
contain the full pathname, so the B<-S> tells Perl to search for the
|
|
script if necessary. After Perl locates the script, it parses the
|
|
lines and ignores them because the variable $running_under_some_shell
|
|
is never true. If the script will be interpreted by csh, you will need
|
|
to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
|
|
embedded spaces (and such) in the argument list. To start up sh rather
|
|
than csh, some systems may have to replace the #! line with a line
|
|
containing just a colon, which will be politely ignored by Perl. Other
|
|
systems can't control that, and need a totally devious construct that
|
|
will work under any of csh, sh, or Perl, such as the following:
|
|
|
|
eval '(exit $?0)' && eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
|
|
& eval 'exec /usr/bin/perl -wS $0 $argv:q'
|
|
if $running_under_some_shell;
|
|
|
|
=item B<-T>
|
|
|
|
forces "taint" checks to be turned on so you can test them. Ordinarily
|
|
these checks are done only when running setuid or setgid. It's a good
|
|
idea to turn them on explicitly for programs run on another's behalf,
|
|
such as CGI programs. See L<perlsec>. Note that (for security reasons)
|
|
this option must be seen by Perl quite early; usually this means it must
|
|
appear early on the command line or in the #! line (for systems which
|
|
support that).
|
|
|
|
=item B<-u>
|
|
|
|
causes Perl to dump core after compiling your script. You can then
|
|
in theory take this core dump and turn it into an executable file by using the
|
|
B<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 script before dumping,
|
|
use the dump() operator instead. Note: availability of B<undump> is
|
|
platform specific and may not be available for a specific port of
|
|
Perl. It has been superseded by the new perl-to-C compiler, which is more
|
|
portable, even though it's still only considered beta.
|
|
|
|
=item B<-U>
|
|
|
|
allows Perl to do unsafe operations. Currently the only "unsafe"
|
|
operations are the unlinking of directories while running as superuser,
|
|
and running setuid programs with fatal taint checks turned into
|
|
warnings. Note that the B<-w> switch (or the C<$^W> variable) must
|
|
be used along with this option to actually B<generate> the
|
|
taint-check warnings.
|
|
|
|
=item B<-v>
|
|
|
|
prints the version and patchlevel of your Perl executable.
|
|
|
|
=item B<-V>
|
|
|
|
prints summary of the major perl configuration values and the current
|
|
value of @INC.
|
|
|
|
=item B<-V:>I<name>
|
|
|
|
Prints to STDOUT the value of the named configuration variable.
|
|
|
|
=item B<-w>
|
|
|
|
prints warnings about variable names that are mentioned only once, and
|
|
scalar variables that are used before being set. Also warns about
|
|
redefined subroutines, and references to undefined filehandles or
|
|
filehandles opened read-only that you are attempting to write on. Also
|
|
warns you if you use values as a number that doesn't look like numbers,
|
|
using an array as though it were a scalar, if your subroutines recurse
|
|
more than 100 deep, and innumerable other things.
|
|
|
|
You can disable specific warnings using C<__WARN__> hooks, as described
|
|
in L<perlvar> and L<perlfunc/warn>. See also L<perldiag> and L<perltrap>.
|
|
|
|
=item B<-x> I<directory>
|
|
|
|
tells Perl that the script is embedded in a message. Leading
|
|
garbage will be discarded until the first line that starts with #! and
|
|
contains the string "perl". Any meaningful switches on that line will
|
|
be applied. If a directory name is specified, Perl will switch to
|
|
that directory before running the script. The B<-x> switch controls
|
|
only the disposal of leading garbage. The script must be
|
|
terminated with C<__END__> if there is trailing garbage to be ignored (the
|
|
script can process any or all of the trailing garbage via the DATA
|
|
filehandle if desired).
|
|
|
|
=back
|
|
|
|
=head1 ENVIRONMENT
|
|
|
|
=over 12
|
|
|
|
=item HOME
|
|
|
|
Used if chdir has no argument.
|
|
|
|
=item LOGDIR
|
|
|
|
Used if chdir has no argument and HOME is not set.
|
|
|
|
=item PATH
|
|
|
|
Used in executing subprocesses, and in finding the script if B<-S> is
|
|
used.
|
|
|
|
=item PERL5LIB
|
|
|
|
A colon-separated list of directories in which to look for Perl library
|
|
files before looking in the standard library and the current
|
|
directory. If PERL5LIB is not defined, PERLLIB is used. When running
|
|
taint checks (because the script was running setuid or setgid, or the
|
|
B<-T> switch was used), neither variable is used. The script should
|
|
instead say
|
|
|
|
use lib "/my/directory";
|
|
|
|
=item PERL5OPT
|
|
|
|
Command-line options (switches). Switches in this variable are taken
|
|
as if they were on every Perl command line. Only the B<-[DIMUdmw]>
|
|
switches are allowed. When running taint checks (because the script
|
|
was running setuid or setgid, or the B<-T> switch was used), this
|
|
variable is ignored. If PERL5OPT begins with B<-T>, tainting will be
|
|
enabled, and any subsequent options ignored.
|
|
|
|
=item PERLLIB
|
|
|
|
A colon-separated list of directories in which to look for Perl library
|
|
files before looking in the standard library and the current directory.
|
|
If PERL5LIB is defined, PERLLIB is not used.
|
|
|
|
=item PERL5DB
|
|
|
|
The command used to load the debugger code. The default is:
|
|
|
|
BEGIN { require 'perl5db.pl' }
|
|
|
|
=item PERL5SHELL (specific to WIN32 port)
|
|
|
|
May be set to an alternative shell that perl must use internally for
|
|
executing "backtick" commands or system(). Default is C<cmd.exe /x/c>
|
|
on WindowsNT and C<command.com /c> on Windows95. The value is considered
|
|
to be space delimited. Precede any character that needs to be protected
|
|
(like a space or backslash) with a backslash.
|
|
|
|
Note that Perl doesn't use COMSPEC for this purpose because
|
|
COMSPEC has a high degree of variability among users, leading to
|
|
portability concerns. Besides, perl can use a shell that may not be
|
|
fit for interactive use, and setting COMSPEC to such a shell may
|
|
interfere with the proper functioning of other programs (which usually
|
|
look in COMSPEC to find a shell fit for interactive use).
|
|
|
|
=item PERL_DEBUG_MSTATS
|
|
|
|
Relevant only if perl is compiled with the malloc included with the perl
|
|
distribution (that is, if C<perl -V:d_mymalloc> is 'define').
|
|
If set, this causes memory statistics to be dumped after execution. If set
|
|
to an integer greater than one, also causes memory statistics to be dumped
|
|
after compilation.
|
|
|
|
=item PERL_DESTRUCT_LEVEL
|
|
|
|
Relevant only if your perl executable was built with B<-DDEBUGGING>,
|
|
this controls the behavior of global destruction of objects and other
|
|
references.
|
|
|
|
=back
|
|
|
|
Perl also has environment variables that control how Perl handles data
|
|
specific to particular natural languages. See L<perllocale>.
|
|
|
|
Apart from these, Perl uses no other environment variables, except
|
|
to make them available to the script being executed, and to child
|
|
processes. However, scripts running setuid would do well to execute
|
|
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)};
|
|
|