1PERLRUN(1) Perl Programmers Reference Guide PERLRUN(1)
2
6 perlrun - how to execute the Perl interpreter
7
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
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 1. Specified line by line via -e or -E switches on the command line.
25 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 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 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 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 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 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 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 #!/bin/sh
67 #! -*- perl -*- -p
68 eval 'exec perl -x -wS $0 ${1+"$@"}'
69 if 0;
70 to let Perl see the "-p" switch.
72 A similar trick involves the env program, if you have it.
74 #!/usr/bin/env perl
76 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 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 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 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 #! and quoting on non-Unix systems
99 Unix's "#!" technique can be simulated on other systems:
100 OS/2
102 Put
103 extproc perl -S -your_switches
105 as the first line in "*.cmd" file ("-S" due to a bug in cmd.exe's
107 `extproc' handling).
108 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 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 VMS Put
124 $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
126 $ exit++ + ++$status != 0 and $exit = $status = undef;
127 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 This incantation is a bit much to remember, but Perl will display
135 it for you if you say "perl "-V:startperl"".
136 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 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 For example:
148 # Unix
150 perl -e 'print "Hello world\n"'
151 # MS-DOS, etc.
153 perl -e "print \"Hello world\n\""
154 # VMS
156 perl -e "print ""Hello world\n"""
157 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 perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
163 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 There is no general solution to all of this. It's just a mess.
169 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 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 #!/usr/local/bin/perl5.14
185 or if you just want to be running at least version, place a statement
187 like this at the top of your program:
188 use v5.14;
190 Command Switches
192 As with all standard commands, a single-character switch may be
193 clustered with the following switch, if any.
194 #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
196 A "--" signals the end of options and disables further option
198 processing. Any arguments after the "--" are treated as filenames and
199 arguments.
200 Switches include:
202 -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 find . -name '*.orig' -print0 | perl -n0e unlink
211 The special value 00 will cause Perl to slurp files in paragraph
213 mode.
214 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 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 -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 perl -ane 'print pop(@F), "\n";'
233 is equivalent to
235 while (<>) {
237 @F = split(' ');
238 print pop(@F), "\n";
239 }
240 An alternate delimiter may be specified using -F.
242 -a implicitly sets "-n".
244 -C [number/list]
246 The -C flag controls some of the Perl Unicode features.
247 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 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 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 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 -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 You can use -C0 (or "0" for "PERL_UNICODE") to explicitly disable
292 all the above Unicode features.
293 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 (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 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 -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 -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 -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 -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 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 As an alternative, specify a number instead of list of letters
347 (e.g., -D14 is equivalent to -Dtls):
348 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 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 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 # If you have "env" utility
400 env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
401 # Bourne shell syntax
403 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
404 # csh syntax
406 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
407 See perldebug for details and variations.
409 -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 -E commandline
417 behaves just like -e, except that it implicitly enables all
418 optional features (in the main compilation unit). See feature.
419 -f Disable executing $Config{sitelib}/sitecustomize.pl at startup.
421 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 Perl actually inserts the following code:
429 BEGIN {
431 do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
432 && do "$Config{sitelib}/sitecustomize.pl";
433 }
434 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 The value of $Config{sitelib} is also determined in C code and not
441 read from "Config.pm", which is not loaded.
442 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 To determine at runtime if this capability has been compiled in
448 your perl, you can check the value of $Config{usesitecustomize}.
449 -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 -F implicitly sets both "-a" and "-n".
457 -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 This flag is a simpler alias for -0777.
463 Mnemonics: gobble, grab, gulp.
465 -h prints a summary of the options.
467 -? synonym for -h: prints a summary of the options.
469 -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 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 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 ($backup = $extension) =~ s/\*/$file_name/g;
489 This allows you to add a prefix to the backup file, instead of (or
491 in addition to) a suffix:
492 $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to
494 # 'orig_fileA'
495 Or even to place backup copies of the original files into another
497 directory (provided the directory already exists):
498 $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to
500 # 'old/fileA.orig'
501 These sets of one-liners are equivalent:
503 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
505 $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
506 $ 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 From the shell, saying
511 $ perl -p -i.orig -e "s/foo/bar/; ... "
513 is the same as using the program:
515 #!/usr/bin/perl -pi.orig
517 s/foo/bar/;
518 which is equivalent to
520 #!/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 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 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 $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
553 or
554 $ perl -p -i'.orig' -e 1 file1 file2 file3...
555 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 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 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 You cannot use -i to create directories or to strip extensions
569 from files.
570 Perl does not expand "~" in filenames, which is good, since some
572 folks use it for their backup files:
573 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
575 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 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 -Idirectory
586 Directories specified by -I are prepended to the search path for
587 modules (@INC).
588 -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 perl -lpe 'substr($_, 80) = ""'
599 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 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
606 This sets "$\" to newline and then sets $/ to the null character.
608 -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 -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 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 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 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 -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 LINE:
645 while (<>) {
646 ... # your program goes here
647 }
648 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 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 Here is an efficient way to delete all files that haven't been
659 modified for at least a week:
660 find . -mtime +7 -print | perl -nle unlink
662 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 "BEGIN" and "END" blocks may be used to capture control before or
671 after the implicit program loop, just as in awk.
672 -p causes Perl to assume the following loop around your program,
674 which makes it iterate over filename arguments somewhat like sed:
675 LINE:
677 while (<>) {
678 ... # your program goes here
679 } continue {
680 print or die "-p destination: $!\n";
681 }
682 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 "BEGIN" and "END" blocks may be used to capture control before or
690 after the implicit loop, just as in awk.
691 -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 #!/usr/bin/perl -s
701 if ($xyz) { print "$xyz\n" }
702 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 -S makes Perl use the "PATH" environment variable to search for the
711 program unless the name of the program contains path separators.
712 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 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 This example works on many platforms that have a shell compatible
727 with Bourne shell:
728 #!/usr/bin/perl
730 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
731 if 0; # ^ Run only under a shell
732 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 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 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 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 -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 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 This has no effect if your perl was built without taint support.
773 -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 -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 -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 -v prints the version and patchlevel of your perl executable.
802 -V prints summary of the major perl configuration values and the
804 current values of @INC.
805 -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 $ 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 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 $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
830 compression-vars: zcat='' zip='zip' are here !
831 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 $ echo "goodvfork="`./perl -Ilib -V::usevfork`
836 goodvfork=false;
837 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 $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
844 building_on 'linux' '5' '1' '9' now
845 -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 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 -W Enables all warnings regardless of "no warnings" or $^W. See
863 warnings.
864 -X Disables all warnings regardless of "use warnings" or $^W. See
866 warnings.
867 Forbidden in "PERL5OPT".
869 -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 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 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 The directory, if specified, must appear immediately following the
893 -x with no intervening whitespace.
894
896 HOME Used if "chdir" has no argument.
897 LOGDIR Used if "chdir" has no argument and "HOME" is not set.
899 PATH Used in executing subprocesses, and in finding the program
901 if "-S" is used.
902 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 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 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 use lib "/my/directory";
925 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 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 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 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 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 Layers it makes sense to include in the PERLIO environment
960 variable are briefly summarized below. For more details see
961 PerlIO.
962 :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 :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 :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 :unix Low-level layer that calls "read", "write",
982 "lseek", etc.
983 The default set of layers should give acceptable results on
985 all platforms.
986 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 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 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 The PERLIO environment variable is completely ignored when
1006 Perl is run in taint mode.
1007 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 % env PERLIO_DEBUG=/tmp/perlio.log perl -Di script ...
1017 and under Win32, the approximately equivalent:
1019 > set PERLIO_DEBUG=CON
1021 perl -Di script ...
1022 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 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 The PERLLIB environment variable is completely ignored when
1032 Perl is run in taint mode.
1033 PERL5DB The command used to load the debugger code. The default
1035 is:
1036 BEGIN { require "perl5db.pl" }
1038 The PERL5DB environment variable is only used when Perl is
1040 started with a bare "-d" switch.
1041 PERL5DB_THREADED
1043 If set to a true value, indicates to the debugger that the
1044 code being debugged uses threads.
1045 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 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 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 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 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 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 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 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 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 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 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 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 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 See "Algorithmic Complexity Attacks" in perlsec,
1133 "PERL_PERTURB_KEYS", and "PERL_HASH_SEED_DEBUG" for more
1134 information.
1135 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 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 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 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 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()"
1178 function from Hash::Util.
1179 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 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 An example output might be:
1197 HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
1199 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 $ 3>foo3 PERL_MEM_LOG=3m perl ...
1213 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 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 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 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 SYS$LOGIN (specific to the VMS port)
1247 Used if chdir has no argument and "HOME" and "LOGDIR" are
1248 not set.
1249 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 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 Perl may be built to ignore this variable.
1260 Perl also has environment variables that control how Perl handles data
1262 specific to particular natural languages; see perllocale.
1263 Perl and its various modules and components, including its test
1265 frameworks, may sometimes make use of certain other environment
1266 variables. Some of these are specific to a particular platform.
1267 Please consult the appropriate module documentation and any
1268 documentation for your platform (like perlsolaris, perllinux,
1269 perlmacosx, perlwin32, etc) for variables peculiar to those specific
1270 situations.
1271 Perl makes all environment variables available to the program being
1273 executed, and passes these along to any child processes it starts.
1274 However, programs running setuid would do well to execute the following
1275 lines before doing anything else, just to keep people honest:
1276 $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need
1278 $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL};
1279 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
1280
1282 Some options, in particular "-I", "-M", "PERL5LIB" and "PERL5OPT" can
1283 interact, and the order in which they are applied is important.
1284 Note that this section does not document what actually happens inside
1286 the perl interpreter, it documents what effectively happens.
1287 -I The effect of multiple "-I" options is to "unshift" them onto @INC
1289 from right to left. So for example:
1290 perl -I 1 -I 2 -I 3
1292 will first prepend 3 onto the front of @INC, then prepend 2, and
1294 then prepend 1. The result is that @INC begins with:
1295 qw(1 2 3)
1297 -M Multiple "-M" options are processed from left to right. So this:
1299 perl -Mlib=1 -Mlib=2 -Mlib=3
1301 will first use the lib pragma to prepend 1 to @INC, then it will
1303 prepend 2, then it will prepend 3, resulting in an @INC that begins
1304 with:
1305 qw(3 2 1)
1307 the PERL5LIB environment variable
1309 This contains a list of directories, separated by colons. The
1310 entire list is prepended to @INC in one go. This:
1311 PERL5LIB=1:2:3 perl
1313 will result in an @INC that begins with:
1315 qw(1 2 3)
1317 combinations of -I, -M and PERL5LIB
1319 "PERL5LIB" is applied first, then all the "-I" arguments, then all
1320 the "-M" arguments. This:
1321 PERL5LIB=e1:e2 perl -I i1 -Mlib=m1 -I i2 -Mlib=m2
1323 will result in an @INC that begins with:
1325 qw(m2 m1 i1 i2 e1 e2)
1327 the PERL5OPT environment variable
1329 This contains a space separated list of switches. We only consider
1330 the effects of "-M" and "-I" in this section.
1331 After normal processing of "-I" switches from the command line, all
1333 the "-I" switches in "PERL5OPT" are extracted. They are processed
1334 from left to right instead of from right to left. Also note that
1335 while whitespace is allowed between a "-I" and its directory on the
1336 command line, it is not allowed in "PERL5OPT".
1337 After normal processing of "-M" switches from the command line, all
1339 the "-M" switches in "PERL5OPT" are extracted. They are processed
1340 from left to right, i.e. the same as those on the command line.
1341 An example may make this clearer:
1343 export PERL5OPT="-Mlib=optm1 -Iopti1 -Mlib=optm2 -Iopti2"
1345 export PERL5LIB=e1:e2
1346 perl -I i1 -Mlib=m1 -I i2 -Mlib=m2
1347 will result in an @INC that begins with:
1349 qw(
1351 optm2
1352 optm1
1353 m2
1355 m1
1356 opti2
1358 opti1
1359 i1
1361 i2
1362 e1
1364 e2
1365 )
1366 Other complications
1368 There are some complications that are ignored in the examples
1369 above:
1370 arch and version subdirs
1372 All of "-I", "PERL5LIB" and "use lib" will also prepend arch
1373 and version subdirs if they are present
1374 sitecustomize.pl
1376perl v5.36.0 2022-08-30 PERLRUN(1)