This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlrun: Note that -W can't be in PERL5OPT
[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
5a0de581 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
2c4188f3 348executing it. Actually, it I<will> execute any C<BEGIN>, C<UNITCHECK>,
f4750dab
TC
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
f075db89
DM
382sets debugging flags. This switch is enabled only if your perl binary has
383been built with debugging enabled: normal production perls won't have
384been.
385
386For example, to watch how perl executes your program, use B<-Dtls>.
387Another nice value is B<-Dx>, which lists your compiled syntax tree, and
388B<-Dr> displays compiled regular expressions; the format of the output is
389explained in L<perldebguts>.
4197b13f
MJD
390
391As an alternative, specify a number instead of list of letters (e.g.,
392B<-D14> is equivalent to B<-Dtls>):
a0d0e21e 393
e17bc05a
TC
394 1 p Tokenizing and parsing (with v, displays parse
395 stack)
396 2 s Stack snapshots (with v, displays all stacks)
397 4 l Context (loop) stack processing
398 8 t Trace execution
399 16 o Method and overloading resolution
400 32 c String/numeric conversions
401 64 P Print profiling info, source file input state
402 128 m Memory and SV allocation
403 256 f Format processing
404 512 r Regular expression parsing and execution
405 1024 x Syntax tree dump
406 2048 u Tainting checks
407 4096 U Unofficial, User hacking (reserved for private,
408 unreleased use)
e17bc05a
TC
409 16384 X Scratchpad allocation
410 32768 D Cleaning up
411 65536 S Op slab allocation
412 131072 T Tokenizing
413 262144 R Include reference counts of dumped variables
414 (eg when using -Ds)
415 524288 J show s,t,P-debug (don't Jump over) on opcodes within
416 package DB
98c74407
KW
417 1048576 v Verbose: use in conjunction with other flags to
418 increase the verbosity of the output. Is a no-op on
419 many of the other flags
e17bc05a
TC
420 2097152 C Copy On Write
421 4194304 A Consistency checks on internal structures
422 8388608 q quiet - currently only suppresses the "EXECUTING"
423 message
7896dde7 424 16777216 M trace smart match resolution
e17bc05a
TC
425 33554432 B dump suBroutine definitions, including special
426 Blocks like BEGIN
427 67108864 L trace Locale-related info; what gets output is very
428 subject to change
429 134217728 i trace PerlIO layer processing. Set PERLIO_DEBUG to
430 the filename to trace to.
a0d0e21e 431
19799a22 432All these flags require B<-DDEBUGGING> when you compile the Perl
c85da6fc
TH
433executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode>
434which may change this).
44a4342c 435See the F<INSTALL> file in the Perl source distribution
f075db89 436for how to do this.
8c52afec 437
19799a22
GS
438If you're just trying to get a print out of each line of Perl code
439as it executes, the way that C<sh -x> provides for shell scripts,
44a4342c 440you can't use Perl's B<-D> switch. Instead do this
19799a22 441
c406981e 442 # If you have "env" utility
fdac53cd 443 env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
c406981e 444
19799a22
GS
445 # Bourne shell syntax
446 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
447
448 # csh syntax
449 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
450
451See L<perldebug> for details and variations.
452
a0d0e21e 453=item B<-e> I<commandline>
d74e8afc 454X<-e>
a0d0e21e 455
19799a22
GS
456may be used to enter one line of program. If B<-e> is given, Perl
457will not look for a filename in the argument list. Multiple B<-e>
458commands may be given to build up a multi-line script. Make sure
459to use semicolons where you would in a normal program.
a0d0e21e 460
bc9b29db
RH
461=item B<-E> I<commandline>
462X<-E>
463
464behaves just like B<-e>, except that it implicitly enables all
465optional features (in the main compilation unit). See L<feature>.
466
20ef40cf 467=item B<-f>
174299ac 468X<-f> X<sitecustomize> X<sitecustomize.pl>
20ef40cf 469
4a42f219 470Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup.
20ef40cf
GA
471
472Perl can be built so that it by default will try to execute
e846cbe5 473F<$Config{sitelib}/sitecustomize.pl> at startup (in a BEGIN block).
f4750dab
TC
474This is a hook that allows the sysadmin to customize how Perl behaves.
475It can for instance be used to add entries to the @INC array to make Perl
e846cbe5 476find modules in non-standard locations.
20ef40cf 477
298ca354
PBB
478Perl actually inserts the following code:
479
480 BEGIN {
481 do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
482 && do "$Config{sitelib}/sitecustomize.pl";
483 }
484
485Since it is an actual C<do> (not a C<require>), F<sitecustomize.pl>
486doesn't need to return a true value. The code is run in package C<main>,
487in its own lexical scope. However, if the script dies, C<$@> will not
488be set.
489
490The value of C<$Config{sitelib}> is also determined in C code and not
491read from C<Config.pm>, which is not loaded.
492
f4750dab 493The code is executed I<very> early. For example, any changes made to
298ca354
PBB
494C<@INC> will show up in the output of `perl -V`. Of course, C<END>
495blocks will be likewise executed very late.
496
497To determine at runtime if this capability has been compiled in your
498perl, you can check the value of C<$Config{usesitecustomize}>.
499
e0ebc809 500=item B<-F>I<pattern>
d74e8afc 501X<-F>
a0d0e21e 502
24ffa309
TC
503specifies the pattern to split on for B<-a>. The pattern may be
504surrounded by C<//>, C<"">, or C<''>, otherwise it will be put in single
f149fd41 505quotes. You can't use literal whitespace or NUL characters in the pattern.
24ffa309
TC
506
507B<-F> implicitly sets both B<-a> and B<-n>.
a0d0e21e 508
e0ebc809 509=item B<-h>
d74e8afc 510X<-h>
e0ebc809
PP
511
512prints a summary of the options.
513
514=item B<-i>[I<extension>]
d74e8afc 515X<-i> X<in-place>
a0d0e21e 516
2d259d92
CK
517specifies that files processed by the C<E<lt>E<gt>> construct are to be
518edited in-place. It does this by renaming the input file, opening the
519output file by the original name, and selecting that output file as the
520default for print() statements. The extension, if supplied, is used to
521modify the name of the old file to make a backup copy, following these
522rules:
523
479e5f87
PM
524If no extension is supplied, and your system supports it, the original
525I<file> is kept open without a name while the output is redirected to
526a new file with the original I<filename>. When perl exits, cleanly or not,
527the original I<file> is unlinked.
2d259d92 528
19799a22
GS
529If the extension doesn't contain a C<*>, then it is appended to the
530end of the current filename as a suffix. If the extension does
531contain one or more C<*> characters, then each C<*> is replaced
532with the current filename. In Perl terms, you could think of this
533as:
2d259d92 534
66606d78 535 ($backup = $extension) =~ s/\*/$file_name/g;
2d259d92
CK
536
537This allows you to add a prefix to the backup file, instead of (or in
538addition to) a suffix:
539
60b7c710
KW
540 $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to
541 # 'orig_fileA'
2d259d92
CK
542
543Or even to place backup copies of the original files into another
544directory (provided the directory already exists):
545
60b7c710
KW
546 $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to
547 # 'old/fileA.orig'
2d259d92 548
66606d78
CK
549These sets of one-liners are equivalent:
550
60b7c710
KW
551 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
552 $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
66606d78 553
60b7c710
KW
554 $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
555 $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
66606d78 556
2d259d92 557From the shell, saying
a0d0e21e 558
19799a22 559 $ perl -p -i.orig -e "s/foo/bar/; ... "
a0d0e21e 560
19799a22 561is the same as using the program:
a0d0e21e 562
19799a22 563 #!/usr/bin/perl -pi.orig
a0d0e21e
LW
564 s/foo/bar/;
565
566which is equivalent to
567
568 #!/usr/bin/perl
19799a22
GS
569 $extension = '.orig';
570 LINE: while (<>) {
a0d0e21e 571 if ($ARGV ne $oldargv) {
66606d78
CK
572 if ($extension !~ /\*/) {
573 $backup = $ARGV . $extension;
574 }
575 else {
576 ($backup = $extension) =~ s/\*/$ARGV/g;
577 }
578 rename($ARGV, $backup);
a0d0e21e
LW
579 open(ARGVOUT, ">$ARGV");
580 select(ARGVOUT);
581 $oldargv = $ARGV;
582 }
583 s/foo/bar/;
584 }
585 continue {
586 print; # this prints to original filename
587 }
588 select(STDOUT);
589
590except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
591know when the filename has changed. It does, however, use ARGVOUT for
66606d78
CK
592the selected filehandle. Note that STDOUT is restored as the default
593output filehandle after the loop.
594
595As shown above, Perl creates the backup file whether or not any output
596is actually changed. So this is just a fancy way to copy files:
597
cd2d1bac 598 $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
19799a22 599or
cd2d1bac 600 $ perl -p -i'.orig' -e 1 file1 file2 file3...
66606d78
CK
601
602You can use C<eof> without parentheses to locate the end of each input
603file, in case you want to append to each file, or reset line numbering
604(see example in L<perlfunc/eof>).
605
606If, for a given file, Perl is unable to create the backup file as
607specified in the extension then it will skip that file and continue on
608with the next one (if it exists).
609
1dcc3c19
DG
610For a discussion of issues surrounding file permissions and B<-i>, see
611L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber
612protected files? Isn't this a bug in Perl?>.
66606d78
CK
613
614You cannot use B<-i> to create directories or to strip extensions from
615files.
a0d0e21e 616
19799a22
GS
617Perl does not expand C<~> in filenames, which is good, since some
618folks use it for their backup files:
a0d0e21e 619
19799a22
GS
620 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
621
a66b22ca 622Note that because B<-i> renames or deletes the original file before
e1020413 623creating a new file of the same name, Unix-style soft and hard links will
0cb0633f 624not be preserved.
a66b22ca 625
19799a22 626Finally, the B<-i> switch does not impede execution when no
a2008d6d
GS
627files are given on the command line. In this case, no backup is made
628(the original file cannot, of course, be determined) and processing
629proceeds from STDIN to STDOUT as might be expected.
630
a0d0e21e 631=item B<-I>I<directory>
d74e8afc 632X<-I> X<@INC>
a0d0e21e 633
e0ebc809 634Directories specified by B<-I> are prepended to the search path for
4c84d7f2 635modules (C<@INC>).
a0d0e21e 636
e0ebc809 637=item B<-l>[I<octnum>]
d74e8afc 638X<-l> X<$/> X<$\>
a0d0e21e 639
19799a22
GS
640enables automatic line-ending processing. It has two separate
641effects. First, it automatically chomps C<$/> (the input record
642separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
643(the output record separator) to have the value of I<octnum> so
644that any print statements will have that separator added back on.
645If I<octnum> is omitted, sets C<$\> to the current value of
646C<$/>. For instance, to trim lines to 80 columns:
a0d0e21e
LW
647
648 perl -lpe 'substr($_, 80) = ""'
649
650Note that the assignment C<$\ = $/> is done when the switch is processed,
651so the input record separator can be different than the output record
652separator if the B<-l> switch is followed by a B<-0> switch:
653
654 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
655
1fef88e7 656This sets C<$\> to newline and then sets C<$/> to the null character.
a0d0e21e 657
e0ebc809 658=item B<-m>[B<->]I<module>
d74e8afc 659X<-m> X<-M>
e0ebc809
PP
660
661=item B<-M>[B<->]I<module>
c07a80fd 662
e0ebc809
PP
663=item B<-M>[B<->]I<'module ...'>
664
665=item B<-[mM]>[B<->]I<module=arg[,arg]...>
3c81428c 666
19799a22 667B<-m>I<module> executes C<use> I<module> C<();> before executing your
e2bcc7d7
Z
668program. This loads the module, but does not call its C<import> method,
669so does not import subroutines and does not give effect to a pragma.
3c81428c 670
19799a22 671B<-M>I<module> executes C<use> I<module> C<;> before executing your
e2bcc7d7
Z
672program. This loads the module and calls its C<import> method, causing
673the module to have its default effect, typically importing subroutines
674or giving effect to a pragma.
675You can use quotes to add extra code after the module name,
f4750dab 676e.g., C<'-MI<MODULE> qw(foo bar)'>.
3c81428c 677
f4750dab 678If the first character after the B<-M> or B<-m> is a dash (B<->)
a5f75d66 679then the 'use' is replaced with 'no'.
e2bcc7d7 680This makes no difference for B<-m>.
a5f75d66 681
54310121 682A little builtin syntactic sugar means you can also say
f4750dab
TC
683B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for
684B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when
685importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is
e0ebc809 686C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
c2d9228f
A
687removes the distinction between B<-m> and B<-M>; that is,
688B<-mI<MODULE>=foo,bar> is the same as B<-MI<MODULE>=foo,bar>.
3c81428c 689
e2bcc7d7
Z
690A consequence of the C<split> formulation
691is that B<-MI<MODULE>=number> never does a version check,
f4750dab
TC
692unless C<I<MODULE>::import()> itself is set up to do a version check, which
693could happen for example if I<MODULE> inherits from L<Exporter>.
642d0c2f 694
a0d0e21e 695=item B<-n>
d74e8afc 696X<-n>
a0d0e21e 697
19799a22 698causes Perl to assume the following loop around your program, which
f4750dab
TC
699makes it iterate over filename arguments somewhat like I<sed -n> or
700I<awk>:
a0d0e21e 701
19799a22 702 LINE:
a0d0e21e 703 while (<>) {
19799a22 704 ... # your program goes here
a0d0e21e
LW
705 }
706
76c9ab0e 707Note that the lines are not printed by default. See L</-p> to have
08e9d68e 708lines printed. If a file named by an argument cannot be opened for
19799a22 709some reason, Perl warns you about it and moves on to the next file.
08e9d68e 710
48ab5743
ML
711Also note that C<< <> >> passes command line arguments to
712L<perlfunc/open>, which doesn't necessarily interpret them as file names.
713See L<perlop> for possible security implications.
714
fa11829f 715Here is an efficient way to delete all files that haven't been modified for
9976c5c7 716at least a week:
a0d0e21e 717
19799a22 718 find . -mtime +7 -print | perl -nle unlink
a0d0e21e 719
f4750dab 720This is faster than using the B<-exec> switch of I<find> because you don't
45cc06e3
DH
721have to start a process on every filename found (but it's not faster
722than using the B<-delete> switch available in newer versions of I<find>.
723It does suffer from the bug of mishandling newlines in pathnames, which
724you can fix if you follow the example under B<-0>.
a0d0e21e
LW
725
726C<BEGIN> and C<END> blocks may be used to capture control before or after
f4750dab 727the implicit program loop, just as in I<awk>.
a0d0e21e
LW
728
729=item B<-p>
d74e8afc 730X<-p>
a0d0e21e 731
19799a22 732causes Perl to assume the following loop around your program, which
f4750dab 733makes it iterate over filename arguments somewhat like I<sed>:
a0d0e21e
LW
734
735
19799a22 736 LINE:
a0d0e21e 737 while (<>) {
19799a22 738 ... # your program goes here
a0d0e21e 739 } continue {
08e9d68e 740 print or die "-p destination: $!\n";
a0d0e21e
LW
741 }
742
08e9d68e
DD
743If a file named by an argument cannot be opened for some reason, Perl
744warns you about it, and moves on to the next file. Note that the
c2611fb3 745lines are printed automatically. An error occurring during printing is
08e9d68e
DD
746treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
747overrides a B<-n> switch.
a0d0e21e
LW
748
749C<BEGIN> and C<END> blocks may be used to capture control before or after
f4750dab 750the implicit loop, just as in I<awk>.
a0d0e21e 751
a0d0e21e 752=item B<-s>
d74e8afc 753X<-s>
a0d0e21e 754
19799a22
GS
755enables rudimentary switch parsing for switches on the command
756line after the program name but before any filename arguments (or before
74ac850a 757an argument of B<-->). Any switch found there is removed from @ARGV and sets the
19799a22 758corresponding variable in the Perl program. The following program
3c0facb2
GS
759prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
760if it is invoked with B<-xyz=abc>.
a0d0e21e
LW
761
762 #!/usr/bin/perl -s
3c0facb2 763 if ($xyz) { print "$xyz\n" }
a0d0e21e 764
1dcc3c19
DG
765Do note that a switch like B<--help> creates the variable C<${-help}>, which is
766not compliant with C<use strict "refs">. Also, when using this option on a
767script with warnings enabled you may get a lot of spurious "used only once"
768warnings.
3bbcc830 769
a0d0e21e 770=item B<-S>
d74e8afc 771X<-S>
a0d0e21e
LW
772
773makes Perl use the PATH environment variable to search for the
f4750dab 774program unless the name of the program contains path separators.
19799a22 775
2a92aaa0
GS
776On some platforms, this also makes Perl append suffixes to the
777filename while searching for it. For example, on Win32 platforms,
778the ".bat" and ".cmd" suffixes are appended if a lookup for the
779original name fails, and if the name does not already end in one
f4750dab
TC
780of those suffixes. If your Perl was compiled with C<DEBUGGING> turned
781on, using the B<-Dp> switch to Perl shows how the search progresses.
2a92aaa0 782
f4750dab
TC
783Typically this is used to emulate C<#!> startup on platforms that don't
784support C<#!>. It's also convenient when debugging a script that uses C<#!>,
fa3aa65a
JC
785and is thus normally found by the shell's $PATH search mechanism.
786
787This example works on many platforms that have a shell compatible with
788Bourne shell:
a0d0e21e
LW
789
790 #!/usr/bin/perl
a3cb178b 791 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
a0d0e21e
LW
792 if $running_under_some_shell;
793
19799a22
GS
794The system ignores the first line and feeds the program to F</bin/sh>,
795which proceeds to try to execute the Perl program as a shell script.
a0d0e21e
LW
796The shell executes the second line as a normal shell command, and thus
797starts up the Perl interpreter. On some systems $0 doesn't always
798contain the full pathname, so the B<-S> tells Perl to search for the
19799a22 799program if necessary. After Perl locates the program, it parses the
a0d0e21e 800lines and ignores them because the variable $running_under_some_shell
19799a22 801is never true. If the program will be interpreted by csh, you will need
a3cb178b 802to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
f4750dab
TC
803embedded spaces (and such) in the argument list. To start up I<sh> rather
804than I<csh>, some systems may have to replace the C<#!> line with a line
a0d0e21e
LW
805containing just a colon, which will be politely ignored by Perl. Other
806systems can't control that, and need a totally devious construct that
f4750dab 807will work under any of I<csh>, I<sh>, or Perl, such as the following:
a0d0e21e 808
19799a22 809 eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
a3cb178b 810 & eval 'exec /usr/bin/perl -wS $0 $argv:q'
5f05dabc 811 if $running_under_some_shell;
a0d0e21e 812
f4750dab 813If the filename supplied contains directory separators (and so is an
19799a22
GS
814absolute or relative pathname), and if that file is not found,
815platforms that append file extensions will do so and try to look
816for the file with those extensions added, one by one.
817
818On DOS-like platforms, if the program does not contain directory
819separators, it will first be searched for in the current directory
820before being searched for on the PATH. On Unix platforms, the
821program will be searched for strictly on the PATH.
822
6537fe72 823=item B<-t>
d74e8afc 824X<-t>
6537fe72
MS
825
826Like B<-T>, but taint checks will issue warnings rather than fatal
f4750dab 827errors. These warnings can now be controlled normally with C<no warnings
317ea90d 828qw(taint)>.
1dbad523 829
f4750dab
TC
830B<Note: This is not a substitute for C<-T>!> This is meant to be
831used I<only> as a temporary development aid while securing legacy code:
832for real production code and for new secure code written from scratch,
1dbad523 833always use the real B<-T>.
6537fe72 834
a0d0e21e 835=item B<-T>
d74e8afc 836X<-T>
a0d0e21e 837
f4750dab 838turns on "taint" so you can test them. Ordinarily
19799a22
GS
839these checks are done only when running setuid or setgid. It's a
840good idea to turn them on explicitly for programs that run on behalf
841of someone else whom you might not necessarily trust, such as CGI
842programs or any internet servers you might write in Perl. See
843L<perlsec> for details. For security reasons, this option must be
844seen by Perl quite early; usually this means it must appear early
f4750dab 845on the command line or in the C<#!> line for systems which support
19799a22 846that construct.
a0d0e21e
LW
847
848=item B<-u>
d74e8afc 849X<-u>
a0d0e21e 850
f4750dab 851This switch causes Perl to dump core after compiling your
19799a22 852program. You can then in theory take this core dump and turn it
f4750dab 853into an executable file by using the I<undump> program (not supplied).
19799a22
GS
854This speeds startup at the expense of some disk space (which you
855can minimize by stripping the executable). (Still, a "hello world"
856executable comes out to about 200K on my machine.) If you want to
d8ff3e95
JK
857execute a portion of your program before dumping, use the C<CORE::dump()>
858function instead. Note: availability of I<undump> is platform
19799a22
GS
859specific and may not be available for a specific port of Perl.
860
a0d0e21e 861=item B<-U>
d74e8afc 862X<-U>
a0d0e21e
LW
863
864allows Perl to do unsafe operations. Currently the only "unsafe"
f4750dab
TC
865operations are attempting to unlink directories while running as superuser
866and running setuid programs with fatal taint checks turned into warnings.
867Note that warnings must be enabled along with this option to actually
868I<generate> the taint-check warnings.
a0d0e21e
LW
869
870=item B<-v>
d74e8afc 871X<-v>
a0d0e21e 872
19799a22 873prints the version and patchlevel of your perl executable.
a0d0e21e 874
3c81428c 875=item B<-V>
d74e8afc 876X<-V>
3c81428c
PP
877
878prints summary of the major perl configuration values and the current
19799a22 879values of @INC.
3c81428c 880
307dc113 881=item B<-V:>I<configvar>
3c81428c 882
4a305f6a 883Prints to STDOUT the value of the named configuration variable(s),
f4750dab 884with multiples when your C<I<configvar>> argument looks like a regex (has
307dc113 885non-letters). For example:
3c81428c 886
307dc113
JC
887 $ perl -V:libc
888 libc='/lib/libc-2.2.4.so';
4a305f6a
JC
889 $ perl -V:lib.
890 libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
891 libc='/lib/libc-2.2.4.so';
892 $ perl -V:lib.*
893 libpth='/usr/local/lib /lib /usr/lib';
894 libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
895 lib_ext='.a';
896 libc='/lib/libc-2.2.4.so';
897 libperl='libperl.a';
898 ....
899
900Additionally, extra colons can be used to control formatting. A
f4750dab 901trailing colon suppresses the linefeed and terminator ";", allowing
4a305f6a 902you to embed queries into shell commands. (mnemonic: PATH separator
f4750dab 903":".)
4a305f6a
JC
904
905 $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
906 compression-vars: zcat='' zip='zip' are here !
907
f4750dab 908A leading colon removes the "name=" part of the response, this allows
307dc113 909you to map to the name you need. (mnemonic: empty label)
4a305f6a
JC
910
911 $ echo "goodvfork="`./perl -Ilib -V::usevfork`
912 goodvfork=false;
913
914Leading and trailing colons can be used together if you need
915positional parameter values without the names. Note that in the case
f4750dab 916below, the C<PERL_API> params are returned in alphabetical order.
4a305f6a
JC
917
918 $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
919 building_on 'linux' '5' '1' '9' now
a0d0e21e 920
19799a22 921=item B<-w>
d74e8afc 922X<-w>
774d564b 923
19799a22 924prints warnings about dubious constructs, such as variable names
f4750dab
TC
925mentioned only once and scalar variables used
926before being set; redefined subroutines; references to undefined
927filehandles; filehandles opened read-only that you are attempting
928to write on; values used as a number that don't I<look> like numbers;
929using an array as though it were a scalar; if your subroutines
930recurse more than 100 deep; and innumerable other things.
931
932This switch really just enables the global C<$^W> variable; normally,
933the lexically scoped C<use warnings> pragma is preferred. You
19799a22
GS
934can disable or promote into fatal errors specific warnings using
935C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
f4750dab 936See also L<perldiag> and L<perltrap>. A fine-grained warning
19799a22 937facility is also available if you want to manipulate entire classes
44ecbbd8 938of warnings; see L<warnings>.
a0d0e21e 939
0453d815 940=item B<-W>
d74e8afc 941X<-W>
0453d815 942
3c3f8cd6 943Enables all warnings regardless of C<no warnings> or C<$^W>.
44ecbbd8 944See L<warnings>.
0453d815
PM
945
946=item B<-X>
d74e8afc 947X<-X>
0453d815 948
3c3f8cd6 949Disables all warnings regardless of C<use warnings> or C<$^W>.
44ecbbd8 950See L<warnings>.
0453d815 951
7cb9b5f3
KW
952Forbidden in L</C<PERL5OPT>>.
953
136e4fd6 954=item B<-x>
d74e8afc 955X<-x>
136e4fd6 956
d3bf4b0e 957=item B<-x>I<directory>
a0d0e21e 958
19799a22 959tells Perl that the program is embedded in a larger chunk of unrelated
f4750dab
TC
960text, such as in a mail message. Leading garbage will be
961discarded until the first line that starts with C<#!> and contains the
19799a22 962string "perl". Any meaningful switches on that line will be applied.
3d6c2ba7
B
963
964All references to line numbers by the program (warnings, errors, ...)
f4750dab
TC
965will treat the C<#!> line as the first line.
966Thus a warning on the 2nd line of the program, which is on the 100th
967line in the file will be reported as line 2, not as line 100.
968This can be overridden by using the C<#line> directive.
96090e4f 969(See L<perlsyn/"Plain Old Comments (Not!)">)
3d6c2ba7 970
19799a22
GS
971If a directory name is specified, Perl will switch to that directory
972before running the program. The B<-x> switch controls only the
973disposal of leading garbage. The program must be terminated with
f4750dab
TC
974C<__END__> if there is trailing garbage to be ignored; the program
975can process any or all of the trailing garbage via the C<DATA> filehandle
976if desired.
a0d0e21e 977
353c6505 978The directory, if specified, must appear immediately following the B<-x>
d3bf4b0e
DN
979with no intervening whitespace.
980
1e422769
PP
981=back
982
983=head1 ENVIRONMENT
d74e8afc 984X<perl, environment variables>
1e422769
PP
985
986=over 12
987
988=item HOME
d74e8afc 989X<HOME>
1e422769 990
f4750dab 991Used if C<chdir> has no argument.
1e422769
PP
992
993=item LOGDIR
d74e8afc 994X<LOGDIR>
1e422769 995
f4750dab 996Used if C<chdir> has no argument and HOME is not set.
1e422769
PP
997
998=item PATH
d74e8afc 999X<PATH>
1e422769 1000
19799a22 1001Used in executing subprocesses, and in finding the program if B<-S> is
1e422769
PP
1002used.
1003
1004=item PERL5LIB
d74e8afc 1005X<PERL5LIB>
1e422769 1006
490a0bff
LM
1007A list of directories in which to look for Perl library files before
1008looking in the standard library.
1009Any architecture-specific and version-specific directories,
4b85e17e
AD
1010such as F<version/archname/>, F<version/>, or F<archname/> under the
1011specified locations are automatically included if they exist, with this
1012lookup done at interpreter startup time. In addition, any directories
1013matching the entries in C<$Config{inc_version_list}> are added.
1014(These typically would be for older compatible perl versions installed
1015in the same directory tree.)
69681433
AK
1016
1017If PERL5LIB is not defined, PERLLIB is used. Directories are separated
e1020413 1018(like in PATH) by a colon on Unixish platforms and by a semicolon on
69681433 1019Windows (the proper path separator being given by the command C<perl
f4750dab 1020-V:I<path_sep>>).
951ba7fe 1021
f4750dab
TC
1022When running taint checks, either because the program was running setuid or
1023setgid, or the B<-T> or B<-t> switch was specified, neither PERL5LIB nor
1024PERLLIB is consulted. The program should instead say:
1e422769
PP
1025
1026 use lib "/my/directory";
1027
54310121 1028=item PERL5OPT
d74e8afc 1029X<PERL5OPT>
54310121 1030
f4750dab 1031Command-line options (switches). Switches in this variable are treated
3809fbed 1032as if they were on every Perl command line. Only the B<-[CDIMTUWdmtw]>
f4750dab
TC
1033switches are allowed. When running taint checks (either because the
1034program was running setuid or setgid, or because the B<-T> or B<-t>
1035switch was used), this variable is ignored. If PERL5OPT begins with
cce9fd8c 1036B<-T>, tainting will be enabled and subsequent options ignored. If
f4750dab
TC
1037PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot
1038removed from @INC, and subsequent options honored.
54310121 1039
16537909 1040=item PERLIO
d74e8afc 1041X<PERLIO>
16537909 1042
44a4342c 1043A space (or colon) separated list of PerlIO layers. If perl is built
f4750dab 1044to use PerlIO system for IO (the default) these layers affect Perl's IO.
44a4342c 1045
f4750dab
TC
1046It is conventional to start layer names with a colon (for example, C<:perlio>) to
1047emphasize their similarity to variable "attributes". But the code that parses
cce9fd8c 1048layer specification strings, which is also used to decode the PERLIO
f4750dab 1049environment variable, treats the colon as a separator.
44a4342c 1050
5b64f2bf 1051An unset or empty PERLIO is equivalent to the default set of layers for
f4750dab 1052your platform; for example, C<:unix:perlio> on Unix-like systems
1f070127 1053and C<:unix:crlf> on Windows and other DOS-like systems.
3b0db4f9 1054
f4750dab
TC
1055The list becomes the default for I<all> Perl's IO. Consequently only built-in
1056layers can appear in this list, as external layers (such as C<:encoding()>) need
cce9fd8c 1057IO in order to load them! See L<"open pragma"|open> for how to add external
44a4342c
NIS
1058encodings as defaults.
1059
f4750dab
TC
1060Layers it makes sense to include in the PERLIO environment
1061variable are briefly summarized below. For more details see L<PerlIO>.
16537909
JH
1062
1063=over 8
1064
1065=item :bytes
d74e8afc 1066X<:bytes>
16537909 1067
f4750dab
TC
1068A pseudolayer that turns the C<:utf8> flag I<off> for the layer below;
1069unlikely to be useful on its own in the global PERLIO environment variable.
18aba96f 1070You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
16537909
JH
1071
1072=item :crlf
d74e8afc 1073X<:crlf>
16537909 1074
f4750dab 1075A layer which does CRLF to C<"\n"> translation distinguishing "text" and
3d897973
IT
1076"binary" files in the manner of MS-DOS and similar operating systems.
1077(It currently does I<not> mimic MS-DOS as far as treating of Control-Z
1078as being an end-of-file marker.)
44a4342c
NIS
1079
1080=item :mmap
d74e8afc 1081X<:mmap>
44a4342c 1082
f4750dab
TC
1083A layer that implements "reading" of files by using I<mmap>(2) to
1084make an entire file appear in the process's address space, and then
3d897973 1085using that as PerlIO's "buffer".
16537909 1086
44a4342c 1087=item :perlio
d74e8afc 1088X<:perlio>
16537909 1089
f4750dab
TC
1090This is a re-implementation of stdio-like buffering written as a
1091PerlIO layer. As such it will call whatever layer is below it for
1092its operations, typically C<:unix>.
16537909 1093
18aba96f 1094=item :pop
d74e8afc 1095X<:pop>
18aba96f
JH
1096
1097An experimental pseudolayer that removes the topmost layer.
f4750dab 1098Use with the same care as is reserved for nitroglycerine.
18aba96f 1099
44a4342c 1100=item :raw
d74e8afc 1101X<:raw>
16537909 1102
136e4fd6 1103A pseudolayer that manipulates other layers. Applying the C<:raw>
18aba96f 1104layer is equivalent to calling C<binmode($fh)>. It makes the stream
f4750dab
TC
1105pass each byte as-is without translation. In particular, both CRLF
1106translation and intuiting C<:utf8> from the locale are disabled.
1cbfc93d 1107
f4750dab
TC
1108Unlike in earlier versions of Perl, C<:raw> is I<not>
1109just the inverse of C<:crlf>: other layers which would affect the
3d897973 1110binary nature of the stream are also removed or disabled.
16537909 1111
44a4342c 1112=item :stdio
d74e8afc 1113X<:stdio>
44a4342c 1114
f4750dab 1115This layer provides a PerlIO interface by wrapping system's ANSI C "stdio"
44a4342c 1116library calls. The layer provides both buffering and IO.
f4750dab
TC
1117Note that the C<:stdio> layer does I<not> do CRLF translation even if that
1118is the platform's normal behaviour. You will need a C<:crlf> layer above it
44a4342c
NIS
1119to do that.
1120
1121=item :unix
d74e8afc 1122X<:unix>
44a4342c 1123
f4750dab 1124Low-level layer that calls C<read>, C<write>, C<lseek>, etc.
16537909
JH
1125
1126=item :utf8
d74e8afc 1127X<:utf8>
16537909 1128
f4750dab 1129A pseudolayer that enables a flag in the layer below to tell Perl
3d897973 1130that output should be in utf8 and that input should be regarded as
f4750dab
TC
1131already in valid utf8 form. B<WARNING: It does not check for validity and as such
1132should be handled with extreme caution for input, because security violations
6d8e7450 1133can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(UTF-8)> is
740d4bb2 1134the best option when reading UTF-8 encoded data.
44a4342c
NIS
1135
1136=item :win32
d74e8afc 1137X<:win32>
44a4342c 1138
ab4f7683 1139On Win32 platforms this I<experimental> layer uses native "handle" IO
f4750dab
TC
1140rather than a Unix-like numeric file descriptor layer. Known to be
1141buggy in this release (5.14).
16537909
JH
1142
1143=back
1144
f4750dab 1145The default set of layers should give acceptable results on all platforms
44a4342c 1146
f4750dab
TC
1147For Unix platforms that will be the equivalent of "unix perlio" or "stdio".
1148Configure is set up to prefer the "stdio" implementation if the system's library
1149provides for fast access to the buffer; otherwise, it uses the "unix perlio"
44a4342c
NIS
1150implementation.
1151
f4750dab
TC
1152On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio"
1153has a number of bugs/mis-features for Perl IO which are somewhat depending
1154on the version and vendor of the C compiler. Using our own C<crlf> layer as
1155the buffer avoids those issues and makes things more uniform. The C<crlf>
1156layer provides CRLF conversion as well as buffering.
44a4342c 1157
f4750dab
TC
1158This release (5.14) uses C<unix> as the bottom layer on Win32, and so still
1159uses the C compiler's numeric file descriptor routines. There is an
1160experimental native C<win32> layer, which is expected to be enhanced and
1161should eventually become the default under Win32.
44a4342c 1162
f4750dab 1163The PERLIO environment variable is completely ignored when Perl
5437faeb
PF
1164is run in taint mode.
1165
44a4342c 1166=item PERLIO_DEBUG
d74e8afc 1167X<PERLIO_DEBUG>
44a4342c 1168
2104c695
CB
1169If set to the name of a file or device when Perl is run with the
1170B<-Di> command-line switch, the logging of certain operations of
1171the PerlIO subsystem will be redirected to the specified file rather
1172than going to stderr, which is the default. The file is opened in append
1173mode. Typical uses are in Unix:
44a4342c 1174
2104c695 1175 % env PERLIO_DEBUG=/tmp/perlio.log perl -Di script ...
44a4342c 1176
f4750dab 1177and under Win32, the approximately equivalent:
44a4342c 1178
f4750dab 1179 > set PERLIO_DEBUG=CON
2104c695 1180 perl -Di script ...
44a4342c 1181
2104c695
CB
1182This functionality is disabled for setuid scripts, for scripts run
1183with B<-T>, and for scripts run on a Perl built without C<-DDEBUGGING>
1184support.
16537909 1185
1e422769 1186=item PERLLIB
d74e8afc 1187X<PERLLIB>
1e422769 1188
48b971ca 1189A list of directories in which to look for Perl library
490a0bff 1190files before looking in the standard library.
1e422769
PP
1191If PERL5LIB is defined, PERLLIB is not used.
1192
f4750dab 1193The PERLLIB environment variable is completely ignored when Perl
5437faeb
PF
1194is run in taint mode.
1195
1e422769 1196=item PERL5DB
d74e8afc 1197X<PERL5DB>
1e422769
PP
1198
1199The command used to load the debugger code. The default is:
1200
f4750dab 1201 BEGIN { require "perl5db.pl" }
1e422769 1202
f4750dab 1203The PERL5DB environment variable is only used when Perl is started with
5437faeb
PF
1204a bare B<-d> switch.
1205
2cbb2ee1 1206=item PERL5DB_THREADED
d74e8afc 1207X<PERL5DB_THREADED>
2cbb2ee1
RGS
1208
1209If set to a true value, indicates to the debugger that the code being
1210debugged uses threads.
1211
19799a22 1212=item PERL5SHELL (specific to the Win32 port)
d74e8afc 1213X<PERL5SHELL>
174c211a 1214
f4750dab
TC
1215On Win32 ports only, may be set to an alternative shell that Perl must use
1216internally for executing "backtick" commands or system(). Default is
1217C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The
1218value is considered space-separated. Precede any character that
1219needs to be protected, like a space or backslash, with another backslash.
ce1da67e
GS
1220
1221Note that Perl doesn't use COMSPEC for this purpose because
1222COMSPEC has a high degree of variability among users, leading to
f4750dab 1223portability concerns. Besides, Perl can use a shell that may not be
ce1da67e
GS
1224fit for interactive use, and setting COMSPEC to such a shell may
1225interfere with the proper functioning of other programs (which usually
1226look in COMSPEC to find a shell fit for interactive use).
174c211a 1227
5437faeb
PF
1228Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked
1229when running external commands. It is recommended that
1230you explicitly set (or delete) C<$ENV{PERL5SHELL}> when running
1231in taint mode under Windows.
1232
1c972609 1233=item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
d74e8afc 1234X<PERL_ALLOW_NON_IFS_LSP>
1c972609 1235
f4750dab 1236Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers).
1c972609
SH
1237Perl normally searches for an IFS-compatible LSP because this is required
1238for its emulation of Windows sockets as real filehandles. However, this may
f4750dab
TC
1239cause problems if you have a firewall such as I<McAfee Guardian>, which requires
1240that all applications use its LSP but which is not IFS-compatible, because clearly
1c972609 1241Perl will normally avoid using such an LSP.
f4750dab 1242
1c972609 1243Setting this environment variable to 1 means that Perl will simply use the
f4750dab
TC
1244first suitable LSP enumerated in the catalog, which keeps I<McAfee Guardian>
1245happy--and in that particular case Perl still works too because I<McAfee
1246Guardian>'s LSP actually plays other games which allow applications
1247requiring IFS compatibility to work.
1c972609 1248
1e422769 1249=item PERL_DEBUG_MSTATS
d74e8afc 1250X<PERL_DEBUG_MSTATS>
1e422769 1251
f4750dab
TC
1252Relevant only if Perl is compiled with the C<malloc> included with the Perl
1253distribution; that is, if C<perl -V:d_mymalloc> is "define".
1254
1255If set, this dumps out memory statistics after execution. If set
1256to an integer greater than one, also dumps out memory statistics
1e422769
PP
1257after compilation.
1258
1259=item PERL_DESTRUCT_LEVEL
d74e8afc 1260X<PERL_DESTRUCT_LEVEL>
1e422769 1261
8008a6e6 1262Controls the behaviour of global destruction of objects and other
96090e4f 1263references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information.
a0d0e21e 1264
02c7413a 1265=item PERL_DL_NONLAZY
d74e8afc 1266X<PERL_DL_NONLAZY>
02c7413a 1267
f4750dab 1268Set to C<"1"> to have Perl resolve I<all> undefined symbols when it loads
02c7413a
GA
1269a dynamic library. The default behaviour is to resolve symbols when
1270they are used. Setting this variable is useful during testing of
f4750dab
TC
1271extensions, as it ensures that you get an error on misspelled function
1272names even if the test suite doesn't call them.
02c7413a 1273
5d170f3a 1274=item PERL_ENCODING
d74e8afc 1275X<PERL_ENCODING>
5d170f3a 1276
f4750dab 1277If using the C<use encoding> pragma without an explicit encoding name, the
5d170f3a
JH
1278PERL_ENCODING environment variable is consulted for an encoding name.
1279
504f80c1 1280=item PERL_HASH_SEED
d74e8afc 1281X<PERL_HASH_SEED>
504f80c1 1282
6a5b4183
YO
1283(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override
1284the randomization of Perl's internal hash function. The value is expressed
1285in hexadecimal, and may include a leading 0x. Truncated patterns
1286are treated as though they are suffixed with sufficient 0's as required.
8d4a1e6c 1287
6a5b4183
YO
1288If the option is provided, and C<PERL_PERTURB_KEYS> is NOT set, then
1289a value of '0' implies C<PERL_PERTURB_KEYS=0> and any other value
1290implies C<PERL_PERTURB_KEYS=2>.
504f80c1 1291
f4750dab 1292B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are
26a2d347 1293randomized to protect against local and remote attacks against Perl
f4750dab 1294code. By manually setting a seed, this protection may be partially or
26a2d347
JH
1295completely lost.
1296
4a70680a 1297See L<perlsec/"Algorithmic Complexity Attacks">, L</PERL_PERTURB_KEYS>, and
26a2d347 1298L</PERL_HASH_SEED_DEBUG> for more information.
504f80c1 1299
6a5b4183
YO
1300=item PERL_PERTURB_KEYS
1301X<PERL_PERTURB_KEYS>
1302
1303(Since Perl 5.18.0) Set to C<"0"> or C<"NO"> then traversing keys
e6b54db6 1304will be repeatable from run to run for the same PERL_HASH_SEED.
6a5b4183
YO
1305Insertion into a hash will not change the order, except to provide
1306for more space in the hash. When combined with setting PERL_HASH_SEED
1307this mode is as close to pre 5.18 behavior as you can get.
1308
1309When set to C<"1"> or C<"RANDOM"> then traversing keys will be randomized.
1310Every time a hash is inserted into the key order will change in a random
e6b54db6 1311fashion. The order may not be repeatable in a following program run
6a5b4183
YO
1312even if the PERL_HASH_SEED has been specified. This is the default
1313mode for perl.
1314
1315When set to C<"2"> or C<"DETERMINISTIC"> then inserting keys into a hash
e6b54db6 1316will cause the key order to change, but in a way that is repeatable
6a5b4183
YO
1317from program run to program run.
1318
1319B<NOTE:> Use of this option is considered insecure, and is intended only
1320for debugging non-deterministic behavior in Perl's hash function. Do
1321not use it in production.
1322
1323See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_HASH_SEED>
1324and L</PERL_HASH_SEED_DEBUG> for more information. You can get and set the
1325key traversal mask for a specific hash by using the C<hash_traversal_mask()>
1326function from L<Hash::Util>.
1327
2191697e 1328=item PERL_HASH_SEED_DEBUG
d74e8afc 1329X<PERL_HASH_SEED_DEBUG>
2191697e 1330
6a5b4183
YO
1331(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) information
1332about the hash function, seed, and what type of key traversal
1333randomization is in effect at the beginning of execution. This, combined
1334with L</PERL_HASH_SEED> and L</PERL_PERTURB_KEYS> is intended to aid in
1335debugging nondeterministic behaviour caused by hash randomization.
1336
1337B<Note> that any information about the hash function, especially the hash
1338seed is B<sensitive information>: by knowing it, one can craft a denial-of-service
1339attack against Perl code, even remotely; see L<perlsec/"Algorithmic Complexity Attacks">
1340for more information. B<Do not disclose the hash seed> to people who
f420138f
KW
1341don't need to know it. See also L<C<hash_seed()>|Hash::Util/hash_seed> and
1342L<C<hash_traversal_mask()>|Hash::Util/hash_traversal_mask>.
6a5b4183
YO
1343
1344An example output might be:
26a2d347 1345
e46aa1dd 1346 HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
2191697e 1347
9aa9f499
JC
1348=item PERL_MEM_LOG
1349X<PERL_MEM_LOG>
1350
f4750dab 1351If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting
7916a455 1352the environment variable C<PERL_MEM_LOG> enables logging debug
f4750dab
TC
1353messages. The value has the form C<< <I<number>>[m][s][t] >>, where
1354C<I<number>> is the file descriptor number you want to write to (2 is
7916a455
JC
1355default), and the combination of letters specifies that you want
1356information about (m)emory and/or (s)v, optionally with
f4750dab
TC
1357(t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all
1358information to stdout. You can write to other opened file descriptors
1359in a variety of ways:
9aa9f499 1360
f4750dab 1361 $ 3>foo3 PERL_MEM_LOG=3m perl ...
9aa9f499 1362
3d0ae7ba 1363=item PERL_ROOT (specific to the VMS port)
d74e8afc 1364X<PERL_ROOT>
3d0ae7ba 1365
f4750dab 1366A translation-concealed rooted logical name that contains Perl and the
3d0ae7ba 1367logical device for the @INC path on VMS only. Other logical names that
f4750dab
TC
1368affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and
1369SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in
3d0ae7ba
GS
1370L<perlvms> and in F<README.vms> in the Perl source distribution.
1371
4ffa73a3 1372=item PERL_SIGNALS
d74e8afc 1373X<PERL_SIGNALS>
4ffa73a3 1374
f4750dab
TC
1375Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0
1376signal behaviour (which is immediate but unsafe) is restored. If set
1377to C<safe>, then safe (but deferred) signals are used. See
1378L<perlipc/"Deferred Signals (Safe Signals)">.
4ffa73a3 1379
a05d7ebb 1380=item PERL_UNICODE
d74e8afc 1381X<PERL_UNICODE>
acae81db 1382
bf61ac64 1383Equivalent to the B<-C> command-line switch. Note that this is not
ac036724 1384a boolean variable. Setting this to C<"1"> is not the right way to
5b4f334e 1385"enable Unicode" (whatever that would mean). You can use C<"0"> to
e654d908 1386"disable Unicode", though (or alternatively unset PERL_UNICODE in
f4750dab 1387your shell before starting Perl). See the description of the B<-C>
e654d908 1388switch for more information.
acae81db 1389
c12592fc
DIM
1390=item PERL_USE_UNSAFE_INC
1391X<PERL_USE_UNSAFE_INC>
1392
1393If perl has been configured to not have the current directory in
1394L<C<@INC>|perlvar/@INC> by default, this variable can be set to C<"1">
1395to reinstate it. It's primarily intended for use while building and
1396testing modules that have not been updated to deal with "." not being in
1397C<@INC> and should not be set in the environment for day-to-day use.
1398
3d0ae7ba 1399=item SYS$LOGIN (specific to the VMS port)
d74e8afc 1400X<SYS$LOGIN>
3d0ae7ba
GS
1401
1402Used if chdir has no argument and HOME and LOGDIR are not set.
1403
d6295071
TC
1404=item PERL_INTERNAL_RAND_SEED
1405X<PERL_INTERNAL_RAND_SEED>
1406
1407Set to a non-negative integer to seed the random number generator used
1408internally by perl for a variety of purposes.
1409
1410Ignored if perl is run setuid or setgid. Used only for some limited
1411startup randomization (hash keys) if C<-T> or C<-t> perl is started
1412with tainting enabled.
1413
1414Perl may be built to ignore this variable.
1415
a0d0e21e 1416=back
1e422769
PP
1417
1418Perl also has environment variables that control how Perl handles data
f4750dab
TC
1419specific to particular natural languages; see L<perllocale>.
1420
1421Perl and its various modules and components, including its test frameworks,
1422may sometimes make use of certain other environment variables. Some of
1423these are specific to a particular platform. Please consult the
1424appropriate module documentation and any documentation for your platform
1425(like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for
1426variables peculiar to those specific situations.
1427
1428Perl makes all environment variables available to the program being
1429executed, and passes these along to any child processes it starts.
1430However, programs running setuid would do well to execute the following
1431lines before doing anything else, just to keep people honest:
1432
1433 $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need
1434 $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
c90c0ff4 1435 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};