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