This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add :bytes to POD part.
[perl5.git] / pod / perlrun.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlrun - how to execute the Perl interpreter
4
5=head1 SYNOPSIS
6
6537fe72 7B<perl> S<[ B<-CsTtuUWX> ]>
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
4197b13f
MJD
304syntax tree. And B<-Dr> displays compiled regular expressions;
305the format of the output is explained in L<perldebguts>.
306
307As an alternative, specify a number instead of list of letters (e.g.,
308B<-D14> is equivalent to B<-Dtls>):
a0d0e21e 309
db2ba183
TB
310 1 p Tokenizing and parsing
311 2 s Stack snapshots
312 4 l Context (loop) stack processing
313 8 t Trace execution
314 16 o Method and overloading resolution
315 32 c String/numeric conversions
1045810a 316 64 P Print profiling info, preprocessor command for -P, source file input state
db2ba183
TB
317 128 m Memory allocation
318 256 f Format processing
319 512 r Regular expression parsing and execution
320 1024 x Syntax tree dump
321 2048 u Tainting checks
19799a22 322 4096 L Memory leaks (needs -DLEAKTEST when compiling Perl)
db2ba183
TB
323 8192 H Hash dump -- usurps values()
324 16384 X Scratchpad allocation
325 32768 D Cleaning up
8b73bbec 326 65536 S Thread synchronization
607df283 327 131072 T Tokenising
04932ac8 328 262144 R Include reference counts of dumped variables (eg when using -Ds)
1045810a 329 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB
a0d0e21e 330
19799a22 331All these flags require B<-DDEBUGGING> when you compile the Perl
1045810a
IZ
332executable (but see L<Devel::Peek>, L<re> which may change this).
333See the F<INSTALL> file in the Perl source distribution
19799a22 334for how to do this. This flag is automatically set if you include B<-g>
8c52afec
IZ
335option when C<Configure> asks you about optimizer/debugger flags.
336
19799a22
GS
337If you're just trying to get a print out of each line of Perl code
338as it executes, the way that C<sh -x> provides for shell scripts,
339you can't use Perl's B<-D> switch. Instead do this
340
c406981e
JH
341 # If you have "env" utility
342 env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
343
19799a22
GS
344 # Bourne shell syntax
345 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
346
347 # csh syntax
348 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
349
350See L<perldebug> for details and variations.
351
a0d0e21e
LW
352=item B<-e> I<commandline>
353
19799a22
GS
354may be used to enter one line of program. If B<-e> is given, Perl
355will not look for a filename in the argument list. Multiple B<-e>
356commands may be given to build up a multi-line script. Make sure
357to use semicolons where you would in a normal program.
a0d0e21e 358
e0ebc809 359=item B<-F>I<pattern>
a0d0e21e 360
e0ebc809 361specifies the pattern to split on if B<-a> is also in effect. The
5f05dabc 362pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
e0ebc809 363put in single quotes.
a0d0e21e 364
e0ebc809
PP
365=item B<-h>
366
367prints a summary of the options.
368
369=item B<-i>[I<extension>]
a0d0e21e 370
2d259d92
CK
371specifies that files processed by the C<E<lt>E<gt>> construct are to be
372edited in-place. It does this by renaming the input file, opening the
373output file by the original name, and selecting that output file as the
374default for print() statements. The extension, if supplied, is used to
375modify the name of the old file to make a backup copy, following these
376rules:
377
378If no extension is supplied, no backup is made and the current file is
379overwritten.
380
19799a22
GS
381If the extension doesn't contain a C<*>, then it is appended to the
382end of the current filename as a suffix. If the extension does
383contain one or more C<*> characters, then each C<*> is replaced
384with the current filename. In Perl terms, you could think of this
385as:
2d259d92 386
66606d78 387 ($backup = $extension) =~ s/\*/$file_name/g;
2d259d92
CK
388
389This allows you to add a prefix to the backup file, instead of (or in
390addition to) a suffix:
391
19799a22 392 $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
2d259d92
CK
393
394Or even to place backup copies of the original files into another
395directory (provided the directory already exists):
396
19799a22 397 $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
2d259d92 398
66606d78
CK
399These sets of one-liners are equivalent:
400
401 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
19799a22 402 $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file
66606d78 403
19799a22
GS
404 $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
405 $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
66606d78 406
2d259d92 407From the shell, saying
a0d0e21e 408
19799a22 409 $ perl -p -i.orig -e "s/foo/bar/; ... "
a0d0e21e 410
19799a22 411is the same as using the program:
a0d0e21e 412
19799a22 413 #!/usr/bin/perl -pi.orig
a0d0e21e
LW
414 s/foo/bar/;
415
416which is equivalent to
417
418 #!/usr/bin/perl
19799a22
GS
419 $extension = '.orig';
420 LINE: while (<>) {
a0d0e21e 421 if ($ARGV ne $oldargv) {
66606d78
CK
422 if ($extension !~ /\*/) {
423 $backup = $ARGV . $extension;
424 }
425 else {
426 ($backup = $extension) =~ s/\*/$ARGV/g;
427 }
428 rename($ARGV, $backup);
a0d0e21e
LW
429 open(ARGVOUT, ">$ARGV");
430 select(ARGVOUT);
431 $oldargv = $ARGV;
432 }
433 s/foo/bar/;
434 }
435 continue {
436 print; # this prints to original filename
437 }
438 select(STDOUT);
439
440except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
441know when the filename has changed. It does, however, use ARGVOUT for
66606d78
CK
442the selected filehandle. Note that STDOUT is restored as the default
443output filehandle after the loop.
444
445As shown above, Perl creates the backup file whether or not any output
446is actually changed. So this is just a fancy way to copy files:
447
19799a22
GS
448 $ perl -p -i '/some/file/path/*' -e 1 file1 file2 file3...
449or
450 $ perl -p -i '.orig' -e 1 file1 file2 file3...
66606d78
CK
451
452You can use C<eof> without parentheses to locate the end of each input
453file, in case you want to append to each file, or reset line numbering
454(see example in L<perlfunc/eof>).
455
456If, for a given file, Perl is unable to create the backup file as
457specified in the extension then it will skip that file and continue on
458with the next one (if it exists).
459
19799a22 460For a discussion of issues surrounding file permissions and B<-i>,
cea6626f 461see 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
462
463You cannot use B<-i> to create directories or to strip extensions from
464files.
a0d0e21e 465
19799a22
GS
466Perl does not expand C<~> in filenames, which is good, since some
467folks use it for their backup files:
a0d0e21e 468
19799a22
GS
469 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
470
471Finally, the B<-i> switch does not impede execution when no
a2008d6d
GS
472files are given on the command line. In this case, no backup is made
473(the original file cannot, of course, be determined) and processing
474proceeds from STDIN to STDOUT as might be expected.
475
a0d0e21e
LW
476=item B<-I>I<directory>
477
e0ebc809 478Directories specified by B<-I> are prepended to the search path for
1fef88e7 479modules (C<@INC>), and also tells the C preprocessor where to search for
e0ebc809
PP
480include files. The C preprocessor is invoked with B<-P>; by default it
481searches /usr/include and /usr/lib/perl.
a0d0e21e 482
e0ebc809 483=item B<-l>[I<octnum>]
a0d0e21e 484
19799a22
GS
485enables automatic line-ending processing. It has two separate
486effects. First, it automatically chomps C<$/> (the input record
487separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
488(the output record separator) to have the value of I<octnum> so
489that any print statements will have that separator added back on.
490If I<octnum> is omitted, sets C<$\> to the current value of
491C<$/>. For instance, to trim lines to 80 columns:
a0d0e21e
LW
492
493 perl -lpe 'substr($_, 80) = ""'
494
495Note that the assignment C<$\ = $/> is done when the switch is processed,
496so the input record separator can be different than the output record
497separator if the B<-l> switch is followed by a B<-0> switch:
498
499 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
500
1fef88e7 501This sets C<$\> to newline and then sets C<$/> to the null character.
a0d0e21e 502
e0ebc809
PP
503=item B<-m>[B<->]I<module>
504
505=item B<-M>[B<->]I<module>
c07a80fd 506
e0ebc809
PP
507=item B<-M>[B<->]I<'module ...'>
508
509=item B<-[mM]>[B<->]I<module=arg[,arg]...>
3c81428c 510
19799a22
GS
511B<-m>I<module> executes C<use> I<module> C<();> before executing your
512program.
3c81428c 513
19799a22
GS
514B<-M>I<module> executes C<use> I<module> C<;> before executing your
515program. You can use quotes to add extra code after the module name,
516e.g., C<'-Mmodule qw(foo bar)'>.
3c81428c 517
19799a22 518If the first character after the B<-M> or B<-m> is a dash (C<->)
a5f75d66
AD
519then the 'use' is replaced with 'no'.
520
54310121 521A little builtin syntactic sugar means you can also say
19799a22
GS
522B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for
523C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when
524importing symbols. The actual code generated by B<-Mmodule=foo,bar> is
e0ebc809 525C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
19799a22 526removes the distinction between B<-m> and B<-M>.
3c81428c 527
a0d0e21e
LW
528=item B<-n>
529
19799a22 530causes Perl to assume the following loop around your program, which
a0d0e21e
LW
531makes it iterate over filename arguments somewhat like B<sed -n> or
532B<awk>:
533
19799a22 534 LINE:
a0d0e21e 535 while (<>) {
19799a22 536 ... # your program goes here
a0d0e21e
LW
537 }
538
539Note that the lines are not printed by default. See B<-p> to have
08e9d68e 540lines printed. If a file named by an argument cannot be opened for
19799a22 541some reason, Perl warns you about it and moves on to the next file.
08e9d68e
DD
542
543Here is an efficient way to delete all files older than a week:
a0d0e21e 544
19799a22 545 find . -mtime +7 -print | perl -nle unlink
a0d0e21e 546
19799a22
GS
547This is faster than using the B<-exec> switch of B<find> because you don't
548have to start a process on every filename found. It does suffer from
549the bug of mishandling newlines in pathnames, which you can fix if
1f6995f0 550you follow the example under B<-0>.
a0d0e21e
LW
551
552C<BEGIN> and C<END> blocks may be used to capture control before or after
19799a22 553the implicit program loop, just as in B<awk>.
a0d0e21e
LW
554
555=item B<-p>
556
19799a22 557causes Perl to assume the following loop around your program, which
a0d0e21e
LW
558makes it iterate over filename arguments somewhat like B<sed>:
559
560
19799a22 561 LINE:
a0d0e21e 562 while (<>) {
19799a22 563 ... # your program goes here
a0d0e21e 564 } continue {
08e9d68e 565 print or die "-p destination: $!\n";
a0d0e21e
LW
566 }
567
08e9d68e
DD
568If a file named by an argument cannot be opened for some reason, Perl
569warns you about it, and moves on to the next file. Note that the
c2611fb3 570lines are printed automatically. An error occurring during printing is
08e9d68e
DD
571treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
572overrides a B<-n> switch.
a0d0e21e
LW
573
574C<BEGIN> and C<END> blocks may be used to capture control before or after
19799a22 575the implicit loop, just as in B<awk>.
a0d0e21e
LW
576
577=item B<-P>
578
079a94c4
JH
579B<NOTE: Use of -P is strongly discouraged because of its inherent
580problems, including poor portability.>
581
582This option causes your program to be run through the C preprocessor before
efdf3af0 583compilation by Perl. Because both comments and B<cpp> directives begin
a0d0e21e 584with the # character, you should avoid starting comments with any words
efdf3af0 585recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">.
079a94c4
JH
586
587If you're considering using C<-P>, you might also want to look at the
588Filter::cpp module from CPAN.
589
590The problems of -P include, but are not limited to:
591
592=over 10
593
594=item *
595
596The C<#!> line is stripped, so any switches there don't apply.
597
598=item *
599
600A C<-P> on a C<#!> line doesn't work.
601
602=item *
603
604B<All> lines that begin with (whitespace and) a C<#> but
605do not look like cpp commands, are stripped, including anything
606inside Perl strings, regular expressions, and here-docs .
607
608=item *
609
610In some platforms the C preprocessor knows too much: it knows about
611the C++ -style until-end-of-line comments starting with C<"//">.
efdf3af0
JH
612This will cause problems with common Perl constructs like
613
614 s/foo//;
615
616because after -P this will became illegal code
617
618 s/foo
619
620The workaround is to use some other quoting separator than C<"/">,
621like for example C<"!">:
622
623 s!foo!!;
a0d0e21e 624
079a94c4
JH
625
626
627=item *
628
629It requires not only a working C preprocessor but also a working
630F<sed>. If not on UNIX, you are probably out of luck on this.
631
632=item *
633
634Script line numbers are not preserved.
635
636=item *
637
638The C<-x> does not work with C<-P>.
639
640=back
9a1f07e7 641
a0d0e21e
LW
642=item B<-s>
643
19799a22
GS
644enables rudimentary switch parsing for switches on the command
645line after the program name but before any filename arguments (or before
3bbcc830
JP
646an argument of B<-->). This means you can have switches with two leading
647dashes (B<--help>). Any switch found there is removed from @ARGV and sets the
19799a22 648corresponding variable in the Perl program. The following program
3c0facb2
GS
649prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
650if it is invoked with B<-xyz=abc>.
a0d0e21e
LW
651
652 #!/usr/bin/perl -s
3c0facb2 653 if ($xyz) { print "$xyz\n" }
a0d0e21e 654
3bbcc830
JP
655Do note that B<--help> creates the variable ${-help}, which is not compliant
656with C<strict refs>.
657
a0d0e21e
LW
658=item B<-S>
659
660makes Perl use the PATH environment variable to search for the
19799a22
GS
661program (unless the name of the program contains directory separators).
662
2a92aaa0
GS
663On some platforms, this also makes Perl append suffixes to the
664filename while searching for it. For example, on Win32 platforms,
665the ".bat" and ".cmd" suffixes are appended if a lookup for the
666original name fails, and if the name does not already end in one
667of those suffixes. If your Perl was compiled with DEBUGGING turned
668on, using the -Dp switch to Perl shows how the search progresses.
669
2a92aaa0
GS
670Typically this is used to emulate #! startup on platforms that
671don't support #!. This example works on many platforms that
672have a shell compatible with Bourne shell:
a0d0e21e
LW
673
674 #!/usr/bin/perl
a3cb178b 675 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
a0d0e21e
LW
676 if $running_under_some_shell;
677
19799a22
GS
678The system ignores the first line and feeds the program to F</bin/sh>,
679which proceeds to try to execute the Perl program as a shell script.
a0d0e21e
LW
680The shell executes the second line as a normal shell command, and thus
681starts up the Perl interpreter. On some systems $0 doesn't always
682contain the full pathname, so the B<-S> tells Perl to search for the
19799a22 683program if necessary. After Perl locates the program, it parses the
a0d0e21e 684lines and ignores them because the variable $running_under_some_shell
19799a22 685is never true. If the program will be interpreted by csh, you will need
a3cb178b
GS
686to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
687embedded spaces (and such) in the argument list. To start up sh rather
a0d0e21e
LW
688than csh, some systems may have to replace the #! line with a line
689containing just a colon, which will be politely ignored by Perl. Other
690systems can't control that, and need a totally devious construct that
19799a22 691will work under any of B<csh>, B<sh>, or Perl, such as the following:
a0d0e21e 692
19799a22 693 eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
a3cb178b 694 & eval 'exec /usr/bin/perl -wS $0 $argv:q'
5f05dabc 695 if $running_under_some_shell;
a0d0e21e 696
19799a22
GS
697If the filename supplied contains directory separators (i.e., is an
698absolute or relative pathname), and if that file is not found,
699platforms that append file extensions will do so and try to look
700for the file with those extensions added, one by one.
701
702On DOS-like platforms, if the program does not contain directory
703separators, it will first be searched for in the current directory
704before being searched for on the PATH. On Unix platforms, the
705program will be searched for strictly on the PATH.
706
6537fe72
MS
707=item B<-t>
708
709Like B<-T>, but taint checks will issue warnings rather than fatal
317ea90d
MS
710errors. These warnings can be controlled normally with C<no warnings
711qw(taint)>.
1dbad523
JH
712
713B<NOTE: this is not a substitute for -T.> This is meant only to be
714used as a temporary development aid while securing legacy code:
715for real production code and for new secure code written from scratch
716always use the real B<-T>.
6537fe72 717
a0d0e21e
LW
718=item B<-T>
719
a3cb178b 720forces "taint" checks to be turned on so you can test them. Ordinarily
19799a22
GS
721these checks are done only when running setuid or setgid. It's a
722good idea to turn them on explicitly for programs that run on behalf
723of someone else whom you might not necessarily trust, such as CGI
724programs or any internet servers you might write in Perl. See
725L<perlsec> for details. For security reasons, this option must be
726seen by Perl quite early; usually this means it must appear early
727on the command line or in the #! line for systems which support
728that construct.
a0d0e21e
LW
729
730=item B<-u>
731
19799a22
GS
732This obsolete switch causes Perl to dump core after compiling your
733program. You can then in theory take this core dump and turn it
734into an executable file by using the B<undump> program (not supplied).
735This speeds startup at the expense of some disk space (which you
736can minimize by stripping the executable). (Still, a "hello world"
737executable comes out to about 200K on my machine.) If you want to
738execute a portion of your program before dumping, use the dump()
739operator instead. Note: availability of B<undump> is platform
740specific and may not be available for a specific port of Perl.
741
742This switch has been superseded in favor of the new Perl code
743generator backends to the compiler. See L<B> and L<B::Bytecode>
744for details.
a0d0e21e
LW
745
746=item B<-U>
747
748allows Perl to do unsafe operations. Currently the only "unsafe"
749operations are the unlinking of directories while running as superuser,
750and running setuid programs with fatal taint checks turned into
19799a22
GS
751warnings. Note that the B<-w> switch (or the C<$^W> variable) must
752be used along with this option to actually I<generate> the
fb73857a 753taint-check warnings.
a0d0e21e
LW
754
755=item B<-v>
756
19799a22 757prints the version and patchlevel of your perl executable.
a0d0e21e 758
3c81428c
PP
759=item B<-V>
760
761prints summary of the major perl configuration values and the current
19799a22 762values of @INC.
3c81428c 763
e0ebc809 764=item B<-V:>I<name>
3c81428c
PP
765
766Prints to STDOUT the value of the named configuration variable.
19799a22 767For example,
3c81428c 768
19799a22
GS
769 $ perl -V:man.dir
770
771will provide strong clues about what your MANPATH variable should
772be set to in order to access the Perl documentation.
a0d0e21e 773
19799a22 774=item B<-w>
774d564b 775
19799a22
GS
776prints warnings about dubious constructs, such as variable names
777that are mentioned only once and scalar variables that are used
778before being set, redefined subroutines, references to undefined
779filehandles or filehandles opened read-only that you are attempting
780to write on, values used as a number that doesn't look like numbers,
781using an array as though it were a scalar, if your subroutines
782recurse more than 100 deep, and innumerable other things.
783
784This switch really just enables the internal C<^$W> variable. You
785can disable or promote into fatal errors specific warnings using
786C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
787See also L<perldiag> and L<perltrap>. A new, fine-grained warning
788facility is also available if you want to manipulate entire classes
9f1b1f2d 789of warnings; see L<warnings> or L<perllexwarn>.
a0d0e21e 790
0453d815
PM
791=item B<-W>
792
3c0facb2 793Enables all warnings regardless of C<no warnings> or C<$^W>.
0453d815
PM
794See L<perllexwarn>.
795
796=item B<-X>
797
3c0facb2 798Disables all warnings regardless of C<use warnings> or C<$^W>.
0453d815
PM
799See L<perllexwarn>.
800
a0d0e21e
LW
801=item B<-x> I<directory>
802
19799a22
GS
803tells Perl that the program is embedded in a larger chunk of unrelated
804ASCII text, such as in a mail message. Leading garbage will be
805discarded until the first line that starts with #! and contains the
806string "perl". Any meaningful switches on that line will be applied.
807If a directory name is specified, Perl will switch to that directory
808before running the program. The B<-x> switch controls only the
809disposal of leading garbage. The program must be terminated with
810C<__END__> if there is trailing garbage to be ignored (the program
811can process any or all of the trailing garbage via the DATA filehandle
812if desired).
a0d0e21e 813
1e422769
PP
814=back
815
816=head1 ENVIRONMENT
817
818=over 12
819
820=item HOME
821
822Used if chdir has no argument.
823
824=item LOGDIR
825
826Used if chdir has no argument and HOME is not set.
827
828=item PATH
829
19799a22 830Used in executing subprocesses, and in finding the program if B<-S> is
1e422769
PP
831used.
832
833=item PERL5LIB
834
835A colon-separated list of directories in which to look for Perl library
836files before looking in the standard library and the current
951ba7fe
GS
837directory. Any architecture-specific directories under the specified
838locations are automatically included if they exist. If PERL5LIB is not
839defined, PERLLIB is used.
840
841When running taint checks (either because the program was running setuid
842or setgid, or the B<-T> switch was used), neither variable is used.
843The program should instead say:
1e422769
PP
844
845 use lib "/my/directory";
846
54310121
PP
847=item PERL5OPT
848
849Command-line options (switches). Switches in this variable are taken
1c4db469 850as if they were on every Perl command line. Only the B<-[DIMUdmtw]>
19799a22 851switches are allowed. When running taint checks (because the program
54310121 852was running setuid or setgid, or the B<-T> switch was used), this
74288ac8
GS
853variable is ignored. If PERL5OPT begins with B<-T>, tainting will be
854enabled, and any subsequent options ignored.
54310121 855
16537909
JH
856=item PERLIO
857
858A space-separated list of PerlIO layers.
859
860=over 8
861
862=item :bytes
863
864XXX
865
866=item :crlf
867
868XXX
869
870=item mmap
871
872XXX
873
874=item perlio
875
876XXX
877
878=item raw
879
880XXX
881
882=item stdio
883
884XXX
885
886=item unix
887
888XXX
889
890=item :utf8
891
892XXX
893
894=back
895
896For example, XXX ... for Unicode XXXX ... for Win32 XXX
897
1e422769
PP
898=item PERLLIB
899
900A colon-separated list of directories in which to look for Perl library
901files before looking in the standard library and the current directory.
902If PERL5LIB is defined, PERLLIB is not used.
903
904=item PERL5DB
905
906The command used to load the debugger code. The default is:
907
908 BEGIN { require 'perl5db.pl' }
909
19799a22 910=item PERL5SHELL (specific to the Win32 port)
174c211a
GS
911
912May be set to an alternative shell that perl must use internally for
ce1da67e
GS
913executing "backtick" commands or system(). Default is C<cmd.exe /x/c>
914on WindowsNT and C<command.com /c> on Windows95. The value is considered
19799a22 915to be space-separated. Precede any character that needs to be protected
ce1da67e
GS
916(like a space or backslash) with a backslash.
917
918Note that Perl doesn't use COMSPEC for this purpose because
919COMSPEC has a high degree of variability among users, leading to
920portability concerns. Besides, perl can use a shell that may not be
921fit for interactive use, and setting COMSPEC to such a shell may
922interfere with the proper functioning of other programs (which usually
923look in COMSPEC to find a shell fit for interactive use).
174c211a 924
1e422769
PP
925=item PERL_DEBUG_MSTATS
926
67ce8856 927Relevant only if perl is compiled with the malloc included with the perl
a3cb178b
GS
928distribution (that is, if C<perl -V:d_mymalloc> is 'define').
929If set, this causes memory statistics to be dumped after execution. If set
1e422769
PP
930to an integer greater than one, also causes memory statistics to be dumped
931after compilation.
932
933=item PERL_DESTRUCT_LEVEL
934
935Relevant only if your perl executable was built with B<-DDEBUGGING>,
936this controls the behavior of global destruction of objects and other
64cea5fd 937references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
a0d0e21e 938
5d170f3a
JH
939=item PERL_ENCODING
940
941If using the C<encoding> pragma without an explicit encoding name, the
942PERL_ENCODING environment variable is consulted for an encoding name.
943
3d0ae7ba
GS
944=item PERL_ROOT (specific to the VMS port)
945
946A translation concealed rooted logical name that contains perl and the
947logical device for the @INC path on VMS only. Other logical names that
948affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and
949SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in
950L<perlvms> and in F<README.vms> in the Perl source distribution.
951
952=item SYS$LOGIN (specific to the VMS port)
953
954Used if chdir has no argument and HOME and LOGDIR are not set.
955
a0d0e21e 956=back
1e422769
PP
957
958Perl also has environment variables that control how Perl handles data
959specific to particular natural languages. See L<perllocale>.
960
961Apart from these, Perl uses no other environment variables, except
19799a22
GS
962to make them available to the program being executed, and to child
963processes. However, programs running setuid would do well to execute
1e422769
PP
964the following lines before doing anything else, just to keep people
965honest:
966
19799a22 967 $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need
7bac28a0 968 $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
c90c0ff4 969 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};