Commit | Line | Data |
a0d0e21e |
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>] ]> |
9 | S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]> |
10 | S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]> |
11 | S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]> |
12 | S<[ B<-P> ]> |
13 | S<[ B<-S> ]> |
14 | S<[ B<-x>[I<dir>] ]> |
15 | S<[ B<-i>[I<extension>] ]> |
16 | S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...> |
a05d7ebb |
17 | S<[ B<-C [I<number/list>] >]> ]> |
a0d0e21e |
18 | |
19 | =head1 DESCRIPTION |
20 | |
19799a22 |
21 | The normal way to run a Perl program is by making it directly |
22 | executable, or else by passing the name of the source file as an |
23 | argument on the command line. (An interactive Perl environment |
24 | is also possible--see L<perldebug> for details on how to do that.) |
25 | Upon startup, Perl looks for your program in one of the following |
a0d0e21e |
26 | places: |
27 | |
28 | =over 4 |
29 | |
30 | =item 1. |
31 | |
32 | Specified line by line via B<-e> switches on the command line. |
33 | |
34 | =item 2. |
35 | |
36 | Contained in the file specified by the first filename on the command line. |
a3cb178b |
37 | (Note that systems supporting the #! notation invoke interpreters this |
38 | way. See L<Location of Perl>.) |
a0d0e21e |
39 | |
40 | =item 3. |
41 | |
5f05dabc |
42 | Passed in implicitly via standard input. This works only if there are |
19799a22 |
43 | no filename arguments--to pass arguments to a STDIN-read program you |
44 | must explicitly specify a "-" for the program name. |
a0d0e21e |
45 | |
46 | =back |
47 | |
48 | With methods 2 and 3, Perl starts parsing the input file from the |
49 | beginning, unless you've specified a B<-x> switch, in which case it |
50 | scans for the first line starting with #! and containing the word |
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 | |
5f05dabc |
55 | The #! line is always examined for switches as the line is being |
56 | parsed. Thus, if you're on a machine that allows only one argument |
57 | with the #! line, or worse, doesn't even recognize the #! line, you |
58 | still can get consistent switch behavior regardless of how Perl was |
19799a22 |
59 | invoked, even if B<-x> was used to find the beginning of the program. |
60 | |
61 | Because historically some operating systems silently chopped off |
62 | kernel interpretation of the #! line after 32 characters, some |
63 | switches may be passed in on the command line, and some may not; |
64 | you could even get a "-" without its letter, if you're not careful. |
65 | You probably want to make sure that all your switches fall either |
66 | before or after that 32-character boundary. Most switches don't |
67 | actually care if they're processed redundantly, but getting a "-" |
68 | instead of a complete switch could cause Perl to try to execute |
69 | standard input instead of your program. And a partial B<-I> switch |
a0d0e21e |
70 | could also cause odd results. |
71 | |
19799a22 |
72 | Some switches do care if they are processed twice, for instance |
73 | combinations of B<-l> and B<-0>. Either put all the switches after |
74 | the 32-character boundary (if applicable), or replace the use of |
75 | B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>. |
fb73857a |
76 | |
a0d0e21e |
77 | Parsing of the #! switches starts wherever "perl" is mentioned in the line. |
78 | The sequences "-*" and "- " are specifically ignored so that you could, |
79 | if you were so inclined, say |
80 | |
81 | #!/bin/sh -- # -*- perl -*- -p |
19799a22 |
82 | eval 'exec perl -wS $0 ${1+"$@"}' |
5f05dabc |
83 | if $running_under_some_shell; |
a0d0e21e |
84 | |
44a4342c |
85 | to let Perl see the B<-p> switch. |
19799a22 |
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 |
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 |
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 |
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 |
112 | |
113 | Unix's #! technique can be simulated on other systems: |
114 | |
115 | =over 4 |
116 | |
117 | =item OS/2 |
118 | |
119 | Put |
120 | |
121 | extproc perl -S -your_switches |
122 | |
19799a22 |
123 | as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's |
68dc0745 |
124 | `extproc' handling). |
125 | |
54310121 |
126 | =item MS-DOS |
68dc0745 |
127 | |
19799a22 |
128 | Create a batch file to run your program, and codify it in |
68dc0745 |
129 | C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source |
130 | distribution for more information). |
131 | |
132 | =item Win95/NT |
133 | |
6c6a61e2 |
134 | The Win95/NT installation, when using the ActiveState installer for Perl, |
c8db1d39 |
135 | will modify the Registry to associate the F<.pl> extension with the perl |
6c6a61e2 |
136 | interpreter. If you install Perl by other means (including building from |
137 | the sources), you may have to modify the Registry yourself. Note that |
138 | this means you can no longer tell the difference between an executable |
139 | Perl program and a Perl library file. |
68dc0745 |
140 | |
141 | =item Macintosh |
142 | |
19799a22 |
143 | A Macintosh perl program will have the appropriate Creator and |
68dc0745 |
144 | Type, so that double-clicking them will invoke the perl application. |
145 | |
bd3fa61c |
146 | =item VMS |
147 | |
148 | Put |
149 | |
150 | $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' ! |
151 | $ exit++ + ++$status != 0 and $exit = $status = undef; |
152 | |
19799a22 |
153 | at the top of your program, where B<-mysw> are any command line switches you |
154 | want to pass to Perl. You can now invoke the program directly, by saying |
155 | C<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly |
156 | via F<DCL$PATH> by just using the name of the program). |
bd3fa61c |
157 | |
158 | This incantation is a bit much to remember, but Perl will display it for |
159 | you if you say C<perl "-V:startperl">. |
160 | |
68dc0745 |
161 | =back |
162 | |
163 | Command-interpreters on non-Unix systems have rather different ideas |
164 | on quoting than Unix shells. You'll need to learn the special |
165 | characters in your command-interpreter (C<*>, C<\> and C<"> are |
166 | common) and how to protect whitespace and these characters to run |
19799a22 |
167 | one-liners (see B<-e> below). |
68dc0745 |
168 | |
169 | On some systems, you may have to change single-quotes to double ones, |
e6f03d26 |
170 | which you must I<not> do on Unix or Plan 9 systems. You might also |
68dc0745 |
171 | have to change a single % to a %%. |
172 | |
173 | For example: |
174 | |
175 | # Unix |
176 | perl -e 'print "Hello world\n"' |
177 | |
54310121 |
178 | # MS-DOS, etc. |
68dc0745 |
179 | perl -e "print \"Hello world\n\"" |
180 | |
54310121 |
181 | # Macintosh |
68dc0745 |
182 | print "Hello world\n" |
183 | (then Run "Myscript" or Shift-Command-R) |
184 | |
185 | # VMS |
186 | perl -e "print ""Hello world\n""" |
187 | |
19799a22 |
188 | The problem is that none of this is reliable: it depends on the |
189 | command and it is entirely possible neither works. If B<4DOS> were |
190 | the command shell, this would probably work better: |
68dc0745 |
191 | |
192 | perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" |
193 | |
19799a22 |
194 | B<CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in |
68dc0745 |
195 | when nobody was looking, but just try to find documentation for its |
196 | quoting rules. |
197 | |
54310121 |
198 | Under the Macintosh, it depends which environment you are using. The MacPerl |
68dc0745 |
199 | shell, or MPW, is much like Unix shells in its support for several |
54310121 |
200 | quoting variants, except that it makes free use of the Macintosh's non-ASCII |
68dc0745 |
201 | characters as control characters. |
202 | |
203 | There is no general solution to all of this. It's just a mess. |
204 | |
a3cb178b |
205 | =head2 Location of Perl |
206 | |
207 | It may seem obvious to say, but Perl is useful only when users can |
19799a22 |
208 | easily find it. When possible, it's good for both F</usr/bin/perl> |
209 | and F</usr/local/bin/perl> to be symlinks to the actual binary. If |
210 | that can't be done, system administrators are strongly encouraged |
211 | to put (symlinks to) perl and its accompanying utilities into a |
212 | directory typically found along a user's PATH, or in some other |
213 | obvious and convenient place. |
214 | |
215 | In this documentation, C<#!/usr/bin/perl> on the first line of the program |
216 | will stand in for whatever method works on your system. You are |
217 | advised to use a specific path if you care about a specific version. |
a3cb178b |
218 | |
19799a22 |
219 | #!/usr/local/bin/perl5.00554 |
a3cb178b |
220 | |
19799a22 |
221 | or if you just want to be running at least version, place a statement |
222 | like this at the top of your program: |
a0d0e21e |
223 | |
19799a22 |
224 | use 5.005_54; |
a0d0e21e |
225 | |
19799a22 |
226 | =head2 Command Switches |
227 | |
228 | As with all standard commands, a single-character switch may be |
229 | clustered with the following switch, if any. |
230 | |
231 | #!/usr/bin/perl -spi.orig # same as -s -p -i.orig |
a0d0e21e |
232 | |
233 | Switches include: |
234 | |
235 | =over 5 |
236 | |
e0ebc809 |
237 | =item B<-0>[I<digits>] |
a0d0e21e |
238 | |
55497cff |
239 | specifies the input record separator (C<$/>) as an octal number. If there are |
a0d0e21e |
240 | no digits, the null character is the separator. Other switches may |
241 | precede or follow the digits. For example, if you have a version of |
242 | B<find> which can print filenames terminated by the null character, you |
243 | can say this: |
244 | |
19799a22 |
245 | find . -name '*.orig' -print0 | perl -n0e unlink |
a0d0e21e |
246 | |
247 | The special value 00 will cause Perl to slurp files in paragraph mode. |
5f05dabc |
248 | The value 0777 will cause Perl to slurp files whole because there is no |
a0d0e21e |
249 | legal character with that value. |
250 | |
251 | =item B<-a> |
252 | |
253 | turns on autosplit mode when used with a B<-n> or B<-p>. An implicit |
254 | split command to the @F array is done as the first thing inside the |
255 | implicit while loop produced by the B<-n> or B<-p>. |
256 | |
257 | perl -ane 'print pop(@F), "\n";' |
258 | |
259 | is equivalent to |
260 | |
261 | while (<>) { |
262 | @F = split(' '); |
263 | print pop(@F), "\n"; |
264 | } |
265 | |
266 | An alternate delimiter may be specified using B<-F>. |
267 | |
a05d7ebb |
268 | =item B<-C [I<number/list>]> |
46487f74 |
269 | |
a05d7ebb |
270 | The C<-C> flag controls some Unicode of the Perl Unicode features. |
271 | |
272 | As of 5.8.1, the C<-C> can be followed either by a number or a list |
273 | of option letters. |
274 | |
275 | I 0x0001 STDIN is assumed to be in UTF-8 |
276 | O 0x0002 STDOUT will be in UTF-8 |
277 | E 0x0004 STDERR will be in UTF-8 |
278 | S 0x0007 I + O + E |
279 | i 0x0008 the default input layer expects UTF-8 |
280 | o 0x0010 the default output layer enforces UTF-8 |
281 | D 0x0018 i + o |
282 | A 0x0020 the @ARGV elements are supposed to be in UTF-8 |
283 | L 0x0040 normally the IOEio (SD) are unconditional, |
284 | the L makes them conditional on the locale environment |
285 | variables (the LC_ALL, LC_TYPE, and LANG; in the order |
286 | of decreasing precedence) |
287 | |
288 | The C<-C> on its own (not followed by any number or option list) has |
289 | the same effect as <-CSDL>. In other words, the standard I/O handles |
290 | and the default C<open()> layer are UTF-8-fied B<but> only if the locale |
291 | environment variables indicate a UTF-8 locale. This behavior follows |
292 | the I<implicit> behaviour of Perl 5.8.0. |
293 | |
294 | You can use C<-C0> to explicitly disable all the above Unicode features. |
fde18df1 |
295 | |
fde18df1 |
296 | See L<perluniintro>, L<perlfunc/open>, and L<open> for more information. |
a05d7ebb |
297 | |
298 | The magic variable C<${^UNICODE}> reflects the state of this setting, |
299 | see L<perlvar/"${^UNICODE}">. (Another way of setting this variable |
300 | is to set the environment variable PERL_UNICODE.) |
fde18df1 |
301 | |
302 | (In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch |
303 | that enabled the use of Unicode-aware "wide system call" Win32 APIs. |
304 | This feature was practically unused, however, and the command line |
305 | switch was therefore "recycled".) |
46487f74 |
306 | |
a0d0e21e |
307 | =item B<-c> |
308 | |
19799a22 |
309 | causes Perl to check the syntax of the program and then exit without |
7d30b5c4 |
310 | executing it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and |
4f25aa18 |
311 | C<use> blocks, because these are considered as occurring outside the |
312 | execution of your program. C<INIT> and C<END> blocks, however, will |
313 | be skipped. |
a0d0e21e |
314 | |
315 | =item B<-d> |
316 | |
19799a22 |
317 | runs the program under the Perl debugger. See L<perldebug>. |
a0d0e21e |
318 | |
70c94a19 |
319 | =item B<-d:>I<foo[=bar,baz]> |
3c81428c |
320 | |
19799a22 |
321 | runs the program under the control of a debugging, profiling, or |
322 | tracing module installed as Devel::foo. E.g., B<-d:DProf> executes |
70c94a19 |
323 | the program using the Devel::DProf profiler. As with the B<-M> |
324 | flag, options may be passed to the Devel::foo package where they |
325 | will be received and interpreted by the Devel::foo::import routine. |
326 | The comma-separated list of options must follow a C<=> character. |
327 | See L<perldebug>. |
3c81428c |
328 | |
db2ba183 |
329 | =item B<-D>I<letters> |
a0d0e21e |
330 | |
db2ba183 |
331 | =item B<-D>I<number> |
a0d0e21e |
332 | |
19799a22 |
333 | sets debugging flags. To watch how it executes your program, use |
db2ba183 |
334 | B<-Dtls>. (This works only if debugging is compiled into your |
335 | Perl.) Another nice value is B<-Dx>, which lists your compiled |
4197b13f |
336 | syntax tree. And B<-Dr> displays compiled regular expressions; |
44a4342c |
337 | the format of the output is explained in L<perldebguts>. |
4197b13f |
338 | |
339 | As an alternative, specify a number instead of list of letters (e.g., |
340 | B<-D14> is equivalent to B<-Dtls>): |
a0d0e21e |
341 | |
db2ba183 |
342 | 1 p Tokenizing and parsing |
343 | 2 s Stack snapshots |
d6721266 |
344 | with v, displays all stacks |
db2ba183 |
345 | 4 l Context (loop) stack processing |
346 | 8 t Trace execution |
347 | 16 o Method and overloading resolution |
348 | 32 c String/numeric conversions |
1045810a |
349 | 64 P Print profiling info, preprocessor command for -P, source file input state |
db2ba183 |
350 | 128 m Memory allocation |
351 | 256 f Format processing |
352 | 512 r Regular expression parsing and execution |
353 | 1024 x Syntax tree dump |
354 | 2048 u Tainting checks |
7bab3ede |
355 | 4096 (Obsolete, previously used for LEAKTEST) |
db2ba183 |
356 | 8192 H Hash dump -- usurps values() |
357 | 16384 X Scratchpad allocation |
358 | 32768 D Cleaning up |
8b73bbec |
359 | 65536 S Thread synchronization |
607df283 |
360 | 131072 T Tokenising |
04932ac8 |
361 | 262144 R Include reference counts of dumped variables (eg when using -Ds) |
1045810a |
362 | 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB |
d6721266 |
363 | 1048576 v Verbose: use in conjunction with other flags |
46187eeb |
364 | 2097152 C Copy On Write |
a0d0e21e |
365 | |
19799a22 |
366 | All these flags require B<-DDEBUGGING> when you compile the Perl |
1045810a |
367 | executable (but see L<Devel::Peek>, L<re> which may change this). |
44a4342c |
368 | See the F<INSTALL> file in the Perl source distribution |
19799a22 |
369 | for how to do this. This flag is automatically set if you include B<-g> |
8c52afec |
370 | option when C<Configure> asks you about optimizer/debugger flags. |
371 | |
19799a22 |
372 | If you're just trying to get a print out of each line of Perl code |
373 | as it executes, the way that C<sh -x> provides for shell scripts, |
44a4342c |
374 | you can't use Perl's B<-D> switch. Instead do this |
19799a22 |
375 | |
c406981e |
376 | # If you have "env" utility |
377 | env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program |
378 | |
19799a22 |
379 | # Bourne shell syntax |
380 | $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program |
381 | |
382 | # csh syntax |
383 | % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program) |
384 | |
385 | See L<perldebug> for details and variations. |
386 | |
a0d0e21e |
387 | =item B<-e> I<commandline> |
388 | |
19799a22 |
389 | may be used to enter one line of program. If B<-e> is given, Perl |
390 | will not look for a filename in the argument list. Multiple B<-e> |
391 | commands may be given to build up a multi-line script. Make sure |
392 | to use semicolons where you would in a normal program. |
a0d0e21e |
393 | |
e0ebc809 |
394 | =item B<-F>I<pattern> |
a0d0e21e |
395 | |
e0ebc809 |
396 | specifies the pattern to split on if B<-a> is also in effect. The |
5f05dabc |
397 | pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be |
e0ebc809 |
398 | put in single quotes. |
a0d0e21e |
399 | |
e0ebc809 |
400 | =item B<-h> |
401 | |
402 | prints a summary of the options. |
403 | |
404 | =item B<-i>[I<extension>] |
a0d0e21e |
405 | |
2d259d92 |
406 | specifies that files processed by the C<E<lt>E<gt>> construct are to be |
407 | edited in-place. It does this by renaming the input file, opening the |
408 | output file by the original name, and selecting that output file as the |
409 | default for print() statements. The extension, if supplied, is used to |
410 | modify the name of the old file to make a backup copy, following these |
411 | rules: |
412 | |
413 | If no extension is supplied, no backup is made and the current file is |
414 | overwritten. |
415 | |
19799a22 |
416 | If the extension doesn't contain a C<*>, then it is appended to the |
417 | end of the current filename as a suffix. If the extension does |
418 | contain one or more C<*> characters, then each C<*> is replaced |
419 | with the current filename. In Perl terms, you could think of this |
420 | as: |
2d259d92 |
421 | |
66606d78 |
422 | ($backup = $extension) =~ s/\*/$file_name/g; |
2d259d92 |
423 | |
424 | This allows you to add a prefix to the backup file, instead of (or in |
425 | addition to) a suffix: |
426 | |
19799a22 |
427 | $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA' |
2d259d92 |
428 | |
429 | Or even to place backup copies of the original files into another |
430 | directory (provided the directory already exists): |
431 | |
19799a22 |
432 | $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig' |
2d259d92 |
433 | |
66606d78 |
434 | These sets of one-liners are equivalent: |
435 | |
436 | $ perl -pi -e 's/bar/baz/' fileA # overwrite current file |
19799a22 |
437 | $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file |
66606d78 |
438 | |
19799a22 |
439 | $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' |
440 | $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig' |
66606d78 |
441 | |
2d259d92 |
442 | From the shell, saying |
a0d0e21e |
443 | |
19799a22 |
444 | $ perl -p -i.orig -e "s/foo/bar/; ... " |
a0d0e21e |
445 | |
19799a22 |
446 | is the same as using the program: |
a0d0e21e |
447 | |
19799a22 |
448 | #!/usr/bin/perl -pi.orig |
a0d0e21e |
449 | s/foo/bar/; |
450 | |
451 | which is equivalent to |
452 | |
453 | #!/usr/bin/perl |
19799a22 |
454 | $extension = '.orig'; |
455 | LINE: while (<>) { |
a0d0e21e |
456 | if ($ARGV ne $oldargv) { |
66606d78 |
457 | if ($extension !~ /\*/) { |
458 | $backup = $ARGV . $extension; |
459 | } |
460 | else { |
461 | ($backup = $extension) =~ s/\*/$ARGV/g; |
462 | } |
463 | rename($ARGV, $backup); |
a0d0e21e |
464 | open(ARGVOUT, ">$ARGV"); |
465 | select(ARGVOUT); |
466 | $oldargv = $ARGV; |
467 | } |
468 | s/foo/bar/; |
469 | } |
470 | continue { |
471 | print; # this prints to original filename |
472 | } |
473 | select(STDOUT); |
474 | |
475 | except that the B<-i> form doesn't need to compare $ARGV to $oldargv to |
476 | know when the filename has changed. It does, however, use ARGVOUT for |
66606d78 |
477 | the selected filehandle. Note that STDOUT is restored as the default |
478 | output filehandle after the loop. |
479 | |
480 | As shown above, Perl creates the backup file whether or not any output |
481 | is actually changed. So this is just a fancy way to copy files: |
482 | |
cd2d1bac |
483 | $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3... |
19799a22 |
484 | or |
cd2d1bac |
485 | $ perl -p -i'.orig' -e 1 file1 file2 file3... |
66606d78 |
486 | |
487 | You can use C<eof> without parentheses to locate the end of each input |
488 | file, in case you want to append to each file, or reset line numbering |
489 | (see example in L<perlfunc/eof>). |
490 | |
491 | If, for a given file, Perl is unable to create the backup file as |
492 | specified in the extension then it will skip that file and continue on |
493 | with the next one (if it exists). |
494 | |
19799a22 |
495 | For a discussion of issues surrounding file permissions and B<-i>, |
cea6626f |
496 | 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 |
497 | |
498 | You cannot use B<-i> to create directories or to strip extensions from |
499 | files. |
a0d0e21e |
500 | |
19799a22 |
501 | Perl does not expand C<~> in filenames, which is good, since some |
502 | folks use it for their backup files: |
a0d0e21e |
503 | |
19799a22 |
504 | $ perl -pi~ -e 's/foo/bar/' file1 file2 file3... |
505 | |
506 | Finally, the B<-i> switch does not impede execution when no |
a2008d6d |
507 | files are given on the command line. In this case, no backup is made |
508 | (the original file cannot, of course, be determined) and processing |
509 | proceeds from STDIN to STDOUT as might be expected. |
510 | |
a0d0e21e |
511 | =item B<-I>I<directory> |
512 | |
e0ebc809 |
513 | Directories specified by B<-I> are prepended to the search path for |
1fef88e7 |
514 | modules (C<@INC>), and also tells the C preprocessor where to search for |
e0ebc809 |
515 | include files. The C preprocessor is invoked with B<-P>; by default it |
516 | searches /usr/include and /usr/lib/perl. |
a0d0e21e |
517 | |
e0ebc809 |
518 | =item B<-l>[I<octnum>] |
a0d0e21e |
519 | |
19799a22 |
520 | enables automatic line-ending processing. It has two separate |
521 | effects. First, it automatically chomps C<$/> (the input record |
522 | separator) when used with B<-n> or B<-p>. Second, it assigns C<$\> |
523 | (the output record separator) to have the value of I<octnum> so |
524 | that any print statements will have that separator added back on. |
525 | If I<octnum> is omitted, sets C<$\> to the current value of |
526 | C<$/>. For instance, to trim lines to 80 columns: |
a0d0e21e |
527 | |
528 | perl -lpe 'substr($_, 80) = ""' |
529 | |
530 | Note that the assignment C<$\ = $/> is done when the switch is processed, |
531 | so the input record separator can be different than the output record |
532 | separator if the B<-l> switch is followed by a B<-0> switch: |
533 | |
534 | gnufind / -print0 | perl -ln0e 'print "found $_" if -p' |
535 | |
1fef88e7 |
536 | This sets C<$\> to newline and then sets C<$/> to the null character. |
a0d0e21e |
537 | |
e0ebc809 |
538 | =item B<-m>[B<->]I<module> |
539 | |
540 | =item B<-M>[B<->]I<module> |
c07a80fd |
541 | |
e0ebc809 |
542 | =item B<-M>[B<->]I<'module ...'> |
543 | |
544 | =item B<-[mM]>[B<->]I<module=arg[,arg]...> |
3c81428c |
545 | |
19799a22 |
546 | B<-m>I<module> executes C<use> I<module> C<();> before executing your |
547 | program. |
3c81428c |
548 | |
19799a22 |
549 | B<-M>I<module> executes C<use> I<module> C<;> before executing your |
550 | program. You can use quotes to add extra code after the module name, |
551 | e.g., C<'-Mmodule qw(foo bar)'>. |
3c81428c |
552 | |
19799a22 |
553 | If the first character after the B<-M> or B<-m> is a dash (C<->) |
a5f75d66 |
554 | then the 'use' is replaced with 'no'. |
555 | |
54310121 |
556 | A little builtin syntactic sugar means you can also say |
19799a22 |
557 | B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for |
558 | C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when |
559 | importing symbols. The actual code generated by B<-Mmodule=foo,bar> is |
e0ebc809 |
560 | C<use module split(/,/,q{foo,bar})>. Note that the C<=> form |
19799a22 |
561 | removes the distinction between B<-m> and B<-M>. |
3c81428c |
562 | |
a0d0e21e |
563 | =item B<-n> |
564 | |
19799a22 |
565 | causes Perl to assume the following loop around your program, which |
a0d0e21e |
566 | makes it iterate over filename arguments somewhat like B<sed -n> or |
567 | B<awk>: |
568 | |
19799a22 |
569 | LINE: |
a0d0e21e |
570 | while (<>) { |
19799a22 |
571 | ... # your program goes here |
a0d0e21e |
572 | } |
573 | |
574 | Note that the lines are not printed by default. See B<-p> to have |
08e9d68e |
575 | lines printed. If a file named by an argument cannot be opened for |
19799a22 |
576 | some reason, Perl warns you about it and moves on to the next file. |
08e9d68e |
577 | |
578 | Here is an efficient way to delete all files older than a week: |
a0d0e21e |
579 | |
19799a22 |
580 | find . -mtime +7 -print | perl -nle unlink |
a0d0e21e |
581 | |
19799a22 |
582 | This is faster than using the B<-exec> switch of B<find> because you don't |
583 | have to start a process on every filename found. It does suffer from |
584 | the bug of mishandling newlines in pathnames, which you can fix if |
44a4342c |
585 | you follow the example under B<-0>. |
a0d0e21e |
586 | |
587 | C<BEGIN> and C<END> blocks may be used to capture control before or after |
19799a22 |
588 | the implicit program loop, just as in B<awk>. |
a0d0e21e |
589 | |
590 | =item B<-p> |
591 | |
19799a22 |
592 | causes Perl to assume the following loop around your program, which |
a0d0e21e |
593 | makes it iterate over filename arguments somewhat like B<sed>: |
594 | |
595 | |
19799a22 |
596 | LINE: |
a0d0e21e |
597 | while (<>) { |
19799a22 |
598 | ... # your program goes here |
a0d0e21e |
599 | } continue { |
08e9d68e |
600 | print or die "-p destination: $!\n"; |
a0d0e21e |
601 | } |
602 | |
08e9d68e |
603 | If a file named by an argument cannot be opened for some reason, Perl |
604 | warns you about it, and moves on to the next file. Note that the |
c2611fb3 |
605 | lines are printed automatically. An error occurring during printing is |
08e9d68e |
606 | treated as fatal. To suppress printing use the B<-n> switch. A B<-p> |
607 | overrides a B<-n> switch. |
a0d0e21e |
608 | |
609 | C<BEGIN> and C<END> blocks may be used to capture control before or after |
19799a22 |
610 | the implicit loop, just as in B<awk>. |
a0d0e21e |
611 | |
612 | =item B<-P> |
613 | |
079a94c4 |
614 | B<NOTE: Use of -P is strongly discouraged because of its inherent |
615 | problems, including poor portability.> |
616 | |
617 | This option causes your program to be run through the C preprocessor before |
efdf3af0 |
618 | compilation by Perl. Because both comments and B<cpp> directives begin |
a0d0e21e |
619 | with the # character, you should avoid starting comments with any words |
efdf3af0 |
620 | recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">. |
079a94c4 |
621 | |
622 | If you're considering using C<-P>, you might also want to look at the |
623 | Filter::cpp module from CPAN. |
624 | |
625 | The problems of -P include, but are not limited to: |
626 | |
627 | =over 10 |
628 | |
629 | =item * |
630 | |
631 | The C<#!> line is stripped, so any switches there don't apply. |
632 | |
633 | =item * |
634 | |
635 | A C<-P> on a C<#!> line doesn't work. |
636 | |
637 | =item * |
638 | |
639 | B<All> lines that begin with (whitespace and) a C<#> but |
640 | do not look like cpp commands, are stripped, including anything |
44a4342c |
641 | inside Perl strings, regular expressions, and here-docs . |
079a94c4 |
642 | |
643 | =item * |
644 | |
645 | In some platforms the C preprocessor knows too much: it knows about |
646 | the C++ -style until-end-of-line comments starting with C<"//">. |
efdf3af0 |
647 | This will cause problems with common Perl constructs like |
648 | |
649 | s/foo//; |
650 | |
651 | because after -P this will became illegal code |
652 | |
653 | s/foo |
654 | |
655 | The workaround is to use some other quoting separator than C<"/">, |
656 | like for example C<"!">: |
657 | |
658 | s!foo!!; |
a0d0e21e |
659 | |
079a94c4 |
660 | |
661 | |
662 | =item * |
663 | |
664 | It requires not only a working C preprocessor but also a working |
665 | F<sed>. If not on UNIX, you are probably out of luck on this. |
666 | |
667 | =item * |
668 | |
669 | Script line numbers are not preserved. |
670 | |
671 | =item * |
672 | |
673 | The C<-x> does not work with C<-P>. |
674 | |
675 | =back |
9a1f07e7 |
676 | |
a0d0e21e |
677 | =item B<-s> |
678 | |
19799a22 |
679 | enables rudimentary switch parsing for switches on the command |
680 | line after the program name but before any filename arguments (or before |
3bbcc830 |
681 | an argument of B<-->). This means you can have switches with two leading |
682 | dashes (B<--help>). Any switch found there is removed from @ARGV and sets the |
19799a22 |
683 | corresponding variable in the Perl program. The following program |
3c0facb2 |
684 | prints "1" if the program is invoked with a B<-xyz> switch, and "abc" |
685 | if it is invoked with B<-xyz=abc>. |
a0d0e21e |
686 | |
687 | #!/usr/bin/perl -s |
3c0facb2 |
688 | if ($xyz) { print "$xyz\n" } |
a0d0e21e |
689 | |
3bbcc830 |
690 | Do note that B<--help> creates the variable ${-help}, which is not compliant |
691 | with C<strict refs>. |
692 | |
a0d0e21e |
693 | =item B<-S> |
694 | |
695 | makes Perl use the PATH environment variable to search for the |
19799a22 |
696 | program (unless the name of the program contains directory separators). |
697 | |
2a92aaa0 |
698 | On some platforms, this also makes Perl append suffixes to the |
699 | filename while searching for it. For example, on Win32 platforms, |
700 | the ".bat" and ".cmd" suffixes are appended if a lookup for the |
701 | original name fails, and if the name does not already end in one |
702 | of those suffixes. If your Perl was compiled with DEBUGGING turned |
703 | on, using the -Dp switch to Perl shows how the search progresses. |
704 | |
2a92aaa0 |
705 | Typically this is used to emulate #! startup on platforms that |
706 | don't support #!. This example works on many platforms that |
707 | have a shell compatible with Bourne shell: |
a0d0e21e |
708 | |
709 | #!/usr/bin/perl |
a3cb178b |
710 | eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}' |
a0d0e21e |
711 | if $running_under_some_shell; |
712 | |
19799a22 |
713 | The system ignores the first line and feeds the program to F</bin/sh>, |
714 | which proceeds to try to execute the Perl program as a shell script. |
a0d0e21e |
715 | The shell executes the second line as a normal shell command, and thus |
716 | starts up the Perl interpreter. On some systems $0 doesn't always |
717 | contain the full pathname, so the B<-S> tells Perl to search for the |
19799a22 |
718 | program if necessary. After Perl locates the program, it parses the |
a0d0e21e |
719 | lines and ignores them because the variable $running_under_some_shell |
19799a22 |
720 | is never true. If the program will be interpreted by csh, you will need |
a3cb178b |
721 | to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand |
722 | embedded spaces (and such) in the argument list. To start up sh rather |
a0d0e21e |
723 | than csh, some systems may have to replace the #! line with a line |
724 | containing just a colon, which will be politely ignored by Perl. Other |
725 | systems can't control that, and need a totally devious construct that |
19799a22 |
726 | will work under any of B<csh>, B<sh>, or Perl, such as the following: |
a0d0e21e |
727 | |
19799a22 |
728 | eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' |
a3cb178b |
729 | & eval 'exec /usr/bin/perl -wS $0 $argv:q' |
5f05dabc |
730 | if $running_under_some_shell; |
a0d0e21e |
731 | |
19799a22 |
732 | If the filename supplied contains directory separators (i.e., is an |
733 | absolute or relative pathname), and if that file is not found, |
734 | platforms that append file extensions will do so and try to look |
735 | for the file with those extensions added, one by one. |
736 | |
737 | On DOS-like platforms, if the program does not contain directory |
738 | separators, it will first be searched for in the current directory |
739 | before being searched for on the PATH. On Unix platforms, the |
740 | program will be searched for strictly on the PATH. |
741 | |
6537fe72 |
742 | =item B<-t> |
743 | |
744 | Like B<-T>, but taint checks will issue warnings rather than fatal |
317ea90d |
745 | errors. These warnings can be controlled normally with C<no warnings |
746 | qw(taint)>. |
1dbad523 |
747 | |
748 | B<NOTE: this is not a substitute for -T.> This is meant only to be |
749 | used as a temporary development aid while securing legacy code: |
750 | for real production code and for new secure code written from scratch |
751 | always use the real B<-T>. |
6537fe72 |
752 | |
a0d0e21e |
753 | =item B<-T> |
754 | |
a3cb178b |
755 | forces "taint" checks to be turned on so you can test them. Ordinarily |
19799a22 |
756 | these checks are done only when running setuid or setgid. It's a |
757 | good idea to turn them on explicitly for programs that run on behalf |
758 | of someone else whom you might not necessarily trust, such as CGI |
759 | programs or any internet servers you might write in Perl. See |
760 | L<perlsec> for details. For security reasons, this option must be |
761 | seen by Perl quite early; usually this means it must appear early |
762 | on the command line or in the #! line for systems which support |
763 | that construct. |
a0d0e21e |
764 | |
765 | =item B<-u> |
766 | |
19799a22 |
767 | This obsolete switch causes Perl to dump core after compiling your |
768 | program. You can then in theory take this core dump and turn it |
769 | into an executable file by using the B<undump> program (not supplied). |
770 | This speeds startup at the expense of some disk space (which you |
771 | can minimize by stripping the executable). (Still, a "hello world" |
772 | executable comes out to about 200K on my machine.) If you want to |
773 | execute a portion of your program before dumping, use the dump() |
774 | operator instead. Note: availability of B<undump> is platform |
775 | specific and may not be available for a specific port of Perl. |
776 | |
777 | This switch has been superseded in favor of the new Perl code |
778 | generator backends to the compiler. See L<B> and L<B::Bytecode> |
779 | for details. |
a0d0e21e |
780 | |
781 | =item B<-U> |
782 | |
783 | allows Perl to do unsafe operations. Currently the only "unsafe" |
784 | operations are the unlinking of directories while running as superuser, |
785 | and running setuid programs with fatal taint checks turned into |
19799a22 |
786 | warnings. Note that the B<-w> switch (or the C<$^W> variable) must |
787 | be used along with this option to actually I<generate> the |
fb73857a |
788 | taint-check warnings. |
a0d0e21e |
789 | |
790 | =item B<-v> |
791 | |
19799a22 |
792 | prints the version and patchlevel of your perl executable. |
a0d0e21e |
793 | |
3c81428c |
794 | =item B<-V> |
795 | |
796 | prints summary of the major perl configuration values and the current |
19799a22 |
797 | values of @INC. |
3c81428c |
798 | |
e0ebc809 |
799 | =item B<-V:>I<name> |
3c81428c |
800 | |
801 | Prints to STDOUT the value of the named configuration variable. |
44a4342c |
802 | For example, |
3c81428c |
803 | |
19799a22 |
804 | $ perl -V:man.dir |
805 | |
806 | will provide strong clues about what your MANPATH variable should |
807 | be set to in order to access the Perl documentation. |
a0d0e21e |
808 | |
19799a22 |
809 | =item B<-w> |
774d564b |
810 | |
19799a22 |
811 | prints warnings about dubious constructs, such as variable names |
812 | that are mentioned only once and scalar variables that are used |
813 | before being set, redefined subroutines, references to undefined |
814 | filehandles or filehandles opened read-only that you are attempting |
815 | to write on, values used as a number that doesn't look like numbers, |
816 | using an array as though it were a scalar, if your subroutines |
817 | recurse more than 100 deep, and innumerable other things. |
818 | |
b40da996 |
819 | This switch really just enables the internal C<$^W> variable. You |
19799a22 |
820 | can disable or promote into fatal errors specific warnings using |
821 | C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. |
822 | See also L<perldiag> and L<perltrap>. A new, fine-grained warning |
823 | facility is also available if you want to manipulate entire classes |
9f1b1f2d |
824 | of warnings; see L<warnings> or L<perllexwarn>. |
a0d0e21e |
825 | |
0453d815 |
826 | =item B<-W> |
827 | |
3c0facb2 |
828 | Enables all warnings regardless of C<no warnings> or C<$^W>. |
0453d815 |
829 | See L<perllexwarn>. |
830 | |
831 | =item B<-X> |
832 | |
3c0facb2 |
833 | Disables all warnings regardless of C<use warnings> or C<$^W>. |
0453d815 |
834 | See L<perllexwarn>. |
835 | |
a0d0e21e |
836 | =item B<-x> I<directory> |
837 | |
19799a22 |
838 | tells Perl that the program is embedded in a larger chunk of unrelated |
839 | ASCII text, such as in a mail message. Leading garbage will be |
840 | discarded until the first line that starts with #! and contains the |
841 | string "perl". Any meaningful switches on that line will be applied. |
842 | If a directory name is specified, Perl will switch to that directory |
843 | before running the program. The B<-x> switch controls only the |
844 | disposal of leading garbage. The program must be terminated with |
845 | C<__END__> if there is trailing garbage to be ignored (the program |
846 | can process any or all of the trailing garbage via the DATA filehandle |
847 | if desired). |
a0d0e21e |
848 | |
1e422769 |
849 | =back |
850 | |
851 | =head1 ENVIRONMENT |
852 | |
853 | =over 12 |
854 | |
855 | =item HOME |
856 | |
857 | Used if chdir has no argument. |
858 | |
859 | =item LOGDIR |
860 | |
861 | Used if chdir has no argument and HOME is not set. |
862 | |
863 | =item PATH |
864 | |
19799a22 |
865 | Used in executing subprocesses, and in finding the program if B<-S> is |
1e422769 |
866 | used. |
867 | |
868 | =item PERL5LIB |
869 | |
870 | A colon-separated list of directories in which to look for Perl library |
871 | files before looking in the standard library and the current |
951ba7fe |
872 | directory. Any architecture-specific directories under the specified |
873 | locations are automatically included if they exist. If PERL5LIB is not |
874 | defined, PERLLIB is used. |
875 | |
876 | When running taint checks (either because the program was running setuid |
877 | or setgid, or the B<-T> switch was used), neither variable is used. |
878 | The program should instead say: |
1e422769 |
879 | |
880 | use lib "/my/directory"; |
881 | |
54310121 |
882 | =item PERL5OPT |
883 | |
884 | Command-line options (switches). Switches in this variable are taken |
1c4db469 |
885 | as if they were on every Perl command line. Only the B<-[DIMUdmtw]> |
19799a22 |
886 | switches are allowed. When running taint checks (because the program |
54310121 |
887 | was running setuid or setgid, or the B<-T> switch was used), this |
74288ac8 |
888 | variable is ignored. If PERL5OPT begins with B<-T>, tainting will be |
889 | enabled, and any subsequent options ignored. |
54310121 |
890 | |
16537909 |
891 | =item PERLIO |
892 | |
44a4342c |
893 | A space (or colon) separated list of PerlIO layers. If perl is built |
03d9e98a |
894 | to use PerlIO system for IO (the default) these layers effect perl's IO. |
44a4342c |
895 | |
896 | It is conventional to start layer names with a colon e.g. C<:perlio> to |
897 | emphasise their similarity to variable "attributes". But the code that parses |
898 | layer specification strings (which is also used to decode the PERLIO |
899 | environment variable) treats the colon as a separator. |
900 | |
901 | The list becomes the default for I<all> perl's IO. Consequently only built-in |
902 | layers can appear in this list, as external layers (such as :encoding()) need |
903 | IO in order to load them!. See L<"open pragma"|open> for how to add external |
904 | encodings as defaults. |
905 | |
906 | The layers that it makes sense to include in the PERLIO environment |
907 | variable are summarised below. For more details see L<PerlIO>. |
16537909 |
908 | |
909 | =over 8 |
910 | |
911 | =item :bytes |
912 | |
44a4342c |
913 | Turns I<off> the C<:utf8> flag for the layer below. |
99366417 |
914 | Unlikely to be useful in global PERLIO environment variable. |
16537909 |
915 | |
916 | =item :crlf |
917 | |
44a4342c |
918 | A layer that implements DOS/Windows like CRLF line endings. |
919 | On read converts pairs of CR,LF to a single "\n" newline character. |
920 | On write converts each "\n" to a CR,LF pair. |
921 | Based on the C<:perlio> layer. |
922 | |
923 | =item :mmap |
924 | |
925 | A layer which implements "reading" of files by using C<mmap()> to |
926 | make (whole) file appear in the process's address space, and then |
927 | using that as PerlIO's "buffer". This I<may> be faster in certain |
928 | circumstances for large files, and may result in less physical memory |
929 | use when multiple processes are reading the same file. |
16537909 |
930 | |
44a4342c |
931 | Files which are not C<mmap()>-able revert to behaving like the C<:perlio> |
932 | layer. Writes also behave like C<:perlio> layer as C<mmap()> for write |
933 | needs extra house-keeping (to extend the file) which negates any advantage. |
16537909 |
934 | |
44a4342c |
935 | The C<:mmap> layer will not exist if platform does not support C<mmap()>. |
16537909 |
936 | |
44a4342c |
937 | =item :perlio |
16537909 |
938 | |
44a4342c |
939 | A from scratch implementation of buffering for PerlIO. Provides fast |
940 | access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt> |
941 | and in general attempts to minimize data copying. |
16537909 |
942 | |
44a4342c |
943 | C<:perlio> will insert a C<:unix> layer below itself to do low level IO. |
16537909 |
944 | |
44a4342c |
945 | =item :raw |
16537909 |
946 | |
0226bbdb |
947 | Applying the <:raw> layer is equivalent to calling C<binmode($fh)>. |
948 | It makes the stream pass each byte as-is without any translation. |
949 | In particular CRLF translation, and/or :utf8 inuited from locale |
950 | are disabled. |
1cbfc93d |
951 | |
0226bbdb |
952 | Arranges for all accesses go straight to the lowest buffered layer provided |
44a4342c |
953 | by the configration. That is it strips off any layers above that layer. |
16537909 |
954 | |
fae2c0fb |
955 | In Perl 5.6 and some books the C<:raw> layer (previously sometimes also |
956 | referred to as a "discipline") is documented as the inverse of the |
957 | C<:crlf> layer. That is no longer the case - other layers which would |
958 | alter binary nature of the stream are also disabled. If you want UNIX |
959 | line endings on a platform that normally does CRLF translation, but still |
960 | want UTF-8 or encoding defaults the appropriate thing to do is to add |
961 | C<:perlio> to PERLIO environment variable. |
16537909 |
962 | |
44a4342c |
963 | =item :stdio |
964 | |
965 | This layer provides PerlIO interface by wrapping system's ANSI C "stdio" |
966 | library calls. The layer provides both buffering and IO. |
967 | Note that C<:stdio> layer does I<not> do CRLF translation even if that |
968 | is platforms normal behaviour. You will need a C<:crlf> layer above it |
969 | to do that. |
970 | |
971 | =item :unix |
972 | |
973 | Lowest level layer which provides basic PerlIO operations in terms of |
974 | UNIX/POSIX numeric file descriptor calls |
975 | C<open(), read(), write(), lseek(), close()> |
16537909 |
976 | |
977 | =item :utf8 |
978 | |
44a4342c |
979 | Turns on a flag on the layer below to tell perl that data sent to the |
980 | stream should be converted to perl internal "utf8" form and that data from the |
981 | stream should be considered as so encoded. On ASCII based platforms the |
982 | encoding is UTF-8 and on EBCDIC platforms UTF-EBCDIC. |
983 | May be useful in PERLIO environment variable to make UTF-8 the |
984 | default. (To turn off that behaviour use C<:bytes> layer.) |
985 | |
986 | =item :win32 |
987 | |
ab4f7683 |
988 | On Win32 platforms this I<experimental> layer uses native "handle" IO |
44a4342c |
989 | rather than unix-like numeric file descriptor layer. Known to be |
990 | buggy in this release. |
16537909 |
991 | |
992 | =back |
993 | |
44a4342c |
994 | On all platforms the default set of layers should give acceptable results. |
995 | |
ab4f7683 |
996 | For UNIX platforms that will equivalent of "unix perlio" or "stdio". |
44a4342c |
997 | Configure is setup to prefer "stdio" implementation if system's library |
998 | provides for fast access to the buffer, otherwise it uses the "unix perlio" |
999 | implementation. |
1000 | |
1001 | On Win32 the default in this release is "unix crlf". Win32's "stdio" |
1002 | has a number of bugs/mis-features for perl IO which are somewhat |
99366417 |
1003 | C compiler vendor/version dependent. Using our own C<crlf> layer as |
44a4342c |
1004 | the buffer avoids those issues and makes things more uniform. |
1005 | The C<crlf> layer provides CRLF to/from "\n" conversion as well as |
1006 | buffering. |
1007 | |
1008 | This release uses C<unix> as the bottom layer on Win32 and so still uses C |
1009 | compiler's numeric file descriptor routines. There is an experimental native |
1010 | C<win32> layer which is expected to be enhanced and should eventually replace |
1011 | the C<unix> layer. |
1012 | |
1013 | =item PERLIO_DEBUG |
1014 | |
1015 | If set to the name of a file or device then certain operations of PerlIO |
1016 | sub-system will be logged to that file (opened as append). Typical uses |
1017 | are UNIX: |
1018 | |
1019 | PERLIO_DEBUG=/dev/tty perl script ... |
1020 | |
1021 | and Win32 approximate equivalent: |
1022 | |
1023 | set PERLIO_DEBUG=CON |
1024 | perl script ... |
1025 | |
16537909 |
1026 | |
1e422769 |
1027 | =item PERLLIB |
1028 | |
1029 | A colon-separated list of directories in which to look for Perl library |
1030 | files before looking in the standard library and the current directory. |
1031 | If PERL5LIB is defined, PERLLIB is not used. |
1032 | |
1033 | =item PERL5DB |
1034 | |
1035 | The command used to load the debugger code. The default is: |
1036 | |
1037 | BEGIN { require 'perl5db.pl' } |
1038 | |
19799a22 |
1039 | =item PERL5SHELL (specific to the Win32 port) |
174c211a |
1040 | |
1041 | May be set to an alternative shell that perl must use internally for |
ce1da67e |
1042 | executing "backtick" commands or system(). Default is C<cmd.exe /x/c> |
1043 | on WindowsNT and C<command.com /c> on Windows95. The value is considered |
19799a22 |
1044 | to be space-separated. Precede any character that needs to be protected |
ce1da67e |
1045 | (like a space or backslash) with a backslash. |
1046 | |
1047 | Note that Perl doesn't use COMSPEC for this purpose because |
1048 | COMSPEC has a high degree of variability among users, leading to |
1049 | portability concerns. Besides, perl can use a shell that may not be |
1050 | fit for interactive use, and setting COMSPEC to such a shell may |
1051 | interfere with the proper functioning of other programs (which usually |
1052 | look in COMSPEC to find a shell fit for interactive use). |
174c211a |
1053 | |
1e422769 |
1054 | =item PERL_DEBUG_MSTATS |
1055 | |
67ce8856 |
1056 | Relevant only if perl is compiled with the malloc included with the perl |
a3cb178b |
1057 | distribution (that is, if C<perl -V:d_mymalloc> is 'define'). |
1058 | If set, this causes memory statistics to be dumped after execution. If set |
1e422769 |
1059 | to an integer greater than one, also causes memory statistics to be dumped |
1060 | after compilation. |
1061 | |
1062 | =item PERL_DESTRUCT_LEVEL |
1063 | |
1064 | Relevant only if your perl executable was built with B<-DDEBUGGING>, |
1065 | this controls the behavior of global destruction of objects and other |
64cea5fd |
1066 | references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. |
a0d0e21e |
1067 | |
5d170f3a |
1068 | =item PERL_ENCODING |
1069 | |
1070 | If using the C<encoding> pragma without an explicit encoding name, the |
1071 | PERL_ENCODING environment variable is consulted for an encoding name. |
1072 | |
3d0ae7ba |
1073 | =item PERL_ROOT (specific to the VMS port) |
1074 | |
1075 | A translation concealed rooted logical name that contains perl and the |
1076 | logical device for the @INC path on VMS only. Other logical names that |
44a4342c |
1077 | affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and |
1078 | SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in |
3d0ae7ba |
1079 | L<perlvms> and in F<README.vms> in the Perl source distribution. |
1080 | |
a05d7ebb |
1081 | =item PERL_UNICODE |
acae81db |
1082 | |
1083 | Equivalent to the B<-C> command-line switch. |
1084 | |
3d0ae7ba |
1085 | =item SYS$LOGIN (specific to the VMS port) |
1086 | |
1087 | Used if chdir has no argument and HOME and LOGDIR are not set. |
1088 | |
a0d0e21e |
1089 | =back |
1e422769 |
1090 | |
1091 | Perl also has environment variables that control how Perl handles data |
1092 | specific to particular natural languages. See L<perllocale>. |
1093 | |
1094 | Apart from these, Perl uses no other environment variables, except |
19799a22 |
1095 | to make them available to the program being executed, and to child |
1096 | processes. However, programs running setuid would do well to execute |
1e422769 |
1097 | the following lines before doing anything else, just to keep people |
1098 | honest: |
1099 | |
19799a22 |
1100 | $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need |
7bac28a0 |
1101 | $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL}; |
c90c0ff4 |
1102 | delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; |