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 $running_under_some_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 variable $running_under_some_shell is never true.  If the
724            program will be interpreted by csh, you will need to replace
725            "${1+"$@"}" with $*, even though that doesn't understand embedded
726            spaces (and such) in the argument list.  To start up sh rather
727            than csh, some systems may have to replace the "#!" line with a
728            line containing just a colon, which will be politely ignored by
729            Perl.  Other systems can't control that, and need a totally
730            devious construct that will work under any of csh, sh, or Perl,
731            such as the following:
732
733                    eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
734                    & eval 'exec /usr/bin/perl -wS $0 $argv:q'
735                            if $running_under_some_shell;
736
737            If the filename supplied contains directory separators (and so is
738            an absolute or relative pathname), and if that file is not found,
739            platforms that append file extensions will do so and try to look
740            for the file with those extensions added, one by one.
741
742            On DOS-like platforms, if the program does not contain directory
743            separators, it will first be searched for in the current directory
744            before being searched for on the PATH.  On Unix platforms, the
745            program will be searched for strictly on the PATH.
746
747       -t   Like "-T", but taint checks will issue warnings rather than fatal
748            errors.  These warnings can now be controlled normally with "no
749            warnings qw(taint)".
750
751            Note: This is not a substitute for "-T"! This is meant to be used
752            only as a temporary development aid while securing legacy code:
753            for real production code and for new secure code written from
754            scratch, always use the real "-T".
755
756       -T   turns on "taint" so you can test them.  Ordinarily these checks
757            are done only when running setuid or setgid.  It's a good idea to
758            turn them on explicitly for programs that run on behalf of someone
759            else whom you might not necessarily trust, such as CGI programs or
760            any internet servers you might write in Perl.  See perlsec for
761            details.  For security reasons, this option must be seen by Perl
762            quite early; usually this means it must appear early on the
763            command line or in the "#!" line for systems which support that
764            construct.
765
766       -u   This switch causes Perl to dump core after compiling your program.
767            You can then in theory take this core dump and turn it into an
768            executable file by using the undump program (not supplied).  This
769            speeds startup at the expense of some disk space (which you can
770            minimize by stripping the executable).  (Still, a "hello world"
771            executable comes out to about 200K on my machine.)  If you want to
772            execute a portion of your program before dumping, use the
773            "CORE::dump()" function instead.  Note: availability of undump is
774            platform specific and may not be available for a specific port of
775            Perl.
776
777       -U   allows Perl to do unsafe operations.  Currently the only "unsafe"
778            operations are attempting to unlink directories while running as
779            superuser and running setuid programs with fatal taint checks
780            turned into warnings.  Note that warnings must be enabled along
781            with this option to actually generate the taint-check warnings.
782
783       -v   prints the version and patchlevel of your perl executable.
784
785       -V   prints summary of the major perl configuration values and the
786            current values of @INC.
787
788       -V:configvar
789            Prints to STDOUT the value of the named configuration variable(s),
790            with multiples when your "configvar" argument looks like a regex
791            (has non-letters).  For example:
792
793                $ perl -V:libc
794                    libc='/lib/libc-2.2.4.so';
795                $ perl -V:lib.
796                    libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
797                    libc='/lib/libc-2.2.4.so';
798                $ perl -V:lib.*
799                    libpth='/usr/local/lib /lib /usr/lib';
800                    libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
801                    lib_ext='.a';
802                    libc='/lib/libc-2.2.4.so';
803                    libperl='libperl.a';
804                    ....
805
806            Additionally, extra colons can be used to control formatting.  A
807            trailing colon suppresses the linefeed and terminator ";",
808            allowing you to embed queries into shell commands.  (mnemonic:
809            PATH separator ":".)
810
811                $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
812                compression-vars:  zcat='' zip='zip'  are here !
813
814            A leading colon removes the "name=" part of the response, this
815            allows you to map to the name you need.  (mnemonic: empty label)
816
817                $ echo "goodvfork="`./perl -Ilib -V::usevfork`
818                goodvfork=false;
819
820            Leading and trailing colons can be used together if you need
821            positional parameter values without the names.  Note that in the
822            case below, the "PERL_API" params are returned in alphabetical
823            order.
824
825                $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
826                building_on 'linux' '5' '1' '9' now
827
828       -w   prints warnings about dubious constructs, such as variable names
829            mentioned only once and scalar variables used before being set;
830            redefined subroutines; references to undefined filehandles;
831            filehandles opened read-only that you are attempting to write on;
832            values used as a number that don't look like numbers; using an
833            array as though it were a scalar; if your subroutines recurse more
834            than 100 deep; and innumerable other things.
835
836            This switch really just enables the global $^W variable; normally,
837            the lexically scoped "use warnings" pragma is preferred. You can
838            disable or promote into fatal errors specific warnings using
839            "__WARN__" hooks, as described in perlvar and "warn" in perlfunc.
840            See also perldiag and perltrap.  A fine-grained warning facility
841            is also available if you want to manipulate entire classes of
842            warnings; see warnings.
843
844       -W   Enables all warnings regardless of "no warnings" or $^W.  See
845            warnings.
846
847       -X   Disables all warnings regardless of "use warnings" or $^W.  See
848            warnings.
849
850            Forbidden in ""PERL5OPT"".
851
852       -x
853       -xdirectory
854            tells Perl that the program is embedded in a larger chunk of
855            unrelated text, such as in a mail message.  Leading garbage will
856            be discarded until the first line that starts with "#!" and
857            contains the string "perl".  Any meaningful switches on that line
858            will be applied.
859
860            All references to line numbers by the program (warnings, errors,
861            ...)  will treat the "#!" line as the first line.  Thus a warning
862            on the 2nd line of the program, which is on the 100th line in the
863            file will be reported as line 2, not as line 100.  This can be
864            overridden by using the "#line" directive.  (See "Plain Old
865            Comments (Not!)" in perlsyn)
866
867            If a directory name is specified, Perl will switch to that
868            directory before running the program.  The -x switch controls only
869            the disposal of leading garbage.  The program must be terminated
870            with "__END__" if there is trailing garbage to be ignored;  the
871            program can process any or all of the trailing garbage via the
872            "DATA" filehandle if desired.
873
874            The directory, if specified, must appear immediately following the
875            -x with no intervening whitespace.
876

ENVIRONMENT

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

ORDER OF APPLICATION

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