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