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