=head1 NAME
perlrun - how to execute the Perl interpreter
=head1 SYNOPSIS
B S<[ B<-sTtuUWX> ]>
S<[ B<-hv> ] [ B<-V>[:I] ]>
S<[ B<-cw> ] [ B<-d>[B][:I] ] [ B<-D>[I] ]>
S<[ B<-pna> ] [ B<-F>I ] [ B<-l>[I] ] [ B<-0>[I] ]>
S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
S<[ B<-C [I] >]>
S<[ B<-P> ]>
S<[ B<-S> ]>
S<[ B<-x>[I] ]>
S<[ B<-i>[I] ]>
S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I ] [ I ]...>
=head1 DESCRIPTION
The normal way to run a Perl program is by making it directly
executable, or else by passing the name of the source file as an
argument on the command line. (An interactive Perl environment
is also possible--see L for details on how to do that.)
Upon startup, Perl looks for your program in one of the following
places:
=over 4
=item 1.
Specified line by line via B<-e> or B<-E> switches on the command line.
=item 2.
Contained in the file specified by the first filename on the command line.
(Note that systems supporting the #! notation invoke interpreters this
way. See L.)
=item 3.
Passed in implicitly via standard input. This works only if there are
no filename arguments--to pass arguments to a STDIN-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 program
embedded in a larger message. (In this case you would indicate the end
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 by C.
Parsing of the #! switches starts wherever "perl" is mentioned in the line.
The sequences "-*" and "- " are specifically ignored so that you could,
if you were so inclined, say
#!/bin/sh
#! -*-perl-*-
eval 'exec perl -x -wS $0 ${1+"$@"}'
if 0;
to let Perl see the B<-p> switch.
A similar trick involves the B program, if you have it.
#!/usr/bin/env perl
The examples above use a relative path to the perl interpreter,
getting whatever version is first in the user's path. If you want
a specific version of Perl, say, perl5.005_57, you should place
that directly in the #! line's path.
If the #! line does not contain the word "perl", the program named after
the #! is executed instead of the Perl interpreter. This is slightly
bizarre, but it helps people on machines that don't do #!, because they
can tell a program that their SHELL is F, and Perl will then
dispatch the program to the correct interpreter for them.
After locating your program, Perl compiles the entire program to an
internal form. If there are any compilation errors, execution of the
program is not attempted. (This is unlike the typical shell script,
which might run part-way through before finding a syntax error.)
If the program is syntactically correct, it is executed. If the program
runs off the end without hitting an exit() or die() operator, an implicit
C is provided to indicate successful completion.
=head2 #! and quoting on non-Unix systems
X X<#!>
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 (see the F 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
Under "Classic" MacOS, a perl program will have the appropriate Creator and
Type, so that double-clicking them will invoke the MacPerl application.
Under Mac OS X, clickable apps can be made from any C<#!> script using Wil
Sanchez' DropScript utility: http://www.wsanchez.net/software/ .
=item VMS
Put
$ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
$ exit++ + ++$status != 0 and $exit = $status = undef;
at the top of your program, where B<-mysw> are any command line switches you
want to pass to Perl. You can now invoke the program directly, by saying
C, or as a DCL procedure, by saying C<@program> (or implicitly
via F by just using the name of the program).
This incantation is a bit much to remember, but Perl will display it for
you if you say C.
=back
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 do on Unix or Plan 9 systems. You might also
have to change a single % to a %%.
For example:
# Unix
perl -e 'print "Hello world\n"'
# MS-DOS, etc.
perl -e "print \"Hello world\n\""
# 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 B<4DOS> were
the command shell, this would probably work better:
perl -e "print "Hello world\n""
B in Windows NT slipped a lot of standard Unix functionality in
when nobody was looking, but just try to find documentation for its
quoting rules.
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
X
It may seem obvious to say, but Perl is useful only when users can
easily find it. When possible, it's good for both F
and F to be symlinks to the actual binary. If
that can't be done, system administrators are strongly encouraged
to put (symlinks to) perl and its accompanying utilities into a
directory typically found along a user's PATH, or in some other
obvious and convenient place.
In this documentation, C<#!/usr/bin/perl> on the first line of the program
will stand in for whatever method works on your system. You are
advised to use a specific path if you care about a specific version.
#!/usr/local/bin/perl5.00554
or if you just want to be running at least version, place a statement
like this at the top of your program:
use 5.005_54;
=head2 Command Switches
X X
As with all standard commands, a single-character switch may be
clustered with the following switch, if any.
#!/usr/bin/perl -spi.orig # same as -s -p -i.orig
Switches include:
=over 5
=item B<-0>[I]
X<-0> X<$/>
specifies the input record separator (C<$/>) as an octal or
hexadecimal number. If there are no digits, the null character is the
separator. Other switches may precede or follow the digits. For
example, if you have a version of B which can print filenames
terminated by the null character, you can say this:
find . -name '*.orig' -print0 | perl -n0e unlink
The special value 00 will cause Perl to slurp files in paragraph mode.
The value 0777 will cause Perl to slurp files whole because there is no
legal byte with that value.
If you want to specify any Unicode character, use the hexadecimal
format: C<-0xHHH...>, where the C are valid hexadecimal digits.
(This means that you cannot use the C<-x> with a directory name that
consists of hexadecimal digits.)
=item B<-a>
X<-a> X
turns on autosplit mode when used with a B<-n> or B<-p>. An implicit
split command to the @F array is done as the first thing inside the
implicit while loop produced by the B<-n> or B<-p>.
perl -ane 'print pop(@F), "\n";'
is equivalent to
while (<>) {
@F = split(' ');
print pop(@F), "\n";
}
An alternate delimiter may be specified using B<-F>.
=item B<-C [I]>
X<-C>
The C<-C> flag controls some of the Perl Unicode features.
As of 5.8.1, the C<-C> can be followed either by a number or a list
of option letters. The letters, their numeric values, and effects
are as follows; listing the letters is equal to summing the numbers.
I 1 STDIN is assumed to be in UTF-8
O 2 STDOUT will be in UTF-8
E 4 STDERR will be in UTF-8
S 7 I + O + E
i 8 UTF-8 is the default PerlIO layer for input streams
o 16 UTF-8 is the default PerlIO layer for output streams
D 24 i + o
A 32 the @ARGV elements are expected to be strings encoded
in UTF-8
L 64 normally the "IOEioA" are unconditional,
the L makes them conditional on the locale environment
variables (the LC_ALL, LC_TYPE, and LANG, in the order
of decreasing precedence) -- if the variables indicate
UTF-8, then the selected "IOEioA" are in effect
a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching code in
debugging mode.
=for documenting_the_underdocumented
perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */"
=for todo
perltodo mentions Unicode in %ENV and filenames. I guess that these will be
options e and f (or F).
For example, C<-COE> and C<-C6> will both turn on UTF-8-ness on both
STDOUT and STDERR. Repeating letters is just redundant, not cumulative
nor toggling.
The C options mean that any subsequent open() (or similar I/O
operations) will have the C<:utf8> PerlIO layer implicitly applied
to them, in other words, UTF-8 is expected from any input stream,
and UTF-8 is produced to any output stream. This is just the default,
with explicit layers in open() and with binmode() one can manipulate
streams as usual.
C<-C> on its own (not followed by any number or option list), or the
empty string C<""> for the C environment variable, has the
same effect as C<-CSDL>. In other words, the standard I/O handles and
the default C layer are UTF-8-fied B only if the locale
environment variables indicate a UTF-8 locale. This behaviour follows
the I (and problematic) UTF-8 behaviour of Perl 5.8.0.
You can use C<-C0> (or C<"0"> for C) to explicitly
disable all the above Unicode features.
The read-only magic variable C<${^UNICODE}> reflects the numeric value
of this setting. This is variable is set during Perl startup and is
thereafter read-only. If you want runtime effects, use the three-arg
open() (see L), the two-arg binmode() (see L),
and the C pragma (see L).
(In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch
that enabled the use of Unicode-aware "wide system call" Win32 APIs.
This feature was practically unused, however, and the command line
switch was therefore "recycled".)
B Since perl 5.10.1, if the -C option is used on the #! line, it
must be specified on the command line as well, since the standard streams
are already set up at this point in the execution of the perl interpreter.
You can also use binmode() to set the encoding of an I/O stream.
=item B<-c>
X<-c>
causes Perl to check the syntax of the program and then exit without
executing it. Actually, it I execute C, C,
C, and C