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