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