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