Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | =head1 NAME |
2 | ||
3 | perlrun - how to execute the Perl interpreter | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | B<perl> S<[ B<-CsTtuUWX> ]> | |
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 Plan 9 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; | |
305 | the format of the output is explained in L<perldebguts>. | |
306 | ||
307 | As an alternative, specify a number instead of list of letters (e.g., | |
308 | B<-D14> is equivalent to B<-Dtls>): | |
309 | ||
310 | 1 p Tokenizing and parsing | |
311 | 2 s Stack snapshots | |
312 | 4 l Context (loop) stack processing | |
313 | 8 t Trace execution | |
314 | 16 o Method and overloading resolution | |
315 | 32 c String/numeric conversions | |
316 | 64 P Print profiling info, preprocessor command for -P, source file input state | |
317 | 128 m Memory allocation | |
318 | 256 f Format processing | |
319 | 512 r Regular expression parsing and execution | |
320 | 1024 x Syntax tree dump | |
321 | 2048 u Tainting checks | |
322 | 4096 L Memory leaks (needs -DLEAKTEST when compiling Perl) | |
323 | 8192 H Hash dump -- usurps values() | |
324 | 16384 X Scratchpad allocation | |
325 | 32768 D Cleaning up | |
326 | 65536 S Thread synchronization | |
327 | 131072 T Tokenising | |
328 | 262144 R Include reference counts of dumped variables (eg when using -Ds) | |
329 | 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB | |
330 | ||
331 | All these flags require B<-DDEBUGGING> when you compile the Perl | |
332 | executable (but see L<Devel::Peek>, L<re> which may change this). | |
333 | See the F<INSTALL> file in the Perl source distribution | |
334 | for how to do this. This flag is automatically set if you include B<-g> | |
335 | option when C<Configure> asks you about optimizer/debugger flags. | |
336 | ||
337 | If you're just trying to get a print out of each line of Perl code | |
338 | as it executes, the way that C<sh -x> provides for shell scripts, | |
339 | you can't use Perl's B<-D> switch. Instead do this | |
340 | ||
341 | # If you have "env" utility | |
342 | env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program | |
343 | ||
344 | # Bourne shell syntax | |
345 | $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program | |
346 | ||
347 | # csh syntax | |
348 | % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program) | |
349 | ||
350 | See L<perldebug> for details and variations. | |
351 | ||
352 | =item B<-e> I<commandline> | |
353 | ||
354 | may be used to enter one line of program. If B<-e> is given, Perl | |
355 | will not look for a filename in the argument list. Multiple B<-e> | |
356 | commands may be given to build up a multi-line script. Make sure | |
357 | to use semicolons where you would in a normal program. | |
358 | ||
359 | =item B<-F>I<pattern> | |
360 | ||
361 | specifies the pattern to split on if B<-a> is also in effect. The | |
362 | pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be | |
363 | put in single quotes. | |
364 | ||
365 | =item B<-h> | |
366 | ||
367 | prints a summary of the options. | |
368 | ||
369 | =item B<-i>[I<extension>] | |
370 | ||
371 | specifies that files processed by the C<E<lt>E<gt>> construct are to be | |
372 | edited in-place. It does this by renaming the input file, opening the | |
373 | output file by the original name, and selecting that output file as the | |
374 | default for print() statements. The extension, if supplied, is used to | |
375 | modify the name of the old file to make a backup copy, following these | |
376 | rules: | |
377 | ||
378 | If no extension is supplied, no backup is made and the current file is | |
379 | overwritten. | |
380 | ||
381 | If the extension doesn't contain a C<*>, then it is appended to the | |
382 | end of the current filename as a suffix. If the extension does | |
383 | contain one or more C<*> characters, then each C<*> is replaced | |
384 | with the current filename. In Perl terms, you could think of this | |
385 | as: | |
386 | ||
387 | ($backup = $extension) =~ s/\*/$file_name/g; | |
388 | ||
389 | This allows you to add a prefix to the backup file, instead of (or in | |
390 | addition to) a suffix: | |
391 | ||
392 | $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA' | |
393 | ||
394 | Or even to place backup copies of the original files into another | |
395 | directory (provided the directory already exists): | |
396 | ||
397 | $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig' | |
398 | ||
399 | These sets of one-liners are equivalent: | |
400 | ||
401 | $ perl -pi -e 's/bar/baz/' fileA # overwrite current file | |
402 | $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file | |
403 | ||
404 | $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' | |
405 | $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' | |
406 | ||
407 | From the shell, saying | |
408 | ||
409 | $ perl -p -i.orig -e "s/foo/bar/; ... " | |
410 | ||
411 | is the same as using the program: | |
412 | ||
413 | #!/usr/bin/perl -pi.orig | |
414 | s/foo/bar/; | |
415 | ||
416 | which is equivalent to | |
417 | ||
418 | #!/usr/bin/perl | |
419 | $extension = '.orig'; | |
420 | LINE: while (<>) { | |
421 | if ($ARGV ne $oldargv) { | |
422 | if ($extension !~ /\*/) { | |
423 | $backup = $ARGV . $extension; | |
424 | } | |
425 | else { | |
426 | ($backup = $extension) =~ s/\*/$ARGV/g; | |
427 | } | |
428 | rename($ARGV, $backup); | |
429 | open(ARGVOUT, ">$ARGV"); | |
430 | select(ARGVOUT); | |
431 | $oldargv = $ARGV; | |
432 | } | |
433 | s/foo/bar/; | |
434 | } | |
435 | continue { | |
436 | print; # this prints to original filename | |
437 | } | |
438 | select(STDOUT); | |
439 | ||
440 | except that the B<-i> form doesn't need to compare $ARGV to $oldargv to | |
441 | know when the filename has changed. It does, however, use ARGVOUT for | |
442 | the selected filehandle. Note that STDOUT is restored as the default | |
443 | output filehandle after the loop. | |
444 | ||
445 | As shown above, Perl creates the backup file whether or not any output | |
446 | is actually changed. So this is just a fancy way to copy files: | |
447 | ||
448 | $ perl -p -i '/some/file/path/*' -e 1 file1 file2 file3... | |
449 | or | |
450 | $ perl -p -i '.orig' -e 1 file1 file2 file3... | |
451 | ||
452 | You can use C<eof> without parentheses to locate the end of each input | |
453 | file, in case you want to append to each file, or reset line numbering | |
454 | (see example in L<perlfunc/eof>). | |
455 | ||
456 | If, for a given file, Perl is unable to create the backup file as | |
457 | specified in the extension then it will skip that file and continue on | |
458 | with the next one (if it exists). | |
459 | ||
460 | For a discussion of issues surrounding file permissions and B<-i>, | |
461 | 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?>. | |
462 | ||
463 | You cannot use B<-i> to create directories or to strip extensions from | |
464 | files. | |
465 | ||
466 | Perl does not expand C<~> in filenames, which is good, since some | |
467 | folks use it for their backup files: | |
468 | ||
469 | $ perl -pi~ -e 's/foo/bar/' file1 file2 file3... | |
470 | ||
471 | Finally, the B<-i> switch does not impede execution when no | |
472 | files are given on the command line. In this case, no backup is made | |
473 | (the original file cannot, of course, be determined) and processing | |
474 | proceeds from STDIN to STDOUT as might be expected. | |
475 | ||
476 | =item B<-I>I<directory> | |
477 | ||
478 | Directories specified by B<-I> are prepended to the search path for | |
479 | modules (C<@INC>), and also tells the C preprocessor where to search for | |
480 | include files. The C preprocessor is invoked with B<-P>; by default it | |
481 | searches /usr/include and /usr/lib/perl. | |
482 | ||
483 | =item B<-l>[I<octnum>] | |
484 | ||
485 | enables automatic line-ending processing. It has two separate | |
486 | effects. First, it automatically chomps C<$/> (the input record | |
487 | separator) when used with B<-n> or B<-p>. Second, it assigns C<$\> | |
488 | (the output record separator) to have the value of I<octnum> so | |
489 | that any print statements will have that separator added back on. | |
490 | If I<octnum> is omitted, sets C<$\> to the current value of | |
491 | C<$/>. For instance, to trim lines to 80 columns: | |
492 | ||
493 | perl -lpe 'substr($_, 80) = ""' | |
494 | ||
495 | Note that the assignment C<$\ = $/> is done when the switch is processed, | |
496 | so the input record separator can be different than the output record | |
497 | separator if the B<-l> switch is followed by a B<-0> switch: | |
498 | ||
499 | gnufind / -print0 | perl -ln0e 'print "found $_" if -p' | |
500 | ||
501 | This sets C<$\> to newline and then sets C<$/> to the null character. | |
502 | ||
503 | =item B<-m>[B<->]I<module> | |
504 | ||
505 | =item B<-M>[B<->]I<module> | |
506 | ||
507 | =item B<-M>[B<->]I<'module ...'> | |
508 | ||
509 | =item B<-[mM]>[B<->]I<module=arg[,arg]...> | |
510 | ||
511 | B<-m>I<module> executes C<use> I<module> C<();> before executing your | |
512 | program. | |
513 | ||
514 | B<-M>I<module> executes C<use> I<module> C<;> before executing your | |
515 | program. You can use quotes to add extra code after the module name, | |
516 | e.g., C<'-Mmodule qw(foo bar)'>. | |
517 | ||
518 | If the first character after the B<-M> or B<-m> is a dash (C<->) | |
519 | then the 'use' is replaced with 'no'. | |
520 | ||
521 | A little builtin syntactic sugar means you can also say | |
522 | B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for | |
523 | C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when | |
524 | importing symbols. The actual code generated by B<-Mmodule=foo,bar> is | |
525 | C<use module split(/,/,q{foo,bar})>. Note that the C<=> form | |
526 | removes the distinction between B<-m> and B<-M>. | |
527 | ||
528 | =item B<-n> | |
529 | ||
530 | causes Perl to assume the following loop around your program, which | |
531 | makes it iterate over filename arguments somewhat like B<sed -n> or | |
532 | B<awk>: | |
533 | ||
534 | LINE: | |
535 | while (<>) { | |
536 | ... # your program goes here | |
537 | } | |
538 | ||
539 | Note that the lines are not printed by default. See B<-p> to have | |
540 | lines printed. If a file named by an argument cannot be opened for | |
541 | some reason, Perl warns you about it and moves on to the next file. | |
542 | ||
543 | Here is an efficient way to delete all files older than a week: | |
544 | ||
545 | find . -mtime +7 -print | perl -nle unlink | |
546 | ||
547 | This is faster than using the B<-exec> switch of B<find> because you don't | |
548 | have to start a process on every filename found. It does suffer from | |
549 | the bug of mishandling newlines in pathnames, which you can fix if | |
550 | you follow the example under B<-0>. | |
551 | ||
552 | C<BEGIN> and C<END> blocks may be used to capture control before or after | |
553 | the implicit program loop, just as in B<awk>. | |
554 | ||
555 | =item B<-p> | |
556 | ||
557 | causes Perl to assume the following loop around your program, which | |
558 | makes it iterate over filename arguments somewhat like B<sed>: | |
559 | ||
560 | ||
561 | LINE: | |
562 | while (<>) { | |
563 | ... # your program goes here | |
564 | } continue { | |
565 | print or die "-p destination: $!\n"; | |
566 | } | |
567 | ||
568 | If a file named by an argument cannot be opened for some reason, Perl | |
569 | warns you about it, and moves on to the next file. Note that the | |
570 | lines are printed automatically. An error occurring during printing is | |
571 | treated as fatal. To suppress printing use the B<-n> switch. A B<-p> | |
572 | overrides a B<-n> switch. | |
573 | ||
574 | C<BEGIN> and C<END> blocks may be used to capture control before or after | |
575 | the implicit loop, just as in B<awk>. | |
576 | ||
577 | =item B<-P> | |
578 | ||
579 | B<NOTE: Use of -P is strongly discouraged because of its inherent | |
580 | problems, including poor portability.> | |
581 | ||
582 | This option causes your program to be run through the C preprocessor before | |
583 | compilation by Perl. Because both comments and B<cpp> directives begin | |
584 | with the # character, you should avoid starting comments with any words | |
585 | recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">. | |
586 | ||
587 | If you're considering using C<-P>, you might also want to look at the | |
588 | Filter::cpp module from CPAN. | |
589 | ||
590 | The problems of -P include, but are not limited to: | |
591 | ||
592 | =over 10 | |
593 | ||
594 | =item * | |
595 | ||
596 | The C<#!> line is stripped, so any switches there don't apply. | |
597 | ||
598 | =item * | |
599 | ||
600 | A C<-P> on a C<#!> line doesn't work. | |
601 | ||
602 | =item * | |
603 | ||
604 | B<All> lines that begin with (whitespace and) a C<#> but | |
605 | do not look like cpp commands, are stripped, including anything | |
606 | inside Perl strings, regular expressions, and here-docs . | |
607 | ||
608 | =item * | |
609 | ||
610 | In some platforms the C preprocessor knows too much: it knows about | |
611 | the C++ -style until-end-of-line comments starting with C<"//">. | |
612 | This will cause problems with common Perl constructs like | |
613 | ||
614 | s/foo//; | |
615 | ||
616 | because after -P this will became illegal code | |
617 | ||
618 | s/foo | |
619 | ||
620 | The workaround is to use some other quoting separator than C<"/">, | |
621 | like for example C<"!">: | |
622 | ||
623 | s!foo!!; | |
624 | ||
625 | ||
626 | ||
627 | =item * | |
628 | ||
629 | It requires not only a working C preprocessor but also a working | |
630 | F<sed>. If not on UNIX, you are probably out of luck on this. | |
631 | ||
632 | =item * | |
633 | ||
634 | Script line numbers are not preserved. | |
635 | ||
636 | =item * | |
637 | ||
638 | The C<-x> does not work with C<-P>. | |
639 | ||
640 | =back | |
641 | ||
642 | =item B<-s> | |
643 | ||
644 | enables rudimentary switch parsing for switches on the command | |
645 | line after the program name but before any filename arguments (or before | |
646 | an argument of B<-->). This means you can have switches with two leading | |
647 | dashes (B<--help>). Any switch found there is removed from @ARGV and sets the | |
648 | corresponding variable in the Perl program. The following program | |
649 | prints "1" if the program is invoked with a B<-xyz> switch, and "abc" | |
650 | if it is invoked with B<-xyz=abc>. | |
651 | ||
652 | #!/usr/bin/perl -s | |
653 | if ($xyz) { print "$xyz\n" } | |
654 | ||
655 | Do note that B<--help> creates the variable ${-help}, which is not compliant | |
656 | with C<strict refs>. | |
657 | ||
658 | =item B<-S> | |
659 | ||
660 | makes Perl use the PATH environment variable to search for the | |
661 | program (unless the name of the program contains directory separators). | |
662 | ||
663 | On some platforms, this also makes Perl append suffixes to the | |
664 | filename while searching for it. For example, on Win32 platforms, | |
665 | the ".bat" and ".cmd" suffixes are appended if a lookup for the | |
666 | original name fails, and if the name does not already end in one | |
667 | of those suffixes. If your Perl was compiled with DEBUGGING turned | |
668 | on, using the -Dp switch to Perl shows how the search progresses. | |
669 | ||
670 | Typically this is used to emulate #! startup on platforms that | |
671 | don't support #!. This example works on many platforms that | |
672 | have a shell compatible with Bourne shell: | |
673 | ||
674 | #!/usr/bin/perl | |
675 | eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}' | |
676 | if $running_under_some_shell; | |
677 | ||
678 | The system ignores the first line and feeds the program to F</bin/sh>, | |
679 | which proceeds to try to execute the Perl program as a shell script. | |
680 | The shell executes the second line as a normal shell command, and thus | |
681 | starts up the Perl interpreter. On some systems $0 doesn't always | |
682 | contain the full pathname, so the B<-S> tells Perl to search for the | |
683 | program if necessary. After Perl locates the program, it parses the | |
684 | lines and ignores them because the variable $running_under_some_shell | |
685 | is never true. If the program will be interpreted by csh, you will need | |
686 | to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand | |
687 | embedded spaces (and such) in the argument list. To start up sh rather | |
688 | than csh, some systems may have to replace the #! line with a line | |
689 | containing just a colon, which will be politely ignored by Perl. Other | |
690 | systems can't control that, and need a totally devious construct that | |
691 | will work under any of B<csh>, B<sh>, or Perl, such as the following: | |
692 | ||
693 | eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' | |
694 | & eval 'exec /usr/bin/perl -wS $0 $argv:q' | |
695 | if $running_under_some_shell; | |
696 | ||
697 | If the filename supplied contains directory separators (i.e., is an | |
698 | absolute or relative pathname), and if that file is not found, | |
699 | platforms that append file extensions will do so and try to look | |
700 | for the file with those extensions added, one by one. | |
701 | ||
702 | On DOS-like platforms, if the program does not contain directory | |
703 | separators, it will first be searched for in the current directory | |
704 | before being searched for on the PATH. On Unix platforms, the | |
705 | program will be searched for strictly on the PATH. | |
706 | ||
707 | =item B<-t> | |
708 | ||
709 | Like B<-T>, but taint checks will issue warnings rather than fatal | |
710 | errors. These warnings can be controlled normally with C<no warnings | |
711 | qw(taint)>. | |
712 | ||
713 | B<NOTE: this is not a substitute for -T.> This is meant only to be | |
714 | used as a temporary development aid while securing legacy code: | |
715 | for real production code and for new secure code written from scratch | |
716 | always use the real B<-T>. | |
717 | ||
718 | =item B<-T> | |
719 | ||
720 | forces "taint" checks to be turned on so you can test them. Ordinarily | |
721 | these checks are done only when running setuid or setgid. It's a | |
722 | good idea to turn them on explicitly for programs that run on behalf | |
723 | of someone else whom you might not necessarily trust, such as CGI | |
724 | programs or any internet servers you might write in Perl. See | |
725 | L<perlsec> for details. For security reasons, this option must be | |
726 | seen by Perl quite early; usually this means it must appear early | |
727 | on the command line or in the #! line for systems which support | |
728 | that construct. | |
729 | ||
730 | =item B<-u> | |
731 | ||
732 | This obsolete switch causes Perl to dump core after compiling your | |
733 | program. You can then in theory take this core dump and turn it | |
734 | into an executable file by using the B<undump> program (not supplied). | |
735 | This speeds startup at the expense of some disk space (which you | |
736 | can minimize by stripping the executable). (Still, a "hello world" | |
737 | executable comes out to about 200K on my machine.) If you want to | |
738 | execute a portion of your program before dumping, use the dump() | |
739 | operator instead. Note: availability of B<undump> is platform | |
740 | specific and may not be available for a specific port of Perl. | |
741 | ||
742 | This switch has been superseded in favor of the new Perl code | |
743 | generator backends to the compiler. See L<B> and L<B::Bytecode> | |
744 | for details. | |
745 | ||
746 | =item B<-U> | |
747 | ||
748 | allows Perl to do unsafe operations. Currently the only "unsafe" | |
749 | operations are the unlinking of directories while running as superuser, | |
750 | and running setuid programs with fatal taint checks turned into | |
751 | warnings. Note that the B<-w> switch (or the C<$^W> variable) must | |
752 | be used along with this option to actually I<generate> the | |
753 | taint-check warnings. | |
754 | ||
755 | =item B<-v> | |
756 | ||
757 | prints the version and patchlevel of your perl executable. | |
758 | ||
759 | =item B<-V> | |
760 | ||
761 | prints summary of the major perl configuration values and the current | |
762 | values of @INC. | |
763 | ||
764 | =item B<-V:>I<name> | |
765 | ||
766 | Prints to STDOUT the value of the named configuration variable. | |
767 | For example, | |
768 | ||
769 | $ perl -V:man.dir | |
770 | ||
771 | will provide strong clues about what your MANPATH variable should | |
772 | be set to in order to access the Perl documentation. | |
773 | ||
774 | =item B<-w> | |
775 | ||
776 | prints warnings about dubious constructs, such as variable names | |
777 | that are mentioned only once and scalar variables that are used | |
778 | before being set, redefined subroutines, references to undefined | |
779 | filehandles or filehandles opened read-only that you are attempting | |
780 | to write on, values used as a number that doesn't look like numbers, | |
781 | using an array as though it were a scalar, if your subroutines | |
782 | recurse more than 100 deep, and innumerable other things. | |
783 | ||
784 | This switch really just enables the internal C<^$W> variable. You | |
785 | can disable or promote into fatal errors specific warnings using | |
786 | C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. | |
787 | See also L<perldiag> and L<perltrap>. A new, fine-grained warning | |
788 | facility is also available if you want to manipulate entire classes | |
789 | of warnings; see L<warnings> or L<perllexwarn>. | |
790 | ||
791 | =item B<-W> | |
792 | ||
793 | Enables all warnings regardless of C<no warnings> or C<$^W>. | |
794 | See L<perllexwarn>. | |
795 | ||
796 | =item B<-X> | |
797 | ||
798 | Disables all warnings regardless of C<use warnings> or C<$^W>. | |
799 | See L<perllexwarn>. | |
800 | ||
801 | =item B<-x> I<directory> | |
802 | ||
803 | tells Perl that the program is embedded in a larger chunk of unrelated | |
804 | ASCII text, such as in a mail message. Leading garbage will be | |
805 | discarded until the first line that starts with #! and contains the | |
806 | string "perl". Any meaningful switches on that line will be applied. | |
807 | If a directory name is specified, Perl will switch to that directory | |
808 | before running the program. The B<-x> switch controls only the | |
809 | disposal of leading garbage. The program must be terminated with | |
810 | C<__END__> if there is trailing garbage to be ignored (the program | |
811 | can process any or all of the trailing garbage via the DATA filehandle | |
812 | if desired). | |
813 | ||
814 | =back | |
815 | ||
816 | =head1 ENVIRONMENT | |
817 | ||
818 | =over 12 | |
819 | ||
820 | =item HOME | |
821 | ||
822 | Used if chdir has no argument. | |
823 | ||
824 | =item LOGDIR | |
825 | ||
826 | Used if chdir has no argument and HOME is not set. | |
827 | ||
828 | =item PATH | |
829 | ||
830 | Used in executing subprocesses, and in finding the program if B<-S> is | |
831 | used. | |
832 | ||
833 | =item PERL5LIB | |
834 | ||
835 | A colon-separated list of directories in which to look for Perl library | |
836 | files before looking in the standard library and the current | |
837 | directory. Any architecture-specific directories under the specified | |
838 | locations are automatically included if they exist. If PERL5LIB is not | |
839 | defined, PERLLIB is used. | |
840 | ||
841 | When running taint checks (either because the program was running setuid | |
842 | or setgid, or the B<-T> switch was used), neither variable is used. | |
843 | The program should instead say: | |
844 | ||
845 | use lib "/my/directory"; | |
846 | ||
847 | =item PERL5OPT | |
848 | ||
849 | Command-line options (switches). Switches in this variable are taken | |
850 | as if they were on every Perl command line. Only the B<-[DIMUdmtw]> | |
851 | switches are allowed. When running taint checks (because the program | |
852 | was running setuid or setgid, or the B<-T> switch was used), this | |
853 | variable is ignored. If PERL5OPT begins with B<-T>, tainting will be | |
854 | enabled, and any subsequent options ignored. | |
855 | ||
856 | =item PERLIO | |
857 | ||
858 | A space (or colon) separated list of PerlIO layers. If perl is built | |
859 | to use PerlIO system for IO (the default) these layers effect perl's IO. | |
860 | ||
861 | It is conventional to start layer names with a colon e.g. C<:perlio> to | |
862 | emphasise their similarity to variable "attributes". But the code that parses | |
863 | layer specification strings (which is also used to decode the PERLIO | |
864 | environment variable) treats the colon as a separator. | |
865 | ||
866 | The list becomes the default for I<all> perl's IO. Consequently only built-in | |
867 | layers can appear in this list, as external layers (such as :encoding()) need | |
868 | IO in order to load them!. See L<"open pragma"|open> for how to add external | |
869 | encodings as defaults. | |
870 | ||
871 | The layers that it makes sense to include in the PERLIO environment | |
872 | variable are summarised below. For more details see L<PerlIO>. | |
873 | ||
874 | =over 8 | |
875 | ||
876 | =item :bytes | |
877 | ||
878 | Turns I<off> the C<:utf8> flag for the layer below. | |
879 | Unlikely to be useful in global PERLIO environment variable. | |
880 | ||
881 | =item :crlf | |
882 | ||
883 | A layer that implements DOS/Windows like CRLF line endings. | |
884 | On read converts pairs of CR,LF to a single "\n" newline character. | |
885 | On write converts each "\n" to a CR,LF pair. | |
886 | Based on the C<:perlio> layer. | |
887 | ||
888 | =item :mmap | |
889 | ||
890 | A layer which implements "reading" of files by using C<mmap()> to | |
891 | make (whole) file appear in the process's address space, and then | |
892 | using that as PerlIO's "buffer". This I<may> be faster in certain | |
893 | circumstances for large files, and may result in less physical memory | |
894 | use when multiple processes are reading the same file. | |
895 | ||
896 | Files which are not C<mmap()>-able revert to behaving like the C<:perlio> | |
897 | layer. Writes also behave like C<:perlio> layer as C<mmap()> for write | |
898 | needs extra house-keeping (to extend the file) which negates any advantage. | |
899 | ||
900 | The C<:mmap> layer will not exist if platform does not support C<mmap()>. | |
901 | ||
902 | =item :perlio | |
903 | ||
904 | A from scratch implementation of buffering for PerlIO. Provides fast | |
905 | access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt> | |
906 | and in general attempts to minimize data copying. | |
907 | ||
908 | C<:perlio> will insert a C<:unix> layer below itself to do low level IO. | |
909 | ||
910 | =item :raw | |
911 | ||
912 | Applying the <:raw> layer is equivalent to calling C<binmode($fh)>. | |
913 | It makes the stream pass each byte as-is without any translation. | |
914 | In particular CRLF translation, and/or :utf8 inuited from locale | |
915 | are disabled. | |
916 | ||
917 | Arranges for all accesses go straight to the lowest buffered layer provided | |
918 | by the configration. That is it strips off any layers above that layer. | |
919 | ||
920 | In Perl 5.6 and some books the C<:raw> layer (previously sometimes also | |
921 | referred to as a "discipline") is documented as the inverse of the | |
922 | C<:crlf> layer. That is no longer the case - other layers which would | |
923 | alter binary nature of the stream are also disabled. If you want UNIX | |
924 | line endings on a platform that normally does CRLF translation, but still | |
925 | want UTF-8 or encoding defaults the appropriate thing to do is to add | |
926 | C<:perlio> to PERLIO environment variable. | |
927 | ||
928 | =item :stdio | |
929 | ||
930 | This layer provides PerlIO interface by wrapping system's ANSI C "stdio" | |
931 | library calls. The layer provides both buffering and IO. | |
932 | Note that C<:stdio> layer does I<not> do CRLF translation even if that | |
933 | is platforms normal behaviour. You will need a C<:crlf> layer above it | |
934 | to do that. | |
935 | ||
936 | =item :unix | |
937 | ||
938 | Lowest level layer which provides basic PerlIO operations in terms of | |
939 | UNIX/POSIX numeric file descriptor calls | |
940 | C<open(), read(), write(), lseek(), close()> | |
941 | ||
942 | =item :utf8 | |
943 | ||
944 | Turns on a flag on the layer below to tell perl that data sent to the | |
945 | stream should be converted to perl internal "utf8" form and that data from the | |
946 | stream should be considered as so encoded. On ASCII based platforms the | |
947 | encoding is UTF-8 and on EBCDIC platforms UTF-EBCDIC. | |
948 | May be useful in PERLIO environment variable to make UTF-8 the | |
949 | default. (To turn off that behaviour use C<:bytes> layer.) | |
950 | ||
951 | =item :win32 | |
952 | ||
953 | On Win32 platforms this I<experimental> layer uses native "handle" IO | |
954 | rather than unix-like numeric file descriptor layer. Known to be | |
955 | buggy in this release. | |
956 | ||
957 | =back | |
958 | ||
959 | On all platforms the default set of layers should give acceptable results. | |
960 | ||
961 | For UNIX platforms that will equivalent of "unix perlio" or "stdio". | |
962 | Configure is setup to prefer "stdio" implementation if system's library | |
963 | provides for fast access to the buffer, otherwise it uses the "unix perlio" | |
964 | implementation. | |
965 | ||
966 | On Win32 the default in this release is "unix crlf". Win32's "stdio" | |
967 | has a number of bugs/mis-features for perl IO which are somewhat | |
968 | C compiler vendor/version dependent. Using our own C<crlf> layer as | |
969 | the buffer avoids those issues and makes things more uniform. | |
970 | The C<crlf> layer provides CRLF to/from "\n" conversion as well as | |
971 | buffering. | |
972 | ||
973 | This release uses C<unix> as the bottom layer on Win32 and so still uses C | |
974 | compiler's numeric file descriptor routines. There is an experimental native | |
975 | C<win32> layer which is expected to be enhanced and should eventually replace | |
976 | the C<unix> layer. | |
977 | ||
978 | =item PERLIO_DEBUG | |
979 | ||
980 | If set to the name of a file or device then certain operations of PerlIO | |
981 | sub-system will be logged to that file (opened as append). Typical uses | |
982 | are UNIX: | |
983 | ||
984 | PERLIO_DEBUG=/dev/tty perl script ... | |
985 | ||
986 | and Win32 approximate equivalent: | |
987 | ||
988 | set PERLIO_DEBUG=CON | |
989 | perl script ... | |
990 | ||
991 | ||
992 | =item PERLLIB | |
993 | ||
994 | A colon-separated list of directories in which to look for Perl library | |
995 | files before looking in the standard library and the current directory. | |
996 | If PERL5LIB is defined, PERLLIB is not used. | |
997 | ||
998 | =item PERL5DB | |
999 | ||
1000 | The command used to load the debugger code. The default is: | |
1001 | ||
1002 | BEGIN { require 'perl5db.pl' } | |
1003 | ||
1004 | =item PERL5SHELL (specific to the Win32 port) | |
1005 | ||
1006 | May be set to an alternative shell that perl must use internally for | |
1007 | executing "backtick" commands or system(). Default is C<cmd.exe /x/c> | |
1008 | on WindowsNT and C<command.com /c> on Windows95. The value is considered | |
1009 | to be space-separated. Precede any character that needs to be protected | |
1010 | (like a space or backslash) with a backslash. | |
1011 | ||
1012 | Note that Perl doesn't use COMSPEC for this purpose because | |
1013 | COMSPEC has a high degree of variability among users, leading to | |
1014 | portability concerns. Besides, perl can use a shell that may not be | |
1015 | fit for interactive use, and setting COMSPEC to such a shell may | |
1016 | interfere with the proper functioning of other programs (which usually | |
1017 | look in COMSPEC to find a shell fit for interactive use). | |
1018 | ||
1019 | =item PERL_DEBUG_MSTATS | |
1020 | ||
1021 | Relevant only if perl is compiled with the malloc included with the perl | |
1022 | distribution (that is, if C<perl -V:d_mymalloc> is 'define'). | |
1023 | If set, this causes memory statistics to be dumped after execution. If set | |
1024 | to an integer greater than one, also causes memory statistics to be dumped | |
1025 | after compilation. | |
1026 | ||
1027 | =item PERL_DESTRUCT_LEVEL | |
1028 | ||
1029 | Relevant only if your perl executable was built with B<-DDEBUGGING>, | |
1030 | this controls the behavior of global destruction of objects and other | |
1031 | references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. | |
1032 | ||
1033 | =item PERL_ENCODING | |
1034 | ||
1035 | If using the C<encoding> pragma without an explicit encoding name, the | |
1036 | PERL_ENCODING environment variable is consulted for an encoding name. | |
1037 | ||
1038 | =item PERL_ROOT (specific to the VMS port) | |
1039 | ||
1040 | A translation concealed rooted logical name that contains perl and the | |
1041 | logical device for the @INC path on VMS only. Other logical names that | |
1042 | affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and | |
1043 | SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in | |
1044 | L<perlvms> and in F<README.vms> in the Perl source distribution. | |
1045 | ||
1046 | =item SYS$LOGIN (specific to the VMS port) | |
1047 | ||
1048 | Used if chdir has no argument and HOME and LOGDIR are not set. | |
1049 | ||
1050 | =back | |
1051 | ||
1052 | Perl also has environment variables that control how Perl handles data | |
1053 | specific to particular natural languages. See L<perllocale>. | |
1054 | ||
1055 | Apart from these, Perl uses no other environment variables, except | |
1056 | to make them available to the program being executed, and to child | |
1057 | processes. However, programs running setuid would do well to execute | |
1058 | the following lines before doing anything else, just to keep people | |
1059 | honest: | |
1060 | ||
1061 | $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need | |
1062 | $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL}; | |
1063 | delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; |