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