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