This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update to Test-Simple 1.302026
[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 8 S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
2cbb2ee1 9 S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]>
f2095865 10 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]>
df451b2a 11 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
c630fe62 12 S<[ B<-C [I<number/list>] >]>
e0ebc809
PP
13 S<[ B<-S> ]>
14 S<[ B<-x>[I<dir>] ]>
15 S<[ B<-i>[I<extension>] ]>
eb1dd64e 16 S<[ [B<-e>|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
bc9b29db 31Specified line by line via B<-e> or B<-E> switches on the command line.
a0d0e21e
LW
32
33=item 2.
34
35Contained in the file specified by the first filename on the command line.
f4750dab 36(Note that systems supporting the C<#!> notation invoke interpreters this
a3cb178b 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
f4750dab 49scans for the first line starting with C<#!> 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
f4750dab 54The C<#!> line is always examined for switches as the line is being
5f05dabc 55parsed. Thus, if you're on a machine that allows only one argument
f4750dab
TC
56with the C<#!> line, or worse, doesn't even recognize the C<#!> line, you
57still can get consistent switch behaviour 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
f4750dab 61kernel interpretation of the C<#!> line after 32 characters, some
19799a22
GS
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
f4750dab 76Parsing of the C<#!> switches starts wherever "perl" is mentioned in the line.
a0d0e21e
LW
77The sequences "-*" and "- " are specifically ignored so that you could,
78if you were so inclined, say
79
428bacd7
SP
80 #!/bin/sh
81 #! -*-perl-*-
82 eval 'exec perl -x -wS $0 ${1+"$@"}'
83 if 0;
a0d0e21e 84
44a4342c 85to let Perl see the B<-p> switch.
19799a22 86
f4750dab 87A similar trick involves the I<env> program, if you have it.
19799a22
GS
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
6898e867 93a specific version of Perl, say, perl5.14.1, you should place
f4750dab 94that directly in the C<#!> line's path.
a0d0e21e 95
3b56f80d 96If the C<#!> line does not contain the word "perl" nor the word "indir",
2f1fe8a3
RGS
97the program named after the C<#!> is executed instead of the Perl
98interpreter. This is slightly bizarre, but it helps people on machines
99that don't do C<#!>, because they can tell a program that their SHELL is
100F</usr/bin/perl>, and Perl will then dispatch the program to the correct
101interpreter for them.
a0d0e21e 102
19799a22 103After locating your program, Perl compiles the entire program to an
a0d0e21e 104internal form. If there are any compilation errors, execution of the
19799a22 105program is not attempted. (This is unlike the typical shell script,
54310121 106which might run part-way through before finding a syntax error.)
a0d0e21e 107
19799a22 108If the program is syntactically correct, it is executed. If the program
a0d0e21e
LW
109runs off the end without hitting an exit() or die() operator, an implicit
110C<exit(0)> is provided to indicate successful completion.
111
68dc0745 112=head2 #! and quoting on non-Unix systems
d74e8afc 113X<hashbang> X<#!>
68dc0745 114
f4750dab 115Unix's C<#!> technique can be simulated on other systems:
68dc0745
PP
116
117=over 4
118
119=item OS/2
120
121Put
122
123 extproc perl -S -your_switches
124
19799a22 125as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's
68dc0745
PP
126`extproc' handling).
127
54310121 128=item MS-DOS
68dc0745 129
19799a22 130Create a batch file to run your program, and codify it in
fd1adc71 131C<ALTERNATE_SHEBANG> (see the F<dosish.h> file in the source
68dc0745
PP
132distribution for more information).
133
134=item Win95/NT
135
6c6a61e2 136The Win95/NT installation, when using the ActiveState installer for Perl,
c8db1d39 137will modify the Registry to associate the F<.pl> extension with the perl
6c6a61e2
GS
138interpreter. If you install Perl by other means (including building from
139the sources), you may have to modify the Registry yourself. Note that
140this means you can no longer tell the difference between an executable
141Perl program and a Perl library file.
68dc0745 142
bd3fa61c
CB
143=item VMS
144
145Put
146
60b7c710
KW
147 $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
148 $ exit++ + ++$status != 0 and $exit = $status = undef;
bd3fa61c 149
19799a22
GS
150at the top of your program, where B<-mysw> are any command line switches you
151want to pass to Perl. You can now invoke the program directly, by saying
152C<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly
153via F<DCL$PATH> by just using the name of the program).
bd3fa61c
CB
154
155This incantation is a bit much to remember, but Perl will display it for
156you if you say C<perl "-V:startperl">.
157
68dc0745
PP
158=back
159
160Command-interpreters on non-Unix systems have rather different ideas
161on quoting than Unix shells. You'll need to learn the special
162characters in your command-interpreter (C<*>, C<\> and C<"> are
163common) and how to protect whitespace and these characters to run
76c9ab0e 164one-liners (see L<-e|/-e commandline> below).
68dc0745
PP
165
166On some systems, you may have to change single-quotes to double ones,
e6f03d26 167which you must I<not> do on Unix or Plan 9 systems. You might also
68dc0745
PP
168have to change a single % to a %%.
169
170For example:
171
172 # Unix
173 perl -e 'print "Hello world\n"'
174
54310121 175 # MS-DOS, etc.
68dc0745
PP
176 perl -e "print \"Hello world\n\""
177
68dc0745
PP
178 # VMS
179 perl -e "print ""Hello world\n"""
180
19799a22 181The problem is that none of this is reliable: it depends on the
f4750dab 182command and it is entirely possible neither works. If I<4DOS> were
19799a22 183the command shell, this would probably work better:
68dc0745
PP
184
185 perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
186
19799a22 187B<CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in
68dc0745
PP
188when nobody was looking, but just try to find documentation for its
189quoting rules.
190
68dc0745
PP
191There is no general solution to all of this. It's just a mess.
192
a3cb178b 193=head2 Location of Perl
d74e8afc 194X<perl, location of interpreter>
a3cb178b
GS
195
196It may seem obvious to say, but Perl is useful only when users can
19799a22
GS
197easily find it. When possible, it's good for both F</usr/bin/perl>
198and F</usr/local/bin/perl> to be symlinks to the actual binary. If
199that can't be done, system administrators are strongly encouraged
200to put (symlinks to) perl and its accompanying utilities into a
201directory typically found along a user's PATH, or in some other
202obvious and convenient place.
203
204In this documentation, C<#!/usr/bin/perl> on the first line of the program
205will stand in for whatever method works on your system. You are
206advised to use a specific path if you care about a specific version.
a3cb178b 207
6898e867 208 #!/usr/local/bin/perl5.14
a3cb178b 209
19799a22
GS
210or if you just want to be running at least version, place a statement
211like this at the top of your program:
a0d0e21e 212
6898e867 213 use 5.014;
a0d0e21e 214
19799a22 215=head2 Command Switches
d74e8afc 216X<perl, command switches> X<command switches>
19799a22
GS
217
218As with all standard commands, a single-character switch may be
219clustered with the following switch, if any.
220
221 #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
a0d0e21e 222
4612c2ba
JK
223A C<--> signals the end of options and disables further option processing. Any
224arguments after the C<--> are treated as filenames and arguments.
225
a0d0e21e
LW
226Switches include:
227
228=over 5
229
f2095865 230=item B<-0>[I<octal/hexadecimal>]
d74e8afc 231X<-0> X<$/>
a0d0e21e 232
f2095865
JH
233specifies the input record separator (C<$/>) as an octal or
234hexadecimal number. If there are no digits, the null character is the
235separator. Other switches may precede or follow the digits. For
f4750dab 236example, if you have a version of I<find> which can print filenames
f2095865 237terminated by the null character, you can say this:
a0d0e21e 238
19799a22 239 find . -name '*.orig' -print0 | perl -n0e unlink
a0d0e21e
LW
240
241The special value 00 will cause Perl to slurp files in paragraph mode.
7ba31cb4
KW
242Any value 0400 or above will cause Perl to slurp files whole, but by convention
243the value 0777 is the one normally used for this purpose.
f2095865 244
7ba31cb4 245You can also specify the separator character using hexadecimal notation:
f4750dab
TC
246B<-0xI<HHH...>>, where the C<I<H>> are valid hexadecimal digits. Unlike
247the octal form, this one may be used to specify any Unicode character, even
248those beyond 0xFF. So if you I<really> want a record separator of 0777,
249specify it as B<-0x1FF>. (This means that you cannot use the B<-x> option
250with a directory name that consists of hexadecimal digits, or else Perl
251will think you have specified a hex number to B<-0>.)
a0d0e21e
LW
252
253=item B<-a>
d74e8afc 254X<-a> X<autosplit>
a0d0e21e
LW
255
256turns on autosplit mode when used with a B<-n> or B<-p>. An implicit
257split command to the @F array is done as the first thing inside the
258implicit while loop produced by the B<-n> or B<-p>.
259
260 perl -ane 'print pop(@F), "\n";'
261
262is equivalent to
263
264 while (<>) {
265 @F = split(' ');
266 print pop(@F), "\n";
267 }
268
269An alternate delimiter may be specified using B<-F>.
270
24ffa309
TC
271B<-a> implicitly sets B<-n>.
272
a05d7ebb 273=item B<-C [I<number/list>]>
d74e8afc 274X<-C>
46487f74 275
f4750dab 276The B<-C> flag controls some of the Perl Unicode features.
a05d7ebb 277
f4750dab 278As of 5.8.1, the B<-C> can be followed either by a number or a list
f3f8427d 279of option letters. The letters, their numeric values, and effects
8aa8f774 280are as follows; listing the letters is equal to summing the numbers.
9f21530f 281
73e12209
A
282 I 1 STDIN is assumed to be in UTF-8
283 O 2 STDOUT will be in UTF-8
284 E 4 STDERR will be in UTF-8
285 S 7 I + O + E
286 i 8 UTF-8 is the default PerlIO layer for input streams
287 o 16 UTF-8 is the default PerlIO layer for output streams
288 D 24 i + o
289 A 32 the @ARGV elements are expected to be strings encoded
290 in UTF-8
60b7c710
KW
291 L 64 normally the "IOEioA" are unconditional, the L makes
292 them conditional on the locale environment variables
407a9f94 293 (the LC_ALL, LC_CTYPE, and LANG, in the order of
60b7c710 294 decreasing precedence) -- if the variables indicate
73e12209 295 UTF-8, then the selected "IOEioA" are in effect
60b7c710
KW
296 a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching
297 code in debugging mode.
5a22a2bb
NC
298
299=for documenting_the_underdocumented
300perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */"
9f21530f 301
f23930d5
NC
302=for todo
303perltodo mentions Unicode in %ENV and filenames. I guess that these will be
304options e and f (or F).
305
f4750dab 306For example, B<-COE> and B<-C6> will both turn on UTF-8-ness on both
9f21530f
JH
307STDOUT and STDERR. Repeating letters is just redundant, not cumulative
308nor toggling.
a05d7ebb 309
44505768 310The C<io> options mean that any subsequent open() (or similar I/O
88770b48
NT
311operations) in the current file scope will have the C<:utf8> PerlIO layer
312implicitly applied to them, in other words, UTF-8 is expected from any
313input stream, and UTF-8 is produced to any output stream. This is just
314the default, with explicit layers in open() and with binmode() one can
315manipulate streams as usual.
44505768 316
f4750dab 317B<-C> on its own (not followed by any number or option list), or the
47427c4e 318empty string C<""> for the C<PERL_UNICODE> environment variable, has the
f4750dab
TC
319same effect as B<-CSDL>. In other words, the standard I/O handles and
320the default C<open()> layer are UTF-8-fied I<but> only if the locale
47427c4e
RGS
321environment variables indicate a UTF-8 locale. This behaviour follows
322the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
370155be 323(See L<perl581delta/UTF-8 no longer default under UTF-8 locales>.)
a05d7ebb 324
f4750dab 325You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
5b4f334e 326disable all the above Unicode features.
fde18df1 327
8aa8f774 328The read-only magic variable C<${^UNICODE}> reflects the numeric value
f60ef620 329of this setting. This variable is set during Perl startup and is
ab9e1bb7 330thereafter read-only. If you want runtime effects, use the three-arg
2307c6d0 331open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>),
ab9e1bb7 332and the C<open> pragma (see L<open>).
fde18df1 333
f4750dab 334(In Perls earlier than 5.8.1 the B<-C> switch was a Win32-only switch
fde18df1
JH
335that enabled the use of Unicode-aware "wide system call" Win32 APIs.
336This feature was practically unused, however, and the command line
337switch was therefore "recycled".)
46487f74 338
f4750dab
TC
339B<Note:> Since perl 5.10.1, if the B<-C> option is used on the C<#!> line,
340it must be specified on the command line as well, since the standard streams
618078e9 341are already set up at this point in the execution of the perl interpreter.
4ba71d51 342You can also use binmode() to set the encoding of an I/O stream.
618078e9 343
a0d0e21e 344=item B<-c>
d74e8afc 345X<-c>
a0d0e21e 346
19799a22 347causes Perl to check the syntax of the program and then exit without
f4750dab
TC
348executing it. Actually, it I<will> execute and C<BEGIN>, C<UNITCHECK>,
349or C<CHECK> blocks and any C<use> statements: these are considered as
350occurring outside the execution of your program. C<INIT> and C<END>
351blocks, however, will be skipped.
a0d0e21e
LW
352
353=item B<-d>
d74e8afc 354X<-d> X<-dt>
a0d0e21e 355
2cbb2ee1
RGS
356=item B<-dt>
357
19799a22 358runs the program under the Perl debugger. See L<perldebug>.
2cbb2ee1
RGS
359If B<t> is specified, it indicates to the debugger that threads
360will be used in the code being debugged.
a0d0e21e 361
f4750dab 362=item B<-d:>I<MOD[=bar,baz]>
d74e8afc 363X<-d> X<-dt>
3c81428c 364
f4750dab 365=item B<-dt:>I<MOD[=bar,baz]>
2cbb2ee1 366
f4750dab
TC
367runs the program under the control of a debugging, profiling, or tracing
368module installed as C<Devel::I<MOD>>. E.g., B<-d:DProf> executes the
369program using the C<Devel::DProf> profiler. As with the B<-M> flag, options
370may be passed to the C<Devel::I<MOD>> package where they will be received
371and interpreted by the C<Devel::I<MOD>::import> routine. Again, like B<-M>,
372use -B<-d:-I<MOD>> to call C<Devel::I<MOD>::unimport> instead of import. The
373comma-separated list of options must follow a C<=> character. If B<t> is
374specified, it indicates to the debugger that threads will be used in the
375code being debugged. See L<perldebug>.
3c81428c 376
db2ba183 377=item B<-D>I<letters>
d74e8afc 378X<-D> X<DEBUGGING> X<-DDEBUGGING>
a0d0e21e 379
db2ba183 380=item B<-D>I<number>
a0d0e21e 381
19799a22 382sets debugging flags. To watch how it executes your program, use
db2ba183
TB
383B<-Dtls>. (This works only if debugging is compiled into your
384Perl.) Another nice value is B<-Dx>, which lists your compiled
4197b13f 385syntax tree. And B<-Dr> displays compiled regular expressions;
44a4342c 386the format of the output is explained in L<perldebguts>.
4197b13f
MJD
387
388As an alternative, specify a number instead of list of letters (e.g.,
389B<-D14> is equivalent to B<-Dtls>):
a0d0e21e 390
9388183f 391 1 p Tokenizing and parsing (with v, displays parse stack)
3679267a 392 2 s Stack snapshots (with v, displays all stacks)
db2ba183
TB
393 4 l Context (loop) stack processing
394 8 t Trace execution
395 16 o Method and overloading resolution
396 32 c String/numeric conversions
4c84d7f2 397 64 P Print profiling info, source file input state
d7a2c63c 398 128 m Memory and SV allocation
db2ba183
TB
399 256 f Format processing
400 512 r Regular expression parsing and execution
401 1024 x Syntax tree dump
402 2048 u Tainting checks
60b7c710
KW
403 4096 U Unofficial, User hacking (reserved for private,
404 unreleased use)
db2ba183
TB
405 8192 H Hash dump -- usurps values()
406 16384 X Scratchpad allocation
407 32768 D Cleaning up
56967202 408 65536 S Op slab allocation
f4750dab 409 131072 T Tokenizing
60b7c710
KW
410 262144 R Include reference counts of dumped variables (eg when
411 using -Ds)
412 524288 J show s,t,P-debug (don't Jump over) on opcodes within
413 package DB
d6721266 414 1048576 v Verbose: use in conjunction with other flags
46187eeb 415 2097152 C Copy On Write
ecae49c0 416 4194304 A Consistency checks on internal structures
60b7c710
KW
417 8388608 q quiet - currently only suppresses the "EXECUTING"
418 message
d7c0d282 419 16777216 M trace smart match resolution
60b7c710
KW
420 33554432 B dump suBroutine definitions, including special Blocks
421 like BEGIN
60949ddd
KW
422 67108864 L trace Locale-related info; what gets output is very
423 subject to change
a0d0e21e 424
19799a22 425All these flags require B<-DDEBUGGING> when you compile the Perl
c85da6fc
TH
426executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode>
427which may change this).
44a4342c 428See the F<INSTALL> file in the Perl source distribution
19799a22 429for how to do this. This flag is automatically set if you include B<-g>
8c52afec
IZ
430option when C<Configure> asks you about optimizer/debugger flags.
431
19799a22
GS
432If you're just trying to get a print out of each line of Perl code
433as it executes, the way that C<sh -x> provides for shell scripts,
44a4342c 434you can't use Perl's B<-D> switch. Instead do this
19799a22 435
c406981e 436 # If you have "env" utility
fdac53cd 437 env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
c406981e 438
19799a22
GS
439 # Bourne shell syntax
440 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
441
442 # csh syntax
443 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
444
445See L<perldebug> for details and variations.
446
a0d0e21e 447=item B<-e> I<commandline>
d74e8afc 448X<-e>
a0d0e21e 449
19799a22
GS
450may be used to enter one line of program. If B<-e> is given, Perl
451will not look for a filename in the argument list. Multiple B<-e>
452commands may be given to build up a multi-line script. Make sure
453to use semicolons where you would in a normal program.
a0d0e21e 454
bc9b29db
RH
455=item B<-E> I<commandline>
456X<-E>
457
458behaves just like B<-e>, except that it implicitly enables all
459optional features (in the main compilation unit). See L<feature>.
460
20ef40cf 461=item B<-f>
174299ac 462X<-f> X<sitecustomize> X<sitecustomize.pl>
20ef40cf 463
4a42f219 464Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup.
20ef40cf
GA
465
466Perl can be built so that it by default will try to execute
e846cbe5 467F<$Config{sitelib}/sitecustomize.pl> at startup (in a BEGIN block).
f4750dab
TC
468This is a hook that allows the sysadmin to customize how Perl behaves.
469It can for instance be used to add entries to the @INC array to make Perl
e846cbe5 470find modules in non-standard locations.
20ef40cf 471
298ca354
PBB
472Perl actually inserts the following code:
473
474 BEGIN {
475 do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
476 && do "$Config{sitelib}/sitecustomize.pl";
477 }
478
479Since it is an actual C<do> (not a C<require>), F<sitecustomize.pl>
480doesn't need to return a true value. The code is run in package C<main>,
481in its own lexical scope. However, if the script dies, C<$@> will not
482be set.
483
484The value of C<$Config{sitelib}> is also determined in C code and not
485read from C<Config.pm>, which is not loaded.
486
f4750dab 487The code is executed I<very> early. For example, any changes made to
298ca354
PBB
488C<@INC> will show up in the output of `perl -V`. Of course, C<END>
489blocks will be likewise executed very late.
490
491To determine at runtime if this capability has been compiled in your
492perl, you can check the value of C<$Config{usesitecustomize}>.
493
e0ebc809 494=item B<-F>I<pattern>
d74e8afc 495X<-F>
a0d0e21e 496
24ffa309
TC
497specifies the pattern to split on for B<-a>. The pattern may be
498surrounded by C<//>, C<"">, or C<''>, otherwise it will be put in single
499quotes. You can't use literal whitespace in the pattern.
500
501B<-F> implicitly sets both B<-a> and B<-n>.
a0d0e21e 502
e0ebc809 503=item B<-h>
d74e8afc 504X<-h>
e0ebc809
PP
505
506prints a summary of the options.
507
508=item B<-i>[I<extension>]
d74e8afc 509X<-i> X<in-place>
a0d0e21e 510
2d259d92
CK
511specifies that files processed by the C<E<lt>E<gt>> construct are to be
512edited in-place. It does this by renaming the input file, opening the
513output file by the original name, and selecting that output file as the
514default for print() statements. The extension, if supplied, is used to
515modify the name of the old file to make a backup copy, following these
516rules:
517
479e5f87
PM
518If no extension is supplied, and your system supports it, the original
519I<file> is kept open without a name while the output is redirected to
520a new file with the original I<filename>. When perl exits, cleanly or not,
521the original I<file> is unlinked.
2d259d92 522
19799a22
GS
523If the extension doesn't contain a C<*>, then it is appended to the
524end of the current filename as a suffix. If the extension does
525contain one or more C<*> characters, then each C<*> is replaced
526with the current filename. In Perl terms, you could think of this
527as:
2d259d92 528
66606d78 529 ($backup = $extension) =~ s/\*/$file_name/g;
2d259d92
CK
530
531This allows you to add a prefix to the backup file, instead of (or in
532addition to) a suffix:
533
60b7c710
KW
534 $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to
535 # 'orig_fileA'
2d259d92
CK
536
537Or even to place backup copies of the original files into another
538directory (provided the directory already exists):
539
60b7c710
KW
540 $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to
541 # 'old/fileA.orig'
2d259d92 542
66606d78
CK
543These sets of one-liners are equivalent:
544
60b7c710
KW
545 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
546 $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
66606d78 547
60b7c710
KW
548 $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
549 $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
66606d78 550
2d259d92 551From the shell, saying
a0d0e21e 552
19799a22 553 $ perl -p -i.orig -e "s/foo/bar/; ... "
a0d0e21e 554
19799a22 555is the same as using the program:
a0d0e21e 556
19799a22 557 #!/usr/bin/perl -pi.orig
a0d0e21e
LW
558 s/foo/bar/;
559
560which is equivalent to
561
562 #!/usr/bin/perl
19799a22
GS
563 $extension = '.orig';
564 LINE: while (<>) {
a0d0e21e 565 if ($ARGV ne $oldargv) {
66606d78
CK
566 if ($extension !~ /\*/) {
567 $backup = $ARGV . $extension;
568 }
569 else {
570 ($backup = $extension) =~ s/\*/$ARGV/g;
571 }
572 rename($ARGV, $backup);
a0d0e21e
LW
573 open(ARGVOUT, ">$ARGV");
574 select(ARGVOUT);
575 $oldargv = $ARGV;
576 }
577 s/foo/bar/;
578 }
579 continue {
580 print; # this prints to original filename
581 }
582 select(STDOUT);
583
584except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
585know when the filename has changed. It does, however, use ARGVOUT for
66606d78
CK
586the selected filehandle. Note that STDOUT is restored as the default
587output filehandle after the loop.
588
589As shown above, Perl creates the backup file whether or not any output
590is actually changed. So this is just a fancy way to copy files:
591
cd2d1bac 592 $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
19799a22 593or
cd2d1bac 594 $ perl -p -i'.orig' -e 1 file1 file2 file3...
66606d78
CK
595
596You can use C<eof> without parentheses to locate the end of each input
597file, in case you want to append to each file, or reset line numbering
598(see example in L<perlfunc/eof>).
599
600If, for a given file, Perl is unable to create the backup file as
601specified in the extension then it will skip that file and continue on
602with the next one (if it exists).
603
1dcc3c19
DG
604For a discussion of issues surrounding file permissions and B<-i>, see
605L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber
606protected files? Isn't this a bug in Perl?>.
66606d78
CK
607
608You cannot use B<-i> to create directories or to strip extensions from
609files.
a0d0e21e 610
19799a22
GS
611Perl does not expand C<~> in filenames, which is good, since some
612folks use it for their backup files:
a0d0e21e 613
19799a22
GS
614 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
615
a66b22ca 616Note that because B<-i> renames or deletes the original file before
e1020413 617creating a new file of the same name, Unix-style soft and hard links will
0cb0633f 618not be preserved.
a66b22ca 619
19799a22 620Finally, the B<-i> switch does not impede execution when no
a2008d6d
GS
621files are given on the command line. In this case, no backup is made
622(the original file cannot, of course, be determined) and processing
623proceeds from STDIN to STDOUT as might be expected.
624
a0d0e21e 625=item B<-I>I<directory>
d74e8afc 626X<-I> X<@INC>
a0d0e21e 627
e0ebc809 628Directories specified by B<-I> are prepended to the search path for
4c84d7f2 629modules (C<@INC>).
a0d0e21e 630
e0ebc809 631=item B<-l>[I<octnum>]
d74e8afc 632X<-l> X<$/> X<$\>
a0d0e21e 633
19799a22
GS
634enables automatic line-ending processing. It has two separate
635effects. First, it automatically chomps C<$/> (the input record
636separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
637(the output record separator) to have the value of I<octnum> so
638that any print statements will have that separator added back on.
639If I<octnum> is omitted, sets C<$\> to the current value of
640C<$/>. For instance, to trim lines to 80 columns:
a0d0e21e
LW
641
642 perl -lpe 'substr($_, 80) = ""'
643
644Note that the assignment C<$\ = $/> is done when the switch is processed,
645so the input record separator can be different than the output record
646separator if the B<-l> switch is followed by a B<-0> switch:
647
648 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
649
1fef88e7 650This sets C<$\> to newline and then sets C<$/> to the null character.
a0d0e21e 651
e0ebc809 652=item B<-m>[B<->]I<module>
d74e8afc 653X<-m> X<-M>
e0ebc809
PP
654
655=item B<-M>[B<->]I<module>
c07a80fd 656
e0ebc809
PP
657=item B<-M>[B<->]I<'module ...'>
658
659=item B<-[mM]>[B<->]I<module=arg[,arg]...>
3c81428c 660
19799a22
GS
661B<-m>I<module> executes C<use> I<module> C<();> before executing your
662program.
3c81428c 663
19799a22
GS
664B<-M>I<module> executes C<use> I<module> C<;> before executing your
665program. You can use quotes to add extra code after the module name,
f4750dab 666e.g., C<'-MI<MODULE> qw(foo bar)'>.
3c81428c 667
f4750dab 668If the first character after the B<-M> or B<-m> is a dash (B<->)
a5f75d66
AD
669then the 'use' is replaced with 'no'.
670
54310121 671A little builtin syntactic sugar means you can also say
f4750dab
TC
672B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for
673B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when
674importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is
e0ebc809 675C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
c2d9228f
A
676removes the distinction between B<-m> and B<-M>; that is,
677B<-mI<MODULE>=foo,bar> is the same as B<-MI<MODULE>=foo,bar>.
3c81428c 678
f4750dab
TC
679A consequence of this is that B<-MI<MODULE>=number> never does a version check,
680unless C<I<MODULE>::import()> itself is set up to do a version check, which
681could happen for example if I<MODULE> inherits from L<Exporter>.
642d0c2f 682
a0d0e21e 683=item B<-n>
d74e8afc 684X<-n>
a0d0e21e 685
19799a22 686causes Perl to assume the following loop around your program, which
f4750dab
TC
687makes it iterate over filename arguments somewhat like I<sed -n> or
688I<awk>:
a0d0e21e 689
19799a22 690 LINE:
a0d0e21e 691 while (<>) {
19799a22 692 ... # your program goes here
a0d0e21e
LW
693 }
694
76c9ab0e 695Note that the lines are not printed by default. See L</-p> to have
08e9d68e 696lines printed. If a file named by an argument cannot be opened for
19799a22 697some reason, Perl warns you about it and moves on to the next file.
08e9d68e 698
48ab5743
ML
699Also note that C<< <> >> passes command line arguments to
700L<perlfunc/open>, which doesn't necessarily interpret them as file names.
701See L<perlop> for possible security implications.
702
fa11829f 703Here is an efficient way to delete all files that haven't been modified for
9976c5c7 704at least a week:
a0d0e21e 705
19799a22 706 find . -mtime +7 -print | perl -nle unlink
a0d0e21e 707
f4750dab 708This is faster than using the B<-exec> switch of I<find> because you don't
45cc06e3
DH
709have to start a process on every filename found (but it's not faster
710than using the B<-delete> switch available in newer versions of I<find>.
711It does suffer from the bug of mishandling newlines in pathnames, which
712you can fix if you follow the example under B<-0>.
a0d0e21e
LW
713
714C<BEGIN> and C<END> blocks may be used to capture control before or after
f4750dab 715the implicit program loop, just as in I<awk>.
a0d0e21e
LW
716
717=item B<-p>
d74e8afc 718X<-p>
a0d0e21e 719
19799a22 720causes Perl to assume the following loop around your program, which
f4750dab 721makes it iterate over filename arguments somewhat like I<sed>:
a0d0e21e
LW
722
723
19799a22 724 LINE:
a0d0e21e 725 while (<>) {
19799a22 726 ... # your program goes here
a0d0e21e 727 } continue {
08e9d68e 728 print or die "-p destination: $!\n";
a0d0e21e
LW
729 }
730
08e9d68e
DD
731If a file named by an argument cannot be opened for some reason, Perl
732warns you about it, and moves on to the next file. Note that the
c2611fb3 733lines are printed automatically. An error occurring during printing is
08e9d68e
DD
734treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
735overrides a B<-n> switch.
a0d0e21e
LW
736
737C<BEGIN> and C<END> blocks may be used to capture control before or after
f4750dab 738the implicit loop, just as in I<awk>.
a0d0e21e 739
a0d0e21e 740=item B<-s>
d74e8afc 741X<-s>
a0d0e21e 742
19799a22
GS
743enables rudimentary switch parsing for switches on the command
744line after the program name but before any filename arguments (or before
74ac850a 745an argument of B<-->). Any switch found there is removed from @ARGV and sets the
19799a22 746corresponding variable in the Perl program. The following program
3c0facb2
GS
747prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
748if it is invoked with B<-xyz=abc>.
a0d0e21e
LW
749
750 #!/usr/bin/perl -s
3c0facb2 751 if ($xyz) { print "$xyz\n" }
a0d0e21e 752
1dcc3c19
DG
753Do note that a switch like B<--help> creates the variable C<${-help}>, which is
754not compliant with C<use strict "refs">. Also, when using this option on a
755script with warnings enabled you may get a lot of spurious "used only once"
756warnings.
3bbcc830 757
a0d0e21e 758=item B<-S>
d74e8afc 759X<-S>
a0d0e21e
LW
760
761makes Perl use the PATH environment variable to search for the
f4750dab 762program unless the name of the program contains path separators.
19799a22 763
2a92aaa0
GS
764On some platforms, this also makes Perl append suffixes to the
765filename while searching for it. For example, on Win32 platforms,
766the ".bat" and ".cmd" suffixes are appended if a lookup for the
767original name fails, and if the name does not already end in one
f4750dab
TC
768of those suffixes. If your Perl was compiled with C<DEBUGGING> turned
769on, using the B<-Dp> switch to Perl shows how the search progresses.
2a92aaa0 770
f4750dab
TC
771Typically this is used to emulate C<#!> startup on platforms that don't
772support C<#!>. It's also convenient when debugging a script that uses C<#!>,
fa3aa65a
JC
773and is thus normally found by the shell's $PATH search mechanism.
774
775This example works on many platforms that have a shell compatible with
776Bourne shell:
a0d0e21e
LW
777
778 #!/usr/bin/perl
a3cb178b 779 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
a0d0e21e
LW
780 if $running_under_some_shell;
781
19799a22
GS
782The system ignores the first line and feeds the program to F</bin/sh>,
783which proceeds to try to execute the Perl program as a shell script.
a0d0e21e
LW
784The shell executes the second line as a normal shell command, and thus
785starts up the Perl interpreter. On some systems $0 doesn't always
786contain the full pathname, so the B<-S> tells Perl to search for the
19799a22 787program if necessary. After Perl locates the program, it parses the
a0d0e21e 788lines and ignores them because the variable $running_under_some_shell
19799a22 789is never true. If the program will be interpreted by csh, you will need
a3cb178b 790to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
f4750dab
TC
791embedded spaces (and such) in the argument list. To start up I<sh> rather
792than I<csh>, some systems may have to replace the C<#!> line with a line
a0d0e21e
LW
793containing just a colon, which will be politely ignored by Perl. Other
794systems can't control that, and need a totally devious construct that
f4750dab 795will work under any of I<csh>, I<sh>, or Perl, such as the following:
a0d0e21e 796
19799a22 797 eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
a3cb178b 798 & eval 'exec /usr/bin/perl -wS $0 $argv:q'
5f05dabc 799 if $running_under_some_shell;
a0d0e21e 800
f4750dab 801If the filename supplied contains directory separators (and so is an
19799a22
GS
802absolute or relative pathname), and if that file is not found,
803platforms that append file extensions will do so and try to look
804for the file with those extensions added, one by one.
805
806On DOS-like platforms, if the program does not contain directory
807separators, it will first be searched for in the current directory
808before being searched for on the PATH. On Unix platforms, the
809program will be searched for strictly on the PATH.
810
6537fe72 811=item B<-t>
d74e8afc 812X<-t>
6537fe72
MS
813
814Like B<-T>, but taint checks will issue warnings rather than fatal
f4750dab 815errors. These warnings can now be controlled normally with C<no warnings
317ea90d 816qw(taint)>.
1dbad523 817
f4750dab
TC
818B<Note: This is not a substitute for C<-T>!> This is meant to be
819used I<only> as a temporary development aid while securing legacy code:
820for real production code and for new secure code written from scratch,
1dbad523 821always use the real B<-T>.
6537fe72 822
a0d0e21e 823=item B<-T>
d74e8afc 824X<-T>
a0d0e21e 825
f4750dab 826turns on "taint" so you can test them. Ordinarily
19799a22
GS
827these checks are done only when running setuid or setgid. It's a
828good idea to turn them on explicitly for programs that run on behalf
829of someone else whom you might not necessarily trust, such as CGI
830programs or any internet servers you might write in Perl. See
831L<perlsec> for details. For security reasons, this option must be
832seen by Perl quite early; usually this means it must appear early
f4750dab 833on the command line or in the C<#!> line for systems which support
19799a22 834that construct.
a0d0e21e
LW
835
836=item B<-u>
d74e8afc 837X<-u>
a0d0e21e 838
f4750dab 839This switch causes Perl to dump core after compiling your
19799a22 840program. You can then in theory take this core dump and turn it
f4750dab 841into an executable file by using the I<undump> program (not supplied).
19799a22
GS
842This speeds startup at the expense of some disk space (which you
843can minimize by stripping the executable). (Still, a "hello world"
844executable comes out to about 200K on my machine.) If you want to
845execute a portion of your program before dumping, use the dump()
f4750dab 846operator instead. Note: availability of I<undump> is platform
19799a22
GS
847specific and may not be available for a specific port of Perl.
848
a0d0e21e 849=item B<-U>
d74e8afc 850X<-U>
a0d0e21e
LW
851
852allows Perl to do unsafe operations. Currently the only "unsafe"
f4750dab
TC
853operations are attempting to unlink directories while running as superuser
854and running setuid programs with fatal taint checks turned into warnings.
855Note that warnings must be enabled along with this option to actually
856I<generate> the taint-check warnings.
a0d0e21e
LW
857
858=item B<-v>
d74e8afc 859X<-v>
a0d0e21e 860
19799a22 861prints the version and patchlevel of your perl executable.
a0d0e21e 862
3c81428c 863=item B<-V>
d74e8afc 864X<-V>
3c81428c
PP
865
866prints summary of the major perl configuration values and the current
19799a22 867values of @INC.
3c81428c 868
307dc113 869=item B<-V:>I<configvar>
3c81428c 870
4a305f6a 871Prints to STDOUT the value of the named configuration variable(s),
f4750dab 872with multiples when your C<I<configvar>> argument looks like a regex (has
307dc113 873non-letters). For example:
3c81428c 874
307dc113
JC
875 $ perl -V:libc
876 libc='/lib/libc-2.2.4.so';
4a305f6a
JC
877 $ perl -V:lib.
878 libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
879 libc='/lib/libc-2.2.4.so';
880 $ perl -V:lib.*
881 libpth='/usr/local/lib /lib /usr/lib';
882 libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
883 lib_ext='.a';
884 libc='/lib/libc-2.2.4.so';
885 libperl='libperl.a';
886 ....
887
888Additionally, extra colons can be used to control formatting. A
f4750dab 889trailing colon suppresses the linefeed and terminator ";", allowing
4a305f6a 890you to embed queries into shell commands. (mnemonic: PATH separator
f4750dab 891":".)
4a305f6a
JC
892
893 $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
894 compression-vars: zcat='' zip='zip' are here !
895
f4750dab 896A leading colon removes the "name=" part of the response, this allows
307dc113 897you to map to the name you need. (mnemonic: empty label)
4a305f6a
JC
898
899 $ echo "goodvfork="`./perl -Ilib -V::usevfork`
900 goodvfork=false;
901
902Leading and trailing colons can be used together if you need
903positional parameter values without the names. Note that in the case
f4750dab 904below, the C<PERL_API> params are returned in alphabetical order.
4a305f6a
JC
905
906 $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
907 building_on 'linux' '5' '1' '9' now
a0d0e21e 908
19799a22 909=item B<-w>
d74e8afc 910X<-w>
774d564b 911
19799a22 912prints warnings about dubious constructs, such as variable names
f4750dab
TC
913mentioned only once and scalar variables used
914before being set; redefined subroutines; references to undefined
915filehandles; filehandles opened read-only that you are attempting
916to write on; values used as a number that don't I<look> like numbers;
917using an array as though it were a scalar; if your subroutines
918recurse more than 100 deep; and innumerable other things.
919
920This switch really just enables the global C<$^W> variable; normally,
921the lexically scoped C<use warnings> pragma is preferred. You
19799a22
GS
922can disable or promote into fatal errors specific warnings using
923C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
f4750dab 924See also L<perldiag> and L<perltrap>. A fine-grained warning
19799a22 925facility is also available if you want to manipulate entire classes
44ecbbd8 926of warnings; see L<warnings>.
a0d0e21e 927
0453d815 928=item B<-W>
d74e8afc 929X<-W>
0453d815 930
3c3f8cd6 931Enables all warnings regardless of C<no warnings> or C<$^W>.
44ecbbd8 932See L<warnings>.
0453d815
PM
933
934=item B<-X>
d74e8afc 935X<-X>
0453d815 936
3c3f8cd6 937Disables all warnings regardless of C<use warnings> or C<$^W>.
44ecbbd8 938See L<warnings>.
0453d815 939
136e4fd6 940=item B<-x>
d74e8afc 941X<-x>
136e4fd6 942
d3bf4b0e 943=item B<-x>I<directory>
a0d0e21e 944
19799a22 945tells Perl that the program is embedded in a larger chunk of unrelated
f4750dab
TC
946text, such as in a mail message. Leading garbage will be
947discarded until the first line that starts with C<#!> and contains the
19799a22 948string "perl". Any meaningful switches on that line will be applied.
3d6c2ba7
B
949
950All references to line numbers by the program (warnings, errors, ...)
f4750dab
TC
951will treat the C<#!> line as the first line.
952Thus a warning on the 2nd line of the program, which is on the 100th
953line in the file will be reported as line 2, not as line 100.
954This can be overridden by using the C<#line> directive.
96090e4f 955(See L<perlsyn/"Plain Old Comments (Not!)">)
3d6c2ba7 956
19799a22
GS
957If a directory name is specified, Perl will switch to that directory
958before running the program. The B<-x> switch controls only the
959disposal of leading garbage. The program must be terminated with
f4750dab
TC
960C<__END__> if there is trailing garbage to be ignored; the program
961can process any or all of the trailing garbage via the C<DATA> filehandle
962if desired.
a0d0e21e 963
353c6505 964The directory, if specified, must appear immediately following the B<-x>
d3bf4b0e
DN
965with no intervening whitespace.
966
1e422769
PP
967=back
968
969=head1 ENVIRONMENT
d74e8afc 970X<perl, environment variables>
1e422769
PP
971
972=over 12
973
974=item HOME
d74e8afc 975X<HOME>
1e422769 976
f4750dab 977Used if C<chdir> has no argument.
1e422769
PP
978
979=item LOGDIR
d74e8afc 980X<LOGDIR>
1e422769 981
f4750dab 982Used if C<chdir> has no argument and HOME is not set.
1e422769
PP
983
984=item PATH
d74e8afc 985X<PATH>
1e422769 986
19799a22 987Used in executing subprocesses, and in finding the program if B<-S> is
1e422769
PP
988used.
989
990=item PERL5LIB
d74e8afc 991X<PERL5LIB>
1e422769 992
48b971ca 993A list of directories in which to look for Perl library
1e422769 994files before looking in the standard library and the current
4b85e17e
AD
995directory. Any architecture-specific and version-specific directories,
996such as F<version/archname/>, F<version/>, or F<archname/> under the
997specified locations are automatically included if they exist, with this
998lookup done at interpreter startup time. In addition, any directories
999matching the entries in C<$Config{inc_version_list}> are added.
1000(These typically would be for older compatible perl versions installed
1001in the same directory tree.)
69681433
AK
1002
1003If PERL5LIB is not defined, PERLLIB is used. Directories are separated
e1020413 1004(like in PATH) by a colon on Unixish platforms and by a semicolon on
69681433 1005Windows (the proper path separator being given by the command C<perl
f4750dab 1006-V:I<path_sep>>).
951ba7fe 1007
f4750dab
TC
1008When running taint checks, either because the program was running setuid or
1009setgid, or the B<-T> or B<-t> switch was specified, neither PERL5LIB nor
1010PERLLIB is consulted. The program should instead say:
1e422769
PP
1011
1012 use lib "/my/directory";
1013
54310121 1014=item PERL5OPT
d74e8afc 1015X<PERL5OPT>
54310121 1016
f4750dab 1017Command-line options (switches). Switches in this variable are treated
2b622f1a 1018as if they were on every Perl command line. Only the B<-[CDIMUdmtwW]>
f4750dab
TC
1019switches are allowed. When running taint checks (either because the
1020program was running setuid or setgid, or because the B<-T> or B<-t>
1021switch was used), this variable is ignored. If PERL5OPT begins with
cce9fd8c 1022B<-T>, tainting will be enabled and subsequent options ignored. If
f4750dab
TC
1023PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot
1024removed from @INC, and subsequent options honored.
54310121 1025
16537909 1026=item PERLIO
d74e8afc 1027X<PERLIO>
16537909 1028
44a4342c 1029A space (or colon) separated list of PerlIO layers. If perl is built
f4750dab 1030to use PerlIO system for IO (the default) these layers affect Perl's IO.
44a4342c 1031
f4750dab
TC
1032It is conventional to start layer names with a colon (for example, C<:perlio>) to
1033emphasize their similarity to variable "attributes". But the code that parses
cce9fd8c 1034layer specification strings, which is also used to decode the PERLIO
f4750dab 1035environment variable, treats the colon as a separator.
44a4342c 1036
5b64f2bf 1037An unset or empty PERLIO is equivalent to the default set of layers for
f4750dab 1038your platform; for example, C<:unix:perlio> on Unix-like systems
1f070127 1039and C<:unix:crlf> on Windows and other DOS-like systems.
3b0db4f9 1040
f4750dab
TC
1041The list becomes the default for I<all> Perl's IO. Consequently only built-in
1042layers can appear in this list, as external layers (such as C<:encoding()>) need
cce9fd8c 1043IO in order to load them! See L<"open pragma"|open> for how to add external
44a4342c
NIS
1044encodings as defaults.
1045
f4750dab
TC
1046Layers it makes sense to include in the PERLIO environment
1047variable are briefly summarized below. For more details see L<PerlIO>.
16537909
JH
1048
1049=over 8
1050
1051=item :bytes
d74e8afc 1052X<:bytes>
16537909 1053
f4750dab
TC
1054A pseudolayer that turns the C<:utf8> flag I<off> for the layer below;
1055unlikely to be useful on its own in the global PERLIO environment variable.
18aba96f 1056You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
16537909
JH
1057
1058=item :crlf
d74e8afc 1059X<:crlf>
16537909 1060
f4750dab 1061A layer which does CRLF to C<"\n"> translation distinguishing "text" and
3d897973
IT
1062"binary" files in the manner of MS-DOS and similar operating systems.
1063(It currently does I<not> mimic MS-DOS as far as treating of Control-Z
1064as being an end-of-file marker.)
44a4342c
NIS
1065
1066=item :mmap
d74e8afc 1067X<:mmap>
44a4342c 1068
f4750dab
TC
1069A layer that implements "reading" of files by using I<mmap>(2) to
1070make an entire file appear in the process's address space, and then
3d897973 1071using that as PerlIO's "buffer".
16537909 1072
44a4342c 1073=item :perlio
d74e8afc 1074X<:perlio>
16537909 1075
f4750dab
TC
1076This is a re-implementation of stdio-like buffering written as a
1077PerlIO layer. As such it will call whatever layer is below it for
1078its operations, typically C<:unix>.
16537909 1079
18aba96f 1080=item :pop
d74e8afc 1081X<:pop>
18aba96f
JH
1082
1083An experimental pseudolayer that removes the topmost layer.
f4750dab 1084Use with the same care as is reserved for nitroglycerine.
18aba96f 1085
44a4342c 1086=item :raw
d74e8afc 1087X<:raw>
16537909 1088
136e4fd6 1089A pseudolayer that manipulates other layers. Applying the C<:raw>
18aba96f 1090layer is equivalent to calling C<binmode($fh)>. It makes the stream
f4750dab
TC
1091pass each byte as-is without translation. In particular, both CRLF
1092translation and intuiting C<:utf8> from the locale are disabled.
1cbfc93d 1093
f4750dab
TC
1094Unlike in earlier versions of Perl, C<:raw> is I<not>
1095just the inverse of C<:crlf>: other layers which would affect the
3d897973 1096binary nature of the stream are also removed or disabled.
16537909 1097
44a4342c 1098=item :stdio
d74e8afc 1099X<:stdio>
44a4342c 1100
f4750dab 1101This layer provides a PerlIO interface by wrapping system's ANSI C "stdio"
44a4342c 1102library calls. The layer provides both buffering and IO.
f4750dab
TC
1103Note that the C<:stdio> layer does I<not> do CRLF translation even if that
1104is the platform's normal behaviour. You will need a C<:crlf> layer above it
44a4342c
NIS
1105to do that.
1106
1107=item :unix
d74e8afc 1108X<:unix>
44a4342c 1109
f4750dab 1110Low-level layer that calls C<read>, C<write>, C<lseek>, etc.
16537909
JH
1111
1112=item :utf8
d74e8afc 1113X<:utf8>
16537909 1114
f4750dab 1115A pseudolayer that enables a flag in the layer below to tell Perl
3d897973 1116that output should be in utf8 and that input should be regarded as
f4750dab
TC
1117already in valid utf8 form. B<WARNING: It does not check for validity and as such
1118should be handled with extreme caution for input, because security violations
1119can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(utf8)> is
740d4bb2 1120the best option when reading UTF-8 encoded data.
44a4342c
NIS
1121
1122=item :win32
d74e8afc 1123X<:win32>
44a4342c 1124
ab4f7683 1125On Win32 platforms this I<experimental> layer uses native "handle" IO
f4750dab
TC
1126rather than a Unix-like numeric file descriptor layer. Known to be
1127buggy in this release (5.14).
16537909
JH
1128
1129=back
1130
f4750dab 1131The default set of layers should give acceptable results on all platforms
44a4342c 1132
f4750dab
TC
1133For Unix platforms that will be the equivalent of "unix perlio" or "stdio".
1134Configure is set up to prefer the "stdio" implementation if the system's library
1135provides for fast access to the buffer; otherwise, it uses the "unix perlio"
44a4342c
NIS
1136implementation.
1137
f4750dab
TC
1138On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio"
1139has a number of bugs/mis-features for Perl IO which are somewhat depending
1140on the version and vendor of the C compiler. Using our own C<crlf> layer as
1141the buffer avoids those issues and makes things more uniform. The C<crlf>
1142layer provides CRLF conversion as well as buffering.
44a4342c 1143
f4750dab
TC
1144This release (5.14) uses C<unix> as the bottom layer on Win32, and so still
1145uses the C compiler's numeric file descriptor routines. There is an
1146experimental native C<win32> layer, which is expected to be enhanced and
1147should eventually become the default under Win32.
44a4342c 1148
f4750dab 1149The PERLIO environment variable is completely ignored when Perl
5437faeb
PF
1150is run in taint mode.
1151
44a4342c 1152=item PERLIO_DEBUG
d74e8afc 1153X<PERLIO_DEBUG>
44a4342c 1154
f4750dab 1155If set to the name of a file or device, certain operations of PerlIO
cce9fd8c 1156subsystem will be logged to that file, which is opened in append mode.
f4750dab 1157Typical uses are in Unix:
44a4342c 1158
f4750dab 1159 % env PERLIO_DEBUG=/dev/tty perl script ...
44a4342c 1160
f4750dab 1161and under Win32, the approximately equivalent:
44a4342c 1162
f4750dab 1163 > set PERLIO_DEBUG=CON
44a4342c
NIS
1164 perl script ...
1165
923e8b21
RGS
1166This functionality is disabled for setuid scripts and for scripts run
1167with B<-T>.
16537909 1168
1e422769 1169=item PERLLIB
d74e8afc 1170X<PERLLIB>
1e422769 1171
48b971ca 1172A list of directories in which to look for Perl library
1e422769
PP
1173files before looking in the standard library and the current directory.
1174If PERL5LIB is defined, PERLLIB is not used.
1175
f4750dab 1176The PERLLIB environment variable is completely ignored when Perl
5437faeb
PF
1177is run in taint mode.
1178
1e422769 1179=item PERL5DB
d74e8afc 1180X<PERL5DB>
1e422769
PP
1181
1182The command used to load the debugger code. The default is:
1183
f4750dab 1184 BEGIN { require "perl5db.pl" }
1e422769 1185
f4750dab 1186The PERL5DB environment variable is only used when Perl is started with
5437faeb
PF
1187a bare B<-d> switch.
1188
2cbb2ee1 1189=item PERL5DB_THREADED
d74e8afc 1190X<PERL5DB_THREADED>
2cbb2ee1
RGS
1191
1192If set to a true value, indicates to the debugger that the code being
1193debugged uses threads.
1194
19799a22 1195=item PERL5SHELL (specific to the Win32 port)
d74e8afc 1196X<PERL5SHELL>
174c211a 1197
f4750dab
TC
1198On Win32 ports only, may be set to an alternative shell that Perl must use
1199internally for executing "backtick" commands or system(). Default is
1200C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The
1201value is considered space-separated. Precede any character that
1202needs to be protected, like a space or backslash, with another backslash.
ce1da67e
GS
1203
1204Note that Perl doesn't use COMSPEC for this purpose because
1205COMSPEC has a high degree of variability among users, leading to
f4750dab 1206portability concerns. Besides, Perl can use a shell that may not be
ce1da67e
GS
1207fit for interactive use, and setting COMSPEC to such a shell may
1208interfere with the proper functioning of other programs (which usually
1209look in COMSPEC to find a shell fit for interactive use).
174c211a 1210
5437faeb
PF
1211Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked
1212when running external commands. It is recommended that
1213you explicitly set (or delete) C<$ENV{PERL5SHELL}> when running
1214in taint mode under Windows.
1215
1c972609 1216=item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
d74e8afc 1217X<PERL_ALLOW_NON_IFS_LSP>
1c972609 1218
f4750dab 1219Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers).
1c972609
SH
1220Perl normally searches for an IFS-compatible LSP because this is required
1221for its emulation of Windows sockets as real filehandles. However, this may
f4750dab
TC
1222cause problems if you have a firewall such as I<McAfee Guardian>, which requires
1223that all applications use its LSP but which is not IFS-compatible, because clearly
1c972609 1224Perl will normally avoid using such an LSP.
f4750dab 1225
1c972609 1226Setting this environment variable to 1 means that Perl will simply use the
f4750dab
TC
1227first suitable LSP enumerated in the catalog, which keeps I<McAfee Guardian>
1228happy--and in that particular case Perl still works too because I<McAfee
1229Guardian>'s LSP actually plays other games which allow applications
1230requiring IFS compatibility to work.
1c972609 1231
1e422769 1232=item PERL_DEBUG_MSTATS
d74e8afc 1233X<PERL_DEBUG_MSTATS>
1e422769 1234
f4750dab
TC
1235Relevant only if Perl is compiled with the C<malloc> included with the Perl
1236distribution; that is, if C<perl -V:d_mymalloc> is "define".
1237
1238If set, this dumps out memory statistics after execution. If set
1239to an integer greater than one, also dumps out memory statistics
1e422769
PP
1240after compilation.
1241
1242=item PERL_DESTRUCT_LEVEL
d74e8afc 1243X<PERL_DESTRUCT_LEVEL>
1e422769 1244
f4750dab
TC
1245Relevant only if your Perl executable was built with B<-DDEBUGGING>,
1246this controls the behaviour of global destruction of objects and other
96090e4f 1247references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information.
a0d0e21e 1248
02c7413a 1249=item PERL_DL_NONLAZY
d74e8afc 1250X<PERL_DL_NONLAZY>
02c7413a 1251
f4750dab 1252Set to C<"1"> to have Perl resolve I<all> undefined symbols when it loads
02c7413a
GA
1253a dynamic library. The default behaviour is to resolve symbols when
1254they are used. Setting this variable is useful during testing of
f4750dab
TC
1255extensions, as it ensures that you get an error on misspelled function
1256names even if the test suite doesn't call them.
02c7413a 1257
5d170f3a 1258=item PERL_ENCODING
d74e8afc 1259X<PERL_ENCODING>
5d170f3a 1260
f4750dab 1261If using the C<use encoding> pragma without an explicit encoding name, the
5d170f3a
JH
1262PERL_ENCODING environment variable is consulted for an encoding name.
1263
504f80c1 1264=item PERL_HASH_SEED
d74e8afc 1265X<PERL_HASH_SEED>
504f80c1 1266
6a5b4183
YO
1267(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override
1268the randomization of Perl's internal hash function. The value is expressed
1269in hexadecimal, and may include a leading 0x. Truncated patterns
1270are treated as though they are suffixed with sufficient 0's as required.
8d4a1e6c 1271
6a5b4183
YO
1272If the option is provided, and C<PERL_PERTURB_KEYS> is NOT set, then
1273a value of '0' implies C<PERL_PERTURB_KEYS=0> and any other value
1274implies C<PERL_PERTURB_KEYS=2>.
504f80c1 1275
f4750dab 1276B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are
26a2d347 1277randomized to protect against local and remote attacks against Perl
f4750dab 1278code. By manually setting a seed, this protection may be partially or
26a2d347
JH
1279completely lost.
1280
4a70680a 1281See L<perlsec/"Algorithmic Complexity Attacks">, L</PERL_PERTURB_KEYS>, and
26a2d347 1282L</PERL_HASH_SEED_DEBUG> for more information.
504f80c1 1283
6a5b4183
YO
1284=item PERL_PERTURB_KEYS
1285X<PERL_PERTURB_KEYS>
1286
1287(Since Perl 5.18.0) Set to C<"0"> or C<"NO"> then traversing keys
e6b54db6 1288will be repeatable from run to run for the same PERL_HASH_SEED.
6a5b4183
YO
1289Insertion into a hash will not change the order, except to provide
1290for more space in the hash. When combined with setting PERL_HASH_SEED
1291this mode is as close to pre 5.18 behavior as you can get.
1292
1293When set to C<"1"> or C<"RANDOM"> then traversing keys will be randomized.
1294Every time a hash is inserted into the key order will change in a random
e6b54db6 1295fashion. The order may not be repeatable in a following program run
6a5b4183
YO
1296even if the PERL_HASH_SEED has been specified. This is the default
1297mode for perl.
1298
1299When set to C<"2"> or C<"DETERMINISTIC"> then inserting keys into a hash
e6b54db6 1300will cause the key order to change, but in a way that is repeatable
6a5b4183
YO
1301from program run to program run.
1302
1303B<NOTE:> Use of this option is considered insecure, and is intended only
1304for debugging non-deterministic behavior in Perl's hash function. Do
1305not use it in production.
1306
1307See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_HASH_SEED>
1308and L</PERL_HASH_SEED_DEBUG> for more information. You can get and set the
1309key traversal mask for a specific hash by using the C<hash_traversal_mask()>
1310function from L<Hash::Util>.
1311
2191697e 1312=item PERL_HASH_SEED_DEBUG
d74e8afc 1313X<PERL_HASH_SEED_DEBUG>
2191697e 1314
6a5b4183
YO
1315(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) information
1316about the hash function, seed, and what type of key traversal
1317randomization is in effect at the beginning of execution. This, combined
1318with L</PERL_HASH_SEED> and L</PERL_PERTURB_KEYS> is intended to aid in
1319debugging nondeterministic behaviour caused by hash randomization.
1320
1321B<Note> that any information about the hash function, especially the hash
1322seed is B<sensitive information>: by knowing it, one can craft a denial-of-service
1323attack against Perl code, even remotely; see L<perlsec/"Algorithmic Complexity Attacks">
1324for more information. B<Do not disclose the hash seed> to people who
1325don't need to know it. See also C<hash_seed()> and
1326C<key_traversal_mask()> in L<Hash::Util>.
1327
1328An example output might be:
26a2d347 1329
e46aa1dd 1330 HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
2191697e 1331
9aa9f499
JC
1332=item PERL_MEM_LOG
1333X<PERL_MEM_LOG>
1334
f4750dab 1335If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting
7916a455 1336the environment variable C<PERL_MEM_LOG> enables logging debug
f4750dab
TC
1337messages. The value has the form C<< <I<number>>[m][s][t] >>, where
1338C<I<number>> is the file descriptor number you want to write to (2 is
7916a455
JC
1339default), and the combination of letters specifies that you want
1340information about (m)emory and/or (s)v, optionally with
f4750dab
TC
1341(t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all
1342information to stdout. You can write to other opened file descriptors
1343in a variety of ways:
9aa9f499 1344
f4750dab 1345 $ 3>foo3 PERL_MEM_LOG=3m perl ...
9aa9f499 1346
3d0ae7ba 1347=item PERL_ROOT (specific to the VMS port)
d74e8afc 1348X<PERL_ROOT>
3d0ae7ba 1349
f4750dab 1350A translation-concealed rooted logical name that contains Perl and the
3d0ae7ba 1351logical device for the @INC path on VMS only. Other logical names that
f4750dab
TC
1352affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and
1353SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in
3d0ae7ba
GS
1354L<perlvms> and in F<README.vms> in the Perl source distribution.
1355
4ffa73a3 1356=item PERL_SIGNALS
d74e8afc 1357X<PERL_SIGNALS>
4ffa73a3 1358
f4750dab
TC
1359Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0
1360signal behaviour (which is immediate but unsafe) is restored. If set
1361to C<safe>, then safe (but deferred) signals are used. See
1362L<perlipc/"Deferred Signals (Safe Signals)">.
4ffa73a3 1363
a05d7ebb 1364=item PERL_UNICODE
d74e8afc 1365X<PERL_UNICODE>
acae81db 1366
bf61ac64 1367Equivalent to the B<-C> command-line switch. Note that this is not
ac036724 1368a boolean variable. Setting this to C<"1"> is not the right way to
5b4f334e 1369"enable Unicode" (whatever that would mean). You can use C<"0"> to
e654d908 1370"disable Unicode", though (or alternatively unset PERL_UNICODE in
f4750dab 1371your shell before starting Perl). See the description of the B<-C>
e654d908 1372switch for more information.
acae81db 1373
3d0ae7ba 1374=item SYS$LOGIN (specific to the VMS port)
d74e8afc 1375X<SYS$LOGIN>
3d0ae7ba
GS
1376
1377Used if chdir has no argument and HOME and LOGDIR are not set.
1378
a0d0e21e 1379=back
1e422769
PP
1380
1381Perl also has environment variables that control how Perl handles data
f4750dab
TC
1382specific to particular natural languages; see L<perllocale>.
1383
1384Perl and its various modules and components, including its test frameworks,
1385may sometimes make use of certain other environment variables. Some of
1386these are specific to a particular platform. Please consult the
1387appropriate module documentation and any documentation for your platform
1388(like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for
1389variables peculiar to those specific situations.
1390
1391Perl makes all environment variables available to the program being
1392executed, and passes these along to any child processes it starts.
1393However, programs running setuid would do well to execute the following
1394lines before doing anything else, just to keep people honest:
1395
1396 $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need
1397 $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
c90c0ff4 1398 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};