Penguin
Recent Changes
Annotated edit history of perlrun(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLRUN
2 !!!PERLRUN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 ENVIRONMENT
7 ----
8 !!NAME
9
10
11 perlrun - how to execute the Perl interpreter
12 !!SYNOPSIS
13
14
15 __perl__ [[ __-CsTuUWX__ ] [[ __-hv__ ] [[
16 __-V__[[:''configvar''] ] [[ __-cw__ ] [[
17 __-d__[[:''debugger''] ] [[
18 __-D__[[''number/list''] ] [[ __-pna__ ] [[
19 __-F__''pattern'' ] [[ __-l__[[''octal''] ] [[
20 __-0__[[''octal''] ] [[ __-I__''dir'' ] [[
21 __-m__[[__-__]''module'' ] [[
22 __-M__[[__-__]'''module...''' ] [[ __-P__ ] [[
23 __-S__ ] [[ __-x__[[''dir''] ] [[
24 __-i__[[''extension''] ] [[ __-e__ '''command''' ]
25 [[ __--__ ] [[ ''programfile'' ] [[ ''argument''
26 ]...
27 !!DESCRIPTION
28
29
30 The normal way to run a Perl program is by making it
31 directly executable, or else by passing the name of the
32 source file as an argument on the command line. (An
33 interactive Perl environment is also possible--see perldebug
34 for details on how to do that.) Upon startup, Perl looks for
35 your program in one of the following places:
36
37
38 1.
39
40
41 Specified line by line via __-e__ switches on the command
42 line.
43
44
45 2.
46
47
48 Contained in the file specified by the first filename on the
49 command line. (Note that systems supporting the #! notation
50 invoke interpreters this way. See ``Location of
51 Perl''.)
52
53
54 3.
55
56
57 Passed in implicitly via standard input. This works only if
58 there are no filename arguments--to pass arguments to a
59 STDIN-read program you must explicitly specify a ``-'' for
60 the program name.
61
62
63 With methods 2 and 3, Perl starts parsing the input file
64 from the beginning, unless you've specified a __-x__
65 switch, in which case it scans for the first line starting
66 with #! and containing the word ``perl'', and starts there
67 instead. This is useful for running a program embedded in a
68 larger message. (In this case you would indicate the end of
69 the program using the __END__ token.)
70
71
72 The #! line is always examined for switches as the line is
73 being parsed. Thus, if you're on a machine that allows only
74 one argument with the #! line, or worse, doesn't even
75 recognize the #! line, you still can get consistent switch
76 behavior regardless of how Perl was invoked, even if
77 __-x__ was used to find the beginning of the
78 program.
79
80
81 Because historically some operating systems silently chopped
82 off kernel interpretation of the #! line after 32
83 characters, some switches may be passed in on the command
84 line, and some may not; you could even get a ``-'' without
85 its letter, if you're not careful. You probably want to make
86 sure that all your switches fall either before or after that
87 32-character boundary. Most switches don't actually care if
88 they're processed redundantly, but getting a ``-'' instead
89 of a complete switch could cause Perl to try to execute
90 standard input instead of your program. And a partial
91 __-I__ switch could also cause odd results.
92
93
94 Some switches do care if they are processed twice, for
95 instance combinations of __-l__ and __-0__. Either put
96 all the switches after the 32-character boundary (if
97 applicable), or replace the use of __-0__''digits'' by
98 BEGIN{ $/ = .
99
100
101 Parsing of the #! switches starts wherever ``perl'' is
102 mentioned in the line. The sequences ``-*'' and ``- '' are
103 specifically ignored so that you could, if you were so
104 inclined, say
105
106
107 #!/bin/sh -- # -*- perl -*- -p
108 eval 'exec perl -wS $0 ${1+
109 to let Perl see the __-p__ switch.
110
111
112 A similar trick involves the __env__ program, if you have
113 it.
114
115
116 #!/usr/bin/env perl
117 The examples above use a relative path to the perl interpreter, getting whatever version is first in the user's path. If you want a specific version of Perl, say, perl5.005_57, you should place that directly in the #! line's path.
118
119
120 If the #! line does not contain the word ``perl'', the
121 program named after the #! is executed instead of the Perl
122 interpreter. This is slightly bizarre, but it helps people
123 on machines that don't do #!, because they can tell a
124 program that their SHELL is
125 ''/usr/bin/perl'', and Perl will then dispatch the
126 program to the correct interpreter for them.
127
128
129 After locating your program, Perl compiles the entire
130 program to an internal form. If there are any compilation
131 errors, execution of the program is not attempted. (This is
132 unlike the typical shell script, which might run part-way
133 through before finding a syntax error.)
134
135
136 If the program is syntactically correct, it is executed. If
137 the program runs off the end without hitting an
138 ''exit()'' or ''die()'' operator, an implicit
139 exit(0) is provided to indicate successful
140 completion.
141
142
143 __#! and quoting on non-Unix systems__
144
145
146 Unix's #! technique can be simulated on other
147 systems:
148
149
150 OS/2
151
152
153 Put
154
155
156 extproc perl -S -your_switches
157 as the first line in *.cmd file (__-S__ due to a bug in cmd.exe's `extproc' handling).
158
159
160 MS-DOS
161
162
163 Create a batch file to run your program, and codify it in
164 ALTERNATIVE_SHEBANG (see the ''dosish.h'' file
165 in the source distribution for more
166 information).
167
168
169 Win95/NT
170
171
2 perry 172 The Win95/NT installation, when using the !ActiveState
1 perry 173 installer for Perl, will modify the Registry to associate
174 the ''.pl'' extension with the perl interpreter. If you
175 install Perl by other means (including building from the
176 sources), you may have to modify the Registry yourself. Note
177 that this means you can no longer tell the difference
178 between an executable Perl program and a Perl library
179 file.
180
181
182 Macintosh
183
184
185 A Macintosh perl program will have the appropriate Creator
186 and Type, so that double-clicking them will invoke the perl
187 application.
188
189
190 VMS
191
192
193 Put
194
195
196 $ perl -mysw 'f$env(
197 at the top of your program, where __-mysw__ are any command line switches you want to pass to Perl. You can now invoke the program directly, by saying perl program, or as a DCL procedure, by saying @program (or implicitly via ''DCL$PATH'' by just using the name of the program).
198
199
200 This incantation is a bit much to remember, but Perl will
201 display it for you if you say perl
202 .
203
204
205 Command-interpreters on non-Unix systems have rather
206 different ideas on quoting than Unix shells. You'll need to
207 learn the special characters in your command-interpreter
208 (*, \ and are common) and
209 how to protect whitespace and these characters to run
210 one-liners (see __-e__ below).
211
212
213 On some systems, you may have to change single-quotes to
214 double ones, which you must ''not'' do on Unix or Plan9
215 systems. You might also have to change a single % to a
216 %%.
217
218
219 For example:
220
221
222 # Unix
223 perl -e 'print
224 # MS-DOS, etc.
225 perl -e
226 # Macintosh
227 print
228 # VMS
229 perl -e
230 The problem is that none of this is reliable: it depends on the command and it is entirely possible neither works. If __4DOS__ were the command shell, this would probably work better:
231
232
233 perl -e
234 __CMD .EXE__ in Windows NT slipped a lot of standard Unix functionality in when nobody was looking, but just try to find documentation for its quoting rules.
235
236
237 Under the Macintosh, it depends which environment you are
2 perry 238 using. The !MacPerl shell, or MPW , is much
1 perry 239 like Unix shells in its support for several quoting
240 variants, except that it makes free use of the Macintosh's
241 non-ASCII characters as control characters.
242
243
244 There is no general solution to all of this. It's just a
245 mess.
246
247
248 __Location of Perl__
249
250
251 It may seem obvious to say, but Perl is useful only when
252 users can easily find it. When possible, it's good for both
253 ''/usr/bin/perl'' and ''/usr/local/bin/perl'' to be
254 symlinks to the actual binary. If that can't be done, system
255 administrators are strongly encouraged to put (symlinks to)
256 perl and its accompanying utilities into a directory
257 typically found along a user's PATH , or in
258 some other obvious and convenient place.
259
260
261 In this documentation, #!/usr/bin/perl on the first
262 line of the program will stand in for whatever method works
263 on your system. You are advised to use a specific path if
264 you care about a specific version.
265
266
267 #!/usr/local/bin/perl5.00554
268 or if you just want to be running at least version, place a statement like this at the top of your program:
269
270
271 use 5.005_54;
272
273
274 __Command Switches__
275
276
277 As with all standard commands, a single-character switch may
278 be clustered with the following switch, if any.
279
280
281 #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
282 Switches include:
283
284
285 __-0__[[''digits'']
286
287
288 specifies the input record separator ($/) as an
289 octal number. If there are no digits, the null character is
290 the separator. Other switches may precede or follow the
291 digits. For example, if you have a version of __find__
292 which can print filenames terminated by the null character,
293 you can say this:
294
295
296 find . -name '*.orig' -print0 perl -n0e unlink
297 The special value 00 will cause Perl to slurp files in paragraph mode. The value 0777 will cause Perl to slurp files whole because there is no legal character with that value.
298
299
300 __-a__
301
302
303 turns on autosplit mode when used with a __-n__ or
304 __-p__. An implicit split command to the @F
305 array is done as the first thing inside the implicit while
306 loop produced by the __-n__ or __-p__.
307
308
309 perl -ane 'print pop(@F),
310 is equivalent to
311
312
313 while (
314 An alternate delimiter may be specified using __-F__.
315
316
317 __-C__
318
319
320 enables Perl to use the native wide character APIs on the
321 target system. The magic variable
322 ${^WIDE_SYSTEM_CALLS} reflects the state of this
323 switch. See ``${^WIDE_SYSTEM_CALLS}'' in
324 perlvar.
325
326
327 This feature is currently only implemented on the Win32
328 platform.
329
330
331 __-c__
332
333
334 causes Perl to check the syntax of the program and then exit
335 without executing it. Actually, it ''will'' execute
336 BEGIN, CHECK, and use blocks,
337 because these are considered as occurring outside the
338 execution of your program. INIT and END
339 blocks, however, will be skipped.
340
341
342 __-d__
343
344
345 runs the program under the Perl debugger. See
346 perldebug.
347
348
349 __-d:__''foo[[=bar,baz]''
350
351
352 runs the program under the control of a debugging,
353 profiling, or tracing module installed as Devel::foo. E.g.,
354 __-d:DProf__ executes the program using the Devel::DProf
355 profiler. As with the __-M__ flag, options may be passed
356 to the Devel::foo package where they will be received and
357 interpreted by the Devel::foo::import routine. The
358 comma-separated list of options must follow a =
359 character. See perldebug.
360
361
362 __-D__''letters''
363
364
365 __-D__''number''
366
367
368 sets debugging flags. To watch how it executes your program,
369 use __-Dtls__. (This works only if debugging is compiled
370 into your Perl.) Another nice value is __-Dx__, which
371 lists your compiled syntax tree. And __-Dr__ displays
372 compiled regular expressions. As an alternative, specify a
373 number instead of list of letters (e.g., __-D14__ is
374 equivalent to __-Dtls__):
375
376
377 1 p Tokenizing and parsing
378 2 s Stack snapshots
379 4 l Context (loop) stack processing
380 8 t Trace execution
381 16 o Method and overloading resolution
382 32 c String/numeric conversions
383 64 P Print preprocessor command for -P, source file input state
384 128 m Memory allocation
385 256 f Format processing
386 512 r Regular expression parsing and execution
387 1024 x Syntax tree dump
388 2048 u Tainting checks
389 4096 L Memory leaks (needs -DLEAKTEST when compiling Perl)
390 8192 H Hash dump -- usurps values()
391 16384 X Scratchpad allocation
392 32768 D Cleaning up
393 65536 S Thread synchronization
394 131072 T Tokenising
395 All these flags require __-DDEBUGGING__ when you compile the Perl executable. See the ''INSTALL'' file in the Perl source distribution for how to do this. This flag is automatically set if you include __-g__ option when Configure asks you about optimizer/debugger flags.
396
397
398 If you're just trying to get a print out of each line of
399 Perl code as it executes, the way that sh -x
400 provides for shell scripts, you can't use Perl's __-D__
401 switch. Instead do this
402
403
404 # Bourne shell syntax
405 $ PERLDB_OPTS=
406 # csh syntax
407 % (setenv PERLDB_OPTS
408 See perldebug for details and variations.
409
410
411 __-e__ ''commandline''
412
413
414 may be used to enter one line of program. If __-e__ is
415 given, Perl will not look for a filename in the argument
416 list. Multiple __-e__ commands may be given to build up a
417 multi-line script. Make sure to use semicolons where you
418 would in a normal program.
419
420
421 __-F__''pattern''
422
423
424 specifies the pattern to split on if __-a__ is also in
425 effect. The pattern may be surrounded by //,
426 , or '', otherwise it will be
427 put in single quotes.
428
429
430 __-h__
431
432
433 prints a summary of the options.
434
435
436 __-i__[[''extension'']
437
438
439 specifies that files processed by the
440 construct are to be edited in-place. It does this by
441 renaming the input file, opening the output file by the
442 original name, and selecting that output file as the default
443 for ''print()'' statements. The extension, if supplied,
444 is used to modify the name of the old file to make a backup
445 copy, following these rules:
446
447
448 If no extension is supplied, no backup is made and the
449 current file is overwritten.
450
451
452 If the extension doesn't contain a *, then it is
453 appended to the end of the current filename as a suffix. If
454 the extension does contain one or more *
455 characters, then each * is replaced with the
456 current filename. In Perl terms, you could think of this
457 as:
458
459
460 ($backup = $extension) =~ s/*/$file_name/g;
461 This allows you to add a prefix to the backup file, instead of (or in addition to) a suffix:
462
463
464 $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
465 Or even to place backup copies of the original files into another directory (provided the directory already exists):
466
467
468 $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
469 These sets of one-liners are equivalent:
470
471
472 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
473 $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file
474 $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
475 $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
476 From the shell, saying
477
478
479 $ perl -p -i.orig -e
480 is the same as using the program:
481
482
483 #!/usr/bin/perl -pi.orig
484 s/foo/bar/;
485 which is equivalent to
486
487
488 #!/usr/bin/perl
489 $extension = '.orig';
490 LINE: while (
491 except that the __-i__ form doesn't need to compare $ARGV to $oldargv to know when the filename has changed. It does, however, use ARGVOUT for the selected filehandle. Note that STDOUT is restored as the default output filehandle after the loop.
492
493
494 As shown above, Perl creates the backup file whether or not
495 any output is actually changed. So this is just a fancy way
496 to copy files:
497
498
499 $ perl -p -i '/some/file/path/*' -e 1 file1 file2 file3...
500 or
501 $ perl -p -i '.orig' -e 1 file1 file2 file3...
502 You can use eof without parentheses to locate the end of each input file, in case you want to append to each file, or reset line numbering (see example in ``eof'' in perlfunc).
503
504
505 If, for a given file, Perl is unable to create the backup
506 file as specified in the extension then it will skip that
507 file and continue on with the next one (if it
508 exists).
509
510
511 For a discussion of issues surrounding file permissions and
512 __-i__, see ``Why does Perl let me delete read-only
513 files? Why does -i clobber protected files? Isn't this a bug
514 in Perl?'' in perlfaq5.
515
516
517 You cannot use __-i__ to create directories or to strip
518 extensions from files.
519
520
521 Perl does not expand ~ in filenames, which is good,
522 since some folks use it for their backup files:
523
524
525 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
526 Finally, the __-i__ switch does not impede execution when no files are given on the command line. In this case, no backup is made (the original file cannot, of course, be determined) and processing proceeds from STDIN to STDOUT as might be expected.
527
528
529 __-I__''directory''
530
531
532 Directories specified by __-I__ are prepended to the
533 search path for modules (@INC), and also tells the
534 C preprocessor where to search for include files. The C
535 preprocessor is invoked with __-P__; by default it
536 searches /usr/include and /usr/lib/perl.
537
538
539 __-l__[[''octnum'']
540
541
542 enables automatic line-ending processing. It has two
543 separate effects. First, it automatically chomps $/
544 (the input record separator) when used with __-n__ or
545 __-p__. Second, it assigns $\ (the output record
546 separator) to have the value of ''octnum'' so that any
547 print statements will have that separator added back on. If
548 ''octnum'' is omitted, sets $\ to the current
549 value of $/. For instance, to trim lines to 80
550 columns:
551
552
553 perl -lpe 'substr($_, 80) =
554 Note that the assignment $\ = $/ is done when the switch is processed, so the input record separator can be different than the output record separator if the __-l__ switch is followed by a __-0__ switch:
555
556
557 gnufind / -print0 perl -ln0e 'print
558 This sets $\ to newline and then sets $/ to the null character.
559
560
561 __-m__[[__-__]''module''
562
563
564 __-M__[[__-__]''module''
565
566
567 __-M__[[__-__]'''module ...'''
568
569
570 __-[[mM]__[[__-__]''module=arg[[,arg]...''
571
572
573 __-m__''module'' executes use ''module''
574 (); before executing your program.
575
576
577 __-M__''module'' executes use ''module''
578 ; before executing your program. You can use quotes
579 to add extra code after the module name, e.g., '-Mmodule
580 qw(foo bar)'.
581
582
583 If the first character after the __-M__ or __-m__ is a
584 dash (-) then the 'use' is replaced with
585 'no'.
586
587
588 A little builtin syntactic sugar means you can also say
589 __-mmodule=foo,bar__ or __-Mmodule=foo,bar__ as a
590 shortcut for '-Mmodule qw(foo bar)'. This avoids
591 the need to use quotes when importing symbols. The actual
592 code generated by __-Mmodule=foo,bar__ is use module
593 split(/,/,q{foo,bar}). Note that the = form
594 removes the distinction between __-m__ and
595 __-M__.
596
597
598 __-n__
599
600
601 causes Perl to assume the following loop around your
602 program, which makes it iterate over filename arguments
603 somewhat like __sed -n__ or __awk__:
604
605
606 LINE:
607 while (
608 Note that the lines are not printed by default. See __-p__ to have lines printed. If a file named by an argument cannot be opened for some reason, Perl warns you about it and moves on to the next file.
609
610
611 Here is an efficient way to delete all files older than a
612 week:
613
614
615 find . -mtime +7 -print perl -nle unlink
616 This is faster than using the __-exec__ switch of __find__ because you don't have to start a process on every filename found. It does suffer from the bug of mishandling newlines in pathnames, which you can fix if you
617
618
619 BEGIN and END blocks may be used to
620 capture control before or after the implicit program loop,
621 just as in __awk__.
622
623
624 __-p__
625
626
627 causes Perl to assume the following loop around your
628 program, which makes it iterate over filename arguments
629 somewhat like __sed__:
630
631
632 LINE:
633 while (
634 If a file named by an argument cannot be opened for some reason, Perl warns you about it, and moves on to the next file. Note that the lines are printed automatically. An error occurring during printing is treated as fatal. To suppress printing use the __-n__ switch. A __-p__ overrides a __-n__ switch.
635
636
637 BEGIN and END blocks may be used to
638 capture control before or after the implicit loop, just as
639 in __awk__.
640
641
642 __-P__
643
644
645 causes your program to be run through the C preprocessor
646 before compilation by Perl. Because both comments and
647 __cpp__ directives begin with the # character, you should
648 avoid starting comments with any words recognized by the C
649 preprocessor such as ,
650 , or .
651 Also, in some platforms the C preprocessor knows too much:
652 it knows about the C ++ -style
653 until-end-of-line comments starting with
654 . This will cause problems with
655 common Perl constructs like
656
657
658 s/foo//;
659 because after -P this will became illegal code
660
661
662 s/foo
663 The workaround is to use some other quoting separator than , like for example :
664
665
666 s!foo!!;
667
668
669 __-s__
670
671
672 enables rudimentary switch parsing for switches on the
673 command line after the program name but before any filename
674 arguments (or before an argument of __--__). This means
675 you can have switches with two leading dashes
676 (__--help__). Any switch found there is removed from
677 @ARGV and sets the corresponding variable in the
678 Perl program. The following program prints ``1'' if the
679 program is invoked with a __-xyz__ switch, and ``abc'' if
680 it is invoked with __-xyz=abc__.
681
682
683 #!/usr/bin/perl -s
684 if ($xyz) { print
685 Do note that __--help__ creates the variable ${-help}, which is not compliant with strict refs.
686
687
688 __-S__
689
690
691 makes Perl use the PATH environment variable
692 to search for the program (unless the name of the program
693 contains directory separators).
694
695
696 On some platforms, this also makes Perl append suffixes to
697 the filename while searching for it. For example, on Win32
698 platforms, the ``.bat'' and ``.cmd'' suffixes are appended
699 if a lookup for the original name fails, and if the name
700 does not already end in one of those suffixes. If your Perl
701 was compiled with DEBUGGING turned on, using
702 the -Dp switch to Perl shows how the search
703 progresses.
704
705
706 Typically this is used to emulate #! startup on platforms
707 that don't support #!. This example works on many platforms
708 that have a shell compatible with Bourne shell:
709
710
711 #!/usr/bin/perl
712 eval 'exec /usr/bin/perl -wS $0 ${1+
713 The system ignores the first line and feeds the program to ''/bin/sh'', which proceeds to try to execute the Perl program as a shell script. The shell executes the second line as a normal shell command, and thus starts up the Perl interpreter. On some systems $0 doesn't always contain the full pathname, so the __-S__ tells Perl to search for the program if necessary. After Perl locates the program, it parses the lines and ignores them because the variable $running_under_some_shell is never true. If the program will be interpreted by csh, you will need to replace ${1+ with $*, even though that doesn't understand embedded spaces (and such) in the argument list. To start up sh rather than csh, some systems may have to replace the #! line with a line containing just a colon, which will be politely ignored by Perl. Other systems can't control that, and need a totally devious construct that will work under any of __csh__, __sh__, or Perl, such as the following:
714
715
716 eval '(exit $?0)'
717 If the filename supplied contains directory separators (i.e., is an absolute or relative pathname), and if that file is not found, platforms that append file extensions will do so and try to look for the file with those extensions added, one by one.
718
719
720 On DOS-like platforms, if the program does not contain
721 directory separators, it will first be searched for in the
722 current directory before being searched for on the
723 PATH . On Unix platforms, the program will be
724 searched for strictly on the PATH
725 .
726
727
728 __-T__
729
730
731 forces ``taint'' checks to be turned on so you can test
732 them. Ordinarily these checks are done only when running
733 setuid or setgid. It's a good idea to turn them on
734 explicitly for programs that run on behalf of someone else
735 whom you might not necessarily trust, such as
736 CGI programs or any internet servers you
737 might write in Perl. See perlsec for details. For security
738 reasons, this option must be seen by Perl quite early;
739 usually this means it must appear early on the command line
740 or in the #! line for systems which support that
741 construct.
742
743
744 __-u__
745
746
747 This obsolete switch causes Perl to dump core after
748 compiling your program. You can then in theory take this
749 core dump and turn it into an executable file by using the
750 __undump__ program (not supplied). This speeds startup at
751 the expense of some disk space (which you can minimize by
752 stripping the executable). (Still, a ``hello world''
753 executable comes out to about 200K on my machine.) If you
754 want to execute a portion of your program before dumping,
755 use the ''dump()'' operator instead. Note: availability
756 of __undump__ is platform specific and may not be
757 available for a specific port of Perl.
758
759
760 This switch has been superseded in favor of the new Perl
761 code generator backends to the compiler. See B and
762 B::Bytecode for details.
763
764
765 __-U__
766
767
768 allows Perl to do unsafe operations. Currently the only
769 ``unsafe'' operations are the unlinking of directories while
770 running as superuser, and running setuid programs with fatal
771 taint checks turned into warnings. Note that the __-w__
772 switch (or the $^W variable) must be used along
773 with this option to actually ''generate'' the taint-check
774 warnings.
775
776
777 __-v__
778
779
780 prints the version and patchlevel of your perl
781 executable.
782
783
784 __-V__
785
786
787 prints summary of the major perl configuration values and
788 the current values of @INC.
789
790
791 __-V:__''name''
792
793
794 Prints to STDOUT the value of the named
795 configuration variable. For example,
796
797
798 $ perl -V:man.dir
799 will provide strong clues about what your MANPATH variable should be set to in order to access the Perl documentation.
800
801
802 __-w__
803
804
805 prints warnings about dubious constructs, such as variable
806 names that are mentioned only once and scalar variables that
807 are used before being set, redefined subroutines, references
808 to undefined filehandles or filehandles opened read-only
809 that you are attempting to write on, values used as a number
810 that doesn't look like numbers, using an array as though it
811 were a scalar, if your subroutines recurse more than 100
812 deep, and innumerable other things.
813
814
815 This switch really just enables the internal ^$W
816 variable. You can disable or promote into fatal errors
817 specific warnings using __WARN__ hooks, as
818 described in perlvar and ``warn'' in perlfunc. See also
819 perldiag and perltrap. A new, fine-grained warning facility
820 is also available if you want to manipulate entire classes
821 of warnings; see warnings or perllexwarn.
822
823
824 __-W__
825
826
827 Enables all warnings regardless of no warnings or
828 $^W. See perllexwarn.
829
830
831 __-X__
832
833
834 Disables all warnings regardless of use warnings or
835 $^W. See perllexwarn.
836
837
838 __-x__ ''directory''
839
840
841 tells Perl that the program is embedded in a larger chunk of
842 unrelated ASCII text, such as in a mail
843 message. Leading garbage will be discarded until the first
844 line that starts with #! and contains the string ``perl''.
845 Any meaningful switches on that line will be applied. If a
846 directory name is specified, Perl will switch to that
847 directory before running the program. The __-x__ switch
848 controls only the disposal of leading garbage. The program
849 must be terminated with __END__ if there is
850 trailing garbage to be ignored (the program can process any
851 or all of the trailing garbage via the DATA
852 filehandle if desired).
853 !!ENVIRONMENT
854
855
856 HOME Used if chdir has no
857 argument.
858
859
860 LOGDIR
861
862
863 Used if chdir has no argument and HOME is not
864 set.
865
866
867 PATH Used in executing subprocesses, and in
868 finding the program if __-S__ is used.
869
870
871 PERL5LIB
872
873
874 A colon-separated list of directories in which to look for
875 Perl library files before looking in the standard library
876 and the current directory. Any architecture-specific
877 directories under the specified locations are automatically
878 included if they exist. If PERL5LIB is not
879 defined, PERLLIB is used.
880
881
882 When running taint checks (either because the program was
883 running setuid or setgid, or the __-T__ switch was used),
884 neither variable is used. The program should instead
885 say:
886
887
888 use lib
889
890
891 PERL5OPT
892
893
894 Command-line options (switches). Switches in this variable
895 are taken as if they were on every Perl command line. Only
896 the __-[[DIMUdmw]__ switches are allowed. When running
897 taint checks (because the program was running setuid or
898 setgid, or the __-T__ switch was used), this variable is
899 ignored. If PERL5OPT begins with __-T__,
900 tainting will be enabled, and any subsequent options
901 ignored.
902
903
904 PERLLIB
905
906
907 A colon-separated list of directories in which to look for
908 Perl library files before looking in the standard library
909 and the current directory. If PERL5LIB is
910 defined, PERLLIB is not used.
911
912
913 PERL5DB
914
915
916 The command used to load the debugger code. The default
917 is:
918
919
920 BEGIN { require 'perl5db.pl' }
921
922
923 PERL5SHELL (specific to the Win32
924 port)
925
926
927 May be set to an alternative shell that perl must use
928 internally for executing ``backtick'' commands or
929 ''system()''. Default is cmd.exe /x/c on
930 WindowsNT and command.com /c on Windows95. The
931 value is considered to be space-separated. Precede any
932 character that needs to be protected (like a space or
933 backslash) with a backslash.
934
935
936 Note that Perl doesn't use COMSPEC for this
937 purpose because COMSPEC has a high degree of
938 variability among users, leading to portability concerns.
939 Besides, perl can use a shell that may not be fit for
940 interactive use, and setting COMSPEC to such
941 a shell may interfere with the proper functioning of other
942 programs (which usually look in COMSPEC to
943 find a shell fit for interactive use).
944
945
946 PERL_DEBUG_MSTATS
947
948
949 Relevant only if perl is compiled with the malloc included
950 with the perl distribution (that is, if perl
951 -V:d_mymalloc is 'define'). If set, this causes memory
952 statistics to be dumped after execution. If set to an
953 integer greater than one, also causes memory statistics to
954 be dumped after compilation.
955
956
957 PERL_DESTRUCT_LEVEL
958
959
960 Relevant only if your perl executable was built with
961 __-DDEBUGGING__, this controls the behavior of global
962 destruction of objects and other references.
963
964
965 PERL_ROOT (specific to the VMS
966 port)
967
968
969 A translation concealed rooted logical name that contains
970 perl and the logical device for the @INC path on
971 VMS only. Other logical names that affect
972 perl on VMS include PERLSHR ,
973 PERL_ENV_TABLES , and
974 SYS$TIMEZONE_DIFFERENTIAL but are optional
975 and discussed further in perlvms and in
976 ''README .vms'' in the Perl source
977 distribution.
978
979
980 SYS$LOGIN (specific to the VMS
981 port)
982
983
984 Used if chdir has no argument and HOME and
985 LOGDIR are not set.
986
987
988 Perl also has environment variables that control how Perl
989 handles data specific to particular natural languages. See
990 perllocale.
991
992
993 Apart from these, Perl uses no other environment variables,
994 except to make them available to the program being executed,
995 and to child processes. However, programs running setuid
996 would do well to execute the following lines before doing
997 anything else, just to keep people honest:
998
999
1000 $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need
1001 $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
1002 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
1003 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.