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