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