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