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