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

NAME

6       perlrun - how to execute the Perl interpreter
7

SYNOPSIS

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

ENVIRONMENT

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

ORDER OF APPLICATION

1309       Some options, in particular "-I", "-M", "PERL5LIB" and "PERL5OPT" can
1310       interact, and the order in which they are applied is important.
1311
1312       Note that this section does not document what actually happens inside
1313       the perl interpreter, it documents what effectively happens.
1314
1315       -I  The effect of multiple "-I" options is to "unshift" them onto @INC
1316           from right to left. So for example:
1317
1318               perl -I 1 -I 2 -I 3
1319
1320           will first prepend 3 onto the front of @INC, then prepend 2, and
1321           then prepend 1. The result is that @INC begins with:
1322
1323               qw(1 2 3)
1324
1325       -M  Multiple "-M" options are processed from left to right. So this:
1326
1327               perl -Mlib=1 -Mlib=2 -Mlib=3
1328
1329           will first use the lib pragma to prepend 1 to @INC, then it will
1330           prepend 2, then it will prepend 3, resulting in an @INC that begins
1331           with:
1332
1333               qw(3 2 1)
1334
1335       the PERL5LIB environment variable
1336           This contains a list of directories, separated by colons. The
1337           entire list is prepended to @INC in one go. This:
1338
1339               PERL5LIB=1:2:3 perl
1340
1341           will result in an @INC that begins with:
1342
1343               qw(1 2 3)
1344
1345       combinations of -I, -M and PERL5LIB
1346           "PERL5LIB" is applied first, then all the "-I" arguments, then all
1347           the "-M" arguments. This:
1348
1349               PERL5LIB=e1:e2 perl -I i1 -Mlib=m1 -I i2 -Mlib=m2
1350
1351           will result in an @INC that begins with:
1352
1353               qw(m2 m1 i1 i2 e1 e2)
1354
1355       the PERL5OPT environment variable
1356           This contains a space separated list of switches. We only consider
1357           the effects of "-M" and "-I" in this section.
1358
1359           After normal processing of "-I" switches from the command line, all
1360           the "-I" switches in "PERL5OPT" are extracted. They are processed
1361           from left to right instead of from right to left. Also note that
1362           while whitespace is allowed between a "-I" and its directory on the
1363           command line, it is not allowed in "PERL5OPT".
1364
1365           After normal processing of "-M" switches from the command line, all
1366           the "-M" switches in "PERL5OPT" are extracted. They are processed
1367           from left to right, i.e. the same as those on the command line.
1368
1369           An example may make this clearer:
1370
1371               export PERL5OPT="-Mlib=optm1 -Iopti1 -Mlib=optm2 -Iopti2"
1372               export PERL5LIB=e1:e2
1373               perl -I i1 -Mlib=m1 -I i2 -Mlib=m2
1374
1375           will result in an @INC that begins with:
1376
1377               qw(
1378                   optm2
1379                   optm1
1380
1381                   m2
1382                   m1
1383
1384                   opti2
1385                   opti1
1386
1387                   i1
1388                   i2
1389
1390                   e1
1391                   e2
1392               )
1393
1394       Other complications
1395           There are some complications that are ignored in the examples
1396           above:
1397
1398           arch and version subdirs
1399               All of "-I", "PERL5LIB" and "use lib" will also prepend arch
1400               and version subdirs if they are present
1401
1402           sitecustomize.pl
1403
1404
1405
1406perl v5.38.2                      2023-11-30                        PERLRUN(1)
Impressum