1 | =head1 NAME |
---|
2 | |
---|
3 | perlrun - how to execute the Perl interpreter |
---|
4 | |
---|
5 | =head1 SYNOPSIS |
---|
6 | |
---|
7 | B<perl> S<[ B<-CsTuUWX> ]> |
---|
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> ]...> |
---|
17 | |
---|
18 | =head1 DESCRIPTION |
---|
19 | |
---|
20 | The normal way to run a Perl program is by making it directly |
---|
21 | executable, or else by passing the name of the source file as an |
---|
22 | argument on the command line. (An interactive Perl environment |
---|
23 | is also possible--see L<perldebug> for details on how to do that.) |
---|
24 | Upon startup, Perl looks for your program in one of the following |
---|
25 | places: |
---|
26 | |
---|
27 | =over 4 |
---|
28 | |
---|
29 | =item 1. |
---|
30 | |
---|
31 | Specified line by line via B<-e> switches on the command line. |
---|
32 | |
---|
33 | =item 2. |
---|
34 | |
---|
35 | Contained in the file specified by the first filename on the command line. |
---|
36 | (Note that systems supporting the #! notation invoke interpreters this |
---|
37 | way. See L<Location of Perl>.) |
---|
38 | |
---|
39 | =item 3. |
---|
40 | |
---|
41 | Passed in implicitly via standard input. This works only if there are |
---|
42 | no filename arguments--to pass arguments to a STDIN-read program you |
---|
43 | must explicitly specify a "-" for the program name. |
---|
44 | |
---|
45 | =back |
---|
46 | |
---|
47 | With methods 2 and 3, Perl starts parsing the input file from the |
---|
48 | beginning, unless you've specified a B<-x> switch, in which case it |
---|
49 | scans for the first line starting with #! and containing the word |
---|
50 | "perl", and starts there instead. This is useful for running a program |
---|
51 | embedded in a larger message. (In this case you would indicate the end |
---|
52 | of the program using the C<__END__> token.) |
---|
53 | |
---|
54 | The #! line is always examined for switches as the line is being |
---|
55 | parsed. Thus, if you're on a machine that allows only one argument |
---|
56 | with the #! line, or worse, doesn't even recognize the #! line, you |
---|
57 | still can get consistent switch behavior regardless of how Perl was |
---|
58 | invoked, even if B<-x> was used to find the beginning of the program. |
---|
59 | |
---|
60 | Because historically some operating systems silently chopped off |
---|
61 | kernel interpretation of the #! line after 32 characters, some |
---|
62 | switches may be passed in on the command line, and some may not; |
---|
63 | you could even get a "-" without its letter, if you're not careful. |
---|
64 | You probably want to make sure that all your switches fall either |
---|
65 | before or after that 32-character boundary. Most switches don't |
---|
66 | actually care if they're processed redundantly, but getting a "-" |
---|
67 | instead of a complete switch could cause Perl to try to execute |
---|
68 | standard input instead of your program. And a partial B<-I> switch |
---|
69 | could also cause odd results. |
---|
70 | |
---|
71 | Some switches do care if they are processed twice, for instance |
---|
72 | combinations of B<-l> and B<-0>. Either put all the switches after |
---|
73 | the 32-character boundary (if applicable), or replace the use of |
---|
74 | B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>. |
---|
75 | |
---|
76 | Parsing of the #! switches starts wherever "perl" is mentioned in the line. |
---|
77 | The sequences "-*" and "- " are specifically ignored so that you could, |
---|
78 | if you were so inclined, say |
---|
79 | |
---|
80 | #!/bin/sh -- # -*- perl -*- -p |
---|
81 | eval 'exec perl -wS $0 ${1+"$@"}' |
---|
82 | if $running_under_some_shell; |
---|
83 | |
---|
84 | to let Perl see the B<-p> switch. |
---|
85 | |
---|
86 | A similar trick involves the B<env> program, if you have it. |
---|
87 | |
---|
88 | #!/usr/bin/env perl |
---|
89 | |
---|
90 | The examples above use a relative path to the perl interpreter, |
---|
91 | getting whatever version is first in the user's path. If you want |
---|
92 | a specific version of Perl, say, perl5.005_57, you should place |
---|
93 | that directly in the #! line's path. |
---|
94 | |
---|
95 | If the #! line does not contain the word "perl", the program named after |
---|
96 | the #! is executed instead of the Perl interpreter. This is slightly |
---|
97 | bizarre, but it helps people on machines that don't do #!, because they |
---|
98 | can tell a program that their SHELL is F</usr/bin/perl>, and Perl will then |
---|
99 | dispatch the program to the correct interpreter for them. |
---|
100 | |
---|
101 | After locating your program, Perl compiles the entire program to an |
---|
102 | internal form. If there are any compilation errors, execution of the |
---|
103 | program is not attempted. (This is unlike the typical shell script, |
---|
104 | which might run part-way through before finding a syntax error.) |
---|
105 | |
---|
106 | If the program is syntactically correct, it is executed. If the program |
---|
107 | runs off the end without hitting an exit() or die() operator, an implicit |
---|
108 | C<exit(0)> is provided to indicate successful completion. |
---|
109 | |
---|
110 | =head2 #! and quoting on non-Unix systems |
---|
111 | |
---|
112 | Unix's #! technique can be simulated on other systems: |
---|
113 | |
---|
114 | =over 4 |
---|
115 | |
---|
116 | =item OS/2 |
---|
117 | |
---|
118 | Put |
---|
119 | |
---|
120 | extproc perl -S -your_switches |
---|
121 | |
---|
122 | as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's |
---|
123 | `extproc' handling). |
---|
124 | |
---|
125 | =item MS-DOS |
---|
126 | |
---|
127 | Create a batch file to run your program, and codify it in |
---|
128 | C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source |
---|
129 | distribution for more information). |
---|
130 | |
---|
131 | =item Win95/NT |
---|
132 | |
---|
133 | The Win95/NT installation, when using the ActiveState installer for Perl, |
---|
134 | will modify the Registry to associate the F<.pl> extension with the perl |
---|
135 | interpreter. If you install Perl by other means (including building from |
---|
136 | the sources), you may have to modify the Registry yourself. Note that |
---|
137 | this means you can no longer tell the difference between an executable |
---|
138 | Perl program and a Perl library file. |
---|
139 | |
---|
140 | =item Macintosh |
---|
141 | |
---|
142 | A Macintosh perl program will have the appropriate Creator and |
---|
143 | Type, so that double-clicking them will invoke the perl application. |
---|
144 | |
---|
145 | =item VMS |
---|
146 | |
---|
147 | Put |
---|
148 | |
---|
149 | $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' ! |
---|
150 | $ exit++ + ++$status != 0 and $exit = $status = undef; |
---|
151 | |
---|
152 | at the top of your program, where B<-mysw> are any command line switches you |
---|
153 | want to pass to Perl. You can now invoke the program directly, by saying |
---|
154 | C<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly |
---|
155 | via F<DCL$PATH> by just using the name of the program). |
---|
156 | |
---|
157 | This incantation is a bit much to remember, but Perl will display it for |
---|
158 | you if you say C<perl "-V:startperl">. |
---|
159 | |
---|
160 | =back |
---|
161 | |
---|
162 | Command-interpreters on non-Unix systems have rather different ideas |
---|
163 | on quoting than Unix shells. You'll need to learn the special |
---|
164 | characters in your command-interpreter (C<*>, C<\> and C<"> are |
---|
165 | common) and how to protect whitespace and these characters to run |
---|
166 | one-liners (see B<-e> below). |
---|
167 | |
---|
168 | On some systems, you may have to change single-quotes to double ones, |
---|
169 | which you must I<not> do on Unix or Plan9 systems. You might also |
---|
170 | have to change a single % to a %%. |
---|
171 | |
---|
172 | For example: |
---|
173 | |
---|
174 | # Unix |
---|
175 | perl -e 'print "Hello world\n"' |
---|
176 | |
---|
177 | # MS-DOS, etc. |
---|
178 | perl -e "print \"Hello world\n\"" |
---|
179 | |
---|
180 | # Macintosh |
---|
181 | print "Hello world\n" |
---|
182 | (then Run "Myscript" or Shift-Command-R) |
---|
183 | |
---|
184 | # VMS |
---|
185 | perl -e "print ""Hello world\n""" |
---|
186 | |
---|
187 | The problem is that none of this is reliable: it depends on the |
---|
188 | command and it is entirely possible neither works. If B<4DOS> were |
---|
189 | the command shell, this would probably work better: |
---|
190 | |
---|
191 | perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" |
---|
192 | |
---|
193 | B<CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in |
---|
194 | when nobody was looking, but just try to find documentation for its |
---|
195 | quoting rules. |
---|
196 | |
---|
197 | Under the Macintosh, it depends which environment you are using. The MacPerl |
---|
198 | shell, or MPW, is much like Unix shells in its support for several |
---|
199 | quoting variants, except that it makes free use of the Macintosh's non-ASCII |
---|
200 | characters as control characters. |
---|
201 | |
---|
202 | There is no general solution to all of this. It's just a mess. |
---|
203 | |
---|
204 | =head2 Location of Perl |
---|
205 | |
---|
206 | It may seem obvious to say, but Perl is useful only when users can |
---|
207 | easily find it. When possible, it's good for both F</usr/bin/perl> |
---|
208 | and F</usr/local/bin/perl> to be symlinks to the actual binary. If |
---|
209 | that can't be done, system administrators are strongly encouraged |
---|
210 | to put (symlinks to) perl and its accompanying utilities into a |
---|
211 | directory typically found along a user's PATH, or in some other |
---|
212 | obvious and convenient place. |
---|
213 | |
---|
214 | In this documentation, C<#!/usr/bin/perl> on the first line of the program |
---|
215 | will stand in for whatever method works on your system. You are |
---|
216 | advised to use a specific path if you care about a specific version. |
---|
217 | |
---|
218 | #!/usr/local/bin/perl5.00554 |
---|
219 | |
---|
220 | or if you just want to be running at least version, place a statement |
---|
221 | like this at the top of your program: |
---|
222 | |
---|
223 | use 5.005_54; |
---|
224 | |
---|
225 | =head2 Command Switches |
---|
226 | |
---|
227 | As with all standard commands, a single-character switch may be |
---|
228 | clustered with the following switch, if any. |
---|
229 | |
---|
230 | #!/usr/bin/perl -spi.orig # same as -s -p -i.orig |
---|
231 | |
---|
232 | Switches include: |
---|
233 | |
---|
234 | =over 5 |
---|
235 | |
---|
236 | =item B<-0>[I<digits>] |
---|
237 | |
---|
238 | specifies the input record separator (C<$/>) as an octal number. If there are |
---|
239 | no digits, the null character is the separator. Other switches may |
---|
240 | precede or follow the digits. For example, if you have a version of |
---|
241 | B<find> which can print filenames terminated by the null character, you |
---|
242 | can say this: |
---|
243 | |
---|
244 | find . -name '*.orig' -print0 | perl -n0e unlink |
---|
245 | |
---|
246 | The special value 00 will cause Perl to slurp files in paragraph mode. |
---|
247 | The value 0777 will cause Perl to slurp files whole because there is no |
---|
248 | legal character with that value. |
---|
249 | |
---|
250 | =item B<-a> |
---|
251 | |
---|
252 | turns on autosplit mode when used with a B<-n> or B<-p>. An implicit |
---|
253 | split command to the @F array is done as the first thing inside the |
---|
254 | implicit while loop produced by the B<-n> or B<-p>. |
---|
255 | |
---|
256 | perl -ane 'print pop(@F), "\n";' |
---|
257 | |
---|
258 | is equivalent to |
---|
259 | |
---|
260 | while (<>) { |
---|
261 | @F = split(' '); |
---|
262 | print pop(@F), "\n"; |
---|
263 | } |
---|
264 | |
---|
265 | An alternate delimiter may be specified using B<-F>. |
---|
266 | |
---|
267 | =item B<-C> |
---|
268 | |
---|
269 | enables Perl to use the native wide character APIs on the target system. |
---|
270 | The magic variable C<${^WIDE_SYSTEM_CALLS}> reflects the state of |
---|
271 | this switch. See L<perlvar/"${^WIDE_SYSTEM_CALLS}">. |
---|
272 | |
---|
273 | This feature is currently only implemented on the Win32 platform. |
---|
274 | |
---|
275 | =item B<-c> |
---|
276 | |
---|
277 | causes Perl to check the syntax of the program and then exit without |
---|
278 | executing it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and |
---|
279 | C<use> blocks, because these are considered as occurring outside the |
---|
280 | execution of your program. C<INIT> and C<END> blocks, however, will |
---|
281 | be skipped. |
---|
282 | |
---|
283 | =item B<-d> |
---|
284 | |
---|
285 | runs the program under the Perl debugger. See L<perldebug>. |
---|
286 | |
---|
287 | =item B<-d:>I<foo[=bar,baz]> |
---|
288 | |
---|
289 | runs the program under the control of a debugging, profiling, or |
---|
290 | tracing module installed as Devel::foo. E.g., B<-d:DProf> executes |
---|
291 | the program using the Devel::DProf profiler. As with the B<-M> |
---|
292 | flag, options may be passed to the Devel::foo package where they |
---|
293 | will be received and interpreted by the Devel::foo::import routine. |
---|
294 | The comma-separated list of options must follow a C<=> character. |
---|
295 | See L<perldebug>. |
---|
296 | |
---|
297 | =item B<-D>I<letters> |
---|
298 | |
---|
299 | =item B<-D>I<number> |
---|
300 | |
---|
301 | sets debugging flags. To watch how it executes your program, use |
---|
302 | B<-Dtls>. (This works only if debugging is compiled into your |
---|
303 | Perl.) Another nice value is B<-Dx>, which lists your compiled |
---|
304 | syntax tree. And B<-Dr> displays compiled regular expressions. As an |
---|
305 | alternative, specify a number instead of list of letters (e.g., B<-D14> is |
---|
306 | equivalent to B<-Dtls>): |
---|
307 | |
---|
308 | 1 p Tokenizing and parsing |
---|
309 | 2 s Stack snapshots |
---|
310 | 4 l Context (loop) stack processing |
---|
311 | 8 t Trace execution |
---|
312 | 16 o Method and overloading resolution |
---|
313 | 32 c String/numeric conversions |
---|
314 | 64 P Print preprocessor command for -P, source file input state |
---|
315 | 128 m Memory allocation |
---|
316 | 256 f Format processing |
---|
317 | 512 r Regular expression parsing and execution |
---|
318 | 1024 x Syntax tree dump |
---|
319 | 2048 u Tainting checks |
---|
320 | 4096 L Memory leaks (needs -DLEAKTEST when compiling Perl) |
---|
321 | 8192 H Hash dump -- usurps values() |
---|
322 | 16384 X Scratchpad allocation |
---|
323 | 32768 D Cleaning up |
---|
324 | 65536 S Thread synchronization |
---|
325 | 131072 T Tokenising |
---|
326 | |
---|
327 | All these flags require B<-DDEBUGGING> when you compile the Perl |
---|
328 | executable. See the F<INSTALL> file in the Perl source distribution |
---|
329 | for how to do this. This flag is automatically set if you include B<-g> |
---|
330 | option when C<Configure> asks you about optimizer/debugger flags. |
---|
331 | |
---|
332 | If you're just trying to get a print out of each line of Perl code |
---|
333 | as it executes, the way that C<sh -x> provides for shell scripts, |
---|
334 | you can't use Perl's B<-D> switch. Instead do this |
---|
335 | |
---|
336 | # Bourne shell syntax |
---|
337 | $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program |
---|
338 | |
---|
339 | # csh syntax |
---|
340 | % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program) |
---|
341 | |
---|
342 | See L<perldebug> for details and variations. |
---|
343 | |
---|
344 | =item B<-e> I<commandline> |
---|
345 | |
---|
346 | may be used to enter one line of program. If B<-e> is given, Perl |
---|
347 | will not look for a filename in the argument list. Multiple B<-e> |
---|
348 | commands may be given to build up a multi-line script. Make sure |
---|
349 | to use semicolons where you would in a normal program. |
---|
350 | |
---|
351 | =item B<-F>I<pattern> |
---|
352 | |
---|
353 | specifies the pattern to split on if B<-a> is also in effect. The |
---|
354 | pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be |
---|
355 | put in single quotes. |
---|
356 | |
---|
357 | =item B<-h> |
---|
358 | |
---|
359 | prints a summary of the options. |
---|
360 | |
---|
361 | =item B<-i>[I<extension>] |
---|
362 | |
---|
363 | specifies that files processed by the C<E<lt>E<gt>> construct are to be |
---|
364 | edited in-place. It does this by renaming the input file, opening the |
---|
365 | output file by the original name, and selecting that output file as the |
---|
366 | default for print() statements. The extension, if supplied, is used to |
---|
367 | modify the name of the old file to make a backup copy, following these |
---|
368 | rules: |
---|
369 | |
---|
370 | If no extension is supplied, no backup is made and the current file is |
---|
371 | overwritten. |
---|
372 | |
---|
373 | If the extension doesn't contain a C<*>, then it is appended to the |
---|
374 | end of the current filename as a suffix. If the extension does |
---|
375 | contain one or more C<*> characters, then each C<*> is replaced |
---|
376 | with the current filename. In Perl terms, you could think of this |
---|
377 | as: |
---|
378 | |
---|
379 | ($backup = $extension) =~ s/\*/$file_name/g; |
---|
380 | |
---|
381 | This allows you to add a prefix to the backup file, instead of (or in |
---|
382 | addition to) a suffix: |
---|
383 | |
---|
384 | $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA' |
---|
385 | |
---|
386 | Or even to place backup copies of the original files into another |
---|
387 | directory (provided the directory already exists): |
---|
388 | |
---|
389 | $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig' |
---|
390 | |
---|
391 | These sets of one-liners are equivalent: |
---|
392 | |
---|
393 | $ perl -pi -e 's/bar/baz/' fileA # overwrite current file |
---|
394 | $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file |
---|
395 | |
---|
396 | $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' |
---|
397 | $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' |
---|
398 | |
---|
399 | From the shell, saying |
---|
400 | |
---|
401 | $ perl -p -i.orig -e "s/foo/bar/; ... " |
---|
402 | |
---|
403 | is the same as using the program: |
---|
404 | |
---|
405 | #!/usr/bin/perl -pi.orig |
---|
406 | s/foo/bar/; |
---|
407 | |
---|
408 | which is equivalent to |
---|
409 | |
---|
410 | #!/usr/bin/perl |
---|
411 | $extension = '.orig'; |
---|
412 | LINE: while (<>) { |
---|
413 | if ($ARGV ne $oldargv) { |
---|
414 | if ($extension !~ /\*/) { |
---|
415 | $backup = $ARGV . $extension; |
---|
416 | } |
---|
417 | else { |
---|
418 | ($backup = $extension) =~ s/\*/$ARGV/g; |
---|
419 | } |
---|
420 | rename($ARGV, $backup); |
---|
421 | open(ARGVOUT, ">$ARGV"); |
---|
422 | select(ARGVOUT); |
---|
423 | $oldargv = $ARGV; |
---|
424 | } |
---|
425 | s/foo/bar/; |
---|
426 | } |
---|
427 | continue { |
---|
428 | print; # this prints to original filename |
---|
429 | } |
---|
430 | select(STDOUT); |
---|
431 | |
---|
432 | except that the B<-i> form doesn't need to compare $ARGV to $oldargv to |
---|
433 | know when the filename has changed. It does, however, use ARGVOUT for |
---|
434 | the selected filehandle. Note that STDOUT is restored as the default |
---|
435 | output filehandle after the loop. |
---|
436 | |
---|
437 | As shown above, Perl creates the backup file whether or not any output |
---|
438 | is actually changed. So this is just a fancy way to copy files: |
---|
439 | |
---|
440 | $ perl -p -i '/some/file/path/*' -e 1 file1 file2 file3... |
---|
441 | or |
---|
442 | $ perl -p -i '.orig' -e 1 file1 file2 file3... |
---|
443 | |
---|
444 | You can use C<eof> without parentheses to locate the end of each input |
---|
445 | file, in case you want to append to each file, or reset line numbering |
---|
446 | (see example in L<perlfunc/eof>). |
---|
447 | |
---|
448 | If, for a given file, Perl is unable to create the backup file as |
---|
449 | specified in the extension then it will skip that file and continue on |
---|
450 | with the next one (if it exists). |
---|
451 | |
---|
452 | For a discussion of issues surrounding file permissions and B<-i>, |
---|
453 | see L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?>. |
---|
454 | |
---|
455 | You cannot use B<-i> to create directories or to strip extensions from |
---|
456 | files. |
---|
457 | |
---|
458 | Perl does not expand C<~> in filenames, which is good, since some |
---|
459 | folks use it for their backup files: |
---|
460 | |
---|
461 | $ perl -pi~ -e 's/foo/bar/' file1 file2 file3... |
---|
462 | |
---|
463 | Finally, the B<-i> switch does not impede execution when no |
---|
464 | files are given on the command line. In this case, no backup is made |
---|
465 | (the original file cannot, of course, be determined) and processing |
---|
466 | proceeds from STDIN to STDOUT as might be expected. |
---|
467 | |
---|
468 | =item B<-I>I<directory> |
---|
469 | |
---|
470 | Directories specified by B<-I> are prepended to the search path for |
---|
471 | modules (C<@INC>), and also tells the C preprocessor where to search for |
---|
472 | include files. The C preprocessor is invoked with B<-P>; by default it |
---|
473 | searches /usr/include and /usr/lib/perl. |
---|
474 | |
---|
475 | =item B<-l>[I<octnum>] |
---|
476 | |
---|
477 | enables automatic line-ending processing. It has two separate |
---|
478 | effects. First, it automatically chomps C<$/> (the input record |
---|
479 | separator) when used with B<-n> or B<-p>. Second, it assigns C<$\> |
---|
480 | (the output record separator) to have the value of I<octnum> so |
---|
481 | that any print statements will have that separator added back on. |
---|
482 | If I<octnum> is omitted, sets C<$\> to the current value of |
---|
483 | C<$/>. For instance, to trim lines to 80 columns: |
---|
484 | |
---|
485 | perl -lpe 'substr($_, 80) = ""' |
---|
486 | |
---|
487 | Note that the assignment C<$\ = $/> is done when the switch is processed, |
---|
488 | so the input record separator can be different than the output record |
---|
489 | separator if the B<-l> switch is followed by a B<-0> switch: |
---|
490 | |
---|
491 | gnufind / -print0 | perl -ln0e 'print "found $_" if -p' |
---|
492 | |
---|
493 | This sets C<$\> to newline and then sets C<$/> to the null character. |
---|
494 | |
---|
495 | =item B<-m>[B<->]I<module> |
---|
496 | |
---|
497 | =item B<-M>[B<->]I<module> |
---|
498 | |
---|
499 | =item B<-M>[B<->]I<'module ...'> |
---|
500 | |
---|
501 | =item B<-[mM]>[B<->]I<module=arg[,arg]...> |
---|
502 | |
---|
503 | B<-m>I<module> executes C<use> I<module> C<();> before executing your |
---|
504 | program. |
---|
505 | |
---|
506 | B<-M>I<module> executes C<use> I<module> C<;> before executing your |
---|
507 | program. You can use quotes to add extra code after the module name, |
---|
508 | e.g., C<'-Mmodule qw(foo bar)'>. |
---|
509 | |
---|
510 | If the first character after the B<-M> or B<-m> is a dash (C<->) |
---|
511 | then the 'use' is replaced with 'no'. |
---|
512 | |
---|
513 | A little builtin syntactic sugar means you can also say |
---|
514 | B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for |
---|
515 | C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when |
---|
516 | importing symbols. The actual code generated by B<-Mmodule=foo,bar> is |
---|
517 | C<use module split(/,/,q{foo,bar})>. Note that the C<=> form |
---|
518 | removes the distinction between B<-m> and B<-M>. |
---|
519 | |
---|
520 | =item B<-n> |
---|
521 | |
---|
522 | causes Perl to assume the following loop around your program, which |
---|
523 | makes it iterate over filename arguments somewhat like B<sed -n> or |
---|
524 | B<awk>: |
---|
525 | |
---|
526 | LINE: |
---|
527 | while (<>) { |
---|
528 | ... # your program goes here |
---|
529 | } |
---|
530 | |
---|
531 | Note that the lines are not printed by default. See B<-p> to have |
---|
532 | lines printed. If a file named by an argument cannot be opened for |
---|
533 | some reason, Perl warns you about it and moves on to the next file. |
---|
534 | |
---|
535 | Here is an efficient way to delete all files older than a week: |
---|
536 | |
---|
537 | find . -mtime +7 -print | perl -nle unlink |
---|
538 | |
---|
539 | This is faster than using the B<-exec> switch of B<find> because you don't |
---|
540 | have to start a process on every filename found. It does suffer from |
---|
541 | the bug of mishandling newlines in pathnames, which you can fix if |
---|
542 | you |
---|
543 | |
---|
544 | C<BEGIN> and C<END> blocks may be used to capture control before or after |
---|
545 | the implicit program loop, just as in B<awk>. |
---|
546 | |
---|
547 | =item B<-p> |
---|
548 | |
---|
549 | causes Perl to assume the following loop around your program, which |
---|
550 | makes it iterate over filename arguments somewhat like B<sed>: |
---|
551 | |
---|
552 | |
---|
553 | LINE: |
---|
554 | while (<>) { |
---|
555 | ... # your program goes here |
---|
556 | } continue { |
---|
557 | print or die "-p destination: $!\n"; |
---|
558 | } |
---|
559 | |
---|
560 | If a file named by an argument cannot be opened for some reason, Perl |
---|
561 | warns you about it, and moves on to the next file. Note that the |
---|
562 | lines are printed automatically. An error occurring during printing is |
---|
563 | treated as fatal. To suppress printing use the B<-n> switch. A B<-p> |
---|
564 | overrides a B<-n> switch. |
---|
565 | |
---|
566 | C<BEGIN> and C<END> blocks may be used to capture control before or after |
---|
567 | the implicit loop, just as in B<awk>. |
---|
568 | |
---|
569 | =item B<-P> |
---|
570 | |
---|
571 | causes your program to be run through the C preprocessor before |
---|
572 | compilation by Perl. Because both comments and B<cpp> directives begin |
---|
573 | with the # character, you should avoid starting comments with any words |
---|
574 | recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">. |
---|
575 | Also, in some platforms the C preprocessor knows too much: it knows |
---|
576 | about the C++ -style until-end-of-line comments starting with C<"//">. |
---|
577 | This will cause problems with common Perl constructs like |
---|
578 | |
---|
579 | s/foo//; |
---|
580 | |
---|
581 | because after -P this will became illegal code |
---|
582 | |
---|
583 | s/foo |
---|
584 | |
---|
585 | The workaround is to use some other quoting separator than C<"/">, |
---|
586 | like for example C<"!">: |
---|
587 | |
---|
588 | s!foo!!; |
---|
589 | |
---|
590 | =item B<-s> |
---|
591 | |
---|
592 | enables rudimentary switch parsing for switches on the command |
---|
593 | line after the program name but before any filename arguments (or before |
---|
594 | an argument of B<-->). This means you can have switches with two leading |
---|
595 | dashes (B<--help>). Any switch found there is removed from @ARGV and sets the |
---|
596 | corresponding variable in the Perl program. The following program |
---|
597 | prints "1" if the program is invoked with a B<-xyz> switch, and "abc" |
---|
598 | if it is invoked with B<-xyz=abc>. |
---|
599 | |
---|
600 | #!/usr/bin/perl -s |
---|
601 | if ($xyz) { print "$xyz\n" } |
---|
602 | |
---|
603 | Do note that B<--help> creates the variable ${-help}, which is not compliant |
---|
604 | with C<strict refs>. |
---|
605 | |
---|
606 | =item B<-S> |
---|
607 | |
---|
608 | makes Perl use the PATH environment variable to search for the |
---|
609 | program (unless the name of the program contains directory separators). |
---|
610 | |
---|
611 | On some platforms, this also makes Perl append suffixes to the |
---|
612 | filename while searching for it. For example, on Win32 platforms, |
---|
613 | the ".bat" and ".cmd" suffixes are appended if a lookup for the |
---|
614 | original name fails, and if the name does not already end in one |
---|
615 | of those suffixes. If your Perl was compiled with DEBUGGING turned |
---|
616 | on, using the -Dp switch to Perl shows how the search progresses. |
---|
617 | |
---|
618 | Typically this is used to emulate #! startup on platforms that |
---|
619 | don't support #!. This example works on many platforms that |
---|
620 | have a shell compatible with Bourne shell: |
---|
621 | |
---|
622 | #!/usr/bin/perl |
---|
623 | eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}' |
---|
624 | if $running_under_some_shell; |
---|
625 | |
---|
626 | The system ignores the first line and feeds the program to F</bin/sh>, |
---|
627 | which proceeds to try to execute the Perl program as a shell script. |
---|
628 | The shell executes the second line as a normal shell command, and thus |
---|
629 | starts up the Perl interpreter. On some systems $0 doesn't always |
---|
630 | contain the full pathname, so the B<-S> tells Perl to search for the |
---|
631 | program if necessary. After Perl locates the program, it parses the |
---|
632 | lines and ignores them because the variable $running_under_some_shell |
---|
633 | is never true. If the program will be interpreted by csh, you will need |
---|
634 | to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand |
---|
635 | embedded spaces (and such) in the argument list. To start up sh rather |
---|
636 | than csh, some systems may have to replace the #! line with a line |
---|
637 | containing just a colon, which will be politely ignored by Perl. Other |
---|
638 | systems can't control that, and need a totally devious construct that |
---|
639 | will work under any of B<csh>, B<sh>, or Perl, such as the following: |
---|
640 | |
---|
641 | eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' |
---|
642 | & eval 'exec /usr/bin/perl -wS $0 $argv:q' |
---|
643 | if $running_under_some_shell; |
---|
644 | |
---|
645 | If the filename supplied contains directory separators (i.e., is an |
---|
646 | absolute or relative pathname), and if that file is not found, |
---|
647 | platforms that append file extensions will do so and try to look |
---|
648 | for the file with those extensions added, one by one. |
---|
649 | |
---|
650 | On DOS-like platforms, if the program does not contain directory |
---|
651 | separators, it will first be searched for in the current directory |
---|
652 | before being searched for on the PATH. On Unix platforms, the |
---|
653 | program will be searched for strictly on the PATH. |
---|
654 | |
---|
655 | =item B<-T> |
---|
656 | |
---|
657 | forces "taint" checks to be turned on so you can test them. Ordinarily |
---|
658 | these checks are done only when running setuid or setgid. It's a |
---|
659 | good idea to turn them on explicitly for programs that run on behalf |
---|
660 | of someone else whom you might not necessarily trust, such as CGI |
---|
661 | programs or any internet servers you might write in Perl. See |
---|
662 | L<perlsec> for details. For security reasons, this option must be |
---|
663 | seen by Perl quite early; usually this means it must appear early |
---|
664 | on the command line or in the #! line for systems which support |
---|
665 | that construct. |
---|
666 | |
---|
667 | =item B<-u> |
---|
668 | |
---|
669 | This obsolete switch causes Perl to dump core after compiling your |
---|
670 | program. You can then in theory take this core dump and turn it |
---|
671 | into an executable file by using the B<undump> program (not supplied). |
---|
672 | This speeds startup at the expense of some disk space (which you |
---|
673 | can minimize by stripping the executable). (Still, a "hello world" |
---|
674 | executable comes out to about 200K on my machine.) If you want to |
---|
675 | execute a portion of your program before dumping, use the dump() |
---|
676 | operator instead. Note: availability of B<undump> is platform |
---|
677 | specific and may not be available for a specific port of Perl. |
---|
678 | |
---|
679 | This switch has been superseded in favor of the new Perl code |
---|
680 | generator backends to the compiler. See L<B> and L<B::Bytecode> |
---|
681 | for details. |
---|
682 | |
---|
683 | =item B<-U> |
---|
684 | |
---|
685 | allows Perl to do unsafe operations. Currently the only "unsafe" |
---|
686 | operations are the unlinking of directories while running as superuser, |
---|
687 | and running setuid programs with fatal taint checks turned into |
---|
688 | warnings. Note that the B<-w> switch (or the C<$^W> variable) must |
---|
689 | be used along with this option to actually I<generate> the |
---|
690 | taint-check warnings. |
---|
691 | |
---|
692 | =item B<-v> |
---|
693 | |
---|
694 | prints the version and patchlevel of your perl executable. |
---|
695 | |
---|
696 | =item B<-V> |
---|
697 | |
---|
698 | prints summary of the major perl configuration values and the current |
---|
699 | values of @INC. |
---|
700 | |
---|
701 | =item B<-V:>I<name> |
---|
702 | |
---|
703 | Prints to STDOUT the value of the named configuration variable. |
---|
704 | For example, |
---|
705 | |
---|
706 | $ perl -V:man.dir |
---|
707 | |
---|
708 | will provide strong clues about what your MANPATH variable should |
---|
709 | be set to in order to access the Perl documentation. |
---|
710 | |
---|
711 | =item B<-w> |
---|
712 | |
---|
713 | prints warnings about dubious constructs, such as variable names |
---|
714 | that are mentioned only once and scalar variables that are used |
---|
715 | before being set, redefined subroutines, references to undefined |
---|
716 | filehandles or filehandles opened read-only that you are attempting |
---|
717 | to write on, values used as a number that doesn't look like numbers, |
---|
718 | using an array as though it were a scalar, if your subroutines |
---|
719 | recurse more than 100 deep, and innumerable other things. |
---|
720 | |
---|
721 | This switch really just enables the internal C<^$W> variable. You |
---|
722 | can disable or promote into fatal errors specific warnings using |
---|
723 | C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. |
---|
724 | See also L<perldiag> and L<perltrap>. A new, fine-grained warning |
---|
725 | facility is also available if you want to manipulate entire classes |
---|
726 | of warnings; see L<warnings> or L<perllexwarn>. |
---|
727 | |
---|
728 | =item B<-W> |
---|
729 | |
---|
730 | Enables all warnings regardless of C<no warnings> or C<$^W>. |
---|
731 | See L<perllexwarn>. |
---|
732 | |
---|
733 | =item B<-X> |
---|
734 | |
---|
735 | Disables all warnings regardless of C<use warnings> or C<$^W>. |
---|
736 | See L<perllexwarn>. |
---|
737 | |
---|
738 | =item B<-x> I<directory> |
---|
739 | |
---|
740 | tells Perl that the program is embedded in a larger chunk of unrelated |
---|
741 | ASCII text, such as in a mail message. Leading garbage will be |
---|
742 | discarded until the first line that starts with #! and contains the |
---|
743 | string "perl". Any meaningful switches on that line will be applied. |
---|
744 | If a directory name is specified, Perl will switch to that directory |
---|
745 | before running the program. The B<-x> switch controls only the |
---|
746 | disposal of leading garbage. The program must be terminated with |
---|
747 | C<__END__> if there is trailing garbage to be ignored (the program |
---|
748 | can process any or all of the trailing garbage via the DATA filehandle |
---|
749 | if desired). |
---|
750 | |
---|
751 | =back |
---|
752 | |
---|
753 | =head1 ENVIRONMENT |
---|
754 | |
---|
755 | =over 12 |
---|
756 | |
---|
757 | =item HOME |
---|
758 | |
---|
759 | Used if chdir has no argument. |
---|
760 | |
---|
761 | =item LOGDIR |
---|
762 | |
---|
763 | Used if chdir has no argument and HOME is not set. |
---|
764 | |
---|
765 | =item PATH |
---|
766 | |
---|
767 | Used in executing subprocesses, and in finding the program if B<-S> is |
---|
768 | used. |
---|
769 | |
---|
770 | =item PERL5LIB |
---|
771 | |
---|
772 | A colon-separated list of directories in which to look for Perl library |
---|
773 | files before looking in the standard library and the current |
---|
774 | directory. Any architecture-specific directories under the specified |
---|
775 | locations are automatically included if they exist. If PERL5LIB is not |
---|
776 | defined, PERLLIB is used. |
---|
777 | |
---|
778 | When running taint checks (either because the program was running setuid |
---|
779 | or setgid, or the B<-T> switch was used), neither variable is used. |
---|
780 | The program should instead say: |
---|
781 | |
---|
782 | use lib "/my/directory"; |
---|
783 | |
---|
784 | =item PERL5OPT |
---|
785 | |
---|
786 | Command-line options (switches). Switches in this variable are taken |
---|
787 | as if they were on every Perl command line. Only the B<-[DIMUdmw]> |
---|
788 | switches are allowed. When running taint checks (because the program |
---|
789 | was running setuid or setgid, or the B<-T> switch was used), this |
---|
790 | variable is ignored. If PERL5OPT begins with B<-T>, tainting will be |
---|
791 | enabled, and any subsequent options ignored. |
---|
792 | |
---|
793 | =item PERLLIB |
---|
794 | |
---|
795 | A colon-separated list of directories in which to look for Perl library |
---|
796 | files before looking in the standard library and the current directory. |
---|
797 | If PERL5LIB is defined, PERLLIB is not used. |
---|
798 | |
---|
799 | =item PERL5DB |
---|
800 | |
---|
801 | The command used to load the debugger code. The default is: |
---|
802 | |
---|
803 | BEGIN { require 'perl5db.pl' } |
---|
804 | |
---|
805 | =item PERL5SHELL (specific to the Win32 port) |
---|
806 | |
---|
807 | May be set to an alternative shell that perl must use internally for |
---|
808 | executing "backtick" commands or system(). Default is C<cmd.exe /x/c> |
---|
809 | on WindowsNT and C<command.com /c> on Windows95. The value is considered |
---|
810 | to be space-separated. Precede any character that needs to be protected |
---|
811 | (like a space or backslash) with a backslash. |
---|
812 | |
---|
813 | Note that Perl doesn't use COMSPEC for this purpose because |
---|
814 | COMSPEC has a high degree of variability among users, leading to |
---|
815 | portability concerns. Besides, perl can use a shell that may not be |
---|
816 | fit for interactive use, and setting COMSPEC to such a shell may |
---|
817 | interfere with the proper functioning of other programs (which usually |
---|
818 | look in COMSPEC to find a shell fit for interactive use). |
---|
819 | |
---|
820 | =item PERL_DEBUG_MSTATS |
---|
821 | |
---|
822 | Relevant only if perl is compiled with the malloc included with the perl |
---|
823 | distribution (that is, if C<perl -V:d_mymalloc> is 'define'). |
---|
824 | If set, this causes memory statistics to be dumped after execution. If set |
---|
825 | to an integer greater than one, also causes memory statistics to be dumped |
---|
826 | after compilation. |
---|
827 | |
---|
828 | =item PERL_DESTRUCT_LEVEL |
---|
829 | |
---|
830 | Relevant only if your perl executable was built with B<-DDEBUGGING>, |
---|
831 | this controls the behavior of global destruction of objects and other |
---|
832 | references. |
---|
833 | |
---|
834 | =item PERL_ROOT (specific to the VMS port) |
---|
835 | |
---|
836 | A translation concealed rooted logical name that contains perl and the |
---|
837 | logical device for the @INC path on VMS only. Other logical names that |
---|
838 | affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and |
---|
839 | SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in |
---|
840 | L<perlvms> and in F<README.vms> in the Perl source distribution. |
---|
841 | |
---|
842 | =item SYS$LOGIN (specific to the VMS port) |
---|
843 | |
---|
844 | Used if chdir has no argument and HOME and LOGDIR are not set. |
---|
845 | |
---|
846 | =back |
---|
847 | |
---|
848 | Perl also has environment variables that control how Perl handles data |
---|
849 | specific to particular natural languages. See L<perllocale>. |
---|
850 | |
---|
851 | Apart from these, Perl uses no other environment variables, except |
---|
852 | to make them available to the program being executed, and to child |
---|
853 | processes. However, programs running setuid would do well to execute |
---|
854 | the following lines before doing anything else, just to keep people |
---|
855 | honest: |
---|
856 | |
---|
857 | $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need |
---|
858 | $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL}; |
---|
859 | delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; |
---|