This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Forgotten from #18715.
[perl5.git] / pod / perlrun.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlrun - how to execute the Perl interpreter
4
5=head1 SYNOPSIS
6
672fde27 7B<perl> S<[ B<-sTtuUWX> ]>
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> ]...>
a05d7ebb 17 S<[ B<-C [I<number/list>] >]> ]>
a0d0e21e
LW
18
19=head1 DESCRIPTION
20
19799a22
GS
21The normal way to run a Perl program is by making it directly
22executable, or else by passing the name of the source file as an
23argument on the command line. (An interactive Perl environment
24is also possible--see L<perldebug> for details on how to do that.)
25Upon startup, Perl looks for your program in one of the following
a0d0e21e
LW
26places:
27
28=over 4
29
30=item 1.
31
32Specified line by line via B<-e> switches on the command line.
33
34=item 2.
35
36Contained in the file specified by the first filename on the command line.
a3cb178b
GS
37(Note that systems supporting the #! notation invoke interpreters this
38way. See L<Location of Perl>.)
a0d0e21e
LW
39
40=item 3.
41
5f05dabc 42Passed in implicitly via standard input. This works only if there are
19799a22
GS
43no filename arguments--to pass arguments to a STDIN-read program you
44must explicitly specify a "-" for the program name.
a0d0e21e
LW
45
46=back
47
48With methods 2 and 3, Perl starts parsing the input file from the
49beginning, unless you've specified a B<-x> switch, in which case it
50scans for the first line starting with #! and containing the word
19799a22 51"perl", and starts there instead. This is useful for running a program
a0d0e21e 52embedded in a larger message. (In this case you would indicate the end
19799a22 53of the program using the C<__END__> token.)
a0d0e21e 54
5f05dabc
PP
55The #! line is always examined for switches as the line is being
56parsed. Thus, if you're on a machine that allows only one argument
57with the #! line, or worse, doesn't even recognize the #! line, you
58still can get consistent switch behavior regardless of how Perl was
19799a22
GS
59invoked, even if B<-x> was used to find the beginning of the program.
60
61Because historically some operating systems silently chopped off
62kernel interpretation of the #! line after 32 characters, some
63switches may be passed in on the command line, and some may not;
64you could even get a "-" without its letter, if you're not careful.
65You probably want to make sure that all your switches fall either
66before or after that 32-character boundary. Most switches don't
67actually care if they're processed redundantly, but getting a "-"
68instead of a complete switch could cause Perl to try to execute
69standard input instead of your program. And a partial B<-I> switch
a0d0e21e
LW
70could also cause odd results.
71
19799a22
GS
72Some switches do care if they are processed twice, for instance
73combinations of B<-l> and B<-0>. Either put all the switches after
74the 32-character boundary (if applicable), or replace the use of
75B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>.
fb73857a 76
a0d0e21e
LW
77Parsing of the #! switches starts wherever "perl" is mentioned in the line.
78The sequences "-*" and "- " are specifically ignored so that you could,
79if you were so inclined, say
80
81 #!/bin/sh -- # -*- perl -*- -p
19799a22 82 eval 'exec perl -wS $0 ${1+"$@"}'
5f05dabc 83 if $running_under_some_shell;
a0d0e21e 84
44a4342c 85to let Perl see the B<-p> switch.
19799a22
GS
86
87A similar trick involves the B<env> program, if you have it.
88
89 #!/usr/bin/env perl
90
91The examples above use a relative path to the perl interpreter,
92getting whatever version is first in the user's path. If you want
93a specific version of Perl, say, perl5.005_57, you should place
94that directly in the #! line's path.
a0d0e21e
LW
95
96If the #! line does not contain the word "perl", the program named after
97the #! is executed instead of the Perl interpreter. This is slightly
98bizarre, but it helps people on machines that don't do #!, because they
19799a22 99can tell a program that their SHELL is F</usr/bin/perl>, and Perl will then
a0d0e21e
LW
100dispatch the program to the correct interpreter for them.
101
19799a22 102After locating your program, Perl compiles the entire program to an
a0d0e21e 103internal form. If there are any compilation errors, execution of the
19799a22 104program is not attempted. (This is unlike the typical shell script,
54310121 105which might run part-way through before finding a syntax error.)
a0d0e21e 106
19799a22 107If the program is syntactically correct, it is executed. If the program
a0d0e21e
LW
108runs off the end without hitting an exit() or die() operator, an implicit
109C<exit(0)> is provided to indicate successful completion.
110
68dc0745
PP
111=head2 #! and quoting on non-Unix systems
112
113Unix's #! technique can be simulated on other systems:
114
115=over 4
116
117=item OS/2
118
119Put
120
121 extproc perl -S -your_switches
122
19799a22 123as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's
68dc0745
PP
124`extproc' handling).
125
54310121 126=item MS-DOS
68dc0745 127
19799a22 128Create a batch file to run your program, and codify it in
68dc0745
PP
129C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source
130distribution for more information).
131
132=item Win95/NT
133
6c6a61e2 134The Win95/NT installation, when using the ActiveState installer for Perl,
c8db1d39 135will modify the Registry to associate the F<.pl> extension with the perl
6c6a61e2
GS
136interpreter. If you install Perl by other means (including building from
137the sources), you may have to modify the Registry yourself. Note that
138this means you can no longer tell the difference between an executable
139Perl program and a Perl library file.
68dc0745
PP
140
141=item Macintosh
142
19799a22 143A Macintosh perl program will have the appropriate Creator and
68dc0745
PP
144Type, so that double-clicking them will invoke the perl application.
145
bd3fa61c
CB
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
GS
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
CB
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
PP
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
PP
168
169On some systems, you may have to change single-quotes to double ones,
e6f03d26 170which you must I<not> do on Unix or Plan 9 systems. You might also
68dc0745
PP
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
PP
179 perl -e "print \"Hello world\n\""
180
54310121 181 # Macintosh
68dc0745
PP
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
GS
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
PP
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
PP
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
PP
201characters as control characters.
202
203There is no general solution to all of this. It's just a mess.
204
a3cb178b
GS
205=head2 Location of Perl
206
207It may seem obvious to say, but Perl is useful only when users can
19799a22
GS
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
GS
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
GS
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
LW
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
LW
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
LW
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
LW
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
a05d7ebb 268=item B<-C [I<number/list>]>
46487f74 269
a05d7ebb
JH
270The C<-C> flag controls some Unicode of the Perl Unicode features.
271
272As of 5.8.1, the C<-C> can be followed either by a number or a list
273of option letters.
274
275 I 0x0001 STDIN is assumed to be in UTF-8
276 O 0x0002 STDOUT will be in UTF-8
277 E 0x0004 STDERR will be in UTF-8
278 S 0x0007 I + O + E
279 i 0x0008 the default input layer expects UTF-8
280 o 0x0010 the default output layer enforces UTF-8
281 D 0x0018 i + o
282 A 0x0020 the @ARGV elements are supposed to be in UTF-8
283 L 0x0040 normally the IOEio (SD) are unconditional,
284 the L makes them conditional on the locale environment
285 variables (the LC_ALL, LC_TYPE, and LANG; in the order
286 of decreasing precedence)
287
288The C<-C> on its own (not followed by any number or option list) has
289the same effect as <-CSDL>. In other words, the standard I/O handles
290and the default C<open()> layer are UTF-8-fied B<but> only if the locale
291environment variables indicate a UTF-8 locale. This behavior follows
292the I<implicit> behaviour of Perl 5.8.0.
293
294You can use C<-C0> to explicitly disable all the above Unicode features.
fde18df1 295
fde18df1 296See L<perluniintro>, L<perlfunc/open>, and L<open> for more information.
a05d7ebb
JH
297
298The magic variable C<${^UNICODE}> reflects the state of this setting,
299see L<perlvar/"${^UNICODE}">. (Another way of setting this variable
300is to set the environment variable PERL_UNICODE.)
fde18df1
JH
301
302(In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch
303that enabled the use of Unicode-aware "wide system call" Win32 APIs.
304This feature was practically unused, however, and the command line
305switch was therefore "recycled".)
46487f74 306
a0d0e21e
LW
307=item B<-c>
308
19799a22 309causes Perl to check the syntax of the program and then exit without
7d30b5c4 310executing it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and
4f25aa18
GS
311C<use> blocks, because these are considered as occurring outside the
312execution of your program. C<INIT> and C<END> blocks, however, will
313be skipped.
a0d0e21e
LW
314
315=item B<-d>
316
19799a22 317runs the program under the Perl debugger. See L<perldebug>.
a0d0e21e 318
70c94a19 319=item B<-d:>I<foo[=bar,baz]>
3c81428c 320
19799a22
GS
321runs the program under the control of a debugging, profiling, or
322tracing module installed as Devel::foo. E.g., B<-d:DProf> executes
70c94a19
RR
323the program using the Devel::DProf profiler. As with the B<-M>
324flag, options may be passed to the Devel::foo package where they
325will be received and interpreted by the Devel::foo::import routine.
326The comma-separated list of options must follow a C<=> character.
327See L<perldebug>.
3c81428c 328
db2ba183 329=item B<-D>I<letters>
a0d0e21e 330
db2ba183 331=item B<-D>I<number>
a0d0e21e 332
19799a22 333sets debugging flags. To watch how it executes your program, use
db2ba183
TB
334B<-Dtls>. (This works only if debugging is compiled into your
335Perl.) Another nice value is B<-Dx>, which lists your compiled
4197b13f 336syntax tree. And B<-Dr> displays compiled regular expressions;
44a4342c 337the format of the output is explained in L<perldebguts>.
4197b13f
MJD
338
339As an alternative, specify a number instead of list of letters (e.g.,
340B<-D14> is equivalent to B<-Dtls>):
a0d0e21e 341
db2ba183
TB
342 1 p Tokenizing and parsing
343 2 s Stack snapshots
d6721266 344 with v, displays all stacks
db2ba183
TB
345 4 l Context (loop) stack processing
346 8 t Trace execution
347 16 o Method and overloading resolution
348 32 c String/numeric conversions
1045810a 349 64 P Print profiling info, preprocessor command for -P, source file input state
db2ba183
TB
350 128 m Memory allocation
351 256 f Format processing
352 512 r Regular expression parsing and execution
353 1024 x Syntax tree dump
354 2048 u Tainting checks
7bab3ede 355 4096 (Obsolete, previously used for LEAKTEST)
db2ba183
TB
356 8192 H Hash dump -- usurps values()
357 16384 X Scratchpad allocation
358 32768 D Cleaning up
8b73bbec 359 65536 S Thread synchronization
607df283 360 131072 T Tokenising
04932ac8 361 262144 R Include reference counts of dumped variables (eg when using -Ds)
1045810a 362 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB
d6721266 363 1048576 v Verbose: use in conjunction with other flags
46187eeb 364 2097152 C Copy On Write
a0d0e21e 365
19799a22 366All these flags require B<-DDEBUGGING> when you compile the Perl
1045810a 367executable (but see L<Devel::Peek>, L<re> which may change this).
44a4342c 368See the F<INSTALL> file in the Perl source distribution
19799a22 369for how to do this. This flag is automatically set if you include B<-g>
8c52afec
IZ
370option when C<Configure> asks you about optimizer/debugger flags.
371
19799a22
GS
372If you're just trying to get a print out of each line of Perl code
373as it executes, the way that C<sh -x> provides for shell scripts,
44a4342c 374you can't use Perl's B<-D> switch. Instead do this
19799a22 375
c406981e
JH
376 # If you have "env" utility
377 env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
378
19799a22
GS
379 # Bourne shell syntax
380 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
381
382 # csh syntax
383 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
384
385See L<perldebug> for details and variations.
386
a0d0e21e
LW
387=item B<-e> I<commandline>
388
19799a22
GS
389may be used to enter one line of program. If B<-e> is given, Perl
390will not look for a filename in the argument list. Multiple B<-e>
391commands may be given to build up a multi-line script. Make sure
392to use semicolons where you would in a normal program.
a0d0e21e 393
e0ebc809 394=item B<-F>I<pattern>
a0d0e21e 395
e0ebc809 396specifies the pattern to split on if B<-a> is also in effect. The
5f05dabc 397pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
e0ebc809 398put in single quotes.
a0d0e21e 399
e0ebc809
PP
400=item B<-h>
401
402prints a summary of the options.
403
404=item B<-i>[I<extension>]
a0d0e21e 405
2d259d92
CK
406specifies that files processed by the C<E<lt>E<gt>> construct are to be
407edited in-place. It does this by renaming the input file, opening the
408output file by the original name, and selecting that output file as the
409default for print() statements. The extension, if supplied, is used to
410modify the name of the old file to make a backup copy, following these
411rules:
412
413If no extension is supplied, no backup is made and the current file is
414overwritten.
415
19799a22
GS
416If the extension doesn't contain a C<*>, then it is appended to the
417end of the current filename as a suffix. If the extension does
418contain one or more C<*> characters, then each C<*> is replaced
419with the current filename. In Perl terms, you could think of this
420as:
2d259d92 421
66606d78 422 ($backup = $extension) =~ s/\*/$file_name/g;
2d259d92
CK
423
424This allows you to add a prefix to the backup file, instead of (or in
425addition to) a suffix:
426
19799a22 427 $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
2d259d92
CK
428
429Or even to place backup copies of the original files into another
430directory (provided the directory already exists):
431
19799a22 432 $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
2d259d92 433
66606d78
CK
434These sets of one-liners are equivalent:
435
436 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
19799a22 437 $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file
66606d78 438
19799a22
GS
439 $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
440 $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
66606d78 441
2d259d92 442From the shell, saying
a0d0e21e 443
19799a22 444 $ perl -p -i.orig -e "s/foo/bar/; ... "
a0d0e21e 445
19799a22 446is the same as using the program:
a0d0e21e 447
19799a22 448 #!/usr/bin/perl -pi.orig
a0d0e21e
LW
449 s/foo/bar/;
450
451which is equivalent to
452
453 #!/usr/bin/perl
19799a22
GS
454 $extension = '.orig';
455 LINE: while (<>) {
a0d0e21e 456 if ($ARGV ne $oldargv) {
66606d78
CK
457 if ($extension !~ /\*/) {
458 $backup = $ARGV . $extension;
459 }
460 else {
461 ($backup = $extension) =~ s/\*/$ARGV/g;
462 }
463 rename($ARGV, $backup);
a0d0e21e
LW
464 open(ARGVOUT, ">$ARGV");
465 select(ARGVOUT);
466 $oldargv = $ARGV;
467 }
468 s/foo/bar/;
469 }
470 continue {
471 print; # this prints to original filename
472 }
473 select(STDOUT);
474
475except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
476know when the filename has changed. It does, however, use ARGVOUT for
66606d78
CK
477the selected filehandle. Note that STDOUT is restored as the default
478output filehandle after the loop.
479
480As shown above, Perl creates the backup file whether or not any output
481is actually changed. So this is just a fancy way to copy files:
482
cd2d1bac 483 $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
19799a22 484or
cd2d1bac 485 $ perl -p -i'.orig' -e 1 file1 file2 file3...
66606d78
CK
486
487You can use C<eof> without parentheses to locate the end of each input
488file, in case you want to append to each file, or reset line numbering
489(see example in L<perlfunc/eof>).
490
491If, for a given file, Perl is unable to create the backup file as
492specified in the extension then it will skip that file and continue on
493with the next one (if it exists).
494
19799a22 495For a discussion of issues surrounding file permissions and B<-i>,
cea6626f 496see 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
497
498You cannot use B<-i> to create directories or to strip extensions from
499files.
a0d0e21e 500
19799a22
GS
501Perl does not expand C<~> in filenames, which is good, since some
502folks use it for their backup files:
a0d0e21e 503
19799a22
GS
504 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
505
506Finally, the B<-i> switch does not impede execution when no
a2008d6d
GS
507files are given on the command line. In this case, no backup is made
508(the original file cannot, of course, be determined) and processing
509proceeds from STDIN to STDOUT as might be expected.
510
a0d0e21e
LW
511=item B<-I>I<directory>
512
e0ebc809 513Directories specified by B<-I> are prepended to the search path for
1fef88e7 514modules (C<@INC>), and also tells the C preprocessor where to search for
e0ebc809
PP
515include files. The C preprocessor is invoked with B<-P>; by default it
516searches /usr/include and /usr/lib/perl.
a0d0e21e 517
e0ebc809 518=item B<-l>[I<octnum>]
a0d0e21e 519
19799a22
GS
520enables automatic line-ending processing. It has two separate
521effects. First, it automatically chomps C<$/> (the input record
522separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
523(the output record separator) to have the value of I<octnum> so
524that any print statements will have that separator added back on.
525If I<octnum> is omitted, sets C<$\> to the current value of
526C<$/>. For instance, to trim lines to 80 columns:
a0d0e21e
LW
527
528 perl -lpe 'substr($_, 80) = ""'
529
530Note that the assignment C<$\ = $/> is done when the switch is processed,
531so the input record separator can be different than the output record
532separator if the B<-l> switch is followed by a B<-0> switch:
533
534 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
535
1fef88e7 536This sets C<$\> to newline and then sets C<$/> to the null character.
a0d0e21e 537
e0ebc809
PP
538=item B<-m>[B<->]I<module>
539
540=item B<-M>[B<->]I<module>
c07a80fd 541
e0ebc809
PP
542=item B<-M>[B<->]I<'module ...'>
543
544=item B<-[mM]>[B<->]I<module=arg[,arg]...>
3c81428c 545
19799a22
GS
546B<-m>I<module> executes C<use> I<module> C<();> before executing your
547program.
3c81428c 548
19799a22
GS
549B<-M>I<module> executes C<use> I<module> C<;> before executing your
550program. You can use quotes to add extra code after the module name,
551e.g., C<'-Mmodule qw(foo bar)'>.
3c81428c 552
19799a22 553If the first character after the B<-M> or B<-m> is a dash (C<->)
a5f75d66
AD
554then the 'use' is replaced with 'no'.
555
54310121 556A little builtin syntactic sugar means you can also say
19799a22
GS
557B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for
558C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when
559importing symbols. The actual code generated by B<-Mmodule=foo,bar> is
e0ebc809 560C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
19799a22 561removes the distinction between B<-m> and B<-M>.
3c81428c 562
a0d0e21e
LW
563=item B<-n>
564
19799a22 565causes Perl to assume the following loop around your program, which
a0d0e21e
LW
566makes it iterate over filename arguments somewhat like B<sed -n> or
567B<awk>:
568
19799a22 569 LINE:
a0d0e21e 570 while (<>) {
19799a22 571 ... # your program goes here
a0d0e21e
LW
572 }
573
574Note that the lines are not printed by default. See B<-p> to have
08e9d68e 575lines printed. If a file named by an argument cannot be opened for
19799a22 576some reason, Perl warns you about it and moves on to the next file.
08e9d68e
DD
577
578Here is an efficient way to delete all files older than a week:
a0d0e21e 579
19799a22 580 find . -mtime +7 -print | perl -nle unlink
a0d0e21e 581
19799a22
GS
582This is faster than using the B<-exec> switch of B<find> because you don't
583have to start a process on every filename found. It does suffer from
584the bug of mishandling newlines in pathnames, which you can fix if
44a4342c 585you follow the example under B<-0>.
a0d0e21e
LW
586
587C<BEGIN> and C<END> blocks may be used to capture control before or after
19799a22 588the implicit program loop, just as in B<awk>.
a0d0e21e
LW
589
590=item B<-p>
591
19799a22 592causes Perl to assume the following loop around your program, which
a0d0e21e
LW
593makes it iterate over filename arguments somewhat like B<sed>:
594
595
19799a22 596 LINE:
a0d0e21e 597 while (<>) {
19799a22 598 ... # your program goes here
a0d0e21e 599 } continue {
08e9d68e 600 print or die "-p destination: $!\n";
a0d0e21e
LW
601 }
602
08e9d68e
DD
603If a file named by an argument cannot be opened for some reason, Perl
604warns you about it, and moves on to the next file. Note that the
c2611fb3 605lines are printed automatically. An error occurring during printing is
08e9d68e
DD
606treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
607overrides a B<-n> switch.
a0d0e21e
LW
608
609C<BEGIN> and C<END> blocks may be used to capture control before or after
19799a22 610the implicit loop, just as in B<awk>.
a0d0e21e
LW
611
612=item B<-P>
613
079a94c4
JH
614B<NOTE: Use of -P is strongly discouraged because of its inherent
615problems, including poor portability.>
616
617This option causes your program to be run through the C preprocessor before
efdf3af0 618compilation by Perl. Because both comments and B<cpp> directives begin
a0d0e21e 619with the # character, you should avoid starting comments with any words
efdf3af0 620recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">.
079a94c4
JH
621
622If you're considering using C<-P>, you might also want to look at the
623Filter::cpp module from CPAN.
624
625The problems of -P include, but are not limited to:
626
627=over 10
628
629=item *
630
631The C<#!> line is stripped, so any switches there don't apply.
632
633=item *
634
635A C<-P> on a C<#!> line doesn't work.
636
637=item *
638
639B<All> lines that begin with (whitespace and) a C<#> but
640do not look like cpp commands, are stripped, including anything
44a4342c 641inside Perl strings, regular expressions, and here-docs .
079a94c4
JH
642
643=item *
644
645In some platforms the C preprocessor knows too much: it knows about
646the C++ -style until-end-of-line comments starting with C<"//">.
efdf3af0
JH
647This will cause problems with common Perl constructs like
648
649 s/foo//;
650
651because after -P this will became illegal code
652
653 s/foo
654
655The workaround is to use some other quoting separator than C<"/">,
656like for example C<"!">:
657
658 s!foo!!;
a0d0e21e 659
079a94c4
JH
660
661
662=item *
663
664It requires not only a working C preprocessor but also a working
665F<sed>. If not on UNIX, you are probably out of luck on this.
666
667=item *
668
669Script line numbers are not preserved.
670
671=item *
672
673The C<-x> does not work with C<-P>.
674
675=back
9a1f07e7 676
a0d0e21e
LW
677=item B<-s>
678
19799a22
GS
679enables rudimentary switch parsing for switches on the command
680line after the program name but before any filename arguments (or before
3bbcc830
JP
681an argument of B<-->). This means you can have switches with two leading
682dashes (B<--help>). Any switch found there is removed from @ARGV and sets the
19799a22 683corresponding variable in the Perl program. The following program
3c0facb2
GS
684prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
685if it is invoked with B<-xyz=abc>.
a0d0e21e
LW
686
687 #!/usr/bin/perl -s
3c0facb2 688 if ($xyz) { print "$xyz\n" }
a0d0e21e 689
3bbcc830
JP
690Do note that B<--help> creates the variable ${-help}, which is not compliant
691with C<strict refs>.
692
a0d0e21e
LW
693=item B<-S>
694
695makes Perl use the PATH environment variable to search for the
19799a22
GS
696program (unless the name of the program contains directory separators).
697
2a92aaa0
GS
698On some platforms, this also makes Perl append suffixes to the
699filename while searching for it. For example, on Win32 platforms,
700the ".bat" and ".cmd" suffixes are appended if a lookup for the
701original name fails, and if the name does not already end in one
702of those suffixes. If your Perl was compiled with DEBUGGING turned
703on, using the -Dp switch to Perl shows how the search progresses.
704
2a92aaa0
GS
705Typically this is used to emulate #! startup on platforms that
706don't support #!. This example works on many platforms that
707have a shell compatible with Bourne shell:
a0d0e21e
LW
708
709 #!/usr/bin/perl
a3cb178b 710 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
a0d0e21e
LW
711 if $running_under_some_shell;
712
19799a22
GS
713The system ignores the first line and feeds the program to F</bin/sh>,
714which proceeds to try to execute the Perl program as a shell script.
a0d0e21e
LW
715The shell executes the second line as a normal shell command, and thus
716starts up the Perl interpreter. On some systems $0 doesn't always
717contain the full pathname, so the B<-S> tells Perl to search for the
19799a22 718program if necessary. After Perl locates the program, it parses the
a0d0e21e 719lines and ignores them because the variable $running_under_some_shell
19799a22 720is never true. If the program will be interpreted by csh, you will need
a3cb178b
GS
721to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
722embedded spaces (and such) in the argument list. To start up sh rather
a0d0e21e
LW
723than csh, some systems may have to replace the #! line with a line
724containing just a colon, which will be politely ignored by Perl. Other
725systems can't control that, and need a totally devious construct that
19799a22 726will work under any of B<csh>, B<sh>, or Perl, such as the following:
a0d0e21e 727
19799a22 728 eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
a3cb178b 729 & eval 'exec /usr/bin/perl -wS $0 $argv:q'
5f05dabc 730 if $running_under_some_shell;
a0d0e21e 731
19799a22
GS
732If the filename supplied contains directory separators (i.e., is an
733absolute or relative pathname), and if that file is not found,
734platforms that append file extensions will do so and try to look
735for the file with those extensions added, one by one.
736
737On DOS-like platforms, if the program does not contain directory
738separators, it will first be searched for in the current directory
739before being searched for on the PATH. On Unix platforms, the
740program will be searched for strictly on the PATH.
741
6537fe72
MS
742=item B<-t>
743
744Like B<-T>, but taint checks will issue warnings rather than fatal
317ea90d
MS
745errors. These warnings can be controlled normally with C<no warnings
746qw(taint)>.
1dbad523
JH
747
748B<NOTE: this is not a substitute for -T.> This is meant only to be
749used as a temporary development aid while securing legacy code:
750for real production code and for new secure code written from scratch
751always use the real B<-T>.
6537fe72 752
a0d0e21e
LW
753=item B<-T>
754
a3cb178b 755forces "taint" checks to be turned on so you can test them. Ordinarily
19799a22
GS
756these checks are done only when running setuid or setgid. It's a
757good idea to turn them on explicitly for programs that run on behalf
758of someone else whom you might not necessarily trust, such as CGI
759programs or any internet servers you might write in Perl. See
760L<perlsec> for details. For security reasons, this option must be
761seen by Perl quite early; usually this means it must appear early
762on the command line or in the #! line for systems which support
763that construct.
a0d0e21e
LW
764
765=item B<-u>
766
19799a22
GS
767This obsolete switch causes Perl to dump core after compiling your
768program. You can then in theory take this core dump and turn it
769into an executable file by using the B<undump> program (not supplied).
770This speeds startup at the expense of some disk space (which you
771can minimize by stripping the executable). (Still, a "hello world"
772executable comes out to about 200K on my machine.) If you want to
773execute a portion of your program before dumping, use the dump()
774operator instead. Note: availability of B<undump> is platform
775specific and may not be available for a specific port of Perl.
776
777This switch has been superseded in favor of the new Perl code
778generator backends to the compiler. See L<B> and L<B::Bytecode>
779for details.
a0d0e21e
LW
780
781=item B<-U>
782
783allows Perl to do unsafe operations. Currently the only "unsafe"
784operations are the unlinking of directories while running as superuser,
785and running setuid programs with fatal taint checks turned into
19799a22
GS
786warnings. Note that the B<-w> switch (or the C<$^W> variable) must
787be used along with this option to actually I<generate> the
fb73857a 788taint-check warnings.
a0d0e21e
LW
789
790=item B<-v>
791
19799a22 792prints the version and patchlevel of your perl executable.
a0d0e21e 793
3c81428c
PP
794=item B<-V>
795
796prints summary of the major perl configuration values and the current
19799a22 797values of @INC.
3c81428c 798
e0ebc809 799=item B<-V:>I<name>
3c81428c
PP
800
801Prints to STDOUT the value of the named configuration variable.
44a4342c 802For example,
3c81428c 803
19799a22
GS
804 $ perl -V:man.dir
805
806will provide strong clues about what your MANPATH variable should
807be set to in order to access the Perl documentation.
a0d0e21e 808
19799a22 809=item B<-w>
774d564b 810
19799a22
GS
811prints warnings about dubious constructs, such as variable names
812that are mentioned only once and scalar variables that are used
813before being set, redefined subroutines, references to undefined
814filehandles or filehandles opened read-only that you are attempting
815to write on, values used as a number that doesn't look like numbers,
816using an array as though it were a scalar, if your subroutines
817recurse more than 100 deep, and innumerable other things.
818
b40da996 819This switch really just enables the internal C<$^W> variable. You
19799a22
GS
820can disable or promote into fatal errors specific warnings using
821C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
822See also L<perldiag> and L<perltrap>. A new, fine-grained warning
823facility is also available if you want to manipulate entire classes
9f1b1f2d 824of warnings; see L<warnings> or L<perllexwarn>.
a0d0e21e 825
0453d815
PM
826=item B<-W>
827
3c0facb2 828Enables all warnings regardless of C<no warnings> or C<$^W>.
0453d815
PM
829See L<perllexwarn>.
830
831=item B<-X>
832
3c0facb2 833Disables all warnings regardless of C<use warnings> or C<$^W>.
0453d815
PM
834See L<perllexwarn>.
835
a0d0e21e
LW
836=item B<-x> I<directory>
837
19799a22
GS
838tells Perl that the program is embedded in a larger chunk of unrelated
839ASCII text, such as in a mail message. Leading garbage will be
840discarded until the first line that starts with #! and contains the
841string "perl". Any meaningful switches on that line will be applied.
842If a directory name is specified, Perl will switch to that directory
843before running the program. The B<-x> switch controls only the
844disposal of leading garbage. The program must be terminated with
845C<__END__> if there is trailing garbage to be ignored (the program
846can process any or all of the trailing garbage via the DATA filehandle
847if desired).
a0d0e21e 848
1e422769
PP
849=back
850
851=head1 ENVIRONMENT
852
853=over 12
854
855=item HOME
856
857Used if chdir has no argument.
858
859=item LOGDIR
860
861Used if chdir has no argument and HOME is not set.
862
863=item PATH
864
19799a22 865Used in executing subprocesses, and in finding the program if B<-S> is
1e422769
PP
866used.
867
868=item PERL5LIB
869
870A colon-separated list of directories in which to look for Perl library
871files before looking in the standard library and the current
951ba7fe
GS
872directory. Any architecture-specific directories under the specified
873locations are automatically included if they exist. If PERL5LIB is not
874defined, PERLLIB is used.
875
876When running taint checks (either because the program was running setuid
877or setgid, or the B<-T> switch was used), neither variable is used.
878The program should instead say:
1e422769
PP
879
880 use lib "/my/directory";
881
54310121
PP
882=item PERL5OPT
883
884Command-line options (switches). Switches in this variable are taken
1c4db469 885as if they were on every Perl command line. Only the B<-[DIMUdmtw]>
19799a22 886switches are allowed. When running taint checks (because the program
54310121 887was running setuid or setgid, or the B<-T> switch was used), this
74288ac8
GS
888variable is ignored. If PERL5OPT begins with B<-T>, tainting will be
889enabled, and any subsequent options ignored.
54310121 890
16537909
JH
891=item PERLIO
892
44a4342c 893A space (or colon) separated list of PerlIO layers. If perl is built
03d9e98a 894to use PerlIO system for IO (the default) these layers effect perl's IO.
44a4342c
NIS
895
896It is conventional to start layer names with a colon e.g. C<:perlio> to
897emphasise their similarity to variable "attributes". But the code that parses
898layer specification strings (which is also used to decode the PERLIO
899environment variable) treats the colon as a separator.
900
901The list becomes the default for I<all> perl's IO. Consequently only built-in
902layers can appear in this list, as external layers (such as :encoding()) need
903IO in order to load them!. See L<"open pragma"|open> for how to add external
904encodings as defaults.
905
906The layers that it makes sense to include in the PERLIO environment
907variable are summarised below. For more details see L<PerlIO>.
16537909
JH
908
909=over 8
910
911=item :bytes
912
44a4342c 913Turns I<off> the C<:utf8> flag for the layer below.
99366417 914Unlikely to be useful in global PERLIO environment variable.
16537909
JH
915
916=item :crlf
917
44a4342c
NIS
918A layer that implements DOS/Windows like CRLF line endings.
919On read converts pairs of CR,LF to a single "\n" newline character.
920On write converts each "\n" to a CR,LF pair.
921Based on the C<:perlio> layer.
922
923=item :mmap
924
925A layer which implements "reading" of files by using C<mmap()> to
926make (whole) file appear in the process's address space, and then
927using that as PerlIO's "buffer". This I<may> be faster in certain
928circumstances for large files, and may result in less physical memory
929use when multiple processes are reading the same file.
16537909 930
44a4342c
NIS
931Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
932layer. Writes also behave like C<:perlio> layer as C<mmap()> for write
933needs extra house-keeping (to extend the file) which negates any advantage.
16537909 934
44a4342c 935The C<:mmap> layer will not exist if platform does not support C<mmap()>.
16537909 936
44a4342c 937=item :perlio
16537909 938
44a4342c
NIS
939A from scratch implementation of buffering for PerlIO. Provides fast
940access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt>
941and in general attempts to minimize data copying.
16537909 942
44a4342c 943C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
16537909 944
44a4342c 945=item :raw
16537909 946
0226bbdb
NIS
947Applying the <:raw> layer is equivalent to calling C<binmode($fh)>.
948It makes the stream pass each byte as-is without any translation.
949In particular CRLF translation, and/or :utf8 inuited from locale
950are disabled.
1cbfc93d 951
0226bbdb 952Arranges for all accesses go straight to the lowest buffered layer provided
44a4342c 953by the configration. That is it strips off any layers above that layer.
16537909 954
fae2c0fb
RGS
955In Perl 5.6 and some books the C<:raw> layer (previously sometimes also
956referred to as a "discipline") is documented as the inverse of the
957C<:crlf> layer. That is no longer the case - other layers which would
958alter binary nature of the stream are also disabled. If you want UNIX
959line endings on a platform that normally does CRLF translation, but still
960want UTF-8 or encoding defaults the appropriate thing to do is to add
961C<:perlio> to PERLIO environment variable.
16537909 962
44a4342c
NIS
963=item :stdio
964
965This layer provides PerlIO interface by wrapping system's ANSI C "stdio"
966library calls. The layer provides both buffering and IO.
967Note that C<:stdio> layer does I<not> do CRLF translation even if that
968is platforms normal behaviour. You will need a C<:crlf> layer above it
969to do that.
970
971=item :unix
972
973Lowest level layer which provides basic PerlIO operations in terms of
974UNIX/POSIX numeric file descriptor calls
975C<open(), read(), write(), lseek(), close()>
16537909
JH
976
977=item :utf8
978
44a4342c
NIS
979Turns on a flag on the layer below to tell perl that data sent to the
980stream should be converted to perl internal "utf8" form and that data from the
981stream should be considered as so encoded. On ASCII based platforms the
982encoding is UTF-8 and on EBCDIC platforms UTF-EBCDIC.
983May be useful in PERLIO environment variable to make UTF-8 the
984default. (To turn off that behaviour use C<:bytes> layer.)
985
986=item :win32
987
ab4f7683 988On Win32 platforms this I<experimental> layer uses native "handle" IO
44a4342c
NIS
989rather than unix-like numeric file descriptor layer. Known to be
990buggy in this release.
16537909
JH
991
992=back
993
44a4342c
NIS
994On all platforms the default set of layers should give acceptable results.
995
ab4f7683 996For UNIX platforms that will equivalent of "unix perlio" or "stdio".
44a4342c
NIS
997Configure is setup to prefer "stdio" implementation if system's library
998provides for fast access to the buffer, otherwise it uses the "unix perlio"
999implementation.
1000
1001On Win32 the default in this release is "unix crlf". Win32's "stdio"
1002has a number of bugs/mis-features for perl IO which are somewhat
99366417 1003C compiler vendor/version dependent. Using our own C<crlf> layer as
44a4342c
NIS
1004the buffer avoids those issues and makes things more uniform.
1005The C<crlf> layer provides CRLF to/from "\n" conversion as well as
1006buffering.
1007
1008This release uses C<unix> as the bottom layer on Win32 and so still uses C
1009compiler's numeric file descriptor routines. There is an experimental native
1010C<win32> layer which is expected to be enhanced and should eventually replace
1011the C<unix> layer.
1012
1013=item PERLIO_DEBUG
1014
1015If set to the name of a file or device then certain operations of PerlIO
1016sub-system will be logged to that file (opened as append). Typical uses
1017are UNIX:
1018
1019 PERLIO_DEBUG=/dev/tty perl script ...
1020
1021and Win32 approximate equivalent:
1022
1023 set PERLIO_DEBUG=CON
1024 perl script ...
1025
16537909 1026
1e422769
PP
1027=item PERLLIB
1028
1029A colon-separated list of directories in which to look for Perl library
1030files before looking in the standard library and the current directory.
1031If PERL5LIB is defined, PERLLIB is not used.
1032
1033=item PERL5DB
1034
1035The command used to load the debugger code. The default is:
1036
1037 BEGIN { require 'perl5db.pl' }
1038
19799a22 1039=item PERL5SHELL (specific to the Win32 port)
174c211a
GS
1040
1041May be set to an alternative shell that perl must use internally for
ce1da67e
GS
1042executing "backtick" commands or system(). Default is C<cmd.exe /x/c>
1043on WindowsNT and C<command.com /c> on Windows95. The value is considered
19799a22 1044to be space-separated. Precede any character that needs to be protected
ce1da67e
GS
1045(like a space or backslash) with a backslash.
1046
1047Note that Perl doesn't use COMSPEC for this purpose because
1048COMSPEC has a high degree of variability among users, leading to
1049portability concerns. Besides, perl can use a shell that may not be
1050fit for interactive use, and setting COMSPEC to such a shell may
1051interfere with the proper functioning of other programs (which usually
1052look in COMSPEC to find a shell fit for interactive use).
174c211a 1053
1e422769
PP
1054=item PERL_DEBUG_MSTATS
1055
67ce8856 1056Relevant only if perl is compiled with the malloc included with the perl
a3cb178b
GS
1057distribution (that is, if C<perl -V:d_mymalloc> is 'define').
1058If set, this causes memory statistics to be dumped after execution. If set
1e422769
PP
1059to an integer greater than one, also causes memory statistics to be dumped
1060after compilation.
1061
1062=item PERL_DESTRUCT_LEVEL
1063
1064Relevant only if your perl executable was built with B<-DDEBUGGING>,
1065this controls the behavior of global destruction of objects and other
64cea5fd 1066references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
a0d0e21e 1067
5d170f3a
JH
1068=item PERL_ENCODING
1069
1070If using the C<encoding> pragma without an explicit encoding name, the
1071PERL_ENCODING environment variable is consulted for an encoding name.
1072
3d0ae7ba
GS
1073=item PERL_ROOT (specific to the VMS port)
1074
1075A translation concealed rooted logical name that contains perl and the
1076logical device for the @INC path on VMS only. Other logical names that
44a4342c
NIS
1077affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and
1078SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in
3d0ae7ba
GS
1079L<perlvms> and in F<README.vms> in the Perl source distribution.
1080
a05d7ebb 1081=item PERL_UNICODE
acae81db
RGS
1082
1083Equivalent to the B<-C> command-line switch.
1084
3d0ae7ba
GS
1085=item SYS$LOGIN (specific to the VMS port)
1086
1087Used if chdir has no argument and HOME and LOGDIR are not set.
1088
a0d0e21e 1089=back
1e422769
PP
1090
1091Perl also has environment variables that control how Perl handles data
1092specific to particular natural languages. See L<perllocale>.
1093
1094Apart from these, Perl uses no other environment variables, except
19799a22
GS
1095to make them available to the program being executed, and to child
1096processes. However, programs running setuid would do well to execute
1e422769
PP
1097the following lines before doing anything else, just to keep people
1098honest:
1099
19799a22 1100 $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need
7bac28a0 1101 $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
c90c0ff4 1102 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};