This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Updates to perlfunc.pod
[perl5.git] / pod / perlrun.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlrun - how to execute the Perl interpreter
4
5=head1 SYNOPSIS
6
e0ebc809
PP
7B<perl> S<[ B<-sTuU> ]>
8 S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
9 S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
10 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
11 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
12 S<[ B<-P> ]>
13 S<[ B<-S> ]>
14 S<[ B<-x>[I<dir>] ]>
15 S<[ B<-i>[I<extension>] ]>
16 S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
a0d0e21e
LW
17
18=head1 DESCRIPTION
19
20Upon startup, Perl looks for your script in one of the following
21places:
22
23=over 4
24
25=item 1.
26
27Specified line by line via B<-e> switches on the command line.
28
29=item 2.
30
31Contained in the file specified by the first filename on the command line.
32(Note that systems supporting the #! notation invoke interpreters this way.)
33
34=item 3.
35
5f05dabc 36Passed in implicitly via standard input. This works only if there are
a0d0e21e
LW
37no filename arguments--to pass arguments to a STDIN script you
38must explicitly specify a "-" for the script name.
39
40=back
41
42With methods 2 and 3, Perl starts parsing the input file from the
43beginning, unless you've specified a B<-x> switch, in which case it
44scans for the first line starting with #! and containing the word
45"perl", and starts there instead. This is useful for running a script
46embedded in a larger message. (In this case you would indicate the end
47of the script using the __END__ token.)
48
5f05dabc
PP
49The #! line is always examined for switches as the line is being
50parsed. Thus, if you're on a machine that allows only one argument
51with the #! line, or worse, doesn't even recognize the #! line, you
52still can get consistent switch behavior regardless of how Perl was
53invoked, even if B<-x> was used to find the beginning of the script.
a0d0e21e
LW
54
55Because many operating systems silently chop off kernel interpretation of
56the #! line after 32 characters, some switches may be passed in on the
57command line, and some may not; you could even get a "-" without its
58letter, if you're not careful. You probably want to make sure that all
59your switches fall either before or after that 32 character boundary.
60Most switches don't actually care if they're processed redundantly, but
61getting a - instead of a complete switch could cause Perl to try to
62execute standard input instead of your script. And a partial B<-I> switch
63could also cause odd results.
64
65Parsing of the #! switches starts wherever "perl" is mentioned in the line.
66The sequences "-*" and "- " are specifically ignored so that you could,
67if you were so inclined, say
68
69 #!/bin/sh -- # -*- perl -*- -p
5f05dabc
PP
70 eval 'exec /usr/bin/perl $0 -S ${1+"$@"}'
71 if $running_under_some_shell;
a0d0e21e
LW
72
73to let Perl see the B<-p> switch.
74
75If the #! line does not contain the word "perl", the program named after
76the #! is executed instead of the Perl interpreter. This is slightly
77bizarre, but it helps people on machines that don't do #!, because they
78can tell a program that their SHELL is /usr/bin/perl, and Perl will then
79dispatch the program to the correct interpreter for them.
80
81After locating your script, Perl compiles the entire script to an
82internal form. If there are any compilation errors, execution of the
83script is not attempted. (This is unlike the typical shell script,
84which might run partway through before finding a syntax error.)
85
86If the script is syntactically correct, it is executed. If the script
87runs off the end without hitting an exit() or die() operator, an implicit
88C<exit(0)> is provided to indicate successful completion.
89
90=head2 Switches
91
92A single-character switch may be combined with the following switch, if
93any.
94
95 #!/usr/bin/perl -spi.bak # same as -s -p -i.bak
96
97Switches include:
98
99=over 5
100
e0ebc809 101=item B<-0>[I<digits>]
a0d0e21e 102
55497cff 103specifies the input record separator (C<$/>) as an octal number. If there are
a0d0e21e
LW
104no digits, the null character is the separator. Other switches may
105precede or follow the digits. For example, if you have a version of
106B<find> which can print filenames terminated by the null character, you
107can say this:
108
109 find . -name '*.bak' -print0 | perl -n0e unlink
110
111The special value 00 will cause Perl to slurp files in paragraph mode.
5f05dabc 112The value 0777 will cause Perl to slurp files whole because there is no
a0d0e21e
LW
113legal character with that value.
114
115=item B<-a>
116
117turns on autosplit mode when used with a B<-n> or B<-p>. An implicit
118split command to the @F array is done as the first thing inside the
119implicit while loop produced by the B<-n> or B<-p>.
120
121 perl -ane 'print pop(@F), "\n";'
122
123is equivalent to
124
125 while (<>) {
126 @F = split(' ');
127 print pop(@F), "\n";
128 }
129
130An alternate delimiter may be specified using B<-F>.
131
132=item B<-c>
133
134causes Perl to check the syntax of the script and then exit without
cb1a09d0 135executing it. Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks,
5f05dabc 136because these are considered as occurring outside the execution of
cb1a09d0 137your program.
a0d0e21e
LW
138
139=item B<-d>
140
141runs the script under the Perl debugger. See L<perldebug>.
142
e0ebc809 143=item B<-d:>I<foo>
3c81428c
PP
144
145runs the script under the control of a debugging or tracing module
a77489aa 146installed as Devel::foo. E.g., B<-d:DProf> executes the script using the
3c81428c
PP
147Devel::DProf profiler. See L<perldebug>.
148
a0d0e21e
LW
149=item B<-D>I<number>
150
151=item B<-D>I<list>
152
153sets debugging flags. To watch how it executes your script, use
5f05dabc 154B<-D14>. (This works only if debugging is compiled into your
a0d0e21e
LW
155Perl.) Another nice value is B<-D1024>, which lists your compiled
156syntax tree. And B<-D512> displays compiled regular expressions. As an
5f05dabc 157alternative specify a list of letters instead of numbers (e.g., B<-D14> is
a0d0e21e
LW
158equivalent to B<-Dtls>):
159
160 1 p Tokenizing and Parsing
161 2 s Stack Snapshots
162 4 l Label Stack Processing
163 8 t Trace Execution
164 16 o Operator Node Construction
165 32 c String/Numeric Conversions
166 64 P Print Preprocessor Command for -P
167 128 m Memory Allocation
168 256 f Format Processing
169 512 r Regular Expression Parsing
170 1024 x Syntax Tree Dump
171 2048 u Tainting Checks
172 4096 L Memory Leaks (not supported anymore)
173 8192 H Hash Dump -- usurps values()
174 16384 X Scratchpad Allocation
175 32768 D Cleaning Up
176
177=item B<-e> I<commandline>
178
179may be used to enter one line of script.
180If B<-e> is given, Perl
181will not look for a script filename in the argument list.
182Multiple B<-e> commands may
183be given to build up a multi-line script.
184Make sure to use semicolons where you would in a normal program.
185
e0ebc809 186=item B<-F>I<pattern>
a0d0e21e 187
e0ebc809 188specifies the pattern to split on if B<-a> is also in effect. The
5f05dabc 189pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
e0ebc809 190put in single quotes.
a0d0e21e 191
e0ebc809
PP
192=item B<-h>
193
194prints a summary of the options.
195
196=item B<-i>[I<extension>]
a0d0e21e
LW
197
198specifies that files processed by the C<E<lt>E<gt>> construct are to be edited
199in-place. It does this by renaming the input file, opening the output
200file by the original name, and selecting that output file as the default
201for print() statements. The extension, if supplied, is added to the name
202of the old file to make a backup copy. If no extension is supplied, no
203backup is made. From the shell, saying
204
205 $ perl -p -i.bak -e "s/foo/bar/; ... "
206
207is the same as using the script:
208
209 #!/usr/bin/perl -pi.bak
210 s/foo/bar/;
211
212which is equivalent to
213
214 #!/usr/bin/perl
215 while (<>) {
216 if ($ARGV ne $oldargv) {
217 rename($ARGV, $ARGV . '.bak');
218 open(ARGVOUT, ">$ARGV");
219 select(ARGVOUT);
220 $oldargv = $ARGV;
221 }
222 s/foo/bar/;
223 }
224 continue {
225 print; # this prints to original filename
226 }
227 select(STDOUT);
228
229except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
230know when the filename has changed. It does, however, use ARGVOUT for
231the selected filehandle. Note that STDOUT is restored as the
232default output filehandle after the loop.
233
234You can use C<eof> without parenthesis to locate the end of each input file,
235in case you want to append to each file, or reset line numbering (see
236example in L<perlfunc/eof>).
237
238=item B<-I>I<directory>
239
e0ebc809 240Directories specified by B<-I> are prepended to the search path for
1fef88e7 241modules (C<@INC>), and also tells the C preprocessor where to search for
e0ebc809
PP
242include files. The C preprocessor is invoked with B<-P>; by default it
243searches /usr/include and /usr/lib/perl.
a0d0e21e 244
e0ebc809 245=item B<-l>[I<octnum>]
a0d0e21e
LW
246
247enables automatic line-ending processing. It has two effects: first,
55497cff
PP
248it automatically chomps "C<$/>" (the input record separator) when used
249with B<-n> or B<-p>, and second, it assigns "C<$\>"
250(the output record separator) to have the value of I<octnum> so that
251any print statements will have that separator added back on. If
a0d0e21e
LW
252I<octnum> is omitted, sets "C<$\>" to the current value of "C<$/>". For
253instance, to trim lines to 80 columns:
254
255 perl -lpe 'substr($_, 80) = ""'
256
257Note that the assignment C<$\ = $/> is done when the switch is processed,
258so the input record separator can be different than the output record
259separator if the B<-l> switch is followed by a B<-0> switch:
260
261 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
262
1fef88e7 263This sets C<$\> to newline and then sets C<$/> to the null character.
a0d0e21e 264
e0ebc809
PP
265=item B<-m>[B<->]I<module>
266
267=item B<-M>[B<->]I<module>
c07a80fd 268
e0ebc809
PP
269=item B<-M>[B<->]I<'module ...'>
270
271=item B<-[mM]>[B<->]I<module=arg[,arg]...>
3c81428c 272
c07a80fd
PP
273C<-m>I<module> executes C<use> I<module> C<();> before executing your
274script.
3c81428c 275
c07a80fd
PP
276C<-M>I<module> executes C<use> I<module> C<;> before executing your
277script. You can use quotes to add extra code after the module name,
278e.g., C<-M'module qw(foo bar)'>.
3c81428c 279
a5f75d66
AD
280If the first character after the C<-M> or C<-m> is a dash (C<->)
281then the 'use' is replaced with 'no'.
282
c07a80fd 283A little built-in syntactic sugar means you can also say
e0ebc809
PP
284C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for
285C<-M'module qw(foo bar)'>. This avoids the need to use quotes when
286importing symbols. The actual code generated by C<-Mmodule=foo,bar> is
287C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
a77489aa 288removes the distinction between C<-m> and C<-M>.
3c81428c 289
a0d0e21e
LW
290=item B<-n>
291
292causes Perl to assume the following loop around your script, which
293makes it iterate over filename arguments somewhat like B<sed -n> or
294B<awk>:
295
296 while (<>) {
297 ... # your script goes here
298 }
299
300Note that the lines are not printed by default. See B<-p> to have
301lines printed. Here is an efficient way to delete all files older than
302a week:
303
304 find . -mtime +7 -print | perl -nle 'unlink;'
305
306This is faster than using the C<-exec> switch of B<find> because you don't
307have to start a process on every filename found.
308
309C<BEGIN> and C<END> blocks may be used to capture control before or after
310the implicit loop, just as in B<awk>.
311
312=item B<-p>
313
314causes Perl to assume the following loop around your script, which
315makes it iterate over filename arguments somewhat like B<sed>:
316
317
318 while (<>) {
319 ... # your script goes here
320 } continue {
321 print;
322 }
323
324Note that the lines are printed automatically. To suppress printing
325use the B<-n> switch. A B<-p> overrides a B<-n> switch.
326
327C<BEGIN> and C<END> blocks may be used to capture control before or after
328the implicit loop, just as in awk.
329
330=item B<-P>
331
332causes your script to be run through the C preprocessor before
5f05dabc 333compilation by Perl. (Because both comments and cpp directives begin
a0d0e21e 334with the # character, you should avoid starting comments with any words
5f05dabc 335recognized by the C preprocessor such as "if", "else", or "define".)
a0d0e21e
LW
336
337=item B<-s>
338
339enables some rudimentary switch parsing for switches on the command
340line after the script name but before any filename arguments (or before
341a B<-->). Any switch found there is removed from @ARGV and sets the
342corresponding variable in the Perl script. The following script
343prints "true" if and only if the script is invoked with a B<-xyz> switch.
344
345 #!/usr/bin/perl -s
346 if ($xyz) { print "true\n"; }
347
348=item B<-S>
349
350makes Perl use the PATH environment variable to search for the
351script (unless the name of the script starts with a slash). Typically
352this is used to emulate #! startup on machines that don't support #!,
353in the following manner:
354
355 #!/usr/bin/perl
5f05dabc 356 eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
a0d0e21e
LW
357 if $running_under_some_shell;
358
359The system ignores the first line and feeds the script to /bin/sh,
360which proceeds to try to execute the Perl script as a shell script.
361The shell executes the second line as a normal shell command, and thus
362starts up the Perl interpreter. On some systems $0 doesn't always
363contain the full pathname, so the B<-S> tells Perl to search for the
364script if necessary. After Perl locates the script, it parses the
365lines and ignores them because the variable $running_under_some_shell
366is never true. A better construct than C<$*> would be C<${1+"$@"}>, which
367handles embedded spaces and such in the filenames, but doesn't work if
5f05dabc 368the script is being interpreted by csh. To start up sh rather
a0d0e21e
LW
369than csh, some systems may have to replace the #! line with a line
370containing just a colon, which will be politely ignored by Perl. Other
371systems can't control that, and need a totally devious construct that
5f05dabc 372will work under any of csh, sh, or Perl, such as the following:
a0d0e21e
LW
373
374 eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
375 & eval 'exec /usr/bin/perl -S $0 $argv:q'
5f05dabc 376 if $running_under_some_shell;
a0d0e21e
LW
377
378=item B<-T>
379
cb1a09d0
AD
380forces "taint" checks to be turned on so you can test them. Ordinarily these checks are
381done only when running setuid or setgid. It's a good idea to turn
382them on explicitly for programs run on another's behalf, such as CGI
383programs. See L<perlsec>.
a0d0e21e
LW
384
385=item B<-u>
386
387causes Perl to dump core after compiling your script. You can then
388take this core dump and turn it into an executable file by using the
389B<undump> program (not supplied). This speeds startup at the expense of
390some disk space (which you can minimize by stripping the executable).
391(Still, a "hello world" executable comes out to about 200K on my
392machine.) If you want to execute a portion of your script before dumping,
393use the dump() operator instead. Note: availability of B<undump> is
394platform specific and may not be available for a specific port of
395Perl.
396
397=item B<-U>
398
399allows Perl to do unsafe operations. Currently the only "unsafe"
400operations are the unlinking of directories while running as superuser,
401and running setuid programs with fatal taint checks turned into
402warnings.
403
404=item B<-v>
405
406prints the version and patchlevel of your Perl executable.
407
3c81428c
PP
408=item B<-V>
409
410prints summary of the major perl configuration values and the current
411value of @INC.
412
e0ebc809 413=item B<-V:>I<name>
3c81428c
PP
414
415Prints to STDOUT the value of the named configuration variable.
416
a0d0e21e
LW
417=item B<-w>
418
049cd8b0 419prints warnings about variable names that are mentioned only once, and
a0d0e21e
LW
420scalar variables that are used before being set. Also warns about
421redefined subroutines, and references to undefined filehandles or
5f05dabc 422filehandles opened read-only that you are attempting to write on. Also
774d564b
PP
423warns you if you use values as a number that doesn't look like numbers,
424using an array as though it were a scalar, if your subroutines recurse
425more than 100 deep, and innumerable other things.
426
427You can disable specific warnings using C<__WARN__> hooks, as described
428in L<perlvar> and L<perlfunc/warn>. See also L<perldiag> and L<perltrap>.
a0d0e21e
LW
429
430=item B<-x> I<directory>
431
432tells Perl that the script is embedded in a message. Leading
433garbage will be discarded until the first line that starts with #! and
434contains the string "perl". Any meaningful switches on that line will
ff0cee69 435be applied. If a directory name is specified, Perl will switch to
5f05dabc
PP
436that directory before running the script. The B<-x> switch controls
437only the disposal of leading garbage. The script must be
a0d0e21e
LW
438terminated with C<__END__> if there is trailing garbage to be ignored (the
439script can process any or all of the trailing garbage via the DATA
440filehandle if desired).
441
442
443=back