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