mingw/html/pod/perlrun.html

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