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