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