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