1PERLRUN(1)             Perl Programmers Reference Guide             PERLRUN(1)
2
3
4

NAME

6       perlrun - how to execute the Perl interpreter
7

SYNOPSIS

9       perl [ -sTtuUWX ]      [ -hv ] [ -V[:configvar] ]
10            [ -cw ] [ -d[t][:debugger] ] [ -D[number/list] ]
11            [ -pna ] [ -Fpattern ] [ -l[octal] ] [ -0[octal/hexadecimal] ]
12            [ -Idir ] [ -m[-]module ] [ -M[-]'module...' ] [ -f ]
13            [ -C [number/list] ]      [ -S ]      [ -x[dir] ]
14            [ -i[extension] ]
15            [ [-e|-E] 'command' ] [ -- ] [ programfile ] [ argument ]...
16

DESCRIPTION

18       The normal way to run a Perl program is by making it directly
19       executable, or else by passing the name of the source file as an
20       argument on the command line.  (An interactive Perl environment is also
21       possible--see perldebug for details on how to do that.)  Upon startup,
22       Perl looks for your program in one of the following places:
23
24       1.  Specified line by line via -e or -E switches on the command line.
25
26       2.  Contained in the file specified by the first filename on the
27           command line.  (Note that systems supporting the "#!" notation
28           invoke interpreters this way. See "Location of Perl".)
29
30       3.  Passed in implicitly via standard input.  This works only if there
31           are no filename arguments--to pass arguments to a STDIN-read
32           program you must explicitly specify a "-" for the program name.
33
34       With methods 2 and 3, Perl starts parsing the input file from the
35       beginning, unless you've specified a "-x" switch, in which case it
36       scans for the first line starting with "#!" and containing the word
37       "perl", and starts there instead.  This is useful for running a program
38       embedded in a larger message.  (In this case you would indicate the end
39       of the program using the "__END__" token.)
40
41       The "#!" line is always examined for switches as the line is being
42       parsed.  Thus, if you're on a machine that allows only one argument
43       with the "#!" line, or worse, doesn't even recognize the "#!" line, you
44       still can get consistent switch behaviour regardless of how Perl was
45       invoked, even if "-x" was used to find the beginning of the program.
46
47       Because historically some operating systems silently chopped off kernel
48       interpretation of the "#!" line after 32 characters, some switches may
49       be passed in on the command line, and some may not; you could even get
50       a "-" without its letter, if you're not careful.  You probably want to
51       make sure that all your switches fall either before or after that
52       32-character boundary.  Most switches don't actually care if they're
53       processed redundantly, but getting a "-" instead of a complete switch
54       could cause Perl to try to execute standard input instead of your
55       program.  And a partial -I switch could also cause odd results.
56
57       Some switches do care if they are processed twice, for instance
58       combinations of -l and -0.  Either put all the switches after the
59       32-character boundary (if applicable), or replace the use of -0digits
60       by "BEGIN{ $/ = "\0digits"; }".
61
62       Parsing of the "#!" switches starts wherever "perl" is mentioned in the
63       line.  The sequences "-*" and "- " are specifically ignored so that you
64       could, if you were so inclined, say
65
66           #!/bin/sh
67           #! -*- perl -*- -p
68           eval 'exec perl -x -wS $0 ${1+"$@"}'
69               if 0;
70
71       to let Perl see the "-p" switch.
72
73       A similar trick involves the env program, if you have it.
74
75           #!/usr/bin/env perl
76
77       The examples above use a relative path to the perl interpreter, getting
78       whatever version is first in the user's path.  If you want a specific
79       version of Perl, say, perl5.14.1, you should place that directly in the
80       "#!" line's path.
81
82       If the "#!" line does not contain the word "perl" nor the word "indir",
83       the program named after the "#!" is executed instead of the Perl
84       interpreter.  This is slightly bizarre, but it helps people on machines
85       that don't do "#!", because they can tell a program that their SHELL is
86       /usr/bin/perl, and Perl will then dispatch the program to the correct
87       interpreter for them.
88
89       After locating your program, Perl compiles the entire program to an
90       internal form.  If there are any compilation errors, execution of the
91       program is not attempted.  (This is unlike the typical shell script,
92       which might run part-way through before finding a syntax error.)
93
94       If the program is syntactically correct, it is executed.  If the
95       program runs off the end without hitting an exit() or die() operator,
96       an implicit exit(0) is provided to indicate successful completion.
97
98   #! and quoting on non-Unix systems
99       Unix's "#!" technique can be simulated on other systems:
100
101       OS/2
102           Put
103
104               extproc perl -S -your_switches
105
106           as the first line in "*.cmd" file ("-S" due to a bug in cmd.exe's
107           `extproc' handling).
108
109       MS-DOS
110           Create a batch file to run your program, and codify it in
111           "ALTERNATE_SHEBANG" (see the dosish.h file in the source
112           distribution for more information).
113
114       Win95/NT
115           The Win95/NT installation, when using the ActiveState installer for
116           Perl, will modify the Registry to associate the .pl extension with
117           the perl interpreter.  If you install Perl by other means
118           (including building from the sources), you may have to modify the
119           Registry yourself.  Note that this means you can no longer tell the
120           difference between an executable Perl program and a Perl library
121           file.
122
123       VMS Put
124
125            $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
126            $ exit++ + ++$status != 0 and $exit = $status = undef;
127
128           at the top of your program, where -mysw are any command line
129           switches you want to pass to Perl.  You can now invoke the program
130           directly, by saying "perl program", or as a DCL procedure, by
131           saying @program (or implicitly via DCL$PATH by just using the name
132           of the program).
133
134           This incantation is a bit much to remember, but Perl will display
135           it for you if you say "perl "-V:startperl"".
136
137       Command-interpreters on non-Unix systems have rather different ideas on
138       quoting than Unix shells.  You'll need to learn the special characters
139       in your command-interpreter ("*", "\" and """ are common) and how to
140       protect whitespace and these characters to run one-liners (see -e
141       below).
142
143       On some systems, you may have to change single-quotes to double ones,
144       which you must not do on Unix or Plan 9 systems.  You might also have
145       to change a single % to a %%.
146
147       For example:
148
149           # Unix
150           perl -e 'print "Hello world\n"'
151
152           # MS-DOS, etc.
153           perl -e "print \"Hello world\n\""
154
155           # VMS
156           perl -e "print ""Hello world\n"""
157
158       The problem is that none of this is reliable: it depends on the command
159       and it is entirely possible neither works.  If 4DOS were the command
160       shell, this would probably work better:
161
162           perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
163
164       CMD.EXE in Windows NT slipped a lot of standard Unix functionality in
165       when nobody was looking, but just try to find documentation for its
166       quoting rules.
167
168       There is no general solution to all of this.  It's just a mess.
169
170   Location of Perl
171       It may seem obvious to say, but Perl is useful only when users can
172       easily find it.  When possible, it's good for both /usr/bin/perl and
173       /usr/local/bin/perl to be symlinks to the actual binary.  If that can't
174       be done, system administrators are strongly encouraged to put (symlinks
175       to) perl and its accompanying utilities into a directory typically
176       found along a user's PATH, or in some other obvious and convenient
177       place.
178
179       In this documentation, "#!/usr/bin/perl" on the first line of the
180       program will stand in for whatever method works on your system.  You
181       are advised to use a specific path if you care about a specific
182       version.
183
184           #!/usr/local/bin/perl5.14
185
186       or if you just want to be running at least version, place a statement
187       like this at the top of your program:
188
189           use 5.014;
190
191   Command Switches
192       As with all standard commands, a single-character switch may be
193       clustered with the following switch, if any.
194
195           #!/usr/bin/perl -spi.orig   # same as -s -p -i.orig
196
197       A "--" signals the end of options and disables further option
198       processing. Any arguments after the "--" are treated as filenames and
199       arguments.
200
201       Switches include:
202
203       -0[octal/hexadecimal]
204            specifies the input record separator ($/) as an octal or
205            hexadecimal number.  If there are no digits, the null character is
206            the separator.  Other switches may precede or follow the digits.
207            For example, if you have a version of find which can print
208            filenames terminated by the null character, you can say this:
209
210                find . -name '*.orig' -print0 | perl -n0e unlink
211
212            The special value 00 will cause Perl to slurp files in paragraph
213            mode.  Any value 0400 or above will cause Perl to slurp files
214            whole, but by convention the value 0777 is the one normally used
215            for this purpose.
216
217            You can also specify the separator character using hexadecimal
218            notation: -0xHHH..., where the "H" are valid hexadecimal digits.
219            Unlike the octal form, this one may be used to specify any Unicode
220            character, even those beyond 0xFF.  So if you really want a record
221            separator of 0777, specify it as -0x1FF.  (This means that you
222            cannot use the "-x" option with a directory name that consists of
223            hexadecimal digits, or else Perl will think you have specified a
224            hex number to -0.)
225
226       -a   turns on autosplit mode when used with a "-n" or "-p".  An
227            implicit split command to the @F array is done as the first thing
228            inside the implicit while loop produced by the "-n" or "-p".
229
230                perl -ane 'print pop(@F), "\n";'
231
232            is equivalent to
233
234                while (<>) {
235                    @F = split(' ');
236                    print pop(@F), "\n";
237                }
238
239            An alternate delimiter may be specified using -F.
240
241            -a implicitly sets "-n".
242
243       -C [number/list]
244            The -C flag controls some of the Perl Unicode features.
245
246            As of 5.8.1, the -C can be followed either by a number or a list
247            of option letters.  The letters, their numeric values, and effects
248            are as follows; listing the letters is equal to summing the
249            numbers.
250
251                I     1   STDIN is assumed to be in UTF-8
252                O     2   STDOUT will be in UTF-8
253                E     4   STDERR will be in UTF-8
254                S     7   I + O + E
255                i     8   UTF-8 is the default PerlIO layer for input streams
256                o    16   UTF-8 is the default PerlIO layer for output streams
257                D    24   i + o
258                A    32   the @ARGV elements are expected to be strings encoded
259                          in UTF-8
260                L    64   normally the "IOEioA" are unconditional, the L makes
261                          them conditional on the locale environment variables
262                          (the LC_ALL, LC_CTYPE, and LANG, in the order of
263                          decreasing precedence) -- if the variables indicate
264                          UTF-8, then the selected "IOEioA" are in effect
265                a   256   Set ${^UTF8CACHE} to -1, to run the UTF-8 caching
266                          code in debugging mode.
267
268            For example, -COE and -C6 will both turn on UTF-8-ness on both
269            STDOUT and STDERR.  Repeating letters is just redundant, not
270            cumulative nor toggling.
271
272            The "io" options mean that any subsequent open() (or similar I/O
273            operations) in main program scope will have the ":utf8" PerlIO
274            layer implicitly applied to them, in other words, UTF-8 is
275            expected from any input stream, and UTF-8 is produced to any
276            output stream.  This is just the default set via "${^OPEN}", with
277            explicit layers in open() and with binmode() one can manipulate
278            streams as usual.  This has no effect on code run in modules.
279
280            -C on its own (not followed by any number or option list), or the
281            empty string "" for the "PERL_UNICODE" environment variable, has
282            the same effect as -CSDL.  In other words, the standard I/O
283            handles and the default "open()" layer are UTF-8-fied but only if
284            the locale environment variables indicate a UTF-8 locale.  This
285            behaviour follows the implicit (and problematic) UTF-8 behaviour
286            of Perl 5.8.0.  (See "UTF-8 no longer default under UTF-8 locales"
287            in perl581delta.)
288
289            You can use -C0 (or "0" for "PERL_UNICODE") to explicitly disable
290            all the above Unicode features.
291
292            The read-only magic variable "${^UNICODE}" reflects the numeric
293            value of this setting.  This variable is set during Perl startup
294            and is thereafter read-only.  If you want runtime effects, use the
295            three-arg open() (see "open" in perlfunc), the two-arg binmode()
296            (see "binmode" in perlfunc), and the "open" pragma (see open).
297
298            (In Perls earlier than 5.8.1 the -C switch was a Win32-only switch
299            that enabled the use of Unicode-aware "wide system call" Win32
300            APIs.  This feature was practically unused, however, and the
301            command line switch was therefore "recycled".)
302
303            Note: Since perl 5.10.1, if the -C option is used on the "#!"
304            line, it must be specified on the command line as well, since the
305            standard streams are already set up at this point in the execution
306            of the perl interpreter.  You can also use binmode() to set the
307            encoding of an I/O stream.
308
309       -c   causes Perl to check the syntax of the program and then exit
310            without executing it.  Actually, it will execute any "BEGIN",
311            "UNITCHECK", or "CHECK" blocks and any "use" statements: these are
312            considered as occurring outside the execution of your program.
313            "INIT" and "END" blocks, however, will be skipped.
314
315       -d
316       -dt  runs the program under the Perl debugger.  See perldebug.  If t is
317            specified, it indicates to the debugger that threads will be used
318            in the code being debugged.
319
320       -d:MOD[=bar,baz]
321       -dt:MOD[=bar,baz]
322            runs the program under the control of a debugging, profiling, or
323            tracing module installed as "Devel::MOD". E.g., -d:DProf executes
324            the program using the "Devel::DProf" profiler.  As with the -M
325            flag, options may be passed to the "Devel::MOD" package where they
326            will be received and interpreted by the "Devel::MOD::import"
327            routine.  Again, like -M, use --d:-MOD to call
328            "Devel::MOD::unimport" instead of import.  The comma-separated
329            list of options must follow a "=" character.  If t is specified,
330            it indicates to the debugger that threads will be used in the code
331            being debugged.  See perldebug.
332
333       -Dletters
334       -Dnumber
335            sets debugging flags. This switch is enabled only if your perl
336            binary has been built with debugging enabled: normal production
337            perls won't have been.
338
339            For example, to watch how perl executes your program, use -Dtls.
340            Another nice value is -Dx, which lists your compiled syntax tree,
341            and -Dr displays compiled regular expressions; the format of the
342            output is explained in perldebguts.
343
344            As an alternative, specify a number instead of list of letters
345            (e.g., -D14 is equivalent to -Dtls):
346
347                     1  p  Tokenizing and parsing (with v, displays parse
348                           stack)
349                     2  s  Stack snapshots (with v, displays all stacks)
350                     4  l  Context (loop) stack processing
351                     8  t  Trace execution
352                    16  o  Method and overloading resolution
353                    32  c  String/numeric conversions
354                    64  P  Print profiling info, source file input state
355                   128  m  Memory and SV allocation
356                   256  f  Format processing
357                   512  r  Regular expression parsing and execution
358                  1024  x  Syntax tree dump
359                  2048  u  Tainting checks
360                  4096  U  Unofficial, User hacking (reserved for private,
361                           unreleased use)
362                 16384  X  Scratchpad allocation
363                 32768  D  Cleaning up
364                 65536  S  Op slab allocation
365                131072  T  Tokenizing
366                262144  R  Include reference counts of dumped variables
367                           (eg when using -Ds)
368                524288  J  show s,t,P-debug (don't Jump over) on opcodes within
369                           package DB
370               1048576  v  Verbose: use in conjunction with other flags to
371                           increase the verbosity of the output.  Is a no-op on
372                           many of the other flags
373               2097152  C  Copy On Write
374               4194304  A  Consistency checks on internal structures
375               8388608  q  quiet - currently only suppresses the "EXECUTING"
376                           message
377              16777216  M  trace smart match resolution
378              33554432  B  dump suBroutine definitions, including special
379                           Blocks like BEGIN
380              67108864  L  trace Locale-related info; what gets output is very
381                           subject to change
382             134217728  i  trace PerlIO layer processing.  Set PERLIO_DEBUG to
383                           the filename to trace to.
384             268435456  y  trace y///, tr/// compilation and execution
385
386            All these flags require -DDEBUGGING when you compile the Perl
387            executable (but see ":opd" in Devel::Peek or "'debug' mode" in re
388            which may change this).  See the INSTALL file in the Perl source
389            distribution for how to do this.
390
391            If you're just trying to get a print out of each line of Perl code
392            as it executes, the way that "sh -x" provides for shell scripts,
393            you can't use Perl's -D switch.  Instead do this
394
395              # If you have "env" utility
396              env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
397
398              # Bourne shell syntax
399              $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
400
401              # csh syntax
402              % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
403
404            See perldebug for details and variations.
405
406       -e commandline
407            may be used to enter one line of program.  If -e is given, Perl
408            will not look for a filename in the argument list.  Multiple -e
409            commands may be given to build up a multi-line script.  Make sure
410            to use semicolons where you would in a normal program.
411
412       -E commandline
413            behaves just like -e, except that it implicitly enables all
414            optional features (in the main compilation unit). See feature.
415
416       -f   Disable executing $Config{sitelib}/sitecustomize.pl at startup.
417
418            Perl can be built so that it by default will try to execute
419            $Config{sitelib}/sitecustomize.pl at startup (in a BEGIN block).
420            This is a hook that allows the sysadmin to customize how Perl
421            behaves.  It can for instance be used to add entries to the @INC
422            array to make Perl find modules in non-standard locations.
423
424            Perl actually inserts the following code:
425
426                BEGIN {
427                    do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
428                        && do "$Config{sitelib}/sitecustomize.pl";
429                }
430
431            Since it is an actual "do" (not a "require"), sitecustomize.pl
432            doesn't need to return a true value. The code is run in package
433            "main", in its own lexical scope. However, if the script dies, $@
434            will not be set.
435
436            The value of $Config{sitelib} is also determined in C code and not
437            read from "Config.pm", which is not loaded.
438
439            The code is executed very early. For example, any changes made to
440            @INC will show up in the output of `perl -V`. Of course, "END"
441            blocks will be likewise executed very late.
442
443            To determine at runtime if this capability has been compiled in
444            your perl, you can check the value of $Config{usesitecustomize}.
445
446       -Fpattern
447            specifies the pattern to split on for "-a". The pattern may be
448            surrounded by "//", "", or '', otherwise it will be put in single
449            quotes. You can't use literal whitespace or NUL characters in the
450            pattern.
451
452            -F implicitly sets both "-a" and "-n".
453
454       -h   prints a summary of the options.
455
456       -i[extension]
457            specifies that files processed by the "<>" construct are to be
458            edited in-place.  It does this by renaming the input file, opening
459            the output file by the original name, and selecting that output
460            file as the default for print() statements.  The extension, if
461            supplied, is used to modify the name of the old file to make a
462            backup copy, following these rules:
463
464            If no extension is supplied, and your system supports it, the
465            original file is kept open without a name while the output is
466            redirected to a new file with the original filename.  When perl
467            exits, cleanly or not, the original file is unlinked.
468
469            If the extension doesn't contain a "*", then it is appended to the
470            end of the current filename as a suffix.  If the extension does
471            contain one or more "*" characters, then each "*" is replaced with
472            the current filename.  In Perl terms, you could think of this as:
473
474                ($backup = $extension) =~ s/\*/$file_name/g;
475
476            This allows you to add a prefix to the backup file, instead of (or
477            in addition to) a suffix:
478
479             $ perl -pi'orig_*' -e 's/bar/baz/' fileA  # backup to
480                                                       # 'orig_fileA'
481
482            Or even to place backup copies of the original files into another
483            directory (provided the directory already exists):
484
485             $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA  # backup to
486                                                           # 'old/fileA.orig'
487
488            These sets of one-liners are equivalent:
489
490             $ perl -pi -e 's/bar/baz/' fileA          # overwrite current file
491             $ perl -pi'*' -e 's/bar/baz/' fileA       # overwrite current file
492
493             $ perl -pi'.orig' -e 's/bar/baz/' fileA   # backup to 'fileA.orig'
494             $ perl -pi'*.orig' -e 's/bar/baz/' fileA  # backup to 'fileA.orig'
495
496            From the shell, saying
497
498                $ perl -p -i.orig -e "s/foo/bar/; ... "
499
500            is the same as using the program:
501
502                #!/usr/bin/perl -pi.orig
503                s/foo/bar/;
504
505            which is equivalent to
506
507                #!/usr/bin/perl
508                $extension = '.orig';
509                LINE: while (<>) {
510                    if ($ARGV ne $oldargv) {
511                        if ($extension !~ /\*/) {
512                            $backup = $ARGV . $extension;
513                        }
514                        else {
515                            ($backup = $extension) =~ s/\*/$ARGV/g;
516                        }
517                        rename($ARGV, $backup);
518                        open(ARGVOUT, ">$ARGV");
519                        select(ARGVOUT);
520                        $oldargv = $ARGV;
521                    }
522                    s/foo/bar/;
523                }
524                continue {
525                    print;  # this prints to original filename
526                }
527                select(STDOUT);
528
529            except that the -i form doesn't need to compare $ARGV to $oldargv
530            to know when the filename has changed.  It does, however, use
531            ARGVOUT for the selected filehandle.  Note that STDOUT is restored
532            as the default output filehandle after the loop.
533
534            As shown above, Perl creates the backup file whether or not any
535            output is actually changed.  So this is just a fancy way to copy
536            files:
537
538                $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
539            or
540                $ perl -p -i'.orig' -e 1 file1 file2 file3...
541
542            You can use "eof" without parentheses to locate the end of each
543            input file, in case you want to append to each file, or reset line
544            numbering (see example in "eof" in perlfunc).
545
546            If, for a given file, Perl is unable to create the backup file as
547            specified in the extension then it will skip that file and
548            continue on with the next one (if it exists).
549
550            For a discussion of issues surrounding file permissions and -i,
551            see "Why does Perl let me delete read-only files?  Why does -i
552            clobber protected files?  Isn't this a bug in Perl?" in perlfaq5.
553
554            You cannot use -i to create directories or to strip extensions
555            from files.
556
557            Perl does not expand "~" in filenames, which is good, since some
558            folks use it for their backup files:
559
560                $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
561
562            Note that because -i renames or deletes the original file before
563            creating a new file of the same name, Unix-style soft and hard
564            links will not be preserved.
565
566            Finally, the -i switch does not impede execution when no files are
567            given on the command line.  In this case, no backup is made (the
568            original file cannot, of course, be determined) and processing
569            proceeds from STDIN to STDOUT as might be expected.
570
571       -Idirectory
572            Directories specified by -I are prepended to the search path for
573            modules (@INC).
574
575       -l[octnum]
576            enables automatic line-ending processing.  It has two separate
577            effects.  First, it automatically chomps $/ (the input record
578            separator) when used with "-n" or "-p".  Second, it assigns "$\"
579            (the output record separator) to have the value of octnum so that
580            any print statements will have that separator added back on.  If
581            octnum is omitted, sets "$\" to the current value of $/.  For
582            instance, to trim lines to 80 columns:
583
584                perl -lpe 'substr($_, 80) = ""'
585
586            Note that the assignment "$\ = $/" is done when the switch is
587            processed, so the input record separator can be different than the
588            output record separator if the -l switch is followed by a -0
589            switch:
590
591                gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
592
593            This sets "$\" to newline and then sets $/ to the null character.
594
595       -m[-]module
596       -M[-]module
597       -M[-]'module ...'
598       -[mM][-]module=arg[,arg]...
599            -mmodule executes "use" module "();" before executing your
600            program.  This loads the module, but does not call its "import"
601            method, so does not import subroutines and does not give effect to
602            a pragma.
603
604            -Mmodule executes "use" module ";" before executing your program.
605            This loads the module and calls its "import" method, causing the
606            module to have its default effect, typically importing subroutines
607            or giving effect to a pragma.  You can use quotes to add extra
608            code after the module name, e.g., '-MMODULE qw(foo bar)'.
609
610            If the first character after the -M or -m is a dash (-) then the
611            'use' is replaced with 'no'.  This makes no difference for -m.
612
613            A little builtin syntactic sugar means you can also say
614            -mMODULE=foo,bar or -MMODULE=foo,bar as a shortcut for '-MMODULE
615            qw(foo bar)'.  This avoids the need to use quotes when importing
616            symbols.  The actual code generated by -MMODULE=foo,bar is "use
617            module split(/,/,q{foo,bar})".  Note that the "=" form removes the
618            distinction between -m and -M; that is, -mMODULE=foo,bar is the
619            same as -MMODULE=foo,bar.
620
621            A consequence of the "split" formulation is that -MMODULE=number
622            never does a version check, unless "MODULE::import()" itself is
623            set up to do a version check, which could happen for example if
624            MODULE inherits from Exporter.
625
626       -n   causes Perl to assume the following loop around your program,
627            which makes it iterate over filename arguments somewhat like sed
628            -n or awk:
629
630              LINE:
631                while (<>) {
632                    ...             # your program goes here
633                }
634
635            Note that the lines are not printed by default.  See "-p" to have
636            lines printed.  If a file named by an argument cannot be opened
637            for some reason, Perl warns you about it and moves on to the next
638            file.
639
640            Also note that "<>" passes command line arguments to "open" in
641            perlfunc, which doesn't necessarily interpret them as file names.
642            See  perlop for possible security implications.
643
644            Here is an efficient way to delete all files that haven't been
645            modified for at least a week:
646
647                find . -mtime +7 -print | perl -nle unlink
648
649            This is faster than using the -exec switch of find because you
650            don't have to start a process on every filename found (but it's
651            not faster than using the -delete switch available in newer
652            versions of find.  It does suffer from the bug of mishandling
653            newlines in pathnames, which you can fix if you follow the example
654            under -0.
655
656            "BEGIN" and "END" blocks may be used to capture control before or
657            after the implicit program loop, just as in awk.
658
659       -p   causes Perl to assume the following loop around your program,
660            which makes it iterate over filename arguments somewhat like sed:
661
662              LINE:
663                while (<>) {
664                    ...             # your program goes here
665                } continue {
666                    print or die "-p destination: $!\n";
667                }
668
669            If a file named by an argument cannot be opened for some reason,
670            Perl warns you about it, and moves on to the next file.  Note that
671            the lines are printed automatically.  An error occurring during
672            printing is treated as fatal.  To suppress printing use the "-n"
673            switch.  A -p overrides a -n switch.
674
675            "BEGIN" and "END" blocks may be used to capture control before or
676            after the implicit loop, just as in awk.
677
678       -s   enables rudimentary switch parsing for switches on the command
679            line after the program name but before any filename arguments (or
680            before an argument of --).  Any switch found there is removed from
681            @ARGV and sets the corresponding variable in the Perl program.
682            The following program prints "1" if the program is invoked with a
683            -xyz switch, and "abc" if it is invoked with -xyz=abc.
684
685                #!/usr/bin/perl -s
686                if ($xyz) { print "$xyz\n" }
687
688            Do note that a switch like --help creates the variable "${-help}",
689            which is not compliant with "use strict "refs"".  Also, when using
690            this option on a script with warnings enabled you may get a lot of
691            spurious "used only once" warnings.
692
693       -S   makes Perl use the "PATH" environment variable to search for the
694            program unless the name of the program contains path separators.
695
696            On some platforms, this also makes Perl append suffixes to the
697            filename while searching for it.  For example, on Win32 platforms,
698            the ".bat" and ".cmd" suffixes are appended if a lookup for the
699            original name fails, and if the name does not already end in one
700            of those suffixes.  If your Perl was compiled with "DEBUGGING"
701            turned on, using the -Dp switch to Perl shows how the search
702            progresses.
703
704            Typically this is used to emulate "#!" startup on platforms that
705            don't support "#!".  It's also convenient when debugging a script
706            that uses "#!", and is thus normally found by the shell's $PATH
707            search mechanism.
708
709            This example works on many platforms that have a shell compatible
710            with Bourne shell:
711
712                #!/usr/bin/perl
713                eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
714                        if 0; # ^ Run only under a shell
715
716            The system ignores the first line and feeds the program to
717            /bin/sh, which proceeds to try to execute the Perl program as a
718            shell script.  The shell executes the second line as a normal
719            shell command, and thus starts up the Perl interpreter.  On some
720            systems $0 doesn't always contain the full pathname, so the "-S"
721            tells Perl to search for the program if necessary.  After Perl
722            locates the program, it parses the lines and ignores them because
723            the check 'if 0' is never true.  If the program will be
724            interpreted by csh, you will need to replace "${1+"$@"}" with $*,
725            even though that doesn't understand embedded spaces (and such) in
726            the argument list.  To start up sh rather than csh, some systems
727            may have to replace the "#!" line with a line containing just a
728            colon, which will be politely ignored by Perl.  Other systems
729            can't control that, and need a totally devious construct that will
730            work under any of csh, sh, or Perl, such as the following:
731
732                    eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
733                    & eval 'exec /usr/bin/perl -wS $0 $argv:q'
734                            if 0; # ^ Run only under a shell
735
736            If the filename supplied contains directory separators (and so is
737            an absolute or relative pathname), and if that file is not found,
738            platforms that append file extensions will do so and try to look
739            for the file with those extensions added, one by one.
740
741            On DOS-like platforms, if the program does not contain directory
742            separators, it will first be searched for in the current directory
743            before being searched for on the PATH.  On Unix platforms, the
744            program will be searched for strictly on the PATH.
745
746       -t   Like "-T", but taint checks will issue warnings rather than fatal
747            errors.  These warnings can now be controlled normally with "no
748            warnings qw(taint)".
749
750            Note: This is not a substitute for "-T"! This is meant to be used
751            only as a temporary development aid while securing legacy code:
752            for real production code and for new secure code written from
753            scratch, always use the real "-T".
754
755       -T   turns on "taint" so you can test them.  Ordinarily these checks
756            are done only when running setuid or setgid.  It's a good idea to
757            turn them on explicitly for programs that run on behalf of someone
758            else whom you might not necessarily trust, such as CGI programs or
759            any internet servers you might write in Perl.  See perlsec for
760            details.  For security reasons, this option must be seen by Perl
761            quite early; usually this means it must appear early on the
762            command line or in the "#!" line for systems which support that
763            construct.
764
765       -u   This switch causes Perl to dump core after compiling your program.
766            You can then in theory take this core dump and turn it into an
767            executable file by using the undump program (not supplied).  This
768            speeds startup at the expense of some disk space (which you can
769            minimize by stripping the executable).  (Still, a "hello world"
770            executable comes out to about 200K on my machine.)  If you want to
771            execute a portion of your program before dumping, use the
772            "CORE::dump()" function instead.  Note: availability of undump is
773            platform specific and may not be available for a specific port of
774            Perl.
775
776       -U   allows Perl to do unsafe operations.  Currently the only "unsafe"
777            operations are attempting to unlink directories while running as
778            superuser and running setuid programs with fatal taint checks
779            turned into warnings.  Note that warnings must be enabled along
780            with this option to actually generate the taint-check warnings.
781
782       -v   prints the version and patchlevel of your perl executable.
783
784       -V   prints summary of the major perl configuration values and the
785            current values of @INC.
786
787       -V:configvar
788            Prints to STDOUT the value of the named configuration variable(s),
789            with multiples when your "configvar" argument looks like a regex
790            (has non-letters).  For example:
791
792                $ perl -V:libc
793                    libc='/lib/libc-2.2.4.so';
794                $ perl -V:lib.
795                    libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
796                    libc='/lib/libc-2.2.4.so';
797                $ perl -V:lib.*
798                    libpth='/usr/local/lib /lib /usr/lib';
799                    libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
800                    lib_ext='.a';
801                    libc='/lib/libc-2.2.4.so';
802                    libperl='libperl.a';
803                    ....
804
805            Additionally, extra colons can be used to control formatting.  A
806            trailing colon suppresses the linefeed and terminator ";",
807            allowing you to embed queries into shell commands.  (mnemonic:
808            PATH separator ":".)
809
810                $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
811                compression-vars:  zcat='' zip='zip'  are here !
812
813            A leading colon removes the "name=" part of the response, this
814            allows you to map to the name you need.  (mnemonic: empty label)
815
816                $ echo "goodvfork="`./perl -Ilib -V::usevfork`
817                goodvfork=false;
818
819            Leading and trailing colons can be used together if you need
820            positional parameter values without the names.  Note that in the
821            case below, the "PERL_API" params are returned in alphabetical
822            order.
823
824                $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
825                building_on 'linux' '5' '1' '9' now
826
827       -w   prints warnings about dubious constructs, such as variable names
828            mentioned only once and scalar variables used before being set;
829            redefined subroutines; references to undefined filehandles;
830            filehandles opened read-only that you are attempting to write on;
831            values used as a number that don't look like numbers; using an
832            array as though it were a scalar; if your subroutines recurse more
833            than 100 deep; and innumerable other things.
834
835            This switch really just enables the global $^W variable; normally,
836            the lexically scoped "use warnings" pragma is preferred. You can
837            disable or promote into fatal errors specific warnings using
838            "__WARN__" hooks, as described in perlvar and "warn" in perlfunc.
839            See also perldiag and perltrap.  A fine-grained warning facility
840            is also available if you want to manipulate entire classes of
841            warnings; see warnings.
842
843       -W   Enables all warnings regardless of "no warnings" or $^W.  See
844            warnings.
845
846       -X   Disables all warnings regardless of "use warnings" or $^W.  See
847            warnings.
848
849            Forbidden in "PERL5OPT".
850
851       -x
852       -xdirectory
853            tells Perl that the program is embedded in a larger chunk of
854            unrelated text, such as in a mail message.  Leading garbage will
855            be discarded until the first line that starts with "#!" and
856            contains the string "perl".  Any meaningful switches on that line
857            will be applied.
858
859            All references to line numbers by the program (warnings, errors,
860            ...)  will treat the "#!" line as the first line.  Thus a warning
861            on the 2nd line of the program, which is on the 100th line in the
862            file will be reported as line 2, not as line 100.  This can be
863            overridden by using the "#line" directive.  (See "Plain Old
864            Comments (Not!)" in perlsyn)
865
866            If a directory name is specified, Perl will switch to that
867            directory before running the program.  The -x switch controls only
868            the disposal of leading garbage.  The program must be terminated
869            with "__END__" if there is trailing garbage to be ignored;  the
870            program can process any or all of the trailing garbage via the
871            "DATA" filehandle if desired.
872
873            The directory, if specified, must appear immediately following the
874            -x with no intervening whitespace.
875

ENVIRONMENT

877       HOME        Used if "chdir" has no argument.
878
879       LOGDIR      Used if "chdir" has no argument and "HOME" is not set.
880
881       PATH        Used in executing subprocesses, and in finding the program
882                   if "-S" is used.
883
884       PERL5LIB    A list of directories in which to look for Perl library
885                   files before looking in the standard library.  Any
886                   architecture-specific and version-specific directories,
887                   such as version/archname/, version/, or archname/ under the
888                   specified locations are automatically included if they
889                   exist, with this lookup done at interpreter startup time.
890                   In addition, any directories matching the entries in
891                   $Config{inc_version_list} are added.  (These typically
892                   would be for older compatible perl versions installed in
893                   the same directory tree.)
894
895                   If PERL5LIB is not defined, "PERLLIB" is used.  Directories
896                   are separated (like in PATH) by a colon on Unixish
897                   platforms and by a semicolon on Windows (the proper path
898                   separator being given by the command "perl -V:path_sep").
899
900                   When running taint checks, either because the program was
901                   running setuid or setgid, or the "-T" or "-t" switch was
902                   specified, neither PERL5LIB nor "PERLLIB" is consulted. The
903                   program should instead say:
904
905                       use lib "/my/directory";
906
907       PERL5OPT    Command-line options (switches).  Switches in this variable
908                   are treated as if they were on every Perl command line.
909                   Only the -[CDIMTUWdmtw] switches are allowed.  When running
910                   taint checks (either because the program was running setuid
911                   or setgid, or because the "-T" or "-t" switch was used),
912                   this variable is ignored.  If PERL5OPT begins with -T,
913                   tainting will be enabled and subsequent options ignored.
914                   If PERL5OPT begins with -t, tainting will be enabled, a
915                   writable dot removed from @INC, and subsequent options
916                   honored.
917
918       PERLIO      A space (or colon) separated list of PerlIO layers. If perl
919                   is built to use PerlIO system for IO (the default) these
920                   layers affect Perl's IO.
921
922                   It is conventional to start layer names with a colon (for
923                   example, ":perlio") to emphasize their similarity to
924                   variable "attributes". But the code that parses layer
925                   specification strings, which is also used to decode the
926                   PERLIO environment variable, treats the colon as a
927                   separator.
928
929                   An unset or empty PERLIO is equivalent to the default set
930                   of layers for your platform; for example, ":unix:perlio" on
931                   Unix-like systems and ":unix:crlf" on Windows and other
932                   DOS-like systems.
933
934                   The list becomes the default for all Perl's IO.
935                   Consequently only built-in layers can appear in this list,
936                   as external layers (such as ":encoding()") need IO in order
937                   to load them!  See "open pragma" for how to add external
938                   encodings as defaults.
939
940                   Layers it makes sense to include in the PERLIO environment
941                   variable are briefly summarized below. For more details see
942                   PerlIO.
943
944                   :crlf   A layer which does CRLF to "\n" translation
945                           distinguishing "text" and "binary" files in the
946                           manner of MS-DOS and similar operating systems, and
947                           also provides buffering similar to ":perlio" on
948                           these architectures.
949
950                   :perlio This is a re-implementation of stdio-like buffering
951                           written as a PerlIO layer.  As such it will call
952                           whatever layer is below it for its operations,
953                           typically ":unix".
954
955                   :stdio  This layer provides a PerlIO interface by wrapping
956                           system's ANSI C "stdio" library calls. The layer
957                           provides both buffering and IO.  Note that the
958                           ":stdio" layer does not do CRLF translation even if
959                           that is the platform's normal behaviour. You will
960                           need a ":crlf" layer above it to do that.
961
962                   :unix   Low-level layer that calls "read", "write",
963                           "lseek", etc.
964
965                   :win32  On Win32 platforms this experimental layer uses
966                           native "handle" IO rather than a Unix-like numeric
967                           file descriptor layer. Known to be buggy in this
968                           release (5.30).
969
970                   The default set of layers should give acceptable results on
971                   all platforms.
972
973                   For Unix platforms that will be the equivalent of
974                   ":unix:perlio" or ":stdio".  Configure is set up to prefer
975                   the ":stdio" implementation if the system's library
976                   provides for fast access to the buffer (not common on
977                   modern architectures); otherwise, it uses the
978                   ":unix:perlio" implementation.
979
980                   On Win32 the default in this release (5.30) is
981                   ":unix:crlf". Win32's ":stdio" has a number of
982                   bugs/mis-features for Perl IO which are somewhat depending
983                   on the version and vendor of the C compiler. Using our own
984                   ":crlf" layer as the buffer avoids those issues and makes
985                   things more uniform.
986
987                   This release (5.30) uses ":unix" as the bottom layer on
988                   Win32, and so still uses the C compiler's numeric file
989                   descriptor routines. There is an experimental native
990                   ":win32" layer, which is expected to be enhanced and may
991                   eventually become the default under Win32.
992
993                   The PERLIO environment variable is completely ignored when
994                   Perl is run in taint mode.
995
996       PERLIO_DEBUG
997                   If set to the name of a file or device when Perl is run
998                   with the -Di command-line switch, the logging of certain
999                   operations of the PerlIO subsystem will be redirected to
1000                   the specified file rather than going to stderr, which is
1001                   the default. The file is opened in append mode. Typical
1002                   uses are in Unix:
1003
1004                      % env PERLIO_DEBUG=/tmp/perlio.log perl -Di script ...
1005
1006                   and under Win32, the approximately equivalent:
1007
1008                      > set PERLIO_DEBUG=CON
1009                      perl -Di script ...
1010
1011                   This functionality is disabled for setuid scripts, for
1012                   scripts run with "-T", and for scripts run on a Perl built
1013                   without "-DDEBUGGING" support.
1014
1015       PERLLIB     A list of directories in which to look for Perl library
1016                   files before looking in the standard library.  If
1017                   "PERL5LIB" is defined, PERLLIB is not used.
1018
1019                   The PERLLIB environment variable is completely ignored when
1020                   Perl is run in taint mode.
1021
1022       PERL5DB     The command used to load the debugger code.  The default
1023                   is:
1024
1025                           BEGIN { require "perl5db.pl" }
1026
1027                   The PERL5DB environment variable is only used when Perl is
1028                   started with a bare "-d" switch.
1029
1030       PERL5DB_THREADED
1031                   If set to a true value, indicates to the debugger that the
1032                   code being debugged uses threads.
1033
1034       PERL5SHELL (specific to the Win32 port)
1035                   On Win32 ports only, may be set to an alternative shell
1036                   that Perl must use internally for executing "backtick"
1037                   commands or system().  Default is "cmd.exe /x/d/c" on
1038                   WindowsNT and "command.com /c" on Windows95.  The value is
1039                   considered space-separated.  Precede any character that
1040                   needs to be protected, like a space or backslash, with
1041                   another backslash.
1042
1043                   Note that Perl doesn't use COMSPEC for this purpose because
1044                   COMSPEC has a high degree of variability among users,
1045                   leading to portability concerns.  Besides, Perl can use a
1046                   shell that may not be fit for interactive use, and setting
1047                   COMSPEC to such a shell may interfere with the proper
1048                   functioning of other programs (which usually look in
1049                   COMSPEC to find a shell fit for interactive use).
1050
1051                   Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint
1052                   checked when running external commands.  It is recommended
1053                   that you explicitly set (or delete) $ENV{PERL5SHELL} when
1054                   running in taint mode under Windows.
1055
1056       PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
1057                   Set to 1 to allow the use of non-IFS compatible LSPs
1058                   (Layered Service Providers).  Perl normally searches for an
1059                   IFS-compatible LSP because this is required for its
1060                   emulation of Windows sockets as real filehandles.  However,
1061                   this may cause problems if you have a firewall such as
1062                   McAfee Guardian, which requires that all applications use
1063                   its LSP but which is not IFS-compatible, because clearly
1064                   Perl will normally avoid using such an LSP.
1065
1066                   Setting this environment variable to 1 means that Perl will
1067                   simply use the first suitable LSP enumerated in the
1068                   catalog, which keeps McAfee Guardian happy--and in that
1069                   particular case Perl still works too because McAfee
1070                   Guardian's LSP actually plays other games which allow
1071                   applications requiring IFS compatibility to work.
1072
1073       PERL_DEBUG_MSTATS
1074                   Relevant only if Perl is compiled with the "malloc"
1075                   included with the Perl distribution; that is, if "perl
1076                   -V:d_mymalloc" is "define".
1077
1078                   If set, this dumps out memory statistics after execution.
1079                   If set to an integer greater than one, also dumps out
1080                   memory statistics after compilation.
1081
1082       PERL_DESTRUCT_LEVEL
1083                   Controls the behaviour of global destruction of objects and
1084                   other references.  See "PERL_DESTRUCT_LEVEL" in
1085                   perlhacktips for more information.
1086
1087       PERL_DL_NONLAZY
1088                   Set to "1" to have Perl resolve all undefined symbols when
1089                   it loads a dynamic library.  The default behaviour is to
1090                   resolve symbols when they are used.  Setting this variable
1091                   is useful during testing of extensions, as it ensures that
1092                   you get an error on misspelled function names even if the
1093                   test suite doesn't call them.
1094
1095       PERL_ENCODING
1096                   If using the "use encoding" pragma without an explicit
1097                   encoding name, the PERL_ENCODING environment variable is
1098                   consulted for an encoding name.
1099
1100       PERL_HASH_SEED
1101                   (Since Perl 5.8.1, new semantics in Perl 5.18.0)  Used to
1102                   override the randomization of Perl's internal hash
1103                   function. The value is expressed in hexadecimal, and may
1104                   include a leading 0x. Truncated patterns are treated as
1105                   though they are suffixed with sufficient 0's as required.
1106
1107                   If the option is provided, and "PERL_PERTURB_KEYS" is NOT
1108                   set, then a value of '0' implies "PERL_PERTURB_KEYS=0" and
1109                   any other value implies "PERL_PERTURB_KEYS=2".
1110
1111                   PLEASE NOTE: The hash seed is sensitive information. Hashes
1112                   are randomized to protect against local and remote attacks
1113                   against Perl code. By manually setting a seed, this
1114                   protection may be partially or completely lost.
1115
1116                   See "Algorithmic Complexity Attacks" in perlsec,
1117                   "PERL_PERTURB_KEYS", and "PERL_HASH_SEED_DEBUG" for more
1118                   information.
1119
1120       PERL_PERTURB_KEYS
1121                   (Since Perl 5.18.0)  Set to "0" or "NO" then traversing
1122                   keys will be repeatable from run to run for the same
1123                   "PERL_HASH_SEED".  Insertion into a hash will not change
1124                   the order, except to provide for more space in the hash.
1125                   When combined with setting PERL_HASH_SEED this mode is as
1126                   close to pre 5.18 behavior as you can get.
1127
1128                   When set to "1" or "RANDOM" then traversing keys will be
1129                   randomized.  Every time a hash is inserted into the key
1130                   order will change in a random fashion. The order may not be
1131                   repeatable in a following program run even if the
1132                   PERL_HASH_SEED has been specified. This is the default mode
1133                   for perl.
1134
1135                   When set to "2" or "DETERMINISTIC" then inserting keys into
1136                   a hash will cause the key order to change, but in a way
1137                   that is repeatable from program run to program run.
1138
1139                   NOTE: Use of this option is considered insecure, and is
1140                   intended only for debugging non-deterministic behavior in
1141                   Perl's hash function. Do not use it in production.
1142
1143                   See "Algorithmic Complexity Attacks" in perlsec and
1144                   "PERL_HASH_SEED" and "PERL_HASH_SEED_DEBUG" for more
1145                   information. You can get and set the key traversal mask for
1146                   a specific hash by using the "hash_traversal_mask()"
1147                   function from Hash::Util.
1148
1149       PERL_HASH_SEED_DEBUG
1150                   (Since Perl 5.8.1.)  Set to "1" to display (to STDERR)
1151                   information about the hash function, seed, and what type of
1152                   key traversal randomization is in effect at the beginning
1153                   of execution.  This, combined with "PERL_HASH_SEED" and
1154                   "PERL_PERTURB_KEYS" is intended to aid in debugging
1155                   nondeterministic behaviour caused by hash randomization.
1156
1157                   Note that any information about the hash function,
1158                   especially the hash seed is sensitive information: by
1159                   knowing it, one can craft a denial-of-service attack
1160                   against Perl code, even remotely; see "Algorithmic
1161                   Complexity Attacks" in perlsec for more information. Do not
1162                   disclose the hash seed to people who don't need to know it.
1163                   See also "hash_seed()" and "hash_traversal_mask()".
1164
1165                   An example output might be:
1166
1167                    HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
1168
1169       PERL_MEM_LOG
1170                   If your Perl was configured with -Accflags=-DPERL_MEM_LOG,
1171                   setting the environment variable "PERL_MEM_LOG" enables
1172                   logging debug messages. The value has the form
1173                   "<number>[m][s][t]", where "number" is the file descriptor
1174                   number you want to write to (2 is default), and the
1175                   combination of letters specifies that you want information
1176                   about (m)emory and/or (s)v, optionally with (t)imestamps.
1177                   For example, "PERL_MEM_LOG=1mst" logs all information to
1178                   stdout. You can write to other opened file descriptors in a
1179                   variety of ways:
1180
1181                     $ 3>foo3 PERL_MEM_LOG=3m perl ...
1182
1183       PERL_ROOT (specific to the VMS port)
1184                   A translation-concealed rooted logical name that contains
1185                   Perl and the logical device for the @INC path on VMS only.
1186                   Other logical names that affect Perl on VMS include
1187                   PERLSHR, PERL_ENV_TABLES, and SYS$TIMEZONE_DIFFERENTIAL,
1188                   but are optional and discussed further in perlvms and in
1189                   README.vms in the Perl source distribution.
1190
1191       PERL_SIGNALS
1192                   Available in Perls 5.8.1 and later.  If set to "unsafe",
1193                   the pre-Perl-5.8.0 signal behaviour (which is immediate but
1194                   unsafe) is restored.  If set to "safe", then safe (but
1195                   deferred) signals are used.  See "Deferred Signals (Safe
1196                   Signals)" in perlipc.
1197
1198       PERL_UNICODE
1199                   Equivalent to the -C command-line switch.  Note that this
1200                   is not a boolean variable. Setting this to "1" is not the
1201                   right way to "enable Unicode" (whatever that would mean).
1202                   You can use "0" to "disable Unicode", though (or
1203                   alternatively unset PERL_UNICODE in your shell before
1204                   starting Perl).  See the description of the -C switch for
1205                   more information.
1206
1207       PERL_USE_UNSAFE_INC
1208                   If perl has been configured to not have the current
1209                   directory in @INC by default, this variable can be set to
1210                   "1" to reinstate it.  It's primarily intended for use while
1211                   building and testing modules that have not been updated to
1212                   deal with "." not being in @INC and should not be set in
1213                   the environment for day-to-day use.
1214
1215       SYS$LOGIN (specific to the VMS port)
1216                   Used if chdir has no argument and "HOME" and "LOGDIR" are
1217                   not set.
1218
1219       PERL_INTERNAL_RAND_SEED
1220                   Set to a non-negative integer to seed the random number
1221                   generator used internally by perl for a variety of
1222                   purposes.
1223
1224                   Ignored if perl is run setuid or setgid.  Used only for
1225                   some limited startup randomization (hash keys) if "-T" or
1226                   "-t" perl is started with tainting enabled.
1227
1228                   Perl may be built to ignore this variable.
1229
1230       Perl also has environment variables that control how Perl handles data
1231       specific to particular natural languages; see perllocale.
1232
1233       Perl and its various modules and components, including its test
1234       frameworks, may sometimes make use of certain other environment
1235       variables.  Some of these are specific to a particular platform.
1236       Please consult the appropriate module documentation and any
1237       documentation for your platform (like perlsolaris, perllinux,
1238       perlmacosx, perlwin32, etc) for variables peculiar to those specific
1239       situations.
1240
1241       Perl makes all environment variables available to the program being
1242       executed, and passes these along to any child processes it starts.
1243       However, programs running setuid would do well to execute the following
1244       lines before doing anything else, just to keep people honest:
1245
1246           $ENV{PATH}  = "/bin:/usr/bin";    # or whatever you need
1247           $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
1248           delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
1249

ORDER OF APPLICATION

1251       Some options, in particular "-I", "-M", "PERL5LIB" and "PERL5OPT" can
1252       interact, and the order in which they are applied is important.
1253
1254       Note that this section does not document what actually happens inside
1255       the perl interpreter, it documents what effectively happens.
1256
1257       -I  The effect of multiple "-I" options is to "unshift" them onto @INC
1258           from right to left. So for example:
1259
1260               perl -I 1 -I 2 -I 3
1261
1262           will first prepend 3 onto the front of @INC, then prepend 2, and
1263           then prepend 1. The result is that @INC begins with:
1264
1265               qw(1 2 3)
1266
1267       -M  Multiple "-M" options are processed from left to right. So this:
1268
1269               perl -Mlib=1 -Mlib=2 -Mlib=3
1270
1271           will first use the lib pragma to prepend 1 to @INC, then it will
1272           prepend 2, then it will prepend 3, resulting in an @INC that begins
1273           with:
1274
1275               qw(3 2 1)
1276
1277       the PERL5LIB environment variable
1278           This contains a list of directories, separated by colons. The
1279           entire list is prepended to @INC in one go. This:
1280
1281               PERL5LIB=1:2:3 perl
1282
1283           will result in an @INC that begins with:
1284
1285               qw(1 2 3)
1286
1287       combinations of -I, -M and PERL5LIB
1288           "PERL5LIB" is applied first, then all the "-I" arguments, then all
1289           the "-M" arguments. This:
1290
1291               PERL5LIB=e1:e2 perl -I i1 -Mlib=m1 -I i2 -Mlib=m2
1292
1293           will result in an @INC that begins with:
1294
1295               qw(m2 m1 i1 i2 e1 e2)
1296
1297       the PERL5OPT environment variable
1298           This contains a space separated list of switches. We only consider
1299           the effects of "-M" and "-I" in this section.
1300
1301           After normal processing of "-I" switches from the command line, all
1302           the "-I" switches in "PERL5OPT" are extracted. They are processed
1303           from left to right instead of from right to left. Also note that
1304           while whitespace is allowed between a "-I" and its directory on the
1305           command line, it is not allowed in "PERL5OPT".
1306
1307           After normal processing of "-M" switches from the command line, all
1308           the "-M" switches in "PERL5OPT" are extracted. They are processed
1309           from left to right, i.e. the same as those on the command line.
1310
1311           An example may make this clearer:
1312
1313               export PERL5OPT="-Mlib=optm1 -Iopti1 -Mlib=optm2 -Iopti2"
1314               export PERL5LIB=e1:e2
1315               perl -I i1 -Mlib=m1 -I i2 -Mlib=m2
1316
1317           will result in an @INC that begins with:
1318
1319               qw(
1320                   optm2
1321                   optm1
1322
1323                   m2
1324                   m1
1325
1326                   opti2
1327                   opti1
1328
1329                   i1
1330                   i2
1331
1332                   e1
1333                   e2
1334               )
1335
1336       Other complications
1337           There are some complications that are ignored in the examples
1338           above:
1339
1340           arch and version subdirs
1341               All of "-I", "PERL5LIB" and "use lib" will also prepend arch
1342               and version subdirs if they are present
1343
1344           sitecustomize.pl
1345
1346
1347
1348perl v5.34.1                      2022-03-15                        PERLRUN(1)
Impressum