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