1PERLRUN(1) Perl Programmers Reference Guide PERLRUN(1)
2
6 perlrun - how to execute the Perl interpreter
7
9 perl [ -sTtuUWX ] [ -hv ] [ -V[:configvar] ]
10 [ -cw ] [ -d[t][:debugger] ] [ -D[number/list] ]
11 [ -pna ] [ -Fpattern ] [ -l[octal] ] [ -0[octal/hexadecimal] ]
12 [ -Idir ] [ -m[-]module ] [ -M[-]'module...' ] [ -f ]
13 [ -C [number/list] ] [ -P ] [ -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 invoke
28 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 scans
36 for the first line starting with #! and containing the word "perl", and
37 starts there instead. This is useful for running a program embedded in
38 a larger message. (In this case you would indicate the end of the
39 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 behavior 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 be
49 passed in on the command line, and some may not; you could even get a
50 "-" 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-*-
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.005_57, you should place that directly in
80 the #! line's path.
81 If the #! line does not contain the word "perl", the program named
83 after the #! is executed instead of the Perl interpreter. This is
84 slightly bizarre, but it helps people on machines that don't do #!,
85 because they can tell a program that their SHELL is /usr/bin/perl, and
86 Perl will then dispatch the program to the correct interpreter for
87 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 Macintosh
124 Under "Classic" MacOS, a perl program will have the appropriate
125 Creator and Type, so that double-clicking them will invoke the
126 MacPerl application. Under Mac OS X, clickable apps can be made
127 from any "#!" script using Wil Sanchez' DropScript utility:
128 http://www.wsanchez.net/software/ .
129 VMS Put
131 $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
133 $ exit++ + ++$status != 0 and $exit = $status = undef;
134 at the top of your program, where -mysw are any command line
136 switches you want to pass to Perl. You can now invoke the program
137 directly, by saying "perl program", or as a DCL procedure, by
138 saying @program (or implicitly via DCL$PATH by just using the name
139 of the program).
140 This incantation is a bit much to remember, but Perl will display
142 it for you if you say "perl "-V:startperl"".
143 Command-interpreters on non-Unix systems have rather different ideas on
145 quoting than Unix shells. You'll need to learn the special characters
146 in your command-interpreter ("*", "\" and """ are common) and how to
147 protect whitespace and these characters to run one-liners (see -e
148 below).
149 On some systems, you may have to change single-quotes to double ones,
151 which you must not do on Unix or Plan 9 systems. You might also have
152 to change a single % to a %%.
153 For example:
155 # Unix
157 perl -e 'print "Hello world\n"'
158 # MS-DOS, etc.
160 perl -e "print \"Hello world\n\""
161 # Macintosh
163 print "Hello world\n"
164 (then Run "Myscript" or Shift-Command-R)
165 # VMS
167 perl -e "print ""Hello world\n"""
168 The problem is that none of this is reliable: it depends on the command
170 and it is entirely possible neither works. If 4DOS were the command
171 shell, this would probably work better:
172 perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
174 CMD.EXE in Windows NT slipped a lot of standard Unix functionality in
176 when nobody was looking, but just try to find documentation for its
177 quoting rules.
178 Under the Macintosh, it depends which environment you are using. The
180 MacPerl shell, or MPW, is much like Unix shells in its support for
181 several quoting variants, except that it makes free use of the
182 Macintosh's non-ASCII characters as control characters.
183 There is no general solution to all of this. It's just a mess.
185 Location of Perl
187 It may seem obvious to say, but Perl is useful only when users can
188 easily find it. When possible, it's good for both /usr/bin/perl and
189 /usr/local/bin/perl to be symlinks to the actual binary. If that can't
190 be done, system administrators are strongly encouraged to put (symlinks
191 to) perl and its accompanying utilities into a directory typically
192 found along a user's PATH, or in some other obvious and convenient
193 place.
194 In this documentation, "#!/usr/bin/perl" on the first line of the
196 program will stand in for whatever method works on your system. You
197 are advised to use a specific path if you care about a specific
198 version.
199 #!/usr/local/bin/perl5.00554
201 or if you just want to be running at least version, place a statement
203 like this at the top of your program:
204 use 5.005_54;
206 Command Switches
208 As with all standard commands, a single-character switch may be
209 clustered with the following switch, if any.
210 #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
212 Switches include:
214 -0[octal/hexadecimal]
216 specifies the input record separator ($/) as an octal or
217 hexadecimal number. If there are no digits, the null character is
218 the separator. Other switches may precede or follow the digits.
219 For example, if you have a version of find which can print
220 filenames terminated by the null character, you can say this:
221 find . -name '*.orig' -print0 | perl -n0e unlink
223 The special value 00 will cause Perl to slurp files in paragraph
225 mode. The value 0777 will cause Perl to slurp files whole because
226 there is no legal byte with that value.
227 If you want to specify any Unicode character, use the hexadecimal
229 format: "-0xHHH...", where the "H" are valid hexadecimal digits.
230 (This means that you cannot use the "-x" with a directory name
231 that consists of hexadecimal digits.)
232 -a turns on autosplit mode when used with a -n or -p. An implicit
234 split command to the @F array is done as the first thing inside
235 the implicit while loop produced by the -n or -p.
236 perl -ane 'print pop(@F), "\n";'
238 is equivalent to
240 while (<>) {
242 @F = split(' ');
243 print pop(@F), "\n";
244 }
245 An alternate delimiter may be specified using -F.
247 -C [number/list]
249 The "-C" flag controls some of the Perl Unicode features.
250 As of 5.8.1, the "-C" can be followed either by a number or a list
252 of option letters. The letters, their numeric values, and effects
253 are as follows; listing the letters is equal to summing the
254 numbers.
255 I 1 STDIN is assumed to be in UTF-8
257 O 2 STDOUT will be in UTF-8
258 E 4 STDERR will be in UTF-8
259 S 7 I + O + E
260 i 8 UTF-8 is the default PerlIO layer for input streams
261 o 16 UTF-8 is the default PerlIO layer for output streams
262 D 24 i + o
263 A 32 the @ARGV elements are expected to be strings encoded
264 in UTF-8
265 L 64 normally the "IOEioA" are unconditional,
266 the L makes them conditional on the locale environment
267 variables (the LC_ALL, LC_TYPE, and LANG, in the order
268 of decreasing precedence) -- if the variables indicate
269 UTF-8, then the selected "IOEioA" are in effect
270 a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching code in
271 debugging mode.
272 For example, "-COE" and "-C6" will both turn on UTF-8-ness on both
274 STDOUT and STDERR. Repeating letters is just redundant, not
275 cumulative nor toggling.
276 The "io" options mean that any subsequent open() (or similar I/O
278 operations) will have the ":utf8" PerlIO layer implicitly applied
279 to them, in other words, UTF-8 is expected from any input stream,
280 and UTF-8 is produced to any output stream. This is just the
281 default, with explicit layers in open() and with binmode() one can
282 manipulate streams as usual.
283 "-C" on its own (not followed by any number or option list), or
285 the empty string "" for the "PERL_UNICODE" environment variable,
286 has the same effect as "-CSDL". In other words, the standard I/O
287 handles and the default "open()" layer are UTF-8-fied but only if
288 the locale environment variables indicate a UTF-8 locale. This
289 behaviour follows the implicit (and problematic) UTF-8 behaviour
290 of Perl 5.8.0.
291 You can use "-C0" (or "0" for "PERL_UNICODE") to explicitly
293 disable all the above Unicode features.
294 The read-only magic variable "${^UNICODE}" reflects the numeric
296 value of this setting. This is variable is set during Perl
297 startup and is thereafter read-only. If you want runtime effects,
298 use the three-arg open() (see "open" in perlfunc), the two-arg
299 binmode() (see "binmode" in perlfunc), and the "open" pragma (see
300 open).
301 (In Perls earlier than 5.8.1 the "-C" switch was a Win32-only
303 switch that enabled the use of Unicode-aware "wide system call"
304 Win32 APIs. This feature was practically unused, however, and the
305 command line switch was therefore "recycled".)
306 Note: Since perl 5.10.1, if the -C option is used on the #! line,
308 it must be specified on the command line as well, since the
309 standard streams are already set up at this point in the execution
310 of the perl interpreter. You can also use binmode() to set the
311 encoding of an I/O stream.
312 -c causes Perl to check the syntax of the program and then exit
314 without executing it. Actually, it will execute "BEGIN",
315 "UNITCHECK", "CHECK", and "use" blocks, because these are
316 considered as occurring outside the execution of your program.
317 "INIT" and "END" blocks, however, will be skipped.
318 -d
320 -dt runs the program under the Perl debugger. See perldebug. If t is
321 specified, it indicates to the debugger that threads will be used
322 in the code being debugged.
323 -d:foo[=bar,baz]
325 -dt:foo[=bar,baz]
326 runs the program under the control of a debugging, profiling, or
327 tracing module installed as Devel::foo. E.g., -d:DProf executes
328 the program using the Devel::DProf profiler. As with the -M flag,
329 options may be passed to the Devel::foo package where they will be
330 received and interpreted by the Devel::foo::import routine. The
331 comma-separated list of options must follow a "=" character. If t
332 is specified, it indicates to the debugger that threads will be
333 used in the code being debugged. See perldebug.
334 -Dletters
336 -Dnumber
337 sets debugging flags. To watch how it executes your program, use
338 -Dtls. (This works only if debugging is compiled into your Perl.)
339 Another nice value is -Dx, which lists your compiled syntax tree.
340 And -Dr displays compiled regular expressions; the format of the
341 output is explained in perldebguts.
342 As an alternative, specify a number instead of list of letters
344 (e.g., -D14 is equivalent to -Dtls):
345 1 p Tokenizing and parsing (with v, displays parse stack)
347 2 s Stack snapshots (with v, displays all stacks)
348 4 l Context (loop) stack processing
349 8 t Trace execution
350 16 o Method and overloading resolution
351 32 c String/numeric conversions
352 64 P Print profiling info, preprocessor command for -P, source file input state
353 128 m Memory and SV allocation
354 256 f Format processing
355 512 r Regular expression parsing and execution
356 1024 x Syntax tree dump
357 2048 u Tainting checks
358 4096 U Unofficial, User hacking (reserved for private, unreleased use)
359 8192 H Hash dump -- usurps values()
360 16384 X Scratchpad allocation
361 32768 D Cleaning up
362 65536 S Thread synchronization
363 131072 T Tokenising
364 262144 R Include reference counts of dumped variables (eg when using -Ds)
365 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB
366 1048576 v Verbose: use in conjunction with other flags
367 2097152 C Copy On Write
368 4194304 A Consistency checks on internal structures
369 8388608 q quiet - currently only suppresses the "EXECUTING" message
370 All these flags require -DDEBUGGING when you compile the Perl
372 executable (but see Devel::Peek, re which may change this). See
373 the INSTALL file in the Perl source distribution for how to do
374 this. This flag is automatically set if you include -g option
375 when "Configure" asks you about optimizer/debugger flags.
376 If you're just trying to get a print out of each line of Perl code
378 as it executes, the way that "sh -x" provides for shell scripts,
379 you can't use Perl's -D switch. Instead do this
380 # If you have "env" utility
382 env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
383 # Bourne shell syntax
385 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
386 # csh syntax
388 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
389 See perldebug for details and variations.
391 -e commandline
393 may be used to enter one line of program. If -e is given, Perl
394 will not look for a filename in the argument list. Multiple -e
395 commands may be given to build up a multi-line script. Make sure
396 to use semicolons where you would in a normal program.
397 -E commandline
399 behaves just like -e, except that it implicitly enables all
400 optional features (in the main compilation unit). See feature.
401 -f Disable executing $Config{sitelib}/sitecustomize.pl at startup.
403 Perl can be built so that it by default will try to execute
405 $Config{sitelib}/sitecustomize.pl at startup (in a BEGIN block).
406 This is a hook that allows the sysadmin to customize how perl
407 behaves. It can for instance be used to add entries to the @INC
408 array to make perl find modules in non-standard locations.
409 -Fpattern
411 specifies the pattern to split on if -a is also in effect. The
412 pattern may be surrounded by "//", "", or '', otherwise it will be
413 put in single quotes. You can't use literal whitespace in the
414 pattern.
415 -h prints a summary of the options.
417 -i[extension]
419 specifies that files processed by the "<>" construct are to be
420 edited in-place. It does this by renaming the input file, opening
421 the output file by the original name, and selecting that output
422 file as the default for print() statements. The extension, if
423 supplied, is used to modify the name of the old file to make a
424 backup copy, following these rules:
425 If no extension is supplied, no backup is made and the current
427 file is overwritten.
428 If the extension doesn't contain a "*", then it is appended to the
430 end of the current filename as a suffix. If the extension does
431 contain one or more "*" characters, then each "*" is replaced with
432 the current filename. In Perl terms, you could think of this as:
433 ($backup = $extension) =~ s/\*/$file_name/g;
435 This allows you to add a prefix to the backup file, instead of (or
437 in addition to) a suffix:
438 $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
440 Or even to place backup copies of the original files into another
442 directory (provided the directory already exists):
443 $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
445 These sets of one-liners are equivalent:
447 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
449 $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
450 $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
452 $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
453 From the shell, saying
455 $ perl -p -i.orig -e "s/foo/bar/; ... "
457 is the same as using the program:
459 #!/usr/bin/perl -pi.orig
461 s/foo/bar/;
462 which is equivalent to
464 #!/usr/bin/perl
466 $extension = '.orig';
467 LINE: while (<>) {
468 if ($ARGV ne $oldargv) {
469 if ($extension !~ /\*/) {
470 $backup = $ARGV . $extension;
471 }
472 else {
473 ($backup = $extension) =~ s/\*/$ARGV/g;
474 }
475 rename($ARGV, $backup);
476 open(ARGVOUT, ">$ARGV");
477 select(ARGVOUT);
478 $oldargv = $ARGV;
479 }
480 s/foo/bar/;
481 }
482 continue {
483 print; # this prints to original filename
484 }
485 select(STDOUT);
486 except that the -i form doesn't need to compare $ARGV to $oldargv
488 to know when the filename has changed. It does, however, use
489 ARGVOUT for the selected filehandle. Note that STDOUT is restored
490 as the default output filehandle after the loop.
491 As shown above, Perl creates the backup file whether or not any
493 output is actually changed. So this is just a fancy way to copy
494 files:
495 $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
497 or
498 $ perl -p -i'.orig' -e 1 file1 file2 file3...
499 You can use "eof" without parentheses to locate the end of each
501 input file, in case you want to append to each file, or reset line
502 numbering (see example in "eof" in perlfunc).
503 If, for a given file, Perl is unable to create the backup file as
505 specified in the extension then it will skip that file and
506 continue on with the next one (if it exists).
507 For a discussion of issues surrounding file permissions and -i,
509 see "Why does Perl let me delete read-only files? Why does -i
510 clobber protected files? Isn't this a bug in Perl?" in perlfaq5.
511 You cannot use -i to create directories or to strip extensions
513 from files.
514 Perl does not expand "~" in filenames, which is good, since some
516 folks use it for their backup files:
517 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
519 Note that because -i renames or deletes the original file before
521 creating a new file of the same name, UNIX-style soft and hard
522 links will not be preserved.
523 Finally, the -i switch does not impede execution when no files are
525 given on the command line. In this case, no backup is made (the
526 original file cannot, of course, be determined) and processing
527 proceeds from STDIN to STDOUT as might be expected.
528 -Idirectory
530 Directories specified by -I are prepended to the search path for
531 modules (@INC), and also tells the C preprocessor where to search
532 for include files. The C preprocessor is invoked with -P; by
533 default it searches /usr/include and /usr/lib/perl.
534 -l[octnum]
536 enables automatic line-ending processing. It has two separate
537 effects. First, it automatically chomps $/ (the input record
538 separator) when used with -n or -p. Second, it assigns "$\" (the
539 output record separator) to have the value of octnum so that any
540 print statements will have that separator added back on. If
541 octnum is omitted, sets "$\" to the current value of $/. For
542 instance, to trim lines to 80 columns:
543 perl -lpe 'substr($_, 80) = ""'
545 Note that the assignment "$\ = $/" is done when the switch is
547 processed, so the input record separator can be different than the
548 output record separator if the -l switch is followed by a -0
549 switch:
550 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
552 This sets "$\" to newline and then sets $/ to the null character.
554 -m[-]module
556 -M[-]module
557 -M[-]'module ...'
558 -[mM][-]module=arg[,arg]...
559 -mmodule executes "use" module "();" before executing your
560 program.
561 -Mmodule executes "use" module ";" before executing your program.
563 You can use quotes to add extra code after the module name, e.g.,
564 '-Mmodule qw(foo bar)'.
565 If the first character after the -M or -m is a dash ("-") then the
567 'use' is replaced with 'no'.
568 A little builtin syntactic sugar means you can also say
570 -mmodule=foo,bar or -Mmodule=foo,bar as a shortcut for '-Mmodule
571 qw(foo bar)'. This avoids the need to use quotes when importing
572 symbols. The actual code generated by -Mmodule=foo,bar is "use
573 module split(/,/,q{foo,bar})". Note that the "=" form removes the
574 distinction between -m and -M.
575 A consequence of this is that -MFoo=number never does a version
577 check (unless "Foo::import()" itself is set up to do a version
578 check, which could happen for example if Foo inherits from
579 Exporter.)
580 -n causes Perl to assume the following loop around your program,
582 which makes it iterate over filename arguments somewhat like sed
583 -n or awk:
584 LINE:
586 while (<>) {
587 ... # your program goes here
588 }
589 Note that the lines are not printed by default. See -p to have
591 lines printed. If a file named by an argument cannot be opened
592 for some reason, Perl warns you about it and moves on to the next
593 file.
594 Also note that "<>" passes command line arguments to "open" in
596 perlfunc, which doesn't necessarily interpret them as file names.
597 See perlop for possible security implications.
598 Here is an efficient way to delete all files that haven't been
600 modified for at least a week:
601 find . -mtime +7 -print | perl -nle unlink
603 This is faster than using the -exec switch of find because you
605 don't have to start a process on every filename found. It does
606 suffer from the bug of mishandling newlines in pathnames, which
607 you can fix if you follow the example under -0.
608 "BEGIN" and "END" blocks may be used to capture control before or
610 after the implicit program loop, just as in awk.
611 -p causes Perl to assume the following loop around your program,
613 which makes it iterate over filename arguments somewhat like sed:
614 LINE:
616 while (<>) {
617 ... # your program goes here
618 } continue {
619 print or die "-p destination: $!\n";
620 }
621 If a file named by an argument cannot be opened for some reason,
623 Perl warns you about it, and moves on to the next file. Note that
624 the lines are printed automatically. An error occurring during
625 printing is treated as fatal. To suppress printing use the -n
626 switch. A -p overrides a -n switch.
627 "BEGIN" and "END" blocks may be used to capture control before or
629 after the implicit loop, just as in awk.
630 -P NOTE: Use of -P is strongly discouraged because of its inherent
632 problems, including poor portability. It is deprecated and will be
633 removed in a future version of Perl.
634 This option causes your program to be run through the C
636 preprocessor before compilation by Perl. Because both comments
637 and cpp directives begin with the # character, you should avoid
638 starting comments with any words recognized by the C preprocessor
639 such as "if", "else", or "define".
640 If you're considering using "-P", you might also want to look at
642 the Filter::cpp module from CPAN.
643 The problems of -P include, but are not limited to:
645 · The "#!" line is stripped, so any switches there don't
647 apply.
648 · A "-P" on a "#!" line doesn't work.
650 · All lines that begin with (whitespace and) a "#" but do
652 not look like cpp commands, are stripped, including
653 anything inside Perl strings, regular expressions, and
654 here-docs .
655 · In some platforms the C preprocessor knows too much: it
657 knows about the C++ -style until-end-of-line comments
658 starting with "//". This will cause problems with
659 common Perl constructs like
660 s/foo//;
662 because after -P this will became illegal code
664 s/foo
666 The workaround is to use some other quoting separator
668 than "/", like for example "!":
669 s!foo!!;
671 · It requires not only a working C preprocessor but also a
673 working sed. If not on UNIX, you are probably out of
674 luck on this.
675 · Script line numbers are not preserved.
677 · The "-x" does not work with "-P".
679 -s enables rudimentary switch parsing for switches on the command
681 line after the program name but before any filename arguments (or
682 before an argument of --). Any switch found there is removed from
683 @ARGV and sets the corresponding variable in the Perl program.
684 The following program prints "1" if the program is invoked with a
685 -xyz switch, and "abc" if it is invoked with -xyz=abc.
686 #!/usr/bin/perl -s
688 if ($xyz) { print "$xyz\n" }
689 Do note that a switch like --help creates the variable ${-help},
691 which is not compliant with "strict refs". Also, when using this
692 option on a script with warnings enabled you may get a lot of
693 spurious "used only once" warnings.
694 -S makes Perl use the PATH environment variable to search for the
696 program (unless the name of the program contains directory
697 separators).
698 On some platforms, this also makes Perl append suffixes to the
700 filename while searching for it. For example, on Win32 platforms,
701 the ".bat" and ".cmd" suffixes are appended if a lookup for the
702 original name fails, and if the name does not already end in one
703 of those suffixes. If your Perl was compiled with DEBUGGING
704 turned on, using the -Dp switch to Perl shows how the search
705 progresses.
706 Typically this is used to emulate #! startup on platforms that
708 don't support #!. Its also convenient when debugging a script
709 that uses #!, and is thus normally found by the shell's $PATH
710 search mechanism.
711 This example works on many platforms that have a shell compatible
713 with Bourne shell:
714 #!/usr/bin/perl
716 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
717 if $running_under_some_shell;
718 The system ignores the first line and feeds the program to
720 /bin/sh, which proceeds to try to execute the Perl program as a
721 shell script. The shell executes the second line as a normal
722 shell command, and thus starts up the Perl interpreter. On some
723 systems $0 doesn't always contain the full pathname, so the -S
724 tells Perl to search for the program if necessary. After Perl
725 locates the program, it parses the lines and ignores them because
726 the variable $running_under_some_shell is never true. If the
727 program will be interpreted by csh, you will need to replace
728 "${1+"$@"}" with $*, even though that doesn't understand embedded
729 spaces (and such) in the argument list. To start up sh rather
730 than csh, some systems may have to replace the #! line with a line
731 containing just a colon, which will be politely ignored by Perl.
732 Other systems can't control that, and need a totally devious
733 construct that will work under any of csh, sh, or Perl, such as
734 the following:
735 eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
737 & eval 'exec /usr/bin/perl -wS $0 $argv:q'
738 if $running_under_some_shell;
739 If the filename supplied contains directory separators (i.e., is
741 an absolute or relative pathname), and if that file is not found,
742 platforms that append file extensions will do so and try to look
743 for the file with those extensions added, one by one.
744 On DOS-like platforms, if the program does not contain directory
746 separators, it will first be searched for in the current directory
747 before being searched for on the PATH. On Unix platforms, the
748 program will be searched for strictly on the PATH.
749 -t Like -T, but taint checks will issue warnings rather than fatal
751 errors. These warnings can be controlled normally with "no
752 warnings qw(taint)".
753 NOTE: this is not a substitute for -T. This is meant only to be
755 used as a temporary development aid while securing legacy code:
756 for real production code and for new secure code written from
757 scratch always use the real -T.
758 -T forces "taint" checks to be turned on so you can test them.
760 Ordinarily these checks are done only when running setuid or
761 setgid. It's a good idea to turn them on explicitly for programs
762 that run on behalf of someone else whom you might not necessarily
763 trust, such as CGI programs or any internet servers you might
764 write in Perl. See perlsec for details. For security reasons,
765 this option must be seen by Perl quite early; usually this means
766 it must appear early on the command line or in the #! line for
767 systems which support that construct.
768 -u This obsolete switch causes Perl to dump core after compiling your
770 program. You can then in theory take this core dump and turn it
771 into an executable file by using the undump program (not
772 supplied). This speeds startup at the expense of some disk space
773 (which you can minimize by stripping the executable). (Still, a
774 "hello world" executable comes out to about 200K on my machine.)
775 If you want to execute a portion of your program before dumping,
776 use the dump() operator instead. Note: availability of undump is
777 platform specific and may not be available for a specific port of
778 Perl.
779 -U allows Perl to do unsafe operations. Currently the only "unsafe"
781 operations are attempting to unlink directories while running as
782 superuser, and running setuid programs with fatal taint checks
783 turned into warnings. Note that the -w switch (or the $^W
784 variable) must be used along with this option to actually generate
785 the taint-check warnings.
786 -v prints the version and patchlevel of your perl executable.
788 -V prints summary of the major perl configuration values and the
790 current values of @INC.
791 -V:configvar
793 Prints to STDOUT the value of the named configuration variable(s),
794 with multiples when your configvar argument looks like a regex
795 (has non-letters). For example:
796 $ perl -V:libc
798 libc='/lib/libc-2.2.4.so';
799 $ perl -V:lib.
800 libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
801 libc='/lib/libc-2.2.4.so';
802 $ perl -V:lib.*
803 libpth='/usr/local/lib /lib /usr/lib';
804 libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
805 lib_ext='.a';
806 libc='/lib/libc-2.2.4.so';
807 libperl='libperl.a';
808 ....
809 Additionally, extra colons can be used to control formatting. A
811 trailing colon suppresses the linefeed and terminator ';',
812 allowing you to embed queries into shell commands. (mnemonic:
813 PATH separator ':'.)
814 $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
816 compression-vars: zcat='' zip='zip' are here !
817 A leading colon removes the 'name=' part of the response, this
819 allows you to map to the name you need. (mnemonic: empty label)
820 $ echo "goodvfork="`./perl -Ilib -V::usevfork`
822 goodvfork=false;
823 Leading and trailing colons can be used together if you need
825 positional parameter values without the names. Note that in the
826 case below, the PERL_API params are returned in alphabetical
827 order.
828 $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
830 building_on 'linux' '5' '1' '9' now
831 -w prints warnings about dubious constructs, such as variable names
833 that are mentioned only once and scalar variables that are used
834 before being set, redefined subroutines, references to undefined
835 filehandles or filehandles opened read-only that you are
836 attempting to write on, values used as a number that don't look
837 like numbers, using an array as though it were a scalar, if your
838 subroutines recurse more than 100 deep, and innumerable other
839 things.
840 This switch really just enables the internal $^W variable. You
842 can disable or promote into fatal errors specific warnings using
843 "__WARN__" hooks, as described in perlvar and "warn" in perlfunc.
844 See also perldiag and perltrap. A new, fine-grained warning
845 facility is also available if you want to manipulate entire
846 classes of warnings; see warnings or perllexwarn.
847 -W Enables all warnings regardless of "no warnings" or $^W. See
849 perllexwarn.
850 -X Disables all warnings regardless of "use warnings" or $^W. See
852 perllexwarn.
853 -x
855 -xdirectory
856 tells Perl that the program is embedded in a larger chunk of
857 unrelated ASCII text, such as in a mail message. Leading garbage
858 will be discarded until the first line that starts with #! and
859 contains the string "perl". Any meaningful switches on that line
860 will be applied.
861 All references to line numbers by the program (warnings, errors,
863 ...) will treat the #! line as the first line. Thus a warning on
864 the 2nd line of the program (which is on the 100th line in the
865 file) will be reported as line 2, and not as line 100. This can
866 be overridden by using the #line directive. (See
867 "Plain-Old-Comments-(Not!)" in perlsyn)
868 If a directory name is specified, Perl will switch to that
870 directory before running the program. The -x switch controls only
871 the disposal of leading garbage. The program must be terminated
872 with "__END__" if there is trailing garbage to be ignored (the
873 program can process any or all of the trailing garbage via the
874 DATA filehandle if desired).
875 The directory, if specified, must appear immediately following the
877 -x with no intervening whitespace.
878
880 HOME Used if chdir has no argument.
881 LOGDIR Used if chdir has no argument and HOME is not set.
883 PATH Used in executing subprocesses, and in finding the program
885 if -S is used.
886 PERL5LIB A list of directories in which to look for Perl library
888 files before looking in the standard library and the
889 current directory. Any architecture-specific directories
890 under the specified locations are automatically included if
891 they exist (this lookup being done at interpreter startup
892 time.)
893 If PERL5LIB is not defined, PERLLIB is used. Directories
895 are separated (like in PATH) by a colon on unixish
896 platforms and by a semicolon on Windows (the proper path
897 separator being given by the command "perl -V:path_sep").
898 When running taint checks (either because the program was
900 running setuid or setgid, or the -T or -t switch was
901 specified), neither variable is used. The program should
902 instead say:
903 use lib "/my/directory";
905 PERL5OPT Command-line options (switches). Switches in this variable
907 are taken as if they were on every Perl command line. Only
908 the -[CDIMUdmtw] switches are allowed. When running taint
909 checks (because the program was running setuid or setgid,
910 or the -T switch was used), this variable is ignored. If
911 PERL5OPT begins with -T, tainting will be enabled, and any
912 subsequent options ignored.
913 PERLIO A space (or colon) separated list of PerlIO layers. If perl
915 is built to use PerlIO system for IO (the default) these
916 layers effect perl's IO.
917 It is conventional to start layer names with a colon e.g.
919 ":perlio" to emphasise their similarity to variable
920 "attributes". But the code that parses layer specification
921 strings (which is also used to decode the PERLIO
922 environment variable) treats the colon as a separator.
923 An unset or empty PERLIO is equivalent to the default set
925 of layers for your platform, for example ":unix:perlio" on
926 UNIX-like systems and ":unix:crlf" on Windows and other
927 DOS-like systems.
928 The list becomes the default for all perl's IO.
930 Consequently only built-in layers can appear in this list,
931 as external layers (such as :encoding()) need IO in order
932 to load them!. See "open pragma" for how to add external
933 encodings as defaults.
934 The layers that it makes sense to include in the PERLIO
936 environment variable are briefly summarised below. For more
937 details see PerlIO.
938 :bytes A pseudolayer that turns off the ":utf8" flag for
940 the layer below. Unlikely to be useful on its own
941 in the global PERLIO environment variable. You
942 perhaps were thinking of ":crlf:bytes" or
943 ":perlio:bytes".
944 :crlf A layer which does CRLF to "\n" translation
946 distinguishing "text" and "binary" files in the
947 manner of MS-DOS and similar operating systems.
948 (It currently does not mimic MS-DOS as far as
949 treating of Control-Z as being an end-of-file
950 marker.)
951 :mmap A layer which implements "reading" of files by
953 using "mmap()" to make (whole) file appear in the
954 process's address space, and then using that as
955 PerlIO's "buffer".
956 :perlio This is a re-implementation of "stdio-like"
958 buffering written as a PerlIO "layer". As such it
959 will call whatever layer is below it for its
960 operations (typically ":unix").
961 :pop An experimental pseudolayer that removes the
963 topmost layer. Use with the same care as is
964 reserved for nitroglycerin.
965 :raw A pseudolayer that manipulates other layers.
967 Applying the ":raw" layer is equivalent to calling
968 "binmode($fh)". It makes the stream pass each byte
969 as-is without any translation. In particular CRLF
970 translation, and/or :utf8 intuited from locale are
971 disabled.
972 Unlike in the earlier versions of Perl ":raw" is
974 not just the inverse of ":crlf" - other layers
975 which would affect the binary nature of the stream
976 are also removed or disabled.
977 :stdio This layer provides PerlIO interface by wrapping
979 system's ANSI C "stdio" library calls. The layer
980 provides both buffering and IO. Note that ":stdio"
981 layer does not do CRLF translation even if that is
982 platforms normal behaviour. You will need a ":crlf"
983 layer above it to do that.
984 :unix Low level layer which calls "read", "write" and
986 "lseek" etc.
987 :utf8 A pseudolayer that turns on a flag on the layer
989 below to tell perl that output should be in utf8
990 and that input should be regarded as already in
991 valid utf8 form. It does not check for validity and
992 as such should be handled with caution for input.
993 Generally ":encoding(utf8)" is the best option when
994 reading UTF-8 encoded data.
995 :win32 On Win32 platforms this experimental layer uses
997 native "handle" IO rather than unix-like numeric
998 file descriptor layer. Known to be buggy in this
999 release.
1000 On all platforms the default set of layers should give
1002 acceptable results.
1003 For UNIX platforms that will equivalent of "unix perlio" or
1005 "stdio". Configure is setup to prefer "stdio"
1006 implementation if system's library provides for fast access
1007 to the buffer, otherwise it uses the "unix perlio"
1008 implementation.
1009 On Win32 the default in this release is "unix crlf".
1011 Win32's "stdio" has a number of bugs/mis-features for perl
1012 IO which are somewhat C compiler vendor/version dependent.
1013 Using our own "crlf" layer as the buffer avoids those
1014 issues and makes things more uniform. The "crlf" layer
1015 provides CRLF to/from "\n" conversion as well as buffering.
1016 This release uses "unix" as the bottom layer on Win32 and
1018 so still uses C compiler's numeric file descriptor
1019 routines. There is an experimental native "win32" layer
1020 which is expected to be enhanced and should eventually be
1021 the default under Win32.
1022 The PERLIO environment variable is completely ignored when
1024 perl is run in taint mode.
1025 PERLIO_DEBUG
1027 If set to the name of a file or device then certain
1028 operations of PerlIO sub-system will be logged to that file
1029 (opened as append). Typical uses are UNIX:
1030 PERLIO_DEBUG=/dev/tty perl script ...
1032 and Win32 approximate equivalent:
1034 set PERLIO_DEBUG=CON
1036 perl script ...
1037 This functionality is disabled for setuid scripts and for
1039 scripts run with -T.
1040 PERLLIB A list of directories in which to look for Perl library
1042 files before looking in the standard library and the
1043 current directory. If PERL5LIB is defined, PERLLIB is not
1044 used.
1045 The PERLLIB environment variable is completely ignored when
1047 perl is run in taint mode.
1048 PERL5DB The command used to load the debugger code. The default
1050 is:
1051 BEGIN { require 'perl5db.pl' }
1053 The PERL5DB environment variable only used when perl is
1055 started with a bare -d switch.
1056 PERL5DB_THREADED
1058 If set to a true value, indicates to the debugger that the
1059 code being debugged uses threads.
1060 PERL5SHELL (specific to the Win32 port)
1062 May be set to an alternative shell that perl must use
1063 internally for executing "backtick" commands or system().
1064 Default is "cmd.exe /x/d/c" on WindowsNT and "command.com
1065 /c" on Windows95. The value is considered to be space-
1066 separated. Precede any character that needs to be
1067 protected (like a space or backslash) with a backslash.
1068 Note that Perl doesn't use COMSPEC for this purpose because
1070 COMSPEC has a high degree of variability among users,
1071 leading to portability concerns. Besides, perl can use a
1072 shell that may not be fit for interactive use, and setting
1073 COMSPEC to such a shell may interfere with the proper
1074 functioning of other programs (which usually look in
1075 COMSPEC to find a shell fit for interactive use).
1076 Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint
1078 checked when running external commands. It is recommended
1079 that you explicitly set (or delete) $ENV{PERL5SHELL} when
1080 running in taint mode under Windows.
1081 PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
1083 Set to 1 to allow the use of non-IFS compatible LSP's.
1084 Perl normally searches for an IFS-compatible LSP because
1085 this is required for its emulation of Windows sockets as
1086 real filehandles. However, this may cause problems if you
1087 have a firewall such as McAfee Guardian which requires all
1088 applications to use its LSP which is not IFS-compatible,
1089 because clearly Perl will normally avoid using such an LSP.
1090 Setting this environment variable to 1 means that Perl will
1091 simply use the first suitable LSP enumerated in the
1092 catalog, which keeps McAfee Guardian happy (and in that
1093 particular case Perl still works too because McAfee
1094 Guardian's LSP actually plays some other games which allow
1095 applications requiring IFS compatibility to work).
1096 PERL_DEBUG_MSTATS
1098 Relevant only if perl is compiled with the malloc included
1099 with the perl distribution (that is, if "perl
1100 -V:d_mymalloc" is 'define'). If set, this causes memory
1101 statistics to be dumped after execution. If set to an
1102 integer greater than one, also causes memory statistics to
1103 be dumped after compilation.
1104 PERL_DESTRUCT_LEVEL
1106 Relevant only if your perl executable was built with
1107 -DDEBUGGING, this controls the behavior of global
1108 destruction of objects and other references. See
1109 "PERL_DESTRUCT_LEVEL" in perlhack for more information.
1110 PERL_DL_NONLAZY
1112 Set to one to have perl resolve all undefined symbols when
1113 it loads a dynamic library. The default behaviour is to
1114 resolve symbols when they are used. Setting this variable
1115 is useful during testing of extensions as it ensures that
1116 you get an error on misspelled function names even if the
1117 test suite doesn't call it.
1118 PERL_ENCODING
1120 If using the "encoding" pragma without an explicit encoding
1121 name, the PERL_ENCODING environment variable is consulted
1122 for an encoding name.
1123 PERL_HASH_SEED
1125 (Since Perl 5.8.1.) Used to randomise perl's internal hash
1126 function. To emulate the pre-5.8.1 behaviour, set to an
1127 integer (zero means exactly the same order as 5.8.0).
1128 "Pre-5.8.1" means, among other things, that hash keys will
1129 always have the same ordering between different runs of
1130 perl.
1131 Most hashes return elements in the same order as Perl 5.8.0
1133 by default. On a hash by hash basis, if pathological data
1134 is detected during a hash key insertion, then that hash
1135 will switch to an alternative random hash seed.
1136 The default behaviour is to randomise unless the
1138 PERL_HASH_SEED is set. If perl has been compiled with
1139 "-DUSE_HASH_SEED_EXPLICIT", the default behaviour is not to
1140 randomise unless the PERL_HASH_SEED is set.
1141 If PERL_HASH_SEED is unset or set to a non-numeric string,
1143 perl uses the pseudorandom seed supplied by the operating
1144 system and libraries.
1145 Please note that the hash seed is sensitive information.
1147 Hashes are randomized to protect against local and remote
1148 attacks against Perl code. By manually setting a seed this
1149 protection may be partially or completely lost.
1150 See "Algorithmic Complexity Attacks" in perlsec and
1152 "PERL_HASH_SEED_DEBUG" for more information.
1153 PERL_HASH_SEED_DEBUG
1155 (Since Perl 5.8.1.) Set to one to display (to STDERR) the
1156 value of the hash seed at the beginning of execution.
1157 This, combined with "PERL_HASH_SEED" is intended to aid in
1158 debugging nondeterministic behavior caused by hash
1159 randomization.
1160 Note that the hash seed is sensitive information: by
1162 knowing it one can craft a denial-of-service attack against
1163 Perl code, even remotely, see "Algorithmic Complexity
1164 Attacks" in perlsec for more information. Do not disclose
1165 the hash seed to people who don't need to know it. See
1166 also hash_seed() of Hash::Util.
1167 PERL_ROOT (specific to the VMS port)
1169 A translation concealed rooted logical name that contains
1170 perl and the logical device for the @INC path on VMS only.
1171 Other logical names that affect perl on VMS include
1172 PERLSHR, PERL_ENV_TABLES, and SYS$TIMEZONE_DIFFERENTIAL but
1173 are optional and discussed further in perlvms and in
1174 README.vms in the Perl source distribution.
1175 PERL_SIGNALS
1177 In Perls 5.8.1 and later. If set to "unsafe" the
1178 pre-Perl-5.8.0 signals behaviour (immediate but unsafe) is
1179 restored. If set to "safe" the safe (or deferred) signals
1180 are used. See "Deferred Signals (Safe Signals)" in
1181 perlipc.
1182 PERL_UNICODE
1184 Equivalent to the -C command-line switch. Note that this
1185 is not a boolean variable-- setting this to "1" is not the
1186 right way to "enable Unicode" (whatever that would mean).
1187 You can use "0" to "disable Unicode", though (or
1188 alternatively unset PERL_UNICODE in your shell before
1189 starting Perl). See the description of the "-C" switch for
1190 more information.
1191 SYS$LOGIN (specific to the VMS port)
1193 Used if chdir has no argument and HOME and LOGDIR are not
1194 set.
1195 Perl also has environment variables that control how Perl handles data
1197 specific to particular natural languages. See perllocale.
1198 Apart from these, Perl uses no other environment variables, except to
1200 make them available to the program being executed, and to child
1201 processes. However, programs running setuid would do well to execute
1202 the following lines before doing anything else, just to keep people
1203 honest:
1204 $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need
1206 $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
1207 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
1208perl v5.10.1 2009-07-26 PERLRUN(1)