| 1 | =head1 NAME |
| 2 | |
| 3 | perlrun - how to execute the Perl interpreter |
| 4 | |
| 5 | =head1 SYNOPSIS |
| 6 | |
| 7 | B<perl> S<[ B<-sTuU> ]> |
| 8 | S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]> |
| 9 | S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]> |
| 10 | S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]> |
| 11 | S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]> |
| 12 | S<[ B<-P> ]> |
| 13 | S<[ B<-S> ]> |
| 14 | S<[ B<-x>[I<dir>] ]> |
| 15 | S<[ B<-i>[I<extension>] ]> |
| 16 | S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...> |
| 17 | |
| 18 | =head1 DESCRIPTION |
| 19 | |
| 20 | Upon startup, Perl looks for your script in one of the following |
| 21 | places: |
| 22 | |
| 23 | =over 4 |
| 24 | |
| 25 | =item 1. |
| 26 | |
| 27 | Specified line by line via B<-e> switches on the command line. |
| 28 | |
| 29 | =item 2. |
| 30 | |
| 31 | Contained in the file specified by the first filename on the command line. |
| 32 | (Note that systems supporting the #! notation invoke interpreters this way.) |
| 33 | |
| 34 | =item 3. |
| 35 | |
| 36 | Passed in implicitly via standard input. This works only if there are |
| 37 | no filename arguments--to pass arguments to a STDIN script you |
| 38 | must explicitly specify a "-" for the script name. |
| 39 | |
| 40 | =back |
| 41 | |
| 42 | With methods 2 and 3, Perl starts parsing the input file from the |
| 43 | beginning, unless you've specified a B<-x> switch, in which case it |
| 44 | scans for the first line starting with #! and containing the word |
| 45 | "perl", and starts there instead. This is useful for running a script |
| 46 | embedded in a larger message. (In this case you would indicate the end |
| 47 | of the script using the __END__ token.) |
| 48 | |
| 49 | The #! line is always examined for switches as the line is being |
| 50 | parsed. Thus, if you're on a machine that allows only one argument |
| 51 | with the #! line, or worse, doesn't even recognize the #! line, you |
| 52 | still can get consistent switch behavior regardless of how Perl was |
| 53 | invoked, even if B<-x> was used to find the beginning of the script. |
| 54 | |
| 55 | Because many operating systems silently chop off kernel interpretation of |
| 56 | the #! line after 32 characters, some switches may be passed in on the |
| 57 | command line, and some may not; you could even get a "-" without its |
| 58 | letter, if you're not careful. You probably want to make sure that all |
| 59 | your switches fall either before or after that 32 character boundary. |
| 60 | Most switches don't actually care if they're processed redundantly, but |
| 61 | getting a - instead of a complete switch could cause Perl to try to |
| 62 | execute standard input instead of your script. And a partial B<-I> switch |
| 63 | could also cause odd results. |
| 64 | |
| 65 | Parsing of the #! switches starts wherever "perl" is mentioned in the line. |
| 66 | The sequences "-*" and "- " are specifically ignored so that you could, |
| 67 | if you were so inclined, say |
| 68 | |
| 69 | #!/bin/sh -- # -*- perl -*- -p |
| 70 | eval 'exec /usr/bin/perl $0 -S ${1+"$@"}' |
| 71 | if $running_under_some_shell; |
| 72 | |
| 73 | to let Perl see the B<-p> switch. |
| 74 | |
| 75 | If the #! line does not contain the word "perl", the program named after |
| 76 | the #! is executed instead of the Perl interpreter. This is slightly |
| 77 | bizarre, but it helps people on machines that don't do #!, because they |
| 78 | can tell a program that their SHELL is /usr/bin/perl, and Perl will then |
| 79 | dispatch the program to the correct interpreter for them. |
| 80 | |
| 81 | After locating your script, Perl compiles the entire script to an |
| 82 | internal form. If there are any compilation errors, execution of the |
| 83 | script is not attempted. (This is unlike the typical shell script, |
| 84 | which might run partway through before finding a syntax error.) |
| 85 | |
| 86 | If the script is syntactically correct, it is executed. If the script |
| 87 | runs off the end without hitting an exit() or die() operator, an implicit |
| 88 | C<exit(0)> is provided to indicate successful completion. |
| 89 | |
| 90 | =head2 Switches |
| 91 | |
| 92 | A single-character switch may be combined with the following switch, if |
| 93 | any. |
| 94 | |
| 95 | #!/usr/bin/perl -spi.bak # same as -s -p -i.bak |
| 96 | |
| 97 | Switches include: |
| 98 | |
| 99 | =over 5 |
| 100 | |
| 101 | =item B<-0>[I<digits>] |
| 102 | |
| 103 | specifies the input record separator (C<$/>) as an octal number. If there are |
| 104 | no digits, the null character is the separator. Other switches may |
| 105 | precede or follow the digits. For example, if you have a version of |
| 106 | B<find> which can print filenames terminated by the null character, you |
| 107 | can say this: |
| 108 | |
| 109 | find . -name '*.bak' -print0 | perl -n0e unlink |
| 110 | |
| 111 | The special value 00 will cause Perl to slurp files in paragraph mode. |
| 112 | The value 0777 will cause Perl to slurp files whole because there is no |
| 113 | legal character with that value. |
| 114 | |
| 115 | =item B<-a> |
| 116 | |
| 117 | turns on autosplit mode when used with a B<-n> or B<-p>. An implicit |
| 118 | split command to the @F array is done as the first thing inside the |
| 119 | implicit while loop produced by the B<-n> or B<-p>. |
| 120 | |
| 121 | perl -ane 'print pop(@F), "\n";' |
| 122 | |
| 123 | is equivalent to |
| 124 | |
| 125 | while (<>) { |
| 126 | @F = split(' '); |
| 127 | print pop(@F), "\n"; |
| 128 | } |
| 129 | |
| 130 | An alternate delimiter may be specified using B<-F>. |
| 131 | |
| 132 | =item B<-c> |
| 133 | |
| 134 | causes Perl to check the syntax of the script and then exit without |
| 135 | executing it. Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks, |
| 136 | because these are considered as occurring outside the execution of |
| 137 | your program. |
| 138 | |
| 139 | =item B<-d> |
| 140 | |
| 141 | runs the script under the Perl debugger. See L<perldebug>. |
| 142 | |
| 143 | =item B<-d:>I<foo> |
| 144 | |
| 145 | runs the script under the control of a debugging or tracing module |
| 146 | installed as Devel::foo. E.g., B<-d:DProf> executes the script using the |
| 147 | Devel::DProf profiler. See L<perldebug>. |
| 148 | |
| 149 | =item B<-D>I<number> |
| 150 | |
| 151 | =item B<-D>I<list> |
| 152 | |
| 153 | sets debugging flags. To watch how it executes your script, use |
| 154 | B<-D14>. (This works only if debugging is compiled into your |
| 155 | Perl.) Another nice value is B<-D1024>, which lists your compiled |
| 156 | syntax tree. And B<-D512> displays compiled regular expressions. As an |
| 157 | alternative specify a list of letters instead of numbers (e.g., B<-D14> is |
| 158 | equivalent to B<-Dtls>): |
| 159 | |
| 160 | 1 p Tokenizing and Parsing |
| 161 | 2 s Stack Snapshots |
| 162 | 4 l Label Stack Processing |
| 163 | 8 t Trace Execution |
| 164 | 16 o Operator Node Construction |
| 165 | 32 c String/Numeric Conversions |
| 166 | 64 P Print Preprocessor Command for -P |
| 167 | 128 m Memory Allocation |
| 168 | 256 f Format Processing |
| 169 | 512 r Regular Expression Parsing |
| 170 | 1024 x Syntax Tree Dump |
| 171 | 2048 u Tainting Checks |
| 172 | 4096 L Memory Leaks (not supported anymore) |
| 173 | 8192 H Hash Dump -- usurps values() |
| 174 | 16384 X Scratchpad Allocation |
| 175 | 32768 D Cleaning Up |
| 176 | |
| 177 | =item B<-e> I<commandline> |
| 178 | |
| 179 | may be used to enter one line of script. |
| 180 | If B<-e> is given, Perl |
| 181 | will not look for a script filename in the argument list. |
| 182 | Multiple B<-e> commands may |
| 183 | be given to build up a multi-line script. |
| 184 | Make sure to use semicolons where you would in a normal program. |
| 185 | |
| 186 | =item B<-F>I<pattern> |
| 187 | |
| 188 | specifies the pattern to split on if B<-a> is also in effect. The |
| 189 | pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be |
| 190 | put in single quotes. |
| 191 | |
| 192 | =item B<-h> |
| 193 | |
| 194 | prints a summary of the options. |
| 195 | |
| 196 | =item B<-i>[I<extension>] |
| 197 | |
| 198 | specifies that files processed by the C<E<lt>E<gt>> construct are to be edited |
| 199 | in-place. It does this by renaming the input file, opening the output |
| 200 | file by the original name, and selecting that output file as the default |
| 201 | for print() statements. The extension, if supplied, is added to the name |
| 202 | of the old file to make a backup copy. If no extension is supplied, no |
| 203 | backup is made. From the shell, saying |
| 204 | |
| 205 | $ perl -p -i.bak -e "s/foo/bar/; ... " |
| 206 | |
| 207 | is the same as using the script: |
| 208 | |
| 209 | #!/usr/bin/perl -pi.bak |
| 210 | s/foo/bar/; |
| 211 | |
| 212 | which is equivalent to |
| 213 | |
| 214 | #!/usr/bin/perl |
| 215 | while (<>) { |
| 216 | if ($ARGV ne $oldargv) { |
| 217 | rename($ARGV, $ARGV . '.bak'); |
| 218 | open(ARGVOUT, ">$ARGV"); |
| 219 | select(ARGVOUT); |
| 220 | $oldargv = $ARGV; |
| 221 | } |
| 222 | s/foo/bar/; |
| 223 | } |
| 224 | continue { |
| 225 | print; # this prints to original filename |
| 226 | } |
| 227 | select(STDOUT); |
| 228 | |
| 229 | except that the B<-i> form doesn't need to compare $ARGV to $oldargv to |
| 230 | know when the filename has changed. It does, however, use ARGVOUT for |
| 231 | the selected filehandle. Note that STDOUT is restored as the |
| 232 | default output filehandle after the loop. |
| 233 | |
| 234 | You can use C<eof> without parenthesis to locate the end of each input file, |
| 235 | in case you want to append to each file, or reset line numbering (see |
| 236 | example in L<perlfunc/eof>). |
| 237 | |
| 238 | =item B<-I>I<directory> |
| 239 | |
| 240 | Directories specified by B<-I> are prepended to the search path for |
| 241 | modules (C<@INC>), and also tells the C preprocessor where to search for |
| 242 | include files. The C preprocessor is invoked with B<-P>; by default it |
| 243 | searches /usr/include and /usr/lib/perl. |
| 244 | |
| 245 | =item B<-l>[I<octnum>] |
| 246 | |
| 247 | enables automatic line-ending processing. It has two effects: first, |
| 248 | it automatically chomps "C<$/>" (the input record separator) when used |
| 249 | with B<-n> or B<-p>, and second, it assigns "C<$\>" |
| 250 | (the output record separator) to have the value of I<octnum> so that |
| 251 | any print statements will have that separator added back on. If |
| 252 | I<octnum> is omitted, sets "C<$\>" to the current value of "C<$/>". For |
| 253 | instance, to trim lines to 80 columns: |
| 254 | |
| 255 | perl -lpe 'substr($_, 80) = ""' |
| 256 | |
| 257 | Note that the assignment C<$\ = $/> is done when the switch is processed, |
| 258 | so the input record separator can be different than the output record |
| 259 | separator if the B<-l> switch is followed by a B<-0> switch: |
| 260 | |
| 261 | gnufind / -print0 | perl -ln0e 'print "found $_" if -p' |
| 262 | |
| 263 | This sets C<$\> to newline and then sets C<$/> to the null character. |
| 264 | |
| 265 | =item B<-m>[B<->]I<module> |
| 266 | |
| 267 | =item B<-M>[B<->]I<module> |
| 268 | |
| 269 | =item B<-M>[B<->]I<'module ...'> |
| 270 | |
| 271 | =item B<-[mM]>[B<->]I<module=arg[,arg]...> |
| 272 | |
| 273 | C<-m>I<module> executes C<use> I<module> C<();> before executing your |
| 274 | script. |
| 275 | |
| 276 | C<-M>I<module> executes C<use> I<module> C<;> before executing your |
| 277 | script. You can use quotes to add extra code after the module name, |
| 278 | e.g., C<-M'module qw(foo bar)'>. |
| 279 | |
| 280 | If the first character after the C<-M> or C<-m> is a dash (C<->) |
| 281 | then the 'use' is replaced with 'no'. |
| 282 | |
| 283 | A little built-in syntactic sugar means you can also say |
| 284 | C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for |
| 285 | C<-M'module qw(foo bar)'>. This avoids the need to use quotes when |
| 286 | importing symbols. The actual code generated by C<-Mmodule=foo,bar> is |
| 287 | C<use module split(/,/,q{foo,bar})>. Note that the C<=> form |
| 288 | removes the distinction between C<-m> and C<-M>. |
| 289 | |
| 290 | =item B<-n> |
| 291 | |
| 292 | causes Perl to assume the following loop around your script, which |
| 293 | makes it iterate over filename arguments somewhat like B<sed -n> or |
| 294 | B<awk>: |
| 295 | |
| 296 | while (<>) { |
| 297 | ... # your script goes here |
| 298 | } |
| 299 | |
| 300 | Note that the lines are not printed by default. See B<-p> to have |
| 301 | lines printed. Here is an efficient way to delete all files older than |
| 302 | a week: |
| 303 | |
| 304 | find . -mtime +7 -print | perl -nle 'unlink;' |
| 305 | |
| 306 | This is faster than using the C<-exec> switch of B<find> because you don't |
| 307 | have to start a process on every filename found. |
| 308 | |
| 309 | C<BEGIN> and C<END> blocks may be used to capture control before or after |
| 310 | the implicit loop, just as in B<awk>. |
| 311 | |
| 312 | =item B<-p> |
| 313 | |
| 314 | causes Perl to assume the following loop around your script, which |
| 315 | makes it iterate over filename arguments somewhat like B<sed>: |
| 316 | |
| 317 | |
| 318 | while (<>) { |
| 319 | ... # your script goes here |
| 320 | } continue { |
| 321 | print; |
| 322 | } |
| 323 | |
| 324 | Note that the lines are printed automatically. To suppress printing |
| 325 | use the B<-n> switch. A B<-p> overrides a B<-n> switch. |
| 326 | |
| 327 | C<BEGIN> and C<END> blocks may be used to capture control before or after |
| 328 | the implicit loop, just as in awk. |
| 329 | |
| 330 | =item B<-P> |
| 331 | |
| 332 | causes your script to be run through the C preprocessor before |
| 333 | compilation by Perl. (Because both comments and cpp directives begin |
| 334 | with the # character, you should avoid starting comments with any words |
| 335 | recognized by the C preprocessor such as "if", "else", or "define".) |
| 336 | |
| 337 | =item B<-s> |
| 338 | |
| 339 | enables some rudimentary switch parsing for switches on the command |
| 340 | line after the script name but before any filename arguments (or before |
| 341 | a B<-->). Any switch found there is removed from @ARGV and sets the |
| 342 | corresponding variable in the Perl script. The following script |
| 343 | prints "true" if and only if the script is invoked with a B<-xyz> switch. |
| 344 | |
| 345 | #!/usr/bin/perl -s |
| 346 | if ($xyz) { print "true\n"; } |
| 347 | |
| 348 | =item B<-S> |
| 349 | |
| 350 | makes Perl use the PATH environment variable to search for the |
| 351 | script (unless the name of the script starts with a slash). Typically |
| 352 | this is used to emulate #! startup on machines that don't support #!, |
| 353 | in the following manner: |
| 354 | |
| 355 | #!/usr/bin/perl |
| 356 | eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' |
| 357 | if $running_under_some_shell; |
| 358 | |
| 359 | The system ignores the first line and feeds the script to /bin/sh, |
| 360 | which proceeds to try to execute the Perl script as a shell script. |
| 361 | The shell executes the second line as a normal shell command, and thus |
| 362 | starts up the Perl interpreter. On some systems $0 doesn't always |
| 363 | contain the full pathname, so the B<-S> tells Perl to search for the |
| 364 | script if necessary. After Perl locates the script, it parses the |
| 365 | lines and ignores them because the variable $running_under_some_shell |
| 366 | is never true. A better construct than C<$*> would be C<${1+"$@"}>, which |
| 367 | handles embedded spaces and such in the filenames, but doesn't work if |
| 368 | the script is being interpreted by csh. To start up sh rather |
| 369 | than csh, some systems may have to replace the #! line with a line |
| 370 | containing just a colon, which will be politely ignored by Perl. Other |
| 371 | systems can't control that, and need a totally devious construct that |
| 372 | will work under any of csh, sh, or Perl, such as the following: |
| 373 | |
| 374 | eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' |
| 375 | & eval 'exec /usr/bin/perl -S $0 $argv:q' |
| 376 | if $running_under_some_shell; |
| 377 | |
| 378 | =item B<-T> |
| 379 | |
| 380 | forces "taint" checks to be turned on so you can test them. Ordinarily these checks are |
| 381 | done only when running setuid or setgid. It's a good idea to turn |
| 382 | them on explicitly for programs run on another's behalf, such as CGI |
| 383 | programs. See L<perlsec>. |
| 384 | |
| 385 | =item B<-u> |
| 386 | |
| 387 | causes Perl to dump core after compiling your script. You can then |
| 388 | take this core dump and turn it into an executable file by using the |
| 389 | B<undump> program (not supplied). This speeds startup at the expense of |
| 390 | some disk space (which you can minimize by stripping the executable). |
| 391 | (Still, a "hello world" executable comes out to about 200K on my |
| 392 | machine.) If you want to execute a portion of your script before dumping, |
| 393 | use the dump() operator instead. Note: availability of B<undump> is |
| 394 | platform specific and may not be available for a specific port of |
| 395 | Perl. |
| 396 | |
| 397 | =item B<-U> |
| 398 | |
| 399 | allows Perl to do unsafe operations. Currently the only "unsafe" |
| 400 | operations are the unlinking of directories while running as superuser, |
| 401 | and running setuid programs with fatal taint checks turned into |
| 402 | warnings. |
| 403 | |
| 404 | =item B<-v> |
| 405 | |
| 406 | prints the version and patchlevel of your Perl executable. |
| 407 | |
| 408 | =item B<-V> |
| 409 | |
| 410 | prints summary of the major perl configuration values and the current |
| 411 | value of @INC. |
| 412 | |
| 413 | =item B<-V:>I<name> |
| 414 | |
| 415 | Prints to STDOUT the value of the named configuration variable. |
| 416 | |
| 417 | =item B<-w> |
| 418 | |
| 419 | prints warnings about variable names that are mentioned only once, and |
| 420 | scalar variables that are used before being set. Also warns about |
| 421 | redefined subroutines, and references to undefined filehandles or |
| 422 | filehandles opened read-only that you are attempting to write on. Also |
| 423 | warns you if you use values as a number that doesn't look like numbers, using |
| 424 | an array as though it were a scalar, if |
| 425 | your subroutines recurse more than 100 deep, and innumerable other things. |
| 426 | See L<perldiag> and L<perltrap>. |
| 427 | |
| 428 | =item B<-x> I<directory> |
| 429 | |
| 430 | tells Perl that the script is embedded in a message. Leading |
| 431 | garbage will be discarded until the first line that starts with #! and |
| 432 | contains the string "perl". Any meaningful switches on that line will |
| 433 | be applied (but only one group of switches, as with normal #! |
| 434 | processing). If a directory name is specified, Perl will switch to |
| 435 | that directory before running the script. The B<-x> switch controls |
| 436 | only the disposal of leading garbage. The script must be |
| 437 | terminated with C<__END__> if there is trailing garbage to be ignored (the |
| 438 | script can process any or all of the trailing garbage via the DATA |
| 439 | filehandle if desired). |
| 440 | |
| 441 | |
| 442 | =back |