=head1 SYNOPSIS
-B<perl> [switches] filename args
+B<perl> S<[ B<-CsTuUWX> ]>
+ 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
+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 2.
Contained in the file specified by the first filename on the command line.
-(Note that systems supporting the #! notation invoke interpreters this way.)
+(Note that systems supporting the #! notation invoke interpreters this
+way. See L<Location of Perl>.)
=item 3.
-Passed in implicitly via standard input. This only works if there are
-no filename arguments--to pass arguments to a STDIN script you
-must explicitly specify a "-" for the script name.
+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 #! and containing the word
-"perl", and starts there instead. This is useful for running a script
+"perl", and starts there instead. This is useful for running a program
embedded in a larger message. (In this case you would indicate the end
-of the script using the __END__ token.)
-
-As of Perl 5, the #! line is always examined for switches as the line is
-being parsed. Thus, if you're on a machine that only allows 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
+of the program using the C<__END__> token.)
+
+The #! line is always examined for switches as the line is being
+parsed. Thus, if you're on a machine that allows only one argument
+with the #! line, or worse, doesn't even recognize the #! line, you
+still can get consistent switch behavior regardless of how Perl was
+invoked, even if B<-x> was used to find the beginning of the program.
+
+Because historically some operating systems silently chopped off
+kernel interpretation of the #! line after 32 characters, some
+switches may be passed in on the command line, and some may not;
+you could even get a "-" without its letter, if you're not careful.
+You probably want to make sure that all your switches fall either
+before or after that 32-character boundary. Most switches don't
+actually care if they're processed redundantly, but getting a "-"
+instead of a complete switch could cause Perl to try to execute
+standard input instead of your program. And a partial B<-I> switch
could also cause odd results.
+Some switches do care if they are processed twice, for instance
+combinations of B<-l> and B<-0>. Either put all the switches after
+the 32-character boundary (if applicable), or replace the use of
+B<-0>I<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 perl $0 -S ${1+"$@"}'
- if 0;
+ eval 'exec perl -wS $0 ${1+"$@"}'
+ if $running_under_some_shell;
+
+to let Perl see the B<-p> switch.
+
+A similar trick involves the B<env> program, if you have it.
+
+ #!/usr/bin/env perl
-to let Perl see the B<-p> switch.
+The examples above use a relative path to the perl interpreter,
+getting whatever version is first in the user's path. If you want
+a specific version of Perl, say, perl5.005_57, you should place
+that directly in the #! line's path.
If the #! line does not contain the word "perl", the program named after
the #! is executed instead of the Perl interpreter. This is slightly
bizarre, but it helps people on machines that don't do #!, because they
-can tell a program that their SHELL is /usr/bin/perl, and Perl will then
+can tell a program that their SHELL is F</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
+After locating your program, Perl compiles the entire program to an
internal form. If there are any compilation errors, execution of the
-script is not attempted. (This is unlike the typical shell script,
-which might run partway through before finding a syntax error.)
+program is not attempted. (This is unlike the typical shell script,
+which might run part-way through before finding a syntax error.)
-If the script is syntactically correct, it is executed. If the script
+If the program is syntactically correct, it is executed. If the program
runs off the end without hitting an exit() or die() operator, an implicit
C<exit(0)> is provided to indicate successful completion.
-=head2 Switches
+=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 (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<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 ActiveState installer for Perl,
+will modify the Registry to associate the F<.pl> extension with the perl
+interpreter. If you install Perl by other means (including building from
+the sources), you may have to modify the Registry yourself. Note that
+this means you can no longer tell the difference between an executable
+Perl program and a Perl library file.
+
+=item Macintosh
+
+A Macintosh perl program 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 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 B<-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"""
-A single-character switch may be combined with the following switch, if
-any.
+The problem is that none of this is reliable: it depends on the
+command and it is entirely possible neither works. If B<4DOS> were
+the command shell, this would probably work better:
- #!/usr/bin/perl -spi.bak # same as -s -p -i.bak
+ 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.
+
+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 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
+
+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<digits>
+=item B<-0>[I<digits>]
-specifies the record separator (C<$/>) as an octal number. If there are
+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
+ find . -name '*.orig' -print0 | perl -n0e unlink
The special value 00 will cause Perl to slurp files in paragraph mode.
-The value 0777 will cause Perl to slurp files whole since there is no
+The value 0777 will cause Perl to slurp files whole because there is no
legal character with that value.
=item B<-a>
An alternate delimiter may be specified using B<-F>.
+=item B<-C>
+
+enables Perl to use the native wide character APIs on the target system.
+The magic variable C<${^WIDE_SYSTEM_CALLS}> reflects the state of
+this switch. See L<perlvar/"${^WIDE_SYSTEM_CALLS}">.
+
+This feature is currently only implemented on the Win32 platform.
+
=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,
-since these are considered as occurring outside the execution of
-your program.
+causes Perl to check the syntax of the program and then exit without
+executing it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and
+C<use> blocks, because these are considered as occurring outside the
+execution of your program. C<INIT> and C<END> blocks, however, will
+be skipped.
=item B<-d>
-runs the script under the Perl debugger. See L<perldebug>.
+runs the program under the Perl debugger. See L<perldebug>.
-=item B<-d:foo>
+=item B<-d:>I<foo[=bar,baz]>
-runs the script under the control of a debugging or tracing module
-installed as Devel::foo. E.g., -d:DProf executes the script using the
-Devel::DProf profiler. See L<perldebug>.
+runs the program under the control of a debugging, profiling, or
+tracing module installed as Devel::foo. E.g., B<-d:DProf> executes
+the program using the Devel::DProf profiler. As with the B<-M>
+flag, options may be passed to the Devel::foo package where they
+will be received and interpreted by the Devel::foo::import routine.
+The comma-separated list of options must follow a C<=> character.
+See L<perldebug>.
-=item B<-D>I<number>
+=item B<-D>I<letters>
-=item B<-D>I<list>
+=item B<-D>I<number>
-sets debugging flags. To watch how it executes your script, use
-B<-D14>. (This only works if debugging is compiled into your
-Perl.) Another nice value is B<-D1024>, which lists your compiled
-syntax tree. And B<-D512> displays compiled regular expressions. As an
-alternative specify a list of letters instead of numbers (e.g. B<-D14> is
+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. 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 Label Stack Processing
- 8 t Trace Execution
- 16 o Operator Node Construction
- 32 c String/Numeric Conversions
- 64 P Print Preprocessor Command for -P
- 128 m Memory Allocation
- 256 f Format Processing
- 512 r Regular Expression Parsing
- 1024 x Syntax Tree Dump
- 2048 u Tainting Checks
- 4096 L Memory Leaks (not supported anymore)
- 8192 H Hash Dump -- usurps values()
- 16384 X Scratchpad Allocation
- 32768 D Cleaning Up
+ 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 -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 B<-DDEBUGGING> when you compile the Perl
+executable. 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
+
+ # 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>
-may be used to enter one line of script.
-If B<-e> is given, Perl
-will not look for a script filename in the argument list.
-Multiple B<-e> commands may
-be given to build up a multi-line script.
-Make sure to use semicolons where you would in a normal program.
+may be used to enter one line of program. If B<-e> is given, Perl
+will not look for a filename in the argument list. Multiple B<-e>
+commands may be given to build up a multi-line script. Make sure
+to use semicolons where you would in a normal program.
+
+=item B<-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.
-=item B<-F>I<regexp>
+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:
-specifies a regular expression to split on if B<-a> is also in effect.
-If regexp has C<//> around it, the slashes will be ignored.
+ ($backup = $extension) =~ s/\*/$file_name/g;
-=item B<-i>I<extension>
+This allows you to add a prefix to the backup file, instead of (or in
+addition to) a suffix:
-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 added to the name
-of the old file to make a backup copy. If no extension is supplied, no
-backup is made. From the shell, saying
+ $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
- $ perl -p -i.bak -e "s/foo/bar/; ... "
+Or even to place backup copies of the original files into another
+directory (provided the directory already exists):
-is the same as using the script:
+ $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
- #!/usr/bin/perl -pi.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 '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+
+From the shell, saying
+
+ $ perl -p -i.orig -e "s/foo/bar/; ... "
+
+is the same as using the program:
+
+ #!/usr/bin/perl -pi.orig
s/foo/bar/;
which is equivalent to
#!/usr/bin/perl
- while (<>) {
+ $extension = '.orig';
+ LINE: while (<>) {
if ($ARGV ne $oldargv) {
- rename($ARGV, $ARGV . '.bak');
+ if ($extension !~ /\*/) {
+ $backup = $ARGV . $extension;
+ }
+ else {
+ ($backup = $extension) =~ s/\*/$ARGV/g;
+ }
+ rename($ARGV, $backup);
open(ARGVOUT, ">$ARGV");
select(ARGVOUT);
$oldargv = $ARGV;
except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
know when the filename has changed. It does, however, use ARGVOUT for
-the selected filehandle. Note that STDOUT is restored as the
-default output filehandle after the loop.
+the selected filehandle. Note that STDOUT is restored as the default
+output filehandle after the loop.
-You can use C<eof> without parenthesis to locate the end of each input file,
-in case you want to append to each file, or reset line numbering (see
-example in L<perlfunc/eof>).
+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...
+
+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>
-may be used in conjunction with B<-P> to tell the C preprocessor where
-to look for include files. By default /usr/include and /usr/lib/perl
-are searched.
+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>
+=item B<-l>[I<octnum>]
-enables automatic line-ending processing. It has two effects: first,
-it automatically chomps the line terminator when used with B<-n> or
-B<-p>, and second, it assigns "C<$\>" to have the value of I<octnum> so that
-any print statements will have that line terminator added back on. If
-I<octnum> is omitted, sets "C<$\>" to the current value of "C<$/>". For
-instance, to trim lines to 80 columns:
+enables automatic line-ending processing. It has two separate
+effects. First, it automatically chomps C<$/> (the input record
+separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
+(the output record separator) to have the value of I<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) = ""'
gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
-This sets $\ to newline and then sets $/ to the null character.
+This sets C<$\> to newline and then sets C<$/> to the null character.
-=item B<-M>I<module>
+=item B<-m>[B<->]I<module>
-executes C<use> I<module> C<;> before executing your script. You can
-also do C<-M'Foo qw(Bar Baz)'>.
+=item B<-M>[B<->]I<module>
-=item B<-m>I<module>
+=item B<-M>[B<->]I<'module ...'>
-executes C<use> I<module> C<();> before executing your script.
+=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<'-Mmodule qw(foo bar)'>.
+
+If the first character after the B<-M> or B<-m> is a dash (C<->)
+then the 'use' is replaced with 'no'.
+
+A little builtin syntactic sugar means you can also say
+B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for
+C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when
+importing symbols. The actual code generated by B<-Mmodule=foo,bar> is
+C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
+removes the distinction between B<-m> and B<-M>.
=item B<-n>
-causes Perl to assume the following loop around your script, which
+causes Perl to assume the following loop around your program, which
makes it iterate over filename arguments somewhat like B<sed -n> or
B<awk>:
+ LINE:
while (<>) {
- ... # your script goes here
+ ... # your program goes here
}
Note that the lines are not printed by default. See B<-p> to have
-lines printed. Here is an efficient way to delete all files older than
-a week:
+lines printed. If a file named by an argument cannot be opened for
+some reason, Perl warns you about it and moves on to the next file.
- find . -mtime +7 -print | perl -nle 'unlink;'
+Here is an efficient way to delete all files older than a week:
-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.
+ find . -mtime +7 -print | perl -nle unlink
+
+This is faster than using the B<-exec> switch of B<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
C<BEGIN> and C<END> blocks may be used to capture control before or after
-the implicit loop, just as in B<awk>.
+the implicit program loop, just as in B<awk>.
=item B<-p>
-causes Perl to assume the following loop around your script, which
+causes Perl to assume the following loop around your program, which
makes it iterate over filename arguments somewhat like B<sed>:
+ LINE:
while (<>) {
- ... # your script goes here
+ ... # your program goes here
} continue {
- print;
+ print or die "-p destination: $!\n";
}
-Note that the lines are printed automatically. To suppress printing
-use the B<-n> switch. A B<-p> overrides a B<-n> switch.
+If a file named by an argument cannot be opened for some reason, Perl
+warns you about it, and moves on to the next file. Note that the
+lines are printed automatically. An error occurring during printing is
+treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
+overrides a B<-n> switch.
C<BEGIN> and C<END> blocks may be used to capture control before or after
-the implicit loop, just as in awk.
+the implicit loop, just as in B<awk>.
=item B<-P>
-causes your script to be run through the C preprocessor before
-compilation by Perl. (Since both comments and cpp directives begin
+causes your program to be run through the C preprocessor before
+compilation by Perl. (Because both comments and B<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".)
+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
+enables rudimentary switch parsing for switches on the command
+line after the program 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.
+corresponding variable in the Perl program. The following program
+prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
+if it is invoked with B<-xyz=abc>.
#!/usr/bin/perl -s
- if ($xyz) { print "true\n"; }
+ if ($xyz) { print "$xyz\n" }
=item B<-S>
makes Perl use the PATH environment variable to search for the
-script (unless the name of the script starts with a slash). Typically
-this is used to emulate #! startup on machines that don't support #!,
-in the following manner:
+program (unless the name of the program contains directory separators).
+
+On some platforms, this also makes Perl append suffixes to the
+filename while searching for it. For example, on Win32 platforms,
+the ".bat" and ".cmd" suffixes are appended if a lookup for the
+original name fails, and if the name does not already end in one
+of those suffixes. If your Perl was compiled with DEBUGGING turned
+on, using the -Dp switch to Perl shows how the search progresses.
+
+Typically this is used to emulate #! startup on platforms that
+don't support #!. This example works on many platforms that
+have a shell compatible with Bourne shell:
#!/usr/bin/perl
- eval "exec /usr/bin/perl -S $0 $*"
+ eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
if $running_under_some_shell;
-The system ignores the first line and feeds the script to /bin/sh,
-which proceeds to try to execute the Perl script as a shell script.
+The system ignores the first line and feeds the program to F</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
-script if necessary. After Perl locates the script, it parses the
+program if necessary. After Perl locates the program, it parses the
lines and ignores them because the variable $running_under_some_shell
-is never true. A better construct than C<$*> would be C<${1+"$@"}>, which
-handles embedded spaces and such in the filenames, but doesn't work if
-the script is being interpreted by csh. In order to start up sh rather
+is never true. If the program will be interpreted by csh, you will need
+to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
+embedded spaces (and such) in the argument list. To start up sh rather
than csh, some systems may have to replace the #! line with a line
containing just a colon, which will be politely ignored by Perl. Other
systems can't control that, and need a totally devious construct that
-will work under any of csh, sh or Perl, such as the following:
+will work under any of B<csh>, B<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;
- eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
- & eval 'exec /usr/bin/perl -S $0 $argv:q'
- if 0;
+If the filename supplied contains directory separators (i.e., is an
+absolute or relative pathname), and if that file is not found,
+platforms that append file extensions will do so and try to look
+for the file with those extensions added, one by one.
+
+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>
-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>.
+forces "taint" checks to be turned on so you can test them. Ordinarily
+these checks are done only when running setuid or setgid. It's a
+good idea to turn them on explicitly for programs that run on behalf
+of someone else whom you might not necessarily trust, such as CGI
+programs or any internet servers you might write in Perl. See
+L<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 #! line for systems which support
+that construct.
=item B<-u>
-causes Perl to dump core after compiling your script. You can then
-take this core dump and turn it into an executable file by using the
-B<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.
+This obsolete switch causes Perl to dump core after compiling your
+program. You can then in theory take this core dump and turn it
+into an executable file by using the B<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 B<undump> is platform
+specific and may not be available for a specific port of Perl.
+
+This switch has been superseded in favor of the new Perl code
+generator backends to the compiler. See L<B> and L<B::Bytecode>
+for details.
=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.
+warnings. Note that the B<-w> switch (or the C<$^W> variable) must
+be used along with this option to actually I<generate> the
+taint-check warnings.
=item B<-v>
-prints the version and patchlevel of your Perl executable.
+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.
+values of @INC.
-=item B<-V:name>
+=item B<-V:>I<name>
Prints to STDOUT the value of the named configuration variable.
+For example,
+
+ $ perl -V:man.dir
+
+will provide strong clues about what your MANPATH variable should
+be set to in order to access the Perl documentation.
=item B<-w>
-prints warnings about identifiers 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 readonly 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.
-See L<perldiag> and L<perltrap>.
+prints warnings about dubious constructs, such as variable names
+that are mentioned only once and scalar variables that are used
+before being set, redefined subroutines, references to undefined
+filehandles or filehandles opened read-only that you are attempting
+to write on, values used as a number that 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.
+
+This switch really just enables the internal C<^$W> variable. You
+can disable or promote into fatal errors specific warnings using
+C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
+See also L<perldiag> and L<perltrap>. A new, 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>
+
+Enables all warnings regardless of C<no warnings> or C<$^W>.
+See L<perllexwarn>.
+
+=item B<-X>
+
+Disables all warnings regardless of C<use warnings> or C<$^W>.
+See L<perllexwarn>.
=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 (but only one group of switches, as with normal #!
-processing). If a directory name is specified, Perl will switch to
-that directory before running the script. The B<-x> switch only
-controls the the disposal of leading garbage. The script must be
-terminated with C<__END__> if there is trailing garbage to be ignored (the
-script can process any or all of the trailing garbage via the DATA
-filehandle if desired).
+tells Perl that the program is embedded in a larger chunk of unrelated
+ASCII text, such as in a mail message. Leading garbage will be
+discarded until the first line that starts with #! and contains the
+string "perl". Any meaningful switches on that line will be applied.
+If a directory name is specified, Perl will switch to that directory
+before running the program. The B<-x> switch controls only the
+disposal of leading garbage. The program must be terminated with
+C<__END__> if there is trailing garbage to be ignored (the program
+can process any or all of the trailing garbage via the DATA filehandle
+if desired).
+
+=back
+
+=head1 ENVIRONMENT
+
+=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 program 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. Any architecture-specific directories under the specified
+locations are automatically included if they exist. If PERL5LIB is not
+defined, PERLLIB is used.
+
+When running taint checks (either because the program was running setuid
+or setgid, or the B<-T> switch was used), neither variable is used.
+The program 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 program
+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 the 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-separated. Precede any character that needs to be protected
+(like a space or backslash) with a backslash.
+
+Note that Perl doesn't use COMSPEC for this purpose because
+COMSPEC has a high degree of variability among users, leading to
+portability concerns. Besides, perl can use a shell that may not be
+fit for interactive use, and setting COMSPEC to such a shell may
+interfere with the proper functioning of other programs (which usually
+look in COMSPEC to find a shell fit for interactive use).
+
+=item PERL_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.
+
+=item PERL_ROOT (specific to the VMS port)
+
+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 SYS$LOGIN (specific to the VMS port)
+
+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>.
+
+Apart from these, Perl uses no other environment variables, except
+to make them available to the program being executed, and to child
+processes. However, programs running setuid would do well to execute
+the following lines before doing anything else, just to keep people
+honest:
+
+ $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need
+ $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
+ delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};