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