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