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