|
perlrun - how to execute the Perl interpreter
| perl | [ -sTtuUWX ]
| | [ -hv ] [ -V[:configvar] ]
| | [ -cw ] [ -d[t][:debugger] ] [ -D[number/list] ]
| | [ -pna ] [ -Fpattern ] [ -l[octal] ] [ -0[octal/hexadecimal] ]
| | [ -Idir ] [ -m[-]module ] [ -M[-]'module...' ] [ -f ]
| | [ -C [number/list] ]
| | [ -P ]
| | [ -S ]
| | [ -x[dir] ]
| | [ -i[extension] ]
| | [ -eE 'command' ] [ -- ] [ programfile ] [ argument ]... |
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 the perldebug manpage for details on how to do that.)
Upon startup, Perl looks for your program in one of the following
places:
-
Specified line by line via -e or -E switches on the command line.
-
Contained in the file specified by the first filename on the command line.
(Note that systems supporting the #! notation invoke interpreters this
way. See Location of Perl.)
-
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.
With methods 2 and 3, Perl starts parsing the input file from the
beginning, unless you've specified a -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 __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 -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 -I switch
could also cause odd results.
Some switches do care if they are processed twice, for instance
combinations of -l and -0. Either put all the switches after
the 32-character boundary (if applicable), or replace the use of
-0digits by 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
eval 'exec perl -wS $0 ${1+"$@"}'
if $running_under_some_shell;
to let Perl see the -p switch.
A similar trick involves the env program, if you have it.
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
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
exit(0) is provided to indicate successful completion.
Unix's #! technique can be simulated on other systems:
- OS/2
-
Put
-
extproc perl -S -your_switches
-
as the first line in *.cmd file (-S due to a bug in cmd.exe's
`extproc' handling).
- MS-DOS
-
Create a batch file to run your program, and codify it in
ALTERNATE_SHEBANG (see the dosish.h file in the source
distribution for more information).
- Win95/NT
-
The Win95/NT installation, when using the ActiveState installer for Perl,
will modify the Registry to associate the .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.
- 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 #! script using Wil
Sanchez' DropScript utility: http://www.wsanchez.net/software/ .
- 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 -mysw are any command line switches you
want to pass to Perl. You can now invoke the program directly, by saying
perl program, or as a DCL procedure, by saying @program (or implicitly
via 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 perl "-V:startperl".
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 (*, \ and " are
common) and how to protect whitespace and these characters to run
one-liners (see -e below).
On some systems, you may have to change single-quotes to double ones,
which you must not do on Unix or Plan 9 systems. You might also
have to change a single % to a %%.
For example:
# Unix
perl -e 'print "Hello world\n"'
# MS-DOS, etc.
perl -e "print \"Hello world\n\""
# 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 were
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.
It may seem obvious to say, but Perl is useful only when users can
easily find it. When possible, it's good for both /usr/bin/perl
and /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, #!/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.
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;
As with all standard commands, a single-character switch may be
clustered with the following switch, if any.
Switches include:
- -0[octal/hexadecimal]
-
specifies the input record separator ($/) 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 find which can print filenames
terminated by the null character, you can say this:
-
find . -name '*.orig' -print0 | perl -n0e unlink
-
The special value 00 will cause Perl to slurp files in paragraph mode.
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: -0xHHH..., where the H are valid hexadecimal digits.
(This means that you cannot use the -x with a directory name that
consists of hexadecimal digits.)
- -a
-
turns on autosplit mode when used with a -n or -p. An implicit
split command to the @F array is done as the first thing inside the
implicit while loop produced by the -n or -p.
-
perl -ane 'print pop(@F), "\n";'
-
is equivalent to
-
while (<>) {
@F = split(' ');
print pop(@F), "\n";
}
-
An alternate delimiter may be specified using -F.
- -C [number/list]
-
The -C flag controls some of the Perl Unicode features.
-
As of 5.8.1, the -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 example, -COE and -C6 will both turn on UTF-8-ness on both
STDOUT and STDERR. Repeating letters is just redundant, not cumulative
nor toggling.
The io options mean that any subsequent open() (or similar I/O
operations) will have the :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 on its own (not followed by any number or option list), or the
empty string "" for the PERL_UNICODE environment variable, has the
same effect as -CSDL. In other words, the standard I/O handles and
the default open() layer are UTF-8-fied but only if the locale
environment variables indicate a UTF-8 locale. This behaviour follows
the implicit (and problematic) UTF-8 behaviour of Perl 5.8.0.
You can use -C0 (or "0" for PERL_UNICODE) to explicitly
disable all the above Unicode features.
The read-only magic variable ${^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 open in the perlfunc manpage), the two-arg binmode() (see binmode in the perlfunc manpage),
and the open pragma (see the open manpage).
(In Perls earlier than 5.8.1 the -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".)
- -c
-
causes Perl to check the syntax of the program and then exit without
executing it. Actually, it will execute BEGIN, UNITCHECK,
CHECK, and use blocks, because these are considered as occurring
outside the execution of your program. INIT and END blocks,
however, will be skipped.
- -d
- -dt
-
runs the program under the Perl debugger. See the perldebug manpage.
If t is specified, it indicates to the debugger that threads
will be used in the code being debugged.
- -d:foo[=bar,baz]
- -dt:foo[=bar,baz]
-
runs the program under the control of a debugging, profiling, or
tracing module installed as Devel::foo. E.g., -d:DProf executes
the program using the Devel::DProf profiler. As with the -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 = character.
If t is specified, it indicates to the debugger that threads
will be used in the code being debugged.
See the perldebug manpage.
- -Dletters
- -Dnumber
-
sets debugging flags. To watch how it executes your program, use
-Dtls. (This works only if debugging is compiled into your
Perl.) Another nice value is -Dx, which lists your compiled
syntax tree. And -Dr displays compiled regular expressions;
the format of the output is explained in the perldebguts manpage.
-
As an alternative, specify a number instead of list of letters (e.g.,
-D14 is equivalent to -Dtls):
-
1 p Tokenizing and parsing (with v, displays parse stack)
2 s Stack snapshots (with v, displays all stacks)
4 l Context (loop) stack processing
8 t Trace execution
16 o Method and overloading resolution
32 c String/numeric conversions
64 P Print profiling info, preprocessor command for -P, source file input state
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 U Unofficial, User hacking (reserved for private, unreleased use)
8192 H Hash dump -- usurps values()
16384 X Scratchpad allocation
32768 D Cleaning up
65536 S Thread synchronization
131072 T Tokenising
262144 R Include reference counts of dumped variables (eg when using -Ds)
524288 J Do not s,t,P-debug (Jump over) opcodes within package DB
1048576 v Verbose: use in conjunction with other flags
2097152 C Copy On Write
4194304 A Consistency checks on internal structures
8388608 q quiet - currently only suppresses the "EXECUTING" message
-
All these flags require -DDEBUGGING when you compile the Perl
executable (but see the Devel::Peek manpage, the re manpage which may change this).
See the INSTALL file in the Perl source distribution
for how to do this. This flag is automatically set if you include -g
option when 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 sh -x provides for shell scripts,
you can't use Perl's -D switch. Instead do this
-
# If you have "env" utility
env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
-
# Bourne shell syntax
$ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
-
% (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
-
See the perldebug manpage for details and variations.
- -e<
|
