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