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