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