Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlrun - how to execute the Perl interpreter | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
672fde27 | 7 | B<perl> S<[ B<-sTtuUWX> ]> |
e0ebc809 | 8 | S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]> |
2cbb2ee1 | 9 | S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]> |
f2095865 | 10 | S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]> |
df451b2a | 11 | S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]> |
c630fe62 | 12 | S<[ B<-C [I<number/list>] >]> |
e0ebc809 | 13 | S<[ B<-S> ]> |
14 | S<[ B<-x>[I<dir>] ]> | |
15 | S<[ B<-i>[I<extension>] ]> | |
eb1dd64e | 16 | S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...> |
a0d0e21e LW |
17 | |
18 | =head1 DESCRIPTION | |
19 | ||
19799a22 GS |
20 | The normal way to run a Perl program is by making it directly |
21 | executable, or else by passing the name of the source file as an | |
22 | argument on the command line. (An interactive Perl environment | |
23 | is also possible--see L<perldebug> for details on how to do that.) | |
24 | Upon startup, Perl looks for your program in one of the following | |
a0d0e21e LW |
25 | places: |
26 | ||
27 | =over 4 | |
28 | ||
29 | =item 1. | |
30 | ||
f7a66378 DB |
31 | Specified line by line via L<-e|/-e commandline> or L<-E|/-E commandline> |
32 | switches on the command line. | |
a0d0e21e LW |
33 | |
34 | =item 2. | |
35 | ||
36 | Contained in the file specified by the first filename on the command line. | |
f4750dab | 37 | (Note that systems supporting the C<#!> notation invoke interpreters this |
5a0de581 | 38 | way. See L</Location of Perl>.) |
a0d0e21e LW |
39 | |
40 | =item 3. | |
41 | ||
5f05dabc | 42 | Passed in implicitly via standard input. This works only if there are |
19799a22 GS |
43 | no filename arguments--to pass arguments to a STDIN-read program you |
44 | must explicitly specify a "-" for the program name. | |
a0d0e21e LW |
45 | |
46 | =back | |
47 | ||
48 | With methods 2 and 3, Perl starts parsing the input file from the | |
f7a66378 | 49 | beginning, unless you've specified a L</-x> switch, in which case it |
f4750dab | 50 | scans for the first line starting with C<#!> and containing the word |
19799a22 | 51 | "perl", and starts there instead. This is useful for running a program |
a0d0e21e | 52 | embedded in a larger message. (In this case you would indicate the end |
19799a22 | 53 | of the program using the C<__END__> token.) |
a0d0e21e | 54 | |
f4750dab | 55 | The C<#!> line is always examined for switches as the line is being |
5f05dabc | 56 | parsed. Thus, if you're on a machine that allows only one argument |
f4750dab TC |
57 | with the C<#!> line, or worse, doesn't even recognize the C<#!> line, you |
58 | still can get consistent switch behaviour regardless of how Perl was | |
f7a66378 | 59 | invoked, even if L</-x> was used to find the beginning of the program. |
19799a22 GS |
60 | |
61 | Because historically some operating systems silently chopped off | |
f4750dab | 62 | kernel interpretation of the C<#!> line after 32 characters, some |
19799a22 GS |
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 | |
f7a66378 DB |
69 | standard input instead of your program. And a partial L<-I|/-Idirectory> |
70 | switch could also cause odd results. | |
a0d0e21e | 71 | |
19799a22 | 72 | Some switches do care if they are processed twice, for instance |
f7a66378 DB |
73 | combinations of L<-l|/-l[octnum]> and L<-0|/-0[octalE<sol>hexadecimal]>. |
74 | Either put all the switches after the 32-character boundary (if | |
75 | applicable), or replace the use of B<-0>I<digits> by | |
76 | C<BEGIN{ $/ = "\0digits"; }>. | |
fb73857a | 77 | |
f4750dab | 78 | Parsing of the C<#!> switches starts wherever "perl" is mentioned in the line. |
a0d0e21e LW |
79 | The sequences "-*" and "- " are specifically ignored so that you could, |
80 | if you were so inclined, say | |
81 | ||
428bacd7 | 82 | #!/bin/sh |
efa23af5 | 83 | #! -*- perl -*- -p |
428bacd7 SP |
84 | eval 'exec perl -x -wS $0 ${1+"$@"}' |
85 | if 0; | |
a0d0e21e | 86 | |
f7a66378 | 87 | to let Perl see the L</-p> switch. |
19799a22 | 88 | |
f4750dab | 89 | A similar trick involves the I<env> program, if you have it. |
19799a22 GS |
90 | |
91 | #!/usr/bin/env perl | |
92 | ||
93 | The examples above use a relative path to the perl interpreter, | |
94 | getting whatever version is first in the user's path. If you want | |
6898e867 | 95 | a specific version of Perl, say, perl5.14.1, you should place |
f4750dab | 96 | that directly in the C<#!> line's path. |
a0d0e21e | 97 | |
3b56f80d | 98 | If the C<#!> line does not contain the word "perl" nor the word "indir", |
2f1fe8a3 RGS |
99 | the program named after the C<#!> is executed instead of the Perl |
100 | interpreter. This is slightly bizarre, but it helps people on machines | |
101 | that don't do C<#!>, because they can tell a program that their SHELL is | |
102 | F</usr/bin/perl>, and Perl will then dispatch the program to the correct | |
103 | interpreter for them. | |
a0d0e21e | 104 | |
19799a22 | 105 | After locating your program, Perl compiles the entire program to an |
a0d0e21e | 106 | internal form. If there are any compilation errors, execution of the |
19799a22 | 107 | program is not attempted. (This is unlike the typical shell script, |
54310121 | 108 | which might run part-way through before finding a syntax error.) |
a0d0e21e | 109 | |
19799a22 | 110 | If the program is syntactically correct, it is executed. If the program |
a0d0e21e LW |
111 | runs off the end without hitting an exit() or die() operator, an implicit |
112 | C<exit(0)> is provided to indicate successful completion. | |
113 | ||
68dc0745 | 114 | =head2 #! and quoting on non-Unix systems |
d74e8afc | 115 | X<hashbang> X<#!> |
68dc0745 | 116 | |
f4750dab | 117 | Unix's C<#!> technique can be simulated on other systems: |
68dc0745 | 118 | |
119 | =over 4 | |
120 | ||
121 | =item OS/2 | |
122 | ||
123 | Put | |
124 | ||
125 | extproc perl -S -your_switches | |
126 | ||
f7a66378 | 127 | as the first line in C<*.cmd> file (L</-S> due to a bug in cmd.exe's |
68dc0745 | 128 | `extproc' handling). |
129 | ||
54310121 | 130 | =item MS-DOS |
68dc0745 | 131 | |
19799a22 | 132 | Create a batch file to run your program, and codify it in |
fd1adc71 | 133 | C<ALTERNATE_SHEBANG> (see the F<dosish.h> file in the source |
68dc0745 | 134 | distribution for more information). |
135 | ||
136 | =item Win95/NT | |
137 | ||
6c6a61e2 | 138 | The Win95/NT installation, when using the ActiveState installer for Perl, |
c8db1d39 | 139 | will modify the Registry to associate the F<.pl> extension with the perl |
6c6a61e2 GS |
140 | interpreter. If you install Perl by other means (including building from |
141 | the sources), you may have to modify the Registry yourself. Note that | |
142 | this means you can no longer tell the difference between an executable | |
143 | Perl program and a Perl library file. | |
68dc0745 | 144 | |
bd3fa61c CB |
145 | =item VMS |
146 | ||
147 | Put | |
148 | ||
60b7c710 KW |
149 | $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' ! |
150 | $ exit++ + ++$status != 0 and $exit = $status = undef; | |
bd3fa61c | 151 | |
19799a22 GS |
152 | at the top of your program, where B<-mysw> are any command line switches you |
153 | want to pass to Perl. You can now invoke the program directly, by saying | |
154 | C<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly | |
155 | via F<DCL$PATH> by just using the name of the program). | |
bd3fa61c CB |
156 | |
157 | This incantation is a bit much to remember, but Perl will display it for | |
158 | you if you say C<perl "-V:startperl">. | |
159 | ||
68dc0745 | 160 | =back |
161 | ||
162 | Command-interpreters on non-Unix systems have rather different ideas | |
163 | on quoting than Unix shells. You'll need to learn the special | |
164 | characters in your command-interpreter (C<*>, C<\> and C<"> are | |
165 | common) and how to protect whitespace and these characters to run | |
76c9ab0e | 166 | one-liners (see L<-e|/-e commandline> below). |
68dc0745 | 167 | |
168 | On some systems, you may have to change single-quotes to double ones, | |
e6f03d26 | 169 | which you must I<not> do on Unix or Plan 9 systems. You might also |
68dc0745 | 170 | have to change a single % to a %%. |
171 | ||
172 | For example: | |
173 | ||
174 | # Unix | |
175 | perl -e 'print "Hello world\n"' | |
176 | ||
54310121 | 177 | # MS-DOS, etc. |
68dc0745 | 178 | perl -e "print \"Hello world\n\"" |
179 | ||
68dc0745 | 180 | # VMS |
181 | perl -e "print ""Hello world\n""" | |
182 | ||
19799a22 | 183 | The problem is that none of this is reliable: it depends on the |
f4750dab | 184 | command and it is entirely possible neither works. If I<4DOS> were |
19799a22 | 185 | the command shell, this would probably work better: |
68dc0745 | 186 | |
187 | perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" | |
188 | ||
19799a22 | 189 | B<CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in |
68dc0745 | 190 | when nobody was looking, but just try to find documentation for its |
191 | quoting rules. | |
192 | ||
68dc0745 | 193 | There is no general solution to all of this. It's just a mess. |
194 | ||
a3cb178b | 195 | =head2 Location of Perl |
d74e8afc | 196 | X<perl, location of interpreter> |
a3cb178b GS |
197 | |
198 | It may seem obvious to say, but Perl is useful only when users can | |
19799a22 GS |
199 | easily find it. When possible, it's good for both F</usr/bin/perl> |
200 | and F</usr/local/bin/perl> to be symlinks to the actual binary. If | |
201 | that can't be done, system administrators are strongly encouraged | |
202 | to put (symlinks to) perl and its accompanying utilities into a | |
203 | directory typically found along a user's PATH, or in some other | |
204 | obvious and convenient place. | |
205 | ||
206 | In this documentation, C<#!/usr/bin/perl> on the first line of the program | |
207 | will stand in for whatever method works on your system. You are | |
208 | advised to use a specific path if you care about a specific version. | |
a3cb178b | 209 | |
6898e867 | 210 | #!/usr/local/bin/perl5.14 |
a3cb178b | 211 | |
19799a22 GS |
212 | or if you just want to be running at least version, place a statement |
213 | like this at the top of your program: | |
a0d0e21e | 214 | |
6898e867 | 215 | use 5.014; |
a0d0e21e | 216 | |
19799a22 | 217 | =head2 Command Switches |
d74e8afc | 218 | X<perl, command switches> X<command switches> |
19799a22 GS |
219 | |
220 | As with all standard commands, a single-character switch may be | |
221 | clustered with the following switch, if any. | |
222 | ||
223 | #!/usr/bin/perl -spi.orig # same as -s -p -i.orig | |
a0d0e21e | 224 | |
4612c2ba JK |
225 | A C<--> signals the end of options and disables further option processing. Any |
226 | arguments after the C<--> are treated as filenames and arguments. | |
227 | ||
a0d0e21e LW |
228 | Switches include: |
229 | ||
230 | =over 5 | |
231 | ||
f2095865 | 232 | =item B<-0>[I<octal/hexadecimal>] |
d74e8afc | 233 | X<-0> X<$/> |
a0d0e21e | 234 | |
f2095865 JH |
235 | specifies the input record separator (C<$/>) as an octal or |
236 | hexadecimal number. If there are no digits, the null character is the | |
237 | separator. Other switches may precede or follow the digits. For | |
f4750dab | 238 | example, if you have a version of I<find> which can print filenames |
f2095865 | 239 | terminated by the null character, you can say this: |
a0d0e21e | 240 | |
19799a22 | 241 | find . -name '*.orig' -print0 | perl -n0e unlink |
a0d0e21e LW |
242 | |
243 | The special value 00 will cause Perl to slurp files in paragraph mode. | |
7ba31cb4 KW |
244 | Any value 0400 or above will cause Perl to slurp files whole, but by convention |
245 | the value 0777 is the one normally used for this purpose. | |
f2095865 | 246 | |
7ba31cb4 | 247 | You can also specify the separator character using hexadecimal notation: |
f4750dab TC |
248 | B<-0xI<HHH...>>, where the C<I<H>> are valid hexadecimal digits. Unlike |
249 | the octal form, this one may be used to specify any Unicode character, even | |
250 | those beyond 0xFF. So if you I<really> want a record separator of 0777, | |
f7a66378 | 251 | specify it as B<-0x1FF>. (This means that you cannot use the L</-x> option |
f4750dab TC |
252 | with a directory name that consists of hexadecimal digits, or else Perl |
253 | will think you have specified a hex number to B<-0>.) | |
a0d0e21e LW |
254 | |
255 | =item B<-a> | |
d74e8afc | 256 | X<-a> X<autosplit> |
a0d0e21e | 257 | |
f7a66378 | 258 | turns on autosplit mode when used with a L</-n> or L</-p>. An implicit |
a0d0e21e | 259 | split command to the @F array is done as the first thing inside the |
f7a66378 | 260 | implicit while loop produced by the L</-n> or L</-p>. |
a0d0e21e LW |
261 | |
262 | perl -ane 'print pop(@F), "\n";' | |
263 | ||
264 | is equivalent to | |
265 | ||
266 | while (<>) { | |
267 | @F = split(' '); | |
268 | print pop(@F), "\n"; | |
269 | } | |
270 | ||
f7a66378 | 271 | An alternate delimiter may be specified using L<-F|/-Fpattern>. |
a0d0e21e | 272 | |
f7a66378 | 273 | B<-a> implicitly sets L</-n>. |
24ffa309 | 274 | |
a05d7ebb | 275 | =item B<-C [I<number/list>]> |
d74e8afc | 276 | X<-C> |
46487f74 | 277 | |
f4750dab | 278 | The B<-C> flag controls some of the Perl Unicode features. |
a05d7ebb | 279 | |
f4750dab | 280 | As of 5.8.1, the B<-C> can be followed either by a number or a list |
f3f8427d | 281 | of option letters. The letters, their numeric values, and effects |
8aa8f774 | 282 | are as follows; listing the letters is equal to summing the numbers. |
9f21530f | 283 | |
73e12209 A |
284 | I 1 STDIN is assumed to be in UTF-8 |
285 | O 2 STDOUT will be in UTF-8 | |
286 | E 4 STDERR will be in UTF-8 | |
287 | S 7 I + O + E | |
288 | i 8 UTF-8 is the default PerlIO layer for input streams | |
289 | o 16 UTF-8 is the default PerlIO layer for output streams | |
290 | D 24 i + o | |
291 | A 32 the @ARGV elements are expected to be strings encoded | |
292 | in UTF-8 | |
60b7c710 KW |
293 | L 64 normally the "IOEioA" are unconditional, the L makes |
294 | them conditional on the locale environment variables | |
407a9f94 | 295 | (the LC_ALL, LC_CTYPE, and LANG, in the order of |
60b7c710 | 296 | decreasing precedence) -- if the variables indicate |
73e12209 | 297 | UTF-8, then the selected "IOEioA" are in effect |
60b7c710 KW |
298 | a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching |
299 | code in debugging mode. | |
5a22a2bb NC |
300 | |
301 | =for documenting_the_underdocumented | |
302 | perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */" | |
9f21530f | 303 | |
f23930d5 NC |
304 | =for todo |
305 | perltodo mentions Unicode in %ENV and filenames. I guess that these will be | |
306 | options e and f (or F). | |
307 | ||
f4750dab | 308 | For example, B<-COE> and B<-C6> will both turn on UTF-8-ness on both |
9f21530f JH |
309 | STDOUT and STDERR. Repeating letters is just redundant, not cumulative |
310 | nor toggling. | |
a05d7ebb | 311 | |
44505768 | 312 | The C<io> options mean that any subsequent open() (or similar I/O |
373d867a | 313 | operations) in main program scope will have the C<:utf8> PerlIO layer |
88770b48 NT |
314 | implicitly applied to them, in other words, UTF-8 is expected from any |
315 | input stream, and UTF-8 is produced to any output stream. This is just | |
e038729f DB |
316 | the default set via L<C<${^OPEN}>|perlvar/${^OPEN}>, |
317 | with explicit layers in open() and with binmode() one can | |
373d867a | 318 | manipulate streams as usual. This has no effect on code run in modules. |
44505768 | 319 | |
f4750dab | 320 | B<-C> on its own (not followed by any number or option list), or the |
f7a66378 | 321 | empty string C<""> for the L</PERL_UNICODE> environment variable, has the |
f4750dab TC |
322 | same effect as B<-CSDL>. In other words, the standard I/O handles and |
323 | the default C<open()> layer are UTF-8-fied I<but> only if the locale | |
47427c4e RGS |
324 | environment variables indicate a UTF-8 locale. This behaviour follows |
325 | the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0. | |
370155be | 326 | (See L<perl581delta/UTF-8 no longer default under UTF-8 locales>.) |
a05d7ebb | 327 | |
f4750dab | 328 | You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly |
5b4f334e | 329 | disable all the above Unicode features. |
fde18df1 | 330 | |
8aa8f774 | 331 | The read-only magic variable C<${^UNICODE}> reflects the numeric value |
f60ef620 | 332 | of this setting. This variable is set during Perl startup and is |
ab9e1bb7 | 333 | thereafter read-only. If you want runtime effects, use the three-arg |
2307c6d0 | 334 | open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>), |
ab9e1bb7 | 335 | and the C<open> pragma (see L<open>). |
fde18df1 | 336 | |
f4750dab | 337 | (In Perls earlier than 5.8.1 the B<-C> switch was a Win32-only switch |
fde18df1 JH |
338 | that enabled the use of Unicode-aware "wide system call" Win32 APIs. |
339 | This feature was practically unused, however, and the command line | |
340 | switch was therefore "recycled".) | |
46487f74 | 341 | |
f4750dab TC |
342 | B<Note:> Since perl 5.10.1, if the B<-C> option is used on the C<#!> line, |
343 | it must be specified on the command line as well, since the standard streams | |
618078e9 | 344 | are already set up at this point in the execution of the perl interpreter. |
4ba71d51 | 345 | You can also use binmode() to set the encoding of an I/O stream. |
618078e9 | 346 | |
a0d0e21e | 347 | =item B<-c> |
d74e8afc | 348 | X<-c> |
a0d0e21e | 349 | |
19799a22 | 350 | causes Perl to check the syntax of the program and then exit without |
2c4188f3 | 351 | executing it. Actually, it I<will> execute any C<BEGIN>, C<UNITCHECK>, |
f4750dab TC |
352 | or C<CHECK> blocks and any C<use> statements: these are considered as |
353 | occurring outside the execution of your program. C<INIT> and C<END> | |
354 | blocks, however, will be skipped. | |
a0d0e21e LW |
355 | |
356 | =item B<-d> | |
d74e8afc | 357 | X<-d> X<-dt> |
a0d0e21e | 358 | |
2cbb2ee1 RGS |
359 | =item B<-dt> |
360 | ||
19799a22 | 361 | runs the program under the Perl debugger. See L<perldebug>. |
2cbb2ee1 RGS |
362 | If B<t> is specified, it indicates to the debugger that threads |
363 | will be used in the code being debugged. | |
a0d0e21e | 364 | |
f4750dab | 365 | =item B<-d:>I<MOD[=bar,baz]> |
d74e8afc | 366 | X<-d> X<-dt> |
3c81428c | 367 | |
f4750dab | 368 | =item B<-dt:>I<MOD[=bar,baz]> |
2cbb2ee1 | 369 | |
f4750dab TC |
370 | runs the program under the control of a debugging, profiling, or tracing |
371 | module installed as C<Devel::I<MOD>>. E.g., B<-d:DProf> executes the | |
f7a66378 DB |
372 | program using the C<Devel::DProf> profiler. As with the L<-M|/-M[-]module> |
373 | flag, options may be passed to the C<Devel::I<MOD>> package where they will | |
374 | be received and interpreted by the C<Devel::I<MOD>::import> routine. Again, | |
375 | like B<-M>, use -B<-d:-I<MOD>> to call C<Devel::I<MOD>::unimport> instead of | |
376 | import. The comma-separated list of options must follow a C<=> character. | |
377 | If B<t> is specified, it indicates to the debugger that threads will be used | |
378 | in the code being debugged. See L<perldebug>. | |
3c81428c | 379 | |
db2ba183 | 380 | =item B<-D>I<letters> |
d74e8afc | 381 | X<-D> X<DEBUGGING> X<-DDEBUGGING> |
a0d0e21e | 382 | |
db2ba183 | 383 | =item B<-D>I<number> |
a0d0e21e | 384 | |
f075db89 DM |
385 | sets debugging flags. This switch is enabled only if your perl binary has |
386 | been built with debugging enabled: normal production perls won't have | |
387 | been. | |
388 | ||
389 | For example, to watch how perl executes your program, use B<-Dtls>. | |
390 | Another nice value is B<-Dx>, which lists your compiled syntax tree, and | |
391 | B<-Dr> displays compiled regular expressions; the format of the output is | |
392 | explained in L<perldebguts>. | |
4197b13f MJD |
393 | |
394 | As an alternative, specify a number instead of list of letters (e.g., | |
395 | B<-D14> is equivalent to B<-Dtls>): | |
a0d0e21e | 396 | |
e17bc05a TC |
397 | 1 p Tokenizing and parsing (with v, displays parse |
398 | stack) | |
399 | 2 s Stack snapshots (with v, displays all stacks) | |
400 | 4 l Context (loop) stack processing | |
401 | 8 t Trace execution | |
402 | 16 o Method and overloading resolution | |
403 | 32 c String/numeric conversions | |
404 | 64 P Print profiling info, source file input state | |
405 | 128 m Memory and SV allocation | |
406 | 256 f Format processing | |
407 | 512 r Regular expression parsing and execution | |
408 | 1024 x Syntax tree dump | |
409 | 2048 u Tainting checks | |
410 | 4096 U Unofficial, User hacking (reserved for private, | |
411 | unreleased use) | |
e17bc05a TC |
412 | 16384 X Scratchpad allocation |
413 | 32768 D Cleaning up | |
414 | 65536 S Op slab allocation | |
415 | 131072 T Tokenizing | |
416 | 262144 R Include reference counts of dumped variables | |
417 | (eg when using -Ds) | |
418 | 524288 J show s,t,P-debug (don't Jump over) on opcodes within | |
419 | package DB | |
98c74407 KW |
420 | 1048576 v Verbose: use in conjunction with other flags to |
421 | increase the verbosity of the output. Is a no-op on | |
422 | many of the other flags | |
e17bc05a TC |
423 | 2097152 C Copy On Write |
424 | 4194304 A Consistency checks on internal structures | |
425 | 8388608 q quiet - currently only suppresses the "EXECUTING" | |
426 | message | |
7896dde7 | 427 | 16777216 M trace smart match resolution |
e17bc05a TC |
428 | 33554432 B dump suBroutine definitions, including special |
429 | Blocks like BEGIN | |
430 | 67108864 L trace Locale-related info; what gets output is very | |
431 | subject to change | |
432 | 134217728 i trace PerlIO layer processing. Set PERLIO_DEBUG to | |
433 | the filename to trace to. | |
5d7580af | 434 | 268435456 y trace y///, tr/// compilation and execution |
a0d0e21e | 435 | |
19799a22 | 436 | All these flags require B<-DDEBUGGING> when you compile the Perl |
c85da6fc TH |
437 | executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode> |
438 | which may change this). | |
44a4342c | 439 | See the F<INSTALL> file in the Perl source distribution |
f075db89 | 440 | for how to do this. |
8c52afec | 441 | |
19799a22 GS |
442 | If you're just trying to get a print out of each line of Perl code |
443 | as it executes, the way that C<sh -x> provides for shell scripts, | |
44a4342c | 444 | you can't use Perl's B<-D> switch. Instead do this |
19799a22 | 445 | |
c406981e | 446 | # If you have "env" utility |
fdac53cd | 447 | env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program |
c406981e | 448 | |
19799a22 GS |
449 | # Bourne shell syntax |
450 | $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program | |
451 | ||
452 | # csh syntax | |
453 | % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program) | |
454 | ||
455 | See L<perldebug> for details and variations. | |
456 | ||
a0d0e21e | 457 | =item B<-e> I<commandline> |
d74e8afc | 458 | X<-e> |
a0d0e21e | 459 | |
19799a22 GS |
460 | may be used to enter one line of program. If B<-e> is given, Perl |
461 | will not look for a filename in the argument list. Multiple B<-e> | |
462 | commands may be given to build up a multi-line script. Make sure | |
463 | to use semicolons where you would in a normal program. | |
a0d0e21e | 464 | |
bc9b29db RH |
465 | =item B<-E> I<commandline> |
466 | X<-E> | |
467 | ||
f7a66378 DB |
468 | behaves just like L<-e|/-e commandline>, except that it implicitly |
469 | enables all optional features (in the main compilation unit). See | |
470 | L<feature>. | |
bc9b29db | 471 | |
20ef40cf | 472 | =item B<-f> |
174299ac | 473 | X<-f> X<sitecustomize> X<sitecustomize.pl> |
20ef40cf | 474 | |
4a42f219 | 475 | Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup. |
20ef40cf GA |
476 | |
477 | Perl can be built so that it by default will try to execute | |
e846cbe5 | 478 | F<$Config{sitelib}/sitecustomize.pl> at startup (in a BEGIN block). |
f4750dab TC |
479 | This is a hook that allows the sysadmin to customize how Perl behaves. |
480 | It can for instance be used to add entries to the @INC array to make Perl | |
e846cbe5 | 481 | find modules in non-standard locations. |
20ef40cf | 482 | |
298ca354 PBB |
483 | Perl actually inserts the following code: |
484 | ||
485 | BEGIN { | |
486 | do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; } | |
487 | && do "$Config{sitelib}/sitecustomize.pl"; | |
488 | } | |
489 | ||
490 | Since it is an actual C<do> (not a C<require>), F<sitecustomize.pl> | |
491 | doesn't need to return a true value. The code is run in package C<main>, | |
492 | in its own lexical scope. However, if the script dies, C<$@> will not | |
493 | be set. | |
494 | ||
495 | The value of C<$Config{sitelib}> is also determined in C code and not | |
496 | read from C<Config.pm>, which is not loaded. | |
497 | ||
f4750dab | 498 | The code is executed I<very> early. For example, any changes made to |
298ca354 PBB |
499 | C<@INC> will show up in the output of `perl -V`. Of course, C<END> |
500 | blocks will be likewise executed very late. | |
501 | ||
502 | To determine at runtime if this capability has been compiled in your | |
503 | perl, you can check the value of C<$Config{usesitecustomize}>. | |
504 | ||
e0ebc809 | 505 | =item B<-F>I<pattern> |
d74e8afc | 506 | X<-F> |
a0d0e21e | 507 | |
f7a66378 | 508 | specifies the pattern to split on for L</-a>. The pattern may be |
24ffa309 | 509 | surrounded by C<//>, C<"">, or C<''>, otherwise it will be put in single |
f149fd41 | 510 | quotes. You can't use literal whitespace or NUL characters in the pattern. |
24ffa309 | 511 | |
f7a66378 | 512 | B<-F> implicitly sets both L</-a> and L</-n>. |
a0d0e21e | 513 | |
e0ebc809 | 514 | =item B<-h> |
d74e8afc | 515 | X<-h> |
e0ebc809 | 516 | |
517 | prints a summary of the options. | |
518 | ||
519 | =item B<-i>[I<extension>] | |
d74e8afc | 520 | X<-i> X<in-place> |
a0d0e21e | 521 | |
2d259d92 CK |
522 | specifies that files processed by the C<E<lt>E<gt>> construct are to be |
523 | edited in-place. It does this by renaming the input file, opening the | |
524 | output file by the original name, and selecting that output file as the | |
525 | default for print() statements. The extension, if supplied, is used to | |
526 | modify the name of the old file to make a backup copy, following these | |
527 | rules: | |
528 | ||
479e5f87 PM |
529 | If no extension is supplied, and your system supports it, the original |
530 | I<file> is kept open without a name while the output is redirected to | |
531 | a new file with the original I<filename>. When perl exits, cleanly or not, | |
532 | the original I<file> is unlinked. | |
2d259d92 | 533 | |
19799a22 GS |
534 | If the extension doesn't contain a C<*>, then it is appended to the |
535 | end of the current filename as a suffix. If the extension does | |
536 | contain one or more C<*> characters, then each C<*> is replaced | |
537 | with the current filename. In Perl terms, you could think of this | |
538 | as: | |
2d259d92 | 539 | |
66606d78 | 540 | ($backup = $extension) =~ s/\*/$file_name/g; |
2d259d92 CK |
541 | |
542 | This allows you to add a prefix to the backup file, instead of (or in | |
543 | addition to) a suffix: | |
544 | ||
60b7c710 KW |
545 | $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to |
546 | # 'orig_fileA' | |
2d259d92 CK |
547 | |
548 | Or even to place backup copies of the original files into another | |
549 | directory (provided the directory already exists): | |
550 | ||
60b7c710 KW |
551 | $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to |
552 | # 'old/fileA.orig' | |
2d259d92 | 553 | |
66606d78 CK |
554 | These sets of one-liners are equivalent: |
555 | ||
60b7c710 KW |
556 | $ perl -pi -e 's/bar/baz/' fileA # overwrite current file |
557 | $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file | |
66606d78 | 558 | |
60b7c710 KW |
559 | $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' |
560 | $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' | |
66606d78 | 561 | |
2d259d92 | 562 | From the shell, saying |
a0d0e21e | 563 | |
19799a22 | 564 | $ perl -p -i.orig -e "s/foo/bar/; ... " |
a0d0e21e | 565 | |
19799a22 | 566 | is the same as using the program: |
a0d0e21e | 567 | |
19799a22 | 568 | #!/usr/bin/perl -pi.orig |
a0d0e21e LW |
569 | s/foo/bar/; |
570 | ||
571 | which is equivalent to | |
572 | ||
573 | #!/usr/bin/perl | |
19799a22 GS |
574 | $extension = '.orig'; |
575 | LINE: while (<>) { | |
a0d0e21e | 576 | if ($ARGV ne $oldargv) { |
66606d78 CK |
577 | if ($extension !~ /\*/) { |
578 | $backup = $ARGV . $extension; | |
579 | } | |
580 | else { | |
581 | ($backup = $extension) =~ s/\*/$ARGV/g; | |
582 | } | |
583 | rename($ARGV, $backup); | |
a0d0e21e LW |
584 | open(ARGVOUT, ">$ARGV"); |
585 | select(ARGVOUT); | |
586 | $oldargv = $ARGV; | |
587 | } | |
588 | s/foo/bar/; | |
589 | } | |
590 | continue { | |
591 | print; # this prints to original filename | |
592 | } | |
593 | select(STDOUT); | |
594 | ||
595 | except that the B<-i> form doesn't need to compare $ARGV to $oldargv to | |
596 | know when the filename has changed. It does, however, use ARGVOUT for | |
66606d78 CK |
597 | the selected filehandle. Note that STDOUT is restored as the default |
598 | output filehandle after the loop. | |
599 | ||
600 | As shown above, Perl creates the backup file whether or not any output | |
601 | is actually changed. So this is just a fancy way to copy files: | |
602 | ||
cd2d1bac | 603 | $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3... |
19799a22 | 604 | or |
cd2d1bac | 605 | $ perl -p -i'.orig' -e 1 file1 file2 file3... |
66606d78 CK |
606 | |
607 | You can use C<eof> without parentheses to locate the end of each input | |
608 | file, in case you want to append to each file, or reset line numbering | |
609 | (see example in L<perlfunc/eof>). | |
610 | ||
611 | If, for a given file, Perl is unable to create the backup file as | |
612 | specified in the extension then it will skip that file and continue on | |
613 | with the next one (if it exists). | |
614 | ||
1dcc3c19 DG |
615 | For a discussion of issues surrounding file permissions and B<-i>, see |
616 | L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber | |
617 | protected files? Isn't this a bug in Perl?>. | |
66606d78 CK |
618 | |
619 | You cannot use B<-i> to create directories or to strip extensions from | |
620 | files. | |
a0d0e21e | 621 | |
19799a22 GS |
622 | Perl does not expand C<~> in filenames, which is good, since some |
623 | folks use it for their backup files: | |
a0d0e21e | 624 | |
19799a22 GS |
625 | $ perl -pi~ -e 's/foo/bar/' file1 file2 file3... |
626 | ||
a66b22ca | 627 | Note that because B<-i> renames or deletes the original file before |
e1020413 | 628 | creating a new file of the same name, Unix-style soft and hard links will |
0cb0633f | 629 | not be preserved. |
a66b22ca | 630 | |
19799a22 | 631 | Finally, the B<-i> switch does not impede execution when no |
a2008d6d GS |
632 | files are given on the command line. In this case, no backup is made |
633 | (the original file cannot, of course, be determined) and processing | |
634 | proceeds from STDIN to STDOUT as might be expected. | |
635 | ||
a0d0e21e | 636 | =item B<-I>I<directory> |
d74e8afc | 637 | X<-I> X<@INC> |
a0d0e21e | 638 | |
e0ebc809 | 639 | Directories specified by B<-I> are prepended to the search path for |
4c84d7f2 | 640 | modules (C<@INC>). |
a0d0e21e | 641 | |
e0ebc809 | 642 | =item B<-l>[I<octnum>] |
d74e8afc | 643 | X<-l> X<$/> X<$\> |
a0d0e21e | 644 | |
19799a22 GS |
645 | enables automatic line-ending processing. It has two separate |
646 | effects. First, it automatically chomps C<$/> (the input record | |
f7a66378 | 647 | separator) when used with L</-n> or L</-p>. Second, it assigns C<$\> |
19799a22 GS |
648 | (the output record separator) to have the value of I<octnum> so |
649 | that any print statements will have that separator added back on. | |
650 | If I<octnum> is omitted, sets C<$\> to the current value of | |
651 | C<$/>. For instance, to trim lines to 80 columns: | |
a0d0e21e LW |
652 | |
653 | perl -lpe 'substr($_, 80) = ""' | |
654 | ||
655 | Note that the assignment C<$\ = $/> is done when the switch is processed, | |
656 | so the input record separator can be different than the output record | |
f7a66378 DB |
657 | separator if the B<-l> switch is followed by a |
658 | L<-0|/-0[octalE<sol>hexadecimal]> switch: | |
a0d0e21e LW |
659 | |
660 | gnufind / -print0 | perl -ln0e 'print "found $_" if -p' | |
661 | ||
1fef88e7 | 662 | This sets C<$\> to newline and then sets C<$/> to the null character. |
a0d0e21e | 663 | |
e0ebc809 | 664 | =item B<-m>[B<->]I<module> |
d74e8afc | 665 | X<-m> X<-M> |
e0ebc809 | 666 | |
667 | =item B<-M>[B<->]I<module> | |
c07a80fd | 668 | |
e0ebc809 | 669 | =item B<-M>[B<->]I<'module ...'> |
670 | ||
671 | =item B<-[mM]>[B<->]I<module=arg[,arg]...> | |
3c81428c | 672 | |
19799a22 | 673 | B<-m>I<module> executes C<use> I<module> C<();> before executing your |
e2bcc7d7 Z |
674 | program. This loads the module, but does not call its C<import> method, |
675 | so does not import subroutines and does not give effect to a pragma. | |
3c81428c | 676 | |
19799a22 | 677 | B<-M>I<module> executes C<use> I<module> C<;> before executing your |
e2bcc7d7 Z |
678 | program. This loads the module and calls its C<import> method, causing |
679 | the module to have its default effect, typically importing subroutines | |
680 | or giving effect to a pragma. | |
681 | You can use quotes to add extra code after the module name, | |
f4750dab | 682 | e.g., C<'-MI<MODULE> qw(foo bar)'>. |
3c81428c | 683 | |
f4750dab | 684 | If the first character after the B<-M> or B<-m> is a dash (B<->) |
a5f75d66 | 685 | then the 'use' is replaced with 'no'. |
e2bcc7d7 | 686 | This makes no difference for B<-m>. |
a5f75d66 | 687 | |
54310121 | 688 | A little builtin syntactic sugar means you can also say |
f4750dab TC |
689 | B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for |
690 | B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when | |
691 | importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is | |
e0ebc809 | 692 | C<use module split(/,/,q{foo,bar})>. Note that the C<=> form |
c2d9228f A |
693 | removes the distinction between B<-m> and B<-M>; that is, |
694 | B<-mI<MODULE>=foo,bar> is the same as B<-MI<MODULE>=foo,bar>. | |
3c81428c | 695 | |
e2bcc7d7 Z |
696 | A consequence of the C<split> formulation |
697 | is that B<-MI<MODULE>=number> never does a version check, | |
f4750dab TC |
698 | unless C<I<MODULE>::import()> itself is set up to do a version check, which |
699 | could happen for example if I<MODULE> inherits from L<Exporter>. | |
642d0c2f | 700 | |
a0d0e21e | 701 | =item B<-n> |
d74e8afc | 702 | X<-n> |
a0d0e21e | 703 | |
19799a22 | 704 | causes Perl to assume the following loop around your program, which |
f4750dab TC |
705 | makes it iterate over filename arguments somewhat like I<sed -n> or |
706 | I<awk>: | |
a0d0e21e | 707 | |
19799a22 | 708 | LINE: |
a0d0e21e | 709 | while (<>) { |
19799a22 | 710 | ... # your program goes here |
a0d0e21e LW |
711 | } |
712 | ||
76c9ab0e | 713 | Note that the lines are not printed by default. See L</-p> to have |
08e9d68e | 714 | lines printed. If a file named by an argument cannot be opened for |
19799a22 | 715 | some reason, Perl warns you about it and moves on to the next file. |
08e9d68e | 716 | |
48ab5743 ML |
717 | Also note that C<< <> >> passes command line arguments to |
718 | L<perlfunc/open>, which doesn't necessarily interpret them as file names. | |
719 | See L<perlop> for possible security implications. | |
720 | ||
fa11829f | 721 | Here is an efficient way to delete all files that haven't been modified for |
9976c5c7 | 722 | at least a week: |
a0d0e21e | 723 | |
19799a22 | 724 | find . -mtime +7 -print | perl -nle unlink |
a0d0e21e | 725 | |
f4750dab | 726 | This is faster than using the B<-exec> switch of I<find> because you don't |
45cc06e3 DH |
727 | have to start a process on every filename found (but it's not faster |
728 | than using the B<-delete> switch available in newer versions of I<find>. | |
729 | It does suffer from the bug of mishandling newlines in pathnames, which | |
f7a66378 DB |
730 | you can fix if you follow the example under |
731 | L<-0|/-0[octalE<sol>hexadecimal]>. | |
a0d0e21e LW |
732 | |
733 | C<BEGIN> and C<END> blocks may be used to capture control before or after | |
f4750dab | 734 | the implicit program loop, just as in I<awk>. |
a0d0e21e LW |
735 | |
736 | =item B<-p> | |
d74e8afc | 737 | X<-p> |
a0d0e21e | 738 | |
19799a22 | 739 | causes Perl to assume the following loop around your program, which |
f4750dab | 740 | makes it iterate over filename arguments somewhat like I<sed>: |
a0d0e21e LW |
741 | |
742 | ||
19799a22 | 743 | LINE: |
a0d0e21e | 744 | while (<>) { |
19799a22 | 745 | ... # your program goes here |
a0d0e21e | 746 | } continue { |
08e9d68e | 747 | print or die "-p destination: $!\n"; |
a0d0e21e LW |
748 | } |
749 | ||
08e9d68e DD |
750 | If a file named by an argument cannot be opened for some reason, Perl |
751 | warns you about it, and moves on to the next file. Note that the | |
c2611fb3 | 752 | lines are printed automatically. An error occurring during printing is |
f7a66378 | 753 | treated as fatal. To suppress printing use the L</-n> switch. A B<-p> |
08e9d68e | 754 | overrides a B<-n> switch. |
a0d0e21e LW |
755 | |
756 | C<BEGIN> and C<END> blocks may be used to capture control before or after | |
f4750dab | 757 | the implicit loop, just as in I<awk>. |
a0d0e21e | 758 | |
a0d0e21e | 759 | =item B<-s> |
d74e8afc | 760 | X<-s> |
a0d0e21e | 761 | |
19799a22 GS |
762 | enables rudimentary switch parsing for switches on the command |
763 | line after the program name but before any filename arguments (or before | |
74ac850a | 764 | an argument of B<-->). Any switch found there is removed from @ARGV and sets the |
19799a22 | 765 | corresponding variable in the Perl program. The following program |
3c0facb2 GS |
766 | prints "1" if the program is invoked with a B<-xyz> switch, and "abc" |
767 | if it is invoked with B<-xyz=abc>. | |
a0d0e21e LW |
768 | |
769 | #!/usr/bin/perl -s | |
3c0facb2 | 770 | if ($xyz) { print "$xyz\n" } |
a0d0e21e | 771 | |
1dcc3c19 DG |
772 | Do note that a switch like B<--help> creates the variable C<${-help}>, which is |
773 | not compliant with C<use strict "refs">. Also, when using this option on a | |
774 | script with warnings enabled you may get a lot of spurious "used only once" | |
775 | warnings. | |
3bbcc830 | 776 | |
a0d0e21e | 777 | =item B<-S> |
d74e8afc | 778 | X<-S> |
a0d0e21e | 779 | |
f7a66378 | 780 | makes Perl use the L</PATH> environment variable to search for the |
f4750dab | 781 | program unless the name of the program contains path separators. |
19799a22 | 782 | |
2a92aaa0 GS |
783 | On some platforms, this also makes Perl append suffixes to the |
784 | filename while searching for it. For example, on Win32 platforms, | |
785 | the ".bat" and ".cmd" suffixes are appended if a lookup for the | |
786 | original name fails, and if the name does not already end in one | |
f4750dab | 787 | of those suffixes. If your Perl was compiled with C<DEBUGGING> turned |
f7a66378 DB |
788 | on, using the L<-Dp|/-Dletters> switch to Perl shows how the search |
789 | progresses. | |
2a92aaa0 | 790 | |
f4750dab TC |
791 | Typically this is used to emulate C<#!> startup on platforms that don't |
792 | support C<#!>. It's also convenient when debugging a script that uses C<#!>, | |
fa3aa65a JC |
793 | and is thus normally found by the shell's $PATH search mechanism. |
794 | ||
795 | This example works on many platforms that have a shell compatible with | |
796 | Bourne shell: | |
a0d0e21e LW |
797 | |
798 | #!/usr/bin/perl | |
a3cb178b | 799 | eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}' |
188e64dd | 800 | if 0; # ^ Run only under a shell |
a0d0e21e | 801 | |
19799a22 GS |
802 | The system ignores the first line and feeds the program to F</bin/sh>, |
803 | which proceeds to try to execute the Perl program as a shell script. | |
a0d0e21e LW |
804 | The shell executes the second line as a normal shell command, and thus |
805 | starts up the Perl interpreter. On some systems $0 doesn't always | |
f7a66378 | 806 | contain the full pathname, so the L</-S> tells Perl to search for the |
19799a22 | 807 | program if necessary. After Perl locates the program, it parses the |
188e64dd N |
808 | lines and ignores them because the check 'if 0' is never true. |
809 | If the program will be interpreted by csh, you will need | |
a3cb178b | 810 | to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand |
f4750dab TC |
811 | embedded spaces (and such) in the argument list. To start up I<sh> rather |
812 | than I<csh>, some systems may have to replace the C<#!> line with a line | |
a0d0e21e LW |
813 | containing just a colon, which will be politely ignored by Perl. Other |
814 | systems can't control that, and need a totally devious construct that | |
f4750dab | 815 | will work under any of I<csh>, I<sh>, or Perl, such as the following: |
a0d0e21e | 816 | |
19799a22 | 817 | eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' |
a3cb178b | 818 | & eval 'exec /usr/bin/perl -wS $0 $argv:q' |
188e64dd | 819 | if 0; # ^ Run only under a shell |
a0d0e21e | 820 | |
f4750dab | 821 | If the filename supplied contains directory separators (and so is an |
19799a22 GS |
822 | absolute or relative pathname), and if that file is not found, |
823 | platforms that append file extensions will do so and try to look | |
824 | for the file with those extensions added, one by one. | |
825 | ||
826 | On DOS-like platforms, if the program does not contain directory | |
827 | separators, it will first be searched for in the current directory | |
828 | before being searched for on the PATH. On Unix platforms, the | |
829 | program will be searched for strictly on the PATH. | |
830 | ||
6537fe72 | 831 | =item B<-t> |
d74e8afc | 832 | X<-t> |
6537fe72 | 833 | |
f7a66378 | 834 | Like L</-T>, but taint checks will issue warnings rather than fatal |
f4750dab | 835 | errors. These warnings can now be controlled normally with C<no warnings |
317ea90d | 836 | qw(taint)>. |
1dbad523 | 837 | |
f4750dab TC |
838 | B<Note: This is not a substitute for C<-T>!> This is meant to be |
839 | used I<only> as a temporary development aid while securing legacy code: | |
840 | for real production code and for new secure code written from scratch, | |
f7a66378 | 841 | always use the real L</-T>. |
6537fe72 | 842 | |
a0d0e21e | 843 | =item B<-T> |
d74e8afc | 844 | X<-T> |
a0d0e21e | 845 | |
f4750dab | 846 | turns on "taint" so you can test them. Ordinarily |
19799a22 GS |
847 | these checks are done only when running setuid or setgid. It's a |
848 | good idea to turn them on explicitly for programs that run on behalf | |
849 | of someone else whom you might not necessarily trust, such as CGI | |
850 | programs or any internet servers you might write in Perl. See | |
851 | L<perlsec> for details. For security reasons, this option must be | |
852 | seen by Perl quite early; usually this means it must appear early | |
f4750dab | 853 | on the command line or in the C<#!> line for systems which support |
19799a22 | 854 | that construct. |
a0d0e21e LW |
855 | |
856 | =item B<-u> | |
d74e8afc | 857 | X<-u> |
a0d0e21e | 858 | |
f4750dab | 859 | This switch causes Perl to dump core after compiling your |
19799a22 | 860 | program. You can then in theory take this core dump and turn it |
f4750dab | 861 | into an executable file by using the I<undump> program (not supplied). |
19799a22 GS |
862 | This speeds startup at the expense of some disk space (which you |
863 | can minimize by stripping the executable). (Still, a "hello world" | |
864 | executable comes out to about 200K on my machine.) If you want to | |
d8ff3e95 JK |
865 | execute a portion of your program before dumping, use the C<CORE::dump()> |
866 | function instead. Note: availability of I<undump> is platform | |
19799a22 GS |
867 | specific and may not be available for a specific port of Perl. |
868 | ||
a0d0e21e | 869 | =item B<-U> |
d74e8afc | 870 | X<-U> |
a0d0e21e LW |
871 | |
872 | allows Perl to do unsafe operations. Currently the only "unsafe" | |
f4750dab TC |
873 | operations are attempting to unlink directories while running as superuser |
874 | and running setuid programs with fatal taint checks turned into warnings. | |
875 | Note that warnings must be enabled along with this option to actually | |
876 | I<generate> the taint-check warnings. | |
a0d0e21e LW |
877 | |
878 | =item B<-v> | |
d74e8afc | 879 | X<-v> |
a0d0e21e | 880 | |
19799a22 | 881 | prints the version and patchlevel of your perl executable. |
a0d0e21e | 882 | |
3c81428c | 883 | =item B<-V> |
d74e8afc | 884 | X<-V> |
3c81428c | 885 | |
886 | prints summary of the major perl configuration values and the current | |
19799a22 | 887 | values of @INC. |
3c81428c | 888 | |
307dc113 | 889 | =item B<-V:>I<configvar> |
3c81428c | 890 | |
4a305f6a | 891 | Prints to STDOUT the value of the named configuration variable(s), |
f4750dab | 892 | with multiples when your C<I<configvar>> argument looks like a regex (has |
307dc113 | 893 | non-letters). For example: |
3c81428c | 894 | |
307dc113 JC |
895 | $ perl -V:libc |
896 | libc='/lib/libc-2.2.4.so'; | |
4a305f6a JC |
897 | $ perl -V:lib. |
898 | libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc'; | |
899 | libc='/lib/libc-2.2.4.so'; | |
900 | $ perl -V:lib.* | |
901 | libpth='/usr/local/lib /lib /usr/lib'; | |
902 | libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc'; | |
903 | lib_ext='.a'; | |
904 | libc='/lib/libc-2.2.4.so'; | |
905 | libperl='libperl.a'; | |
906 | .... | |
907 | ||
908 | Additionally, extra colons can be used to control formatting. A | |
f4750dab | 909 | trailing colon suppresses the linefeed and terminator ";", allowing |
4a305f6a | 910 | you to embed queries into shell commands. (mnemonic: PATH separator |
f4750dab | 911 | ":".) |
4a305f6a JC |
912 | |
913 | $ echo "compression-vars: " `perl -V:z.*: ` " are here !" | |
914 | compression-vars: zcat='' zip='zip' are here ! | |
915 | ||
f4750dab | 916 | A leading colon removes the "name=" part of the response, this allows |
307dc113 | 917 | you to map to the name you need. (mnemonic: empty label) |
4a305f6a JC |
918 | |
919 | $ echo "goodvfork="`./perl -Ilib -V::usevfork` | |
920 | goodvfork=false; | |
921 | ||
922 | Leading and trailing colons can be used together if you need | |
923 | positional parameter values without the names. Note that in the case | |
f4750dab | 924 | below, the C<PERL_API> params are returned in alphabetical order. |
4a305f6a JC |
925 | |
926 | $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now | |
927 | building_on 'linux' '5' '1' '9' now | |
a0d0e21e | 928 | |
19799a22 | 929 | =item B<-w> |
d74e8afc | 930 | X<-w> |
774d564b | 931 | |
19799a22 | 932 | prints warnings about dubious constructs, such as variable names |
f4750dab TC |
933 | mentioned only once and scalar variables used |
934 | before being set; redefined subroutines; references to undefined | |
935 | filehandles; filehandles opened read-only that you are attempting | |
936 | to write on; values used as a number that don't I<look> like numbers; | |
937 | using an array as though it were a scalar; if your subroutines | |
938 | recurse more than 100 deep; and innumerable other things. | |
939 | ||
940 | This switch really just enables the global C<$^W> variable; normally, | |
941 | the lexically scoped C<use warnings> pragma is preferred. You | |
19799a22 GS |
942 | can disable or promote into fatal errors specific warnings using |
943 | C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. | |
f4750dab | 944 | See also L<perldiag> and L<perltrap>. A fine-grained warning |
19799a22 | 945 | facility is also available if you want to manipulate entire classes |
44ecbbd8 | 946 | of warnings; see L<warnings>. |
a0d0e21e | 947 | |
0453d815 | 948 | =item B<-W> |
d74e8afc | 949 | X<-W> |
0453d815 | 950 | |
3c3f8cd6 | 951 | Enables all warnings regardless of C<no warnings> or C<$^W>. |
44ecbbd8 | 952 | See L<warnings>. |
0453d815 PM |
953 | |
954 | =item B<-X> | |
d74e8afc | 955 | X<-X> |
0453d815 | 956 | |
3c3f8cd6 | 957 | Disables all warnings regardless of C<use warnings> or C<$^W>. |
44ecbbd8 | 958 | See L<warnings>. |
0453d815 | 959 | |
eb992c6f | 960 | Forbidden in C<L</PERL5OPT>>. |
7cb9b5f3 | 961 | |
136e4fd6 | 962 | =item B<-x> |
d74e8afc | 963 | X<-x> |
136e4fd6 | 964 | |
d3bf4b0e | 965 | =item B<-x>I<directory> |
a0d0e21e | 966 | |
19799a22 | 967 | tells Perl that the program is embedded in a larger chunk of unrelated |
f4750dab TC |
968 | text, such as in a mail message. Leading garbage will be |
969 | discarded until the first line that starts with C<#!> and contains the | |
19799a22 | 970 | string "perl". Any meaningful switches on that line will be applied. |
3d6c2ba7 B |
971 | |
972 | All references to line numbers by the program (warnings, errors, ...) | |
f4750dab TC |
973 | will treat the C<#!> line as the first line. |
974 | Thus a warning on the 2nd line of the program, which is on the 100th | |
975 | line in the file will be reported as line 2, not as line 100. | |
976 | This can be overridden by using the C<#line> directive. | |
96090e4f | 977 | (See L<perlsyn/"Plain Old Comments (Not!)">) |
3d6c2ba7 | 978 | |
19799a22 GS |
979 | If a directory name is specified, Perl will switch to that directory |
980 | before running the program. The B<-x> switch controls only the | |
981 | disposal of leading garbage. The program must be terminated with | |
f4750dab TC |
982 | C<__END__> if there is trailing garbage to be ignored; the program |
983 | can process any or all of the trailing garbage via the C<DATA> filehandle | |
984 | if desired. | |
a0d0e21e | 985 | |
353c6505 | 986 | The directory, if specified, must appear immediately following the B<-x> |
d3bf4b0e DN |
987 | with no intervening whitespace. |
988 | ||
1e422769 | 989 | =back |
990 | ||
991 | =head1 ENVIRONMENT | |
d74e8afc | 992 | X<perl, environment variables> |
1e422769 | 993 | |
994 | =over 12 | |
995 | ||
996 | =item HOME | |
d74e8afc | 997 | X<HOME> |
1e422769 | 998 | |
f4750dab | 999 | Used if C<chdir> has no argument. |
1e422769 | 1000 | |
1001 | =item LOGDIR | |
d74e8afc | 1002 | X<LOGDIR> |
1e422769 | 1003 | |
f7a66378 | 1004 | Used if C<chdir> has no argument and L</HOME> is not set. |
1e422769 | 1005 | |
1006 | =item PATH | |
d74e8afc | 1007 | X<PATH> |
1e422769 | 1008 | |
f7a66378 | 1009 | Used in executing subprocesses, and in finding the program if L</-S> is |
1e422769 | 1010 | used. |
1011 | ||
1012 | =item PERL5LIB | |
d74e8afc | 1013 | X<PERL5LIB> |
1e422769 | 1014 | |
490a0bff LM |
1015 | A list of directories in which to look for Perl library files before |
1016 | looking in the standard library. | |
1017 | Any architecture-specific and version-specific directories, | |
4b85e17e AD |
1018 | such as F<version/archname/>, F<version/>, or F<archname/> under the |
1019 | specified locations are automatically included if they exist, with this | |
1020 | lookup done at interpreter startup time. In addition, any directories | |
1021 | matching the entries in C<$Config{inc_version_list}> are added. | |
1022 | (These typically would be for older compatible perl versions installed | |
1023 | in the same directory tree.) | |
69681433 | 1024 | |
f7a66378 | 1025 | If PERL5LIB is not defined, L</PERLLIB> is used. Directories are separated |
e1020413 | 1026 | (like in PATH) by a colon on Unixish platforms and by a semicolon on |
69681433 | 1027 | Windows (the proper path separator being given by the command C<perl |
f4750dab | 1028 | -V:I<path_sep>>). |
951ba7fe | 1029 | |
f4750dab | 1030 | When running taint checks, either because the program was running setuid or |
f7a66378 DB |
1031 | setgid, or the L</-T> or L</-t> switch was specified, neither PERL5LIB nor |
1032 | L</PERLLIB> is consulted. The program should instead say: | |
1e422769 | 1033 | |
1034 | use lib "/my/directory"; | |
1035 | ||
54310121 | 1036 | =item PERL5OPT |
d74e8afc | 1037 | X<PERL5OPT> |
54310121 | 1038 | |
f4750dab | 1039 | Command-line options (switches). Switches in this variable are treated |
3809fbed | 1040 | as if they were on every Perl command line. Only the B<-[CDIMTUWdmtw]> |
f4750dab | 1041 | switches are allowed. When running taint checks (either because the |
f7a66378 | 1042 | program was running setuid or setgid, or because the L</-T> or L</-t> |
f4750dab | 1043 | switch was used), this variable is ignored. If PERL5OPT begins with |
cce9fd8c | 1044 | B<-T>, tainting will be enabled and subsequent options ignored. If |
f4750dab TC |
1045 | PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot |
1046 | removed from @INC, and subsequent options honored. | |
54310121 | 1047 | |
16537909 | 1048 | =item PERLIO |
d74e8afc | 1049 | X<PERLIO> |
16537909 | 1050 | |
44a4342c | 1051 | A space (or colon) separated list of PerlIO layers. If perl is built |
f4750dab | 1052 | to use PerlIO system for IO (the default) these layers affect Perl's IO. |
44a4342c | 1053 | |
f4750dab TC |
1054 | It is conventional to start layer names with a colon (for example, C<:perlio>) to |
1055 | emphasize their similarity to variable "attributes". But the code that parses | |
cce9fd8c | 1056 | layer specification strings, which is also used to decode the PERLIO |
f4750dab | 1057 | environment variable, treats the colon as a separator. |
44a4342c | 1058 | |
5b64f2bf | 1059 | An unset or empty PERLIO is equivalent to the default set of layers for |
f4750dab | 1060 | your platform; for example, C<:unix:perlio> on Unix-like systems |
1f070127 | 1061 | and C<:unix:crlf> on Windows and other DOS-like systems. |
3b0db4f9 | 1062 | |
f4750dab TC |
1063 | The list becomes the default for I<all> Perl's IO. Consequently only built-in |
1064 | layers can appear in this list, as external layers (such as C<:encoding()>) need | |
cce9fd8c | 1065 | IO in order to load them! See L<"open pragma"|open> for how to add external |
44a4342c NIS |
1066 | encodings as defaults. |
1067 | ||
f4750dab TC |
1068 | Layers it makes sense to include in the PERLIO environment |
1069 | variable are briefly summarized below. For more details see L<PerlIO>. | |
16537909 JH |
1070 | |
1071 | =over 8 | |
1072 | ||
16537909 | 1073 | =item :crlf |
d74e8afc | 1074 | X<:crlf> |
16537909 | 1075 | |
f4750dab | 1076 | A layer which does CRLF to C<"\n"> translation distinguishing "text" and |
c151e3a7 DB |
1077 | "binary" files in the manner of MS-DOS and similar operating systems, |
1078 | and also provides buffering similar to C<:perlio> on these architectures. | |
16537909 | 1079 | |
44a4342c | 1080 | =item :perlio |
d74e8afc | 1081 | X<:perlio> |
16537909 | 1082 | |
f4750dab TC |
1083 | This is a re-implementation of stdio-like buffering written as a |
1084 | PerlIO layer. As such it will call whatever layer is below it for | |
1085 | its operations, typically C<:unix>. | |
16537909 | 1086 | |
44a4342c | 1087 | =item :stdio |
d74e8afc | 1088 | X<:stdio> |
44a4342c | 1089 | |
f4750dab | 1090 | This layer provides a PerlIO interface by wrapping system's ANSI C "stdio" |
44a4342c | 1091 | library calls. The layer provides both buffering and IO. |
f4750dab TC |
1092 | Note that the C<:stdio> layer does I<not> do CRLF translation even if that |
1093 | is the platform's normal behaviour. You will need a C<:crlf> layer above it | |
44a4342c NIS |
1094 | to do that. |
1095 | ||
1096 | =item :unix | |
d74e8afc | 1097 | X<:unix> |
44a4342c | 1098 | |
f4750dab | 1099 | Low-level layer that calls C<read>, C<write>, C<lseek>, etc. |
16537909 | 1100 | |
44a4342c | 1101 | =item :win32 |
d74e8afc | 1102 | X<:win32> |
44a4342c | 1103 | |
ab4f7683 | 1104 | On Win32 platforms this I<experimental> layer uses native "handle" IO |
f4750dab | 1105 | rather than a Unix-like numeric file descriptor layer. Known to be |
c151e3a7 | 1106 | buggy in this release (5.30). |
16537909 JH |
1107 | |
1108 | =back | |
1109 | ||
c151e3a7 | 1110 | The default set of layers should give acceptable results on all platforms. |
44a4342c | 1111 | |
c151e3a7 DB |
1112 | For Unix platforms that will be the equivalent of ":unix:perlio" or ":stdio". |
1113 | Configure is set up to prefer the ":stdio" implementation if the system's library | |
1114 | provides for fast access to the buffer (not common on modern architectures); | |
1115 | otherwise, it uses the ":unix:perlio" implementation. | |
44a4342c | 1116 | |
c151e3a7 | 1117 | On Win32 the default in this release (5.30) is ":unix:crlf". Win32's ":stdio" |
f4750dab | 1118 | has a number of bugs/mis-features for Perl IO which are somewhat depending |
c151e3a7 DB |
1119 | on the version and vendor of the C compiler. Using our own C<:crlf> layer as |
1120 | the buffer avoids those issues and makes things more uniform. | |
44a4342c | 1121 | |
c151e3a7 | 1122 | This release (5.30) uses C<:unix> as the bottom layer on Win32, and so still |
f4750dab | 1123 | uses the C compiler's numeric file descriptor routines. There is an |
c151e3a7 DB |
1124 | experimental native C<:win32> layer, which is expected to be enhanced and |
1125 | may eventually become the default under Win32. | |
44a4342c | 1126 | |
f4750dab | 1127 | The PERLIO environment variable is completely ignored when Perl |
5437faeb PF |
1128 | is run in taint mode. |
1129 | ||
44a4342c | 1130 | =item PERLIO_DEBUG |
d74e8afc | 1131 | X<PERLIO_DEBUG> |
44a4342c | 1132 | |
2104c695 | 1133 | If set to the name of a file or device when Perl is run with the |
f7a66378 DB |
1134 | L<-Di|/-Dletters> command-line switch, the logging of certain operations |
1135 | of the PerlIO subsystem will be redirected to the specified file rather | |
2104c695 CB |
1136 | than going to stderr, which is the default. The file is opened in append |
1137 | mode. Typical uses are in Unix: | |
44a4342c | 1138 | |
2104c695 | 1139 | % env PERLIO_DEBUG=/tmp/perlio.log perl -Di script ... |
44a4342c | 1140 | |
f4750dab | 1141 | and under Win32, the approximately equivalent: |
44a4342c | 1142 | |
f4750dab | 1143 | > set PERLIO_DEBUG=CON |
2104c695 | 1144 | perl -Di script ... |
44a4342c | 1145 | |
2104c695 | 1146 | This functionality is disabled for setuid scripts, for scripts run |
f7a66378 | 1147 | with L</-T>, and for scripts run on a Perl built without C<-DDEBUGGING> |
2104c695 | 1148 | support. |
16537909 | 1149 | |
1e422769 | 1150 | =item PERLLIB |
d74e8afc | 1151 | X<PERLLIB> |
1e422769 | 1152 | |
48b971ca | 1153 | A list of directories in which to look for Perl library |
490a0bff | 1154 | files before looking in the standard library. |
f7a66378 | 1155 | If L</PERL5LIB> is defined, PERLLIB is not used. |
1e422769 | 1156 | |
f4750dab | 1157 | The PERLLIB environment variable is completely ignored when Perl |
5437faeb PF |
1158 | is run in taint mode. |
1159 | ||
1e422769 | 1160 | =item PERL5DB |
d74e8afc | 1161 | X<PERL5DB> |
1e422769 | 1162 | |
1163 | The command used to load the debugger code. The default is: | |
1164 | ||
f4750dab | 1165 | BEGIN { require "perl5db.pl" } |
1e422769 | 1166 | |
f4750dab | 1167 | The PERL5DB environment variable is only used when Perl is started with |
f7a66378 | 1168 | a bare L</-d> switch. |
5437faeb | 1169 | |
2cbb2ee1 | 1170 | =item PERL5DB_THREADED |
d74e8afc | 1171 | X<PERL5DB_THREADED> |
2cbb2ee1 RGS |
1172 | |
1173 | If set to a true value, indicates to the debugger that the code being | |
1174 | debugged uses threads. | |
1175 | ||
19799a22 | 1176 | =item PERL5SHELL (specific to the Win32 port) |
d74e8afc | 1177 | X<PERL5SHELL> |
174c211a | 1178 | |
f4750dab TC |
1179 | On Win32 ports only, may be set to an alternative shell that Perl must use |
1180 | internally for executing "backtick" commands or system(). Default is | |
1181 | C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The | |
1182 | value is considered space-separated. Precede any character that | |
1183 | needs to be protected, like a space or backslash, with another backslash. | |
ce1da67e GS |
1184 | |
1185 | Note that Perl doesn't use COMSPEC for this purpose because | |
1186 | COMSPEC has a high degree of variability among users, leading to | |
f4750dab | 1187 | portability concerns. Besides, Perl can use a shell that may not be |
ce1da67e GS |
1188 | fit for interactive use, and setting COMSPEC to such a shell may |
1189 | interfere with the proper functioning of other programs (which usually | |
1190 | look in COMSPEC to find a shell fit for interactive use). | |
174c211a | 1191 | |
5437faeb PF |
1192 | Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked |
1193 | when running external commands. It is recommended that | |
1194 | you explicitly set (or delete) C<$ENV{PERL5SHELL}> when running | |
1195 | in taint mode under Windows. | |
1196 | ||
1c972609 | 1197 | =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port) |
d74e8afc | 1198 | X<PERL_ALLOW_NON_IFS_LSP> |
1c972609 | 1199 | |
f4750dab | 1200 | Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers). |
1c972609 SH |
1201 | Perl normally searches for an IFS-compatible LSP because this is required |
1202 | for its emulation of Windows sockets as real filehandles. However, this may | |
f4750dab TC |
1203 | cause problems if you have a firewall such as I<McAfee Guardian>, which requires |
1204 | that all applications use its LSP but which is not IFS-compatible, because clearly | |
1c972609 | 1205 | Perl will normally avoid using such an LSP. |
f4750dab | 1206 | |
1c972609 | 1207 | Setting this environment variable to 1 means that Perl will simply use the |
f4750dab TC |
1208 | first suitable LSP enumerated in the catalog, which keeps I<McAfee Guardian> |
1209 | happy--and in that particular case Perl still works too because I<McAfee | |
1210 | Guardian>'s LSP actually plays other games which allow applications | |
1211 | requiring IFS compatibility to work. | |
1c972609 | 1212 | |
1e422769 | 1213 | =item PERL_DEBUG_MSTATS |
d74e8afc | 1214 | X<PERL_DEBUG_MSTATS> |
1e422769 | 1215 | |
f4750dab TC |
1216 | Relevant only if Perl is compiled with the C<malloc> included with the Perl |
1217 | distribution; that is, if C<perl -V:d_mymalloc> is "define". | |
1218 | ||
1219 | If set, this dumps out memory statistics after execution. If set | |
1220 | to an integer greater than one, also dumps out memory statistics | |
1e422769 | 1221 | after compilation. |
1222 | ||
1223 | =item PERL_DESTRUCT_LEVEL | |
d74e8afc | 1224 | X<PERL_DESTRUCT_LEVEL> |
1e422769 | 1225 | |
8008a6e6 | 1226 | Controls the behaviour of global destruction of objects and other |
96090e4f | 1227 | references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information. |
a0d0e21e | 1228 | |
02c7413a | 1229 | =item PERL_DL_NONLAZY |
d74e8afc | 1230 | X<PERL_DL_NONLAZY> |
02c7413a | 1231 | |
f4750dab | 1232 | Set to C<"1"> to have Perl resolve I<all> undefined symbols when it loads |
02c7413a GA |
1233 | a dynamic library. The default behaviour is to resolve symbols when |
1234 | they are used. Setting this variable is useful during testing of | |
f4750dab TC |
1235 | extensions, as it ensures that you get an error on misspelled function |
1236 | names even if the test suite doesn't call them. | |
02c7413a | 1237 | |
5d170f3a | 1238 | =item PERL_ENCODING |
d74e8afc | 1239 | X<PERL_ENCODING> |
5d170f3a | 1240 | |
f4750dab | 1241 | If using the C<use encoding> pragma without an explicit encoding name, the |
5d170f3a JH |
1242 | PERL_ENCODING environment variable is consulted for an encoding name. |
1243 | ||
504f80c1 | 1244 | =item PERL_HASH_SEED |
d74e8afc | 1245 | X<PERL_HASH_SEED> |
504f80c1 | 1246 | |
6a5b4183 YO |
1247 | (Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override |
1248 | the randomization of Perl's internal hash function. The value is expressed | |
1249 | in hexadecimal, and may include a leading 0x. Truncated patterns | |
1250 | are treated as though they are suffixed with sufficient 0's as required. | |
8d4a1e6c | 1251 | |
6a5b4183 YO |
1252 | If the option is provided, and C<PERL_PERTURB_KEYS> is NOT set, then |
1253 | a value of '0' implies C<PERL_PERTURB_KEYS=0> and any other value | |
1254 | implies C<PERL_PERTURB_KEYS=2>. | |
504f80c1 | 1255 | |
f4750dab | 1256 | B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are |
26a2d347 | 1257 | randomized to protect against local and remote attacks against Perl |
f4750dab | 1258 | code. By manually setting a seed, this protection may be partially or |
26a2d347 JH |
1259 | completely lost. |
1260 | ||
4a70680a | 1261 | See L<perlsec/"Algorithmic Complexity Attacks">, L</PERL_PERTURB_KEYS>, and |
26a2d347 | 1262 | L</PERL_HASH_SEED_DEBUG> for more information. |
504f80c1 | 1263 | |
6a5b4183 YO |
1264 | =item PERL_PERTURB_KEYS |
1265 | X<PERL_PERTURB_KEYS> | |
1266 | ||
1267 | (Since Perl 5.18.0) Set to C<"0"> or C<"NO"> then traversing keys | |
f7a66378 | 1268 | will be repeatable from run to run for the same C<PERL_HASH_SEED>. |
6a5b4183 YO |
1269 | Insertion into a hash will not change the order, except to provide |
1270 | for more space in the hash. When combined with setting PERL_HASH_SEED | |
1271 | this mode is as close to pre 5.18 behavior as you can get. | |
1272 | ||
1273 | When set to C<"1"> or C<"RANDOM"> then traversing keys will be randomized. | |
1274 | Every time a hash is inserted into the key order will change in a random | |
e6b54db6 | 1275 | fashion. The order may not be repeatable in a following program run |
6a5b4183 YO |
1276 | even if the PERL_HASH_SEED has been specified. This is the default |
1277 | mode for perl. | |
1278 | ||
1279 | When set to C<"2"> or C<"DETERMINISTIC"> then inserting keys into a hash | |
e6b54db6 | 1280 | will cause the key order to change, but in a way that is repeatable |
6a5b4183 YO |
1281 | from program run to program run. |
1282 | ||
1283 | B<NOTE:> Use of this option is considered insecure, and is intended only | |
1284 | for debugging non-deterministic behavior in Perl's hash function. Do | |
1285 | not use it in production. | |
1286 | ||
1287 | See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_HASH_SEED> | |
1288 | and L</PERL_HASH_SEED_DEBUG> for more information. You can get and set the | |
1289 | key traversal mask for a specific hash by using the C<hash_traversal_mask()> | |
1290 | function from L<Hash::Util>. | |
1291 | ||
2191697e | 1292 | =item PERL_HASH_SEED_DEBUG |
d74e8afc | 1293 | X<PERL_HASH_SEED_DEBUG> |
2191697e | 1294 | |
6a5b4183 YO |
1295 | (Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) information |
1296 | about the hash function, seed, and what type of key traversal | |
1297 | randomization is in effect at the beginning of execution. This, combined | |
1298 | with L</PERL_HASH_SEED> and L</PERL_PERTURB_KEYS> is intended to aid in | |
1299 | debugging nondeterministic behaviour caused by hash randomization. | |
1300 | ||
1301 | B<Note> that any information about the hash function, especially the hash | |
1302 | seed is B<sensitive information>: by knowing it, one can craft a denial-of-service | |
1303 | attack against Perl code, even remotely; see L<perlsec/"Algorithmic Complexity Attacks"> | |
1304 | for more information. B<Do not disclose the hash seed> to people who | |
f420138f KW |
1305 | don't need to know it. See also L<C<hash_seed()>|Hash::Util/hash_seed> and |
1306 | L<C<hash_traversal_mask()>|Hash::Util/hash_traversal_mask>. | |
6a5b4183 YO |
1307 | |
1308 | An example output might be: | |
26a2d347 | 1309 | |
e46aa1dd | 1310 | HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM) |
2191697e | 1311 | |
9aa9f499 JC |
1312 | =item PERL_MEM_LOG |
1313 | X<PERL_MEM_LOG> | |
1314 | ||
f4750dab | 1315 | If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting |
7916a455 | 1316 | the environment variable C<PERL_MEM_LOG> enables logging debug |
f4750dab TC |
1317 | messages. The value has the form C<< <I<number>>[m][s][t] >>, where |
1318 | C<I<number>> is the file descriptor number you want to write to (2 is | |
7916a455 JC |
1319 | default), and the combination of letters specifies that you want |
1320 | information about (m)emory and/or (s)v, optionally with | |
f4750dab TC |
1321 | (t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all |
1322 | information to stdout. You can write to other opened file descriptors | |
1323 | in a variety of ways: | |
9aa9f499 | 1324 | |
f4750dab | 1325 | $ 3>foo3 PERL_MEM_LOG=3m perl ... |
9aa9f499 | 1326 | |
3d0ae7ba | 1327 | =item PERL_ROOT (specific to the VMS port) |
d74e8afc | 1328 | X<PERL_ROOT> |
3d0ae7ba | 1329 | |
f4750dab | 1330 | A translation-concealed rooted logical name that contains Perl and the |
3d0ae7ba | 1331 | logical device for the @INC path on VMS only. Other logical names that |
f4750dab TC |
1332 | affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and |
1333 | SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in | |
3d0ae7ba GS |
1334 | L<perlvms> and in F<README.vms> in the Perl source distribution. |
1335 | ||
4ffa73a3 | 1336 | =item PERL_SIGNALS |
d74e8afc | 1337 | X<PERL_SIGNALS> |
4ffa73a3 | 1338 | |
f4750dab TC |
1339 | Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0 |
1340 | signal behaviour (which is immediate but unsafe) is restored. If set | |
1341 | to C<safe>, then safe (but deferred) signals are used. See | |
1342 | L<perlipc/"Deferred Signals (Safe Signals)">. | |
4ffa73a3 | 1343 | |
a05d7ebb | 1344 | =item PERL_UNICODE |
d74e8afc | 1345 | X<PERL_UNICODE> |
acae81db | 1346 | |
f7a66378 DB |
1347 | Equivalent to the L<-C|/-C [numberE<sol>list]> command-line switch. Note |
1348 | that this is not a boolean variable. Setting this to C<"1"> is not the | |
1349 | right way to "enable Unicode" (whatever that would mean). You can use | |
1350 | C<"0"> to "disable Unicode", though (or alternatively unset PERL_UNICODE | |
1351 | in your shell before starting Perl). See the description of the | |
1352 | L<-C|/-C [numberE<sol>list]> switch for more information. | |
acae81db | 1353 | |
c12592fc DIM |
1354 | =item PERL_USE_UNSAFE_INC |
1355 | X<PERL_USE_UNSAFE_INC> | |
1356 | ||
1357 | If perl has been configured to not have the current directory in | |
1358 | L<C<@INC>|perlvar/@INC> by default, this variable can be set to C<"1"> | |
1359 | to reinstate it. It's primarily intended for use while building and | |
1360 | testing modules that have not been updated to deal with "." not being in | |
1361 | C<@INC> and should not be set in the environment for day-to-day use. | |
1362 | ||
3d0ae7ba | 1363 | =item SYS$LOGIN (specific to the VMS port) |
d74e8afc | 1364 | X<SYS$LOGIN> |
3d0ae7ba | 1365 | |
f7a66378 | 1366 | Used if chdir has no argument and L</HOME> and L</LOGDIR> are not set. |
3d0ae7ba | 1367 | |
d6295071 TC |
1368 | =item PERL_INTERNAL_RAND_SEED |
1369 | X<PERL_INTERNAL_RAND_SEED> | |
1370 | ||
1371 | Set to a non-negative integer to seed the random number generator used | |
1372 | internally by perl for a variety of purposes. | |
1373 | ||
1374 | Ignored if perl is run setuid or setgid. Used only for some limited | |
1375 | startup randomization (hash keys) if C<-T> or C<-t> perl is started | |
1376 | with tainting enabled. | |
1377 | ||
1378 | Perl may be built to ignore this variable. | |
1379 | ||
a0d0e21e | 1380 | =back |
1e422769 | 1381 | |
1382 | Perl also has environment variables that control how Perl handles data | |
f4750dab TC |
1383 | specific to particular natural languages; see L<perllocale>. |
1384 | ||
1385 | Perl and its various modules and components, including its test frameworks, | |
1386 | may sometimes make use of certain other environment variables. Some of | |
1387 | these are specific to a particular platform. Please consult the | |
1388 | appropriate module documentation and any documentation for your platform | |
1389 | (like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for | |
1390 | variables peculiar to those specific situations. | |
1391 | ||
1392 | Perl makes all environment variables available to the program being | |
1393 | executed, and passes these along to any child processes it starts. | |
1394 | However, programs running setuid would do well to execute the following | |
1395 | lines before doing anything else, just to keep people honest: | |
1396 | ||
1397 | $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need | |
1398 | $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL}; | |
c90c0ff4 | 1399 | delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; |
f2244568 DC |
1400 | |
1401 | =head1 ORDER OF APPLICATION | |
1402 | ||
1403 | Some options, in particular C<-I>, C<-M>, C<PERL5LIB> and C<PERL5OPT> can | |
1404 | interact, and the order in which they are applied is important. | |
1405 | ||
7c3683af DC |
1406 | Note that this section does not document what I<actually> happens inside the |
1407 | perl interpreter, it documents what I<effectively> happens. | |
f2244568 DC |
1408 | |
1409 | =over | |
1410 | ||
1411 | =item -I | |
1412 | ||
1413 | The effect of multiple C<-I> options is to C<unshift> them onto C<@INC> | |
1414 | from right to left. So for example: | |
1415 | ||
1416 | perl -I 1 -I 2 -I 3 | |
1417 | ||
1418 | will first prepend C<3> onto the front of C<@INC>, then prepend C<2>, and | |
1419 | then prepend C<1>. The result is that C<@INC> begins with: | |
1420 | ||
1421 | qw(1 2 3) | |
1422 | ||
1423 | =item -M | |
1424 | ||
1425 | Multiple C<-M> options are processed from left to right. So this: | |
1426 | ||
1427 | perl -Mlib=1 -Mlib=2 -Mlib=3 | |
1428 | ||
1429 | will first use the L<lib> pragma to prepend C<1> to C<@INC>, then | |
1430 | it will prepend C<2>, then it will prepend C<3>, resulting in an C<@INC> | |
1431 | that begins with: | |
1432 | ||
1433 | qw(3 2 1) | |
1434 | ||
1435 | =item the PERL5LIB environment variable | |
1436 | ||
1437 | This contains a list of directories, separated by colons. The entire list | |
1438 | is prepended to C<@INC> in one go. This: | |
1439 | ||
1440 | PERL5LIB=1:2:3 perl | |
1441 | ||
1442 | will result in an C<@INC> that begins with: | |
1443 | ||
1444 | qw(1 2 3) | |
1445 | ||
1446 | =item combinations of -I, -M and PERL5LIB | |
1447 | ||
1448 | C<PERL5LIB> is applied first, then all the C<-I> arguments, then all the | |
1449 | C<-M> arguments. This: | |
1450 | ||
1451 | PERL5LIB=e1:e2 perl -I i1 -Mlib=m1 -I i2 -Mlib=m2 | |
1452 | ||
1453 | will result in an C<@INC> that begins with: | |
1454 | ||
1455 | qw(m2 m1 i1 i2 e1 e2) | |
1456 | ||
1457 | =item the PERL5OPT environment variable | |
1458 | ||
1459 | This contains a space separated list of switches. We only consider the | |
1460 | effects of C<-M> and C<-I> in this section. | |
1461 | ||
1462 | After normal processing of C<-I> switches from the command line, all | |
1463 | the C<-I> switches in C<PERL5OPT> are extracted. They are processed from | |
1464 | left to right instead of from right to left. Also note that while | |
1465 | whitespace is allowed between a C<-I> and its directory on the command | |
1466 | line, it is not allowed in C<PERL5OPT>. | |
1467 | ||
1468 | After normal processing of C<-M> switches from the command line, all | |
1469 | the C<-M> switches in C<PERL5OPT> are extracted. They are processed from | |
7c3683af | 1470 | left to right, I<i.e.> the same as those on the command line. |
f2244568 | 1471 | |
7c3683af | 1472 | An example may make this clearer: |
f2244568 DC |
1473 | |
1474 | export PERL5OPT="-Mlib=optm1 -Iopti1 -Mlib=optm2 -Iopti2" | |
1475 | export PERL5LIB=e1:e2 | |
1476 | perl -I i1 -Mlib=m1 -I i2 -Mlib=m2 | |
1477 | ||
1478 | will result in an C<@INC> that begins with: | |
1479 | ||
1480 | qw( | |
1481 | optm2 | |
1482 | optm1 | |
1483 | ||
1484 | m2 | |
1485 | m1 | |
1486 | ||
1487 | opti2 | |
1488 | opti1 | |
1489 | ||
1490 | i1 | |
1491 | i2 | |
1492 | ||
1493 | e1 | |
1494 | e2 | |
1495 | ) | |
1496 | ||
7c3683af DC |
1497 | =item Other complications |
1498 | ||
1499 | There are some complications that are ignored in the examples above: | |
1500 | ||
1501 | =over | |
1502 | ||
1503 | =item arch and version subdirs | |
1504 | ||
1505 | All of C<-I>, C<PERL5LIB> and C<use lib> will also prepend arch and version | |
1506 | subdirs if they are present | |
1507 | ||
1508 | =item sitecustomize.pl | |
1509 | ||
f2244568 | 1510 | =back |
8d84f763 DC |
1511 | |
1512 | =back |