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