diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlrun.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlrun.1 | 1630 |
1 files changed, 1630 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlrun.1 b/upstream/mageia-cauldron/man1/perlrun.1 new file mode 100644 index 00000000..0301f67a --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlrun.1 @@ -0,0 +1,1630 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLRUN 1" +.TH PERLRUN 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlrun \- how to execute the Perl interpreter +.SH SYNOPSIS +.IX Header "SYNOPSIS" +\&\fBperl\fR [\ \fB\-gsTtuUWX\fR\ ] + [\ \fB\-h?v\fR\ ]\ [\ \fB\-V\fR[:\fIconfigvar\fR]\ ] + [\ \fB\-cw\fR\ ]\ [\ \fB\-d\fR[\fBt\fR][:\fIdebugger\fR]\ ]\ [\ \fB\-D\fR[\fInumber/list\fR]\ ] + [\ \fB\-pna\fR\ ]\ [\ \fB\-F\fR\fIpattern\fR\ ]\ [\ \fB\-l\fR[\fIoctal\fR]\ ]\ [\ \fB\-0\fR[\fIoctal/hexadecimal\fR]\ ] + [\ \fB\-I\fR\fIdir\fR\ ]\ [\ \fB\-m\fR[\fB\-\fR]\fImodule\fR\ ]\ [\ \fB\-M\fR[\fB\-\fR]\fI'module...'\fR\ ]\ [\ \fB\-f\fR\ ] + [\ \fB\-C\ [\fR\f(BInumber/list\fR\fB]\ \fR] + [\ \fB\-S\fR\ ] + [\ \fB\-x\fR[\fIdir\fR]\ ] + [\ \fB\-i\fR[\fIextension\fR]\ ] + [\ [\fB\-e\fR|\fB\-E\fR]\ \fI'command'\fR\ ]\ [\ \fB\-\-\fR\ ]\ [\ \fIprogramfile\fR\ ]\ [\ \fIargument\fR\ ]... +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The normal way to run a Perl program is by making it directly +executable, or else by passing the name of the source file as an +argument on the command line. (An interactive Perl environment +is also possible\-\-see perldebug for details on how to do that.) +Upon startup, Perl looks for your program in one of the following +places: +.IP 1. 4 +Specified line by line via \-e or \-E +switches on the command line. +.IP 2. 4 +Contained in the file specified by the first filename on the command line. +(Note that systems supporting the \f(CW\*(C`#!\*(C'\fR notation invoke interpreters this +way. See "Location of Perl".) +.IP 3. 4 +Passed in implicitly via standard input. This works only if there are +no filename arguments\-\-to pass arguments to a STDIN-read program you +must explicitly specify a "\-" for the program name. +.PP +With methods 2 and 3, Perl starts parsing the input file from the +beginning, unless you've specified a "\-x" switch, in which case it +scans for the first line starting with \f(CW\*(C`#!\*(C'\fR and containing the word +"perl", and starts there instead. This is useful for running a program +embedded in a larger message. (In this case you would indicate the end +of the program using the \f(CW\*(C`_\|_END_\|_\*(C'\fR token.) +.PP +The \f(CW\*(C`#!\*(C'\fR line is always examined for switches as the line is being +parsed. Thus, if you're on a machine that allows only one argument +with the \f(CW\*(C`#!\*(C'\fR line, or worse, doesn't even recognize the \f(CW\*(C`#!\*(C'\fR line, you +still can get consistent switch behaviour regardless of how Perl was +invoked, even if "\-x" was used to find the beginning of the program. +.PP +Because historically some operating systems silently chopped off +kernel interpretation of the \f(CW\*(C`#!\*(C'\fR line after 32 characters, some +switches may be passed in on the command line, and some may not; +you could even get a "\-" without its letter, if you're not careful. +You probably want to make sure that all your switches fall either +before or after that 32\-character boundary. Most switches don't +actually care if they're processed redundantly, but getting a "\-" +instead of a complete switch could cause Perl to try to execute +standard input instead of your program. And a partial \-I +switch could also cause odd results. +.PP +Some switches do care if they are processed twice, for instance +combinations of \-l and \-0. +Either put all the switches after the 32\-character boundary (if +applicable), or replace the use of \fB\-0\fR\fIdigits\fR by +\&\f(CW\*(C`BEGIN{ $/ = "\e0digits"; }\*(C'\fR. +.PP +Parsing of the \f(CW\*(C`#!\*(C'\fR switches starts wherever "perl" is mentioned in the line. +The sequences "\-*" and "\- " are specifically ignored so that you could, +if you were so inclined, say +.PP +.Vb 4 +\& #!/bin/sh +\& #! \-*\- perl \-*\- \-p +\& eval \*(Aqexec perl \-x \-wS $0 ${1+"$@"}\*(Aq +\& if 0; +.Ve +.PP +to let Perl see the "\-p" switch. +.PP +A similar trick involves the \fIenv\fR program, if you have it. +.PP +.Vb 1 +\& #!/usr/bin/env perl +.Ve +.PP +The examples above use a relative path to the perl interpreter, +getting whatever version is first in the user's path. If you want +a specific version of Perl, say, perl5.14.1, you should place +that directly in the \f(CW\*(C`#!\*(C'\fR line's path. +.PP +If the \f(CW\*(C`#!\*(C'\fR line does not contain the word "perl" nor the word "indir", +the program named after the \f(CW\*(C`#!\*(C'\fR is executed instead of the Perl +interpreter. This is slightly bizarre, but it helps people on machines +that don't do \f(CW\*(C`#!\*(C'\fR, because they can tell a program that their SHELL is +\&\fI/usr/bin/perl\fR, and Perl will then dispatch the program to the correct +interpreter for them. +.PP +After locating your program, Perl compiles the entire program to an +internal form. If there are any compilation errors, execution of the +program is not attempted. (This is unlike the typical shell script, +which might run part-way through before finding a syntax error.) +.PP +If the program is syntactically correct, it is executed. If the program +runs off the end without hitting an \fBexit()\fR or \fBdie()\fR operator, an implicit +\&\f(CWexit(0)\fR is provided to indicate successful completion. +.SS "#! and quoting on non-Unix systems" +.IX Xref "hashbang #!" +.IX Subsection "#! and quoting on non-Unix systems" +Unix's \f(CW\*(C`#!\*(C'\fR technique can be simulated on other systems: +.IP OS/2 4 +.IX Item "OS/2" +Put +.Sp +.Vb 1 +\& extproc perl \-S \-your_switches +.Ve +.Sp +as the first line in \f(CW\*(C`*.cmd\*(C'\fR file ("\-S" due to a bug in cmd.exe's +`extproc' handling). +.IP MS-DOS 4 +.IX Item "MS-DOS" +Create a batch file to run your program, and codify it in +\&\f(CW\*(C`ALTERNATE_SHEBANG\*(C'\fR (see the \fIdosish.h\fR file in the source +distribution for more information). +.IP Win95/NT 4 +.IX Item "Win95/NT" +The Win95/NT installation, when using the ActiveState installer for Perl, +will modify the Registry to associate the \fI.pl\fR extension with the perl +interpreter. If you install Perl by other means (including building from +the sources), you may have to modify the Registry yourself. Note that +this means you can no longer tell the difference between an executable +Perl program and a Perl library file. +.IP VMS 4 +.IX Item "VMS" +Put +.Sp +.Vb 2 +\& $ perl \-mysw \*(Aqf$env("procedure")\*(Aq \*(Aqp1\*(Aq \*(Aqp2\*(Aq \*(Aqp3\*(Aq \*(Aqp4\*(Aq \*(Aqp5\*(Aq \*(Aqp6\*(Aq \*(Aqp7\*(Aq \*(Aqp8\*(Aq ! +\& $ exit++ + ++$status != 0 and $exit = $status = undef; +.Ve +.Sp +at the top of your program, where \fB\-mysw\fR are any command line switches you +want to pass to Perl. You can now invoke the program directly, by saying +\&\f(CW\*(C`perl program\*(C'\fR, or as a DCL procedure, by saying \f(CW@program\fR (or implicitly +via \fIDCL$PATH\fR by just using the name of the program). +.Sp +This incantation is a bit much to remember, but Perl will display it for +you if you say \f(CW\*(C`perl "\-V:startperl"\*(C'\fR. +.PP +Command-interpreters on non-Unix systems have rather different ideas +on quoting than Unix shells. You'll need to learn the special +characters in your command-interpreter (\f(CW\*(C`*\*(C'\fR, \f(CW\*(C`\e\*(C'\fR and \f(CW\*(C`"\*(C'\fR are +common) and how to protect whitespace and these characters to run +one-liners (see \-e below). +.PP +On some systems, you may have to change single-quotes to double ones, +which you must \fInot\fR do on Unix or Plan 9 systems. You might also +have to change a single % to a %%. +.PP +For example: +.PP +.Vb 2 +\& # Unix +\& perl \-e \*(Aqprint "Hello world\en"\*(Aq +\& +\& # MS\-DOS, etc. +\& perl \-e "print \e"Hello world\en\e"" +\& +\& # VMS +\& perl \-e "print ""Hello world\en""" +.Ve +.PP +The problem is that none of this is reliable: it depends on the +command and it is entirely possible neither works. If \fI4DOS\fR were +the command shell, this would probably work better: +.PP +.Vb 1 +\& perl \-e "print <Ctrl\-x>"Hello world\en<Ctrl\-x>"" +.Ve +.PP +\&\fBCMD.EXE\fR in Windows NT slipped a lot of standard Unix functionality in +when nobody was looking, but just try to find documentation for its +quoting rules. +.PP +There is no general solution to all of this. It's just a mess. +.SS "Location of Perl" +.IX Xref "perl, location of interpreter" +.IX Subsection "Location of Perl" +It may seem obvious to say, but Perl is useful only when users can +easily find it. When possible, it's good for both \fI/usr/bin/perl\fR +and \fI/usr/local/bin/perl\fR to be symlinks to the actual binary. If +that can't be done, system administrators are strongly encouraged +to put (symlinks to) perl and its accompanying utilities into a +directory typically found along a user's PATH, or in some other +obvious and convenient place. +.PP +In this documentation, \f(CW\*(C`#!/usr/bin/perl\*(C'\fR on the first line of the program +will stand in for whatever method works on your system. You are +advised to use a specific path if you care about a specific version. +.PP +.Vb 1 +\& #!/usr/local/bin/perl5.14 +.Ve +.PP +or if you just want to be running at least version, place a statement +like this at the top of your program: +.PP +.Vb 1 +\& use v5.14; +.Ve +.SS "Command Switches" +.IX Xref "perl, command switches command switches" +.IX Subsection "Command Switches" +As with all standard commands, a single-character switch may be +clustered with the following switch, if any. +.PP +.Vb 1 +\& #!/usr/bin/perl \-spi.orig # same as \-s \-p \-i.orig +.Ve +.PP +A \f(CW\*(C`\-\-\*(C'\fR signals the end of options and disables further option processing. Any +arguments after the \f(CW\*(C`\-\-\*(C'\fR are treated as filenames and arguments. +.PP +Switches include: +.IP \fB\-0\fR[\fIoctal/hexadecimal\fR] 5 +.IX Xref "-0 $" +.IX Item "-0[octal/hexadecimal]" +specifies the input record separator (\f(CW$/\fR) as an octal or +hexadecimal number. If there are no digits, the null character is the +separator. Other switches may precede or follow the digits. For +example, if you have a version of \fIfind\fR which can print filenames +terminated by the null character, you can say this: +.Sp +.Vb 1 +\& find . \-name \*(Aq*.orig\*(Aq \-print0 | perl \-n0e unlink +.Ve +.Sp +The special value 00 will cause Perl to slurp files in paragraph mode. +.Sp +Any value 0400 or above will cause Perl to slurp files whole, but by convention +the value 0777 is the one normally used for this purpose. The "\-g" flag +is a simpler alias for it. +.Sp +You can also specify the separator character using hexadecimal notation: +\&\fB\-0x\fR\f(BIHHH...\fR, where the \f(CW\*(C`\fR\f(CIH\fR\f(CW\*(C'\fR are valid hexadecimal digits. Unlike +the octal form, this one may be used to specify any Unicode character, even +those beyond 0xFF. So if you \fIreally\fR want a record separator of 0777, +specify it as \fB\-0x1FF\fR. (This means that you cannot use the "\-x" option +with a directory name that consists of hexadecimal digits, or else Perl +will think you have specified a hex number to \fB\-0\fR.) +.IP \fB\-a\fR 5 +.IX Xref "-a autosplit" +.IX Item "-a" +turns on autosplit mode when used with a "\-n" or "\-p". An implicit +split command to the \f(CW@F\fR array is done as the first thing inside the +implicit while loop produced by the "\-n" or "\-p". +.Sp +.Vb 1 +\& perl \-ane \*(Aqprint pop(@F), "\en";\*(Aq +.Ve +.Sp +is equivalent to +.Sp +.Vb 4 +\& while (<>) { +\& @F = split(\*(Aq \*(Aq); +\& print pop(@F), "\en"; +\& } +.Ve +.Sp +An alternate delimiter may be specified using \-F. +.Sp +\&\fB\-a\fR implicitly sets "\-n". +.IP "\fB\-C [\fR\f(BInumber/list\fR\fB]\fR" 5 +.IX Xref "-C" +.IX Item "-C [number/list]" +The \fB\-C\fR flag controls some of the Perl Unicode features. +.Sp +As of 5.8.1, the \fB\-C\fR can be followed either by a number or a list +of option letters. The letters, their numeric values, and effects +are as follows; listing the letters is equal to summing the numbers. +.Sp +.Vb 10 +\& I 1 STDIN is assumed to be in UTF\-8 +\& O 2 STDOUT will be in UTF\-8 +\& E 4 STDERR will be in UTF\-8 +\& S 7 I + O + E +\& i 8 UTF\-8 is the default PerlIO layer for input streams +\& o 16 UTF\-8 is the default PerlIO layer for output streams +\& D 24 i + o +\& A 32 the @ARGV elements are expected to be strings encoded +\& in UTF\-8 +\& L 64 normally the "IOEioA" are unconditional, the L makes +\& them conditional on the locale environment variables +\& (the LC_ALL, LC_CTYPE, and LANG, in the order of +\& decreasing precedence) \-\- if the variables indicate +\& UTF\-8, then the selected "IOEioA" are in effect +\& a 256 Set ${^UTF8CACHE} to \-1, to run the UTF\-8 caching +\& code in debugging mode. +.Ve +.Sp +For example, \fB\-COE\fR and \fB\-C6\fR will both turn on UTF\-8\-ness on both +STDOUT and STDERR. Repeating letters is just redundant, not cumulative +nor toggling. +.Sp +The \f(CW\*(C`io\*(C'\fR options mean that any subsequent \fBopen()\fR (or similar I/O +operations) in main program scope will have the \f(CW\*(C`:utf8\*(C'\fR PerlIO layer +implicitly applied to them, in other words, UTF\-8 is expected from any +input stream, and UTF\-8 is produced to any output stream. This is just +the default set via \f(CW\*(C`${^OPEN}\*(C'\fR, +with explicit layers in \fBopen()\fR and with \fBbinmode()\fR one can +manipulate streams as usual. This has no effect on code run in modules. +.Sp +\&\fB\-C\fR on its own (not followed by any number or option list), or the +empty string \f(CW""\fR for the "PERL_UNICODE" environment variable, has the +same effect as \fB\-CSDL\fR. In other words, the standard I/O handles and +the default \f(CWopen()\fR layer are UTF\-8\-fied \fIbut\fR only if the locale +environment variables indicate a UTF\-8 locale. This behaviour follows +the \fIimplicit\fR (and problematic) UTF\-8 behaviour of Perl 5.8.0. +(See "UTF\-8 no longer default under UTF\-8 locales" in perl581delta.) +.Sp +You can use \fB\-C0\fR (or \f(CW"0"\fR for \f(CW\*(C`PERL_UNICODE\*(C'\fR) to explicitly +disable all the above Unicode features. +.Sp +The read-only magic variable \f(CW\*(C`${^UNICODE}\*(C'\fR reflects the numeric value +of this setting. This variable is set during Perl startup and is +thereafter read-only. If you want runtime effects, use the three-arg +\&\fBopen()\fR (see "open" in perlfunc), the two-arg \fBbinmode()\fR (see "binmode" in perlfunc), +and the \f(CW\*(C`open\*(C'\fR pragma (see open). +.Sp +(In Perls earlier than 5.8.1 the \fB\-C\fR switch was a Win32\-only switch +that enabled the use of Unicode-aware "wide system call" Win32 APIs. +This feature was practically unused, however, and the command line +switch was therefore "recycled".) +.Sp +\&\fBNote:\fR Since perl 5.10.1, if the \fB\-C\fR option is used on the \f(CW\*(C`#!\*(C'\fR line, +it must be specified on the command line as well, since the standard streams +are already set up at this point in the execution of the perl interpreter. +You can also use \fBbinmode()\fR to set the encoding of an I/O stream. +.IP \fB\-c\fR 5 +.IX Xref "-c" +.IX Item "-c" +causes Perl to check the syntax of the program and then exit without +executing it. Actually, it \fIwill\fR execute any \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, +or \f(CW\*(C`CHECK\*(C'\fR blocks and any \f(CW\*(C`use\*(C'\fR statements: these are considered as +occurring outside the execution of your program. \f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR +blocks, however, will be skipped. +.IP \fB\-d\fR 5 +.IX Xref "-d -dt" +.IX Item "-d" +.PD 0 +.IP \fB\-dt\fR 5 +.IX Item "-dt" +.PD +runs the program under the Perl debugger. See perldebug. +If \fBt\fR is specified, it indicates to the debugger that threads +will be used in the code being debugged. +.IP \fB\-d:\fR\fIMOD[=bar,baz]\fR 5 +.IX Xref "-d -dt" +.IX Item "-d:MOD[=bar,baz]" +.PD 0 +.IP \fB\-dt:\fR\fIMOD[=bar,baz]\fR 5 +.IX Item "-dt:MOD[=bar,baz]" +.PD +runs the program under the control of a debugging, profiling, or tracing +module installed as \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW\*(C'\fR. E.g., \fB\-d:DProf\fR executes the +program using the \f(CW\*(C`Devel::DProf\*(C'\fR profiler. As with the \-M +flag, options may be passed to the \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW\*(C'\fR package where they will +be received and interpreted by the \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW::import\*(C'\fR routine. Again, +like \fB\-M\fR, use \-\fB\-d:\-\fR\f(BIMOD\fR to call \f(CW\*(C`Devel::\fR\f(CIMOD\fR\f(CW::unimport\*(C'\fR instead of +import. The comma-separated list of options must follow a \f(CW\*(C`=\*(C'\fR character. +If \fBt\fR is specified, it indicates to the debugger that threads will be used +in the code being debugged. See perldebug. +.IP \fB\-D\fR\fIletters\fR 5 +.IX Xref "-D DEBUGGING -DDEBUGGING" +.IX Item "-Dletters" +.PD 0 +.IP \fB\-D\fR\fInumber\fR 5 +.IX Item "-Dnumber" +.PD +sets debugging flags. This switch is enabled only if your perl binary has +been built with debugging enabled: normal production perls won't have +been. +.Sp +For example, to watch how perl executes your program, use \fB\-Dtls\fR. +Another nice value is \fB\-Dx\fR, which lists your compiled syntax tree, and +\&\fB\-Dr\fR displays compiled regular expressions; the format of the output is +explained in perldebguts. +.Sp +As an alternative, specify a number instead of list of letters (e.g., +\&\fB\-D14\fR is equivalent to \fB\-Dtls\fR): +.Sp +.Vb 10 +\& 1 p Tokenizing and parsing (with v, displays parse +\& stack) +\& 2 s Stack snapshots (with v, displays all stacks) +\& 4 l Context (loop) stack processing +\& 8 t Trace execution +\& 16 o Method and overloading resolution +\& 32 c String/numeric conversions +\& 64 P Print profiling info, source file input state +\& 128 m Memory and SV allocation +\& 256 f Format processing +\& 512 r Regular expression parsing and execution +\& 1024 x Syntax tree dump +\& 2048 u Tainting checks +\& 4096 U Unofficial, User hacking (reserved for private, +\& unreleased use) +\& 8192 h Show hash randomization debug output (changes to +\& PL_hash_rand_bits and their origin) +\& 16384 X Scratchpad allocation +\& 32768 D Cleaning up +\& 65536 S Op slab allocation +\& 131072 T Tokenizing +\& 262144 R Include reference counts of dumped variables +\& (eg when using \-Ds) +\& 524288 J show s,t,P\-debug (don\*(Aqt Jump over) on opcodes within +\& package DB +\& 1048576 v Verbose: use in conjunction with other flags to +\& increase the verbosity of the output. Is a no\-op on +\& many of the other flags +\& 2097152 C Copy On Write +\& 4194304 A Consistency checks on internal structures +\& 8388608 q quiet \- currently only suppresses the "EXECUTING" +\& message +\& 16777216 M trace smart match resolution +\& 33554432 B dump suBroutine definitions, including special +\& Blocks like BEGIN +\& 67108864 L trace Locale\-related info; what gets output is very +\& subject to change +\& 134217728 i trace PerlIO layer processing. Set PERLIO_DEBUG to +\& the filename to trace to. +\& 268435456 y trace y///, tr/// compilation and execution +.Ve +.Sp +All these flags require \fB\-DDEBUGGING\fR when you compile the Perl +executable (but see \f(CW\*(C`:opd\*(C'\fR in Devel::Peek or "'debug' mode" in re +which may change this). +See the INSTALL file in the Perl source distribution +for how to do this. +.Sp +If you're just trying to get a print out of each line of Perl code +as it executes, the way that \f(CW\*(C`sh \-x\*(C'\fR provides for shell scripts, +you can't use Perl's \fB\-D\fR switch. Instead do this +.Sp +.Vb 2 +\& # If you have "env" utility +\& env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl \-dS program +\& +\& # Bourne shell syntax +\& $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl \-dS program +\& +\& # csh syntax +\& % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl \-dS program) +.Ve +.Sp +See perldebug for details and variations. +.IP "\fB\-e\fR \fIcommandline\fR" 5 +.IX Xref "-e" +.IX Item "-e commandline" +may be used to enter one line of program. If \fB\-e\fR is given, Perl +will not look for a filename in the argument list. Multiple \fB\-e\fR +commands may be given to build up a multi-line script. Make sure +to use semicolons where you would in a normal program. +.IP "\fB\-E\fR \fIcommandline\fR" 5 +.IX Xref "-E" +.IX Item "-E commandline" +behaves just like \-e, except that it implicitly +enables all optional features (in the main compilation unit). See +feature. +.IP \fB\-f\fR 5 +.IX Xref "-f sitecustomize sitecustomize.pl" +.IX Item "-f" +Disable executing \fR\f(CI$Config\fR\fI{sitelib}/sitecustomize.pl\fR at startup. +.Sp +Perl can be built so that it by default will try to execute +\&\fR\f(CI$Config\fR\fI{sitelib}/sitecustomize.pl\fR at startup (in a BEGIN block). +This is a hook that allows the sysadmin to customize how Perl behaves. +It can for instance be used to add entries to the \f(CW@INC\fR array to make Perl +find modules in non-standard locations. +.Sp +Perl actually inserts the following code: +.Sp +.Vb 4 +\& BEGIN { +\& do { local $!; \-f "$Config{sitelib}/sitecustomize.pl"; } +\& && do "$Config{sitelib}/sitecustomize.pl"; +\& } +.Ve +.Sp +Since it is an actual \f(CW\*(C`do\*(C'\fR (not a \f(CW\*(C`require\*(C'\fR), \fIsitecustomize.pl\fR +doesn't need to return a true value. The code is run in package \f(CW\*(C`main\*(C'\fR, +in its own lexical scope. However, if the script dies, \f(CW$@\fR will not +be set. +.Sp +The value of \f(CW$Config{sitelib}\fR is also determined in C code and not +read from \f(CW\*(C`Config.pm\*(C'\fR, which is not loaded. +.Sp +The code is executed \fIvery\fR early. For example, any changes made to +\&\f(CW@INC\fR will show up in the output of `perl \-V`. Of course, \f(CW\*(C`END\*(C'\fR +blocks will be likewise executed very late. +.Sp +To determine at runtime if this capability has been compiled in your +perl, you can check the value of \f(CW$Config{usesitecustomize}\fR. +.IP \fB\-F\fR\fIpattern\fR 5 +.IX Xref "-F" +.IX Item "-Fpattern" +specifies the pattern to split on for "\-a". The pattern may be +surrounded by \f(CW\*(C`//\*(C'\fR, \f(CW""\fR, or \f(CW\*(Aq\*(Aq\fR, otherwise it will be put in single +quotes. You can't use literal whitespace or NUL characters in the pattern. +.Sp +\&\fB\-F\fR implicitly sets both "\-a" and "\-n". +.IP \fB\-g\fR 5 +.IX Xref "-g" +.IX Item "-g" +undefines the input record separator (\f(CW$/\fR) and thus +enables the slurp mode. In other words, it causes Perl to read whole +files at once, instead of line by line. +.Sp +This flag is a simpler alias for \-0777. +.Sp +Mnemonics: gobble, grab, gulp. +.IP \fB\-h\fR 5 +.IX Xref "-h" +.IX Item "-h" +prints a summary of the options. +.IP \fB\-?\fR 5 +.IX Xref "-?" +.IX Item "-?" +synonym for \fB\-h\fR: prints a summary of the options. +.IP \fB\-i\fR[\fIextension\fR] 5 +.IX Xref "-i in-place" +.IX Item "-i[extension]" +specifies that files processed by the \f(CW\*(C`<>\*(C'\fR construct are to be +edited in-place. It does this by renaming the input file, opening the +output file by the original name, and selecting that output file as the +default for \fBprint()\fR statements. The extension, if supplied, is used to +modify the name of the old file to make a backup copy, following these +rules: +.Sp +If no extension is supplied, and your system supports it, the original +\&\fIfile\fR is kept open without a name while the output is redirected to +a new file with the original \fIfilename\fR. When perl exits, cleanly or not, +the original \fIfile\fR is unlinked. +.Sp +If the extension doesn't contain a \f(CW\*(C`*\*(C'\fR, then it is appended to the +end of the current filename as a suffix. If the extension does +contain one or more \f(CW\*(C`*\*(C'\fR characters, then each \f(CW\*(C`*\*(C'\fR is replaced +with the current filename. In Perl terms, you could think of this +as: +.Sp +.Vb 1 +\& ($backup = $extension) =~ s/\e*/$file_name/g; +.Ve +.Sp +This allows you to add a prefix to the backup file, instead of (or in +addition to) a suffix: +.Sp +.Vb 2 +\& $ perl \-pi\*(Aqorig_*\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA # backup to +\& # \*(Aqorig_fileA\*(Aq +.Ve +.Sp +Or even to place backup copies of the original files into another +directory (provided the directory already exists): +.Sp +.Vb 2 +\& $ perl \-pi\*(Aqold/*.orig\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA # backup to +\& # \*(Aqold/fileA.orig\*(Aq +.Ve +.Sp +These sets of one-liners are equivalent: +.Sp +.Vb 2 +\& $ perl \-pi \-e \*(Aqs/bar/baz/\*(Aq fileA # overwrite current file +\& $ perl \-pi\*(Aq*\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA # overwrite current file +\& +\& $ perl \-pi\*(Aq.orig\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA # backup to \*(AqfileA.orig\*(Aq +\& $ perl \-pi\*(Aq*.orig\*(Aq \-e \*(Aqs/bar/baz/\*(Aq fileA # backup to \*(AqfileA.orig\*(Aq +.Ve +.Sp +From the shell, saying +.Sp +.Vb 1 +\& $ perl \-p \-i.orig \-e "s/foo/bar/; ... " +.Ve +.Sp +is the same as using the program: +.Sp +.Vb 2 +\& #!/usr/bin/perl \-pi.orig +\& s/foo/bar/; +.Ve +.Sp +which is equivalent to +.Sp +.Vb 10 +\& #!/usr/bin/perl +\& $extension = \*(Aq.orig\*(Aq; +\& LINE: while (<>) { +\& if ($ARGV ne $oldargv) { +\& if ($extension !~ /\e*/) { +\& $backup = $ARGV . $extension; +\& } +\& else { +\& ($backup = $extension) =~ s/\e*/$ARGV/g; +\& } +\& rename($ARGV, $backup); +\& open(ARGVOUT, ">$ARGV"); +\& select(ARGVOUT); +\& $oldargv = $ARGV; +\& } +\& s/foo/bar/; +\& } +\& continue { +\& print; # this prints to original filename +\& } +\& select(STDOUT); +.Ve +.Sp +except that the \fB\-i\fR form doesn't need to compare \f(CW$ARGV\fR to \f(CW$oldargv\fR to +know when the filename has changed. It does, however, use ARGVOUT for +the selected filehandle. Note that STDOUT is restored as the default +output filehandle after the loop. +.Sp +As shown above, Perl creates the backup file whether or not any output +is actually changed. So this is just a fancy way to copy files: +.Sp +.Vb 3 +\& $ perl \-p \-i\*(Aq/some/file/path/*\*(Aq \-e 1 file1 file2 file3... +\&or +\& $ perl \-p \-i\*(Aq.orig\*(Aq \-e 1 file1 file2 file3... +.Ve +.Sp +You can use \f(CW\*(C`eof\*(C'\fR without parentheses to locate the end of each input +file, in case you want to append to each file, or reset line numbering +(see example in "eof" in perlfunc). +.Sp +If, for a given file, Perl is unable to create the backup file as +specified in the extension then it will skip that file and continue on +with the next one (if it exists). +.Sp +For a discussion of issues surrounding file permissions and \fB\-i\fR, see +"Why does Perl let me delete read-only files? Why does \-i clobber +protected files? Isn't this a bug in Perl?" in perlfaq5. +.Sp +You cannot use \fB\-i\fR to create directories or to strip extensions from +files. +.Sp +Perl does not expand \f(CW\*(C`~\*(C'\fR in filenames, which is good, since some +folks use it for their backup files: +.Sp +.Vb 1 +\& $ perl \-pi~ \-e \*(Aqs/foo/bar/\*(Aq file1 file2 file3... +.Ve +.Sp +Note that because \fB\-i\fR renames or deletes the original file before +creating a new file of the same name, Unix-style soft and hard links will +not be preserved. +.Sp +Finally, the \fB\-i\fR switch does not impede execution when no +files are given on the command line. In this case, no backup is made +(the original file cannot, of course, be determined) and processing +proceeds from STDIN to STDOUT as might be expected. +.IP \fB\-I\fR\fIdirectory\fR 5 +.IX Xref "-I @INC" +.IX Item "-Idirectory" +Directories specified by \fB\-I\fR are prepended to the search path for +modules (\f(CW@INC\fR). +.IP \fB\-l\fR[\fIoctnum\fR] 5 +.IX Xref "-l $ $\\" +.IX Item "-l[octnum]" +enables automatic line-ending processing. It has two separate +effects. First, it automatically chomps \f(CW$/\fR (the input record +separator) when used with "\-n" or "\-p". Second, it assigns \f(CW\*(C`$\e\*(C'\fR +(the output record separator) to have the value of \fIoctnum\fR so +that any print statements will have that separator added back on. +If \fIoctnum\fR is omitted, sets \f(CW\*(C`$\e\*(C'\fR to the current value of +\&\f(CW$/\fR. For instance, to trim lines to 80 columns: +.Sp +.Vb 1 +\& perl \-lpe \*(Aqsubstr($_, 80) = ""\*(Aq +.Ve +.Sp +Note that the assignment \f(CW\*(C`$\e = $/\*(C'\fR is done when the switch is processed, +so the input record separator can be different than the output record +separator if the \fB\-l\fR switch is followed by a +\&\-0 switch: +.Sp +.Vb 1 +\& gnufind / \-print0 | perl \-ln0e \*(Aqprint "found $_" if \-p\*(Aq +.Ve +.Sp +This sets \f(CW\*(C`$\e\*(C'\fR to newline and then sets \f(CW$/\fR to the null character. +.IP \fB\-m\fR[\fB\-\fR]\fImodule\fR 5 +.IX Xref "-m -M" +.IX Item "-m[-]module" +.PD 0 +.IP \fB\-M\fR[\fB\-\fR]\fImodule\fR 5 +.IX Item "-M[-]module" +.IP "\fB\-M\fR[\fB\-\fR]\fI'module ...'\fR" 5 +.IX Item "-M[-]'module ...'" +.IP \fB\-[mM]\fR[\fB\-\fR]\fImodule=arg[,arg]...\fR 5 +.IX Item "-[mM][-]module=arg[,arg]..." +.PD +\&\fB\-m\fR\fImodule\fR executes \f(CW\*(C`use\*(C'\fR \fImodule\fR \f(CW\*(C`();\*(C'\fR before executing your +program. This loads the module, but does not call its \f(CW\*(C`import\*(C'\fR method, +so does not import subroutines and does not give effect to a pragma. +.Sp +\&\fB\-M\fR\fImodule\fR executes \f(CW\*(C`use\*(C'\fR \fImodule\fR \f(CW\*(C`;\*(C'\fR before executing your +program. This loads the module and calls its \f(CW\*(C`import\*(C'\fR method, causing +the module to have its default effect, typically importing subroutines +or giving effect to a pragma. +You can use quotes to add extra code after the module name, +e.g., \f(CW\*(Aq\-M\fR\f(CIMODULE\fR\f(CW qw(foo bar)\*(Aq\fR. +.Sp +If the first character after the \fB\-M\fR or \fB\-m\fR is a dash (\fB\-\fR) +then the 'use' is replaced with 'no'. +This makes no difference for \fB\-m\fR. +.Sp +A little builtin syntactic sugar means you can also say +\&\fB\-m\fR\f(BIMODULE\fR\fB=foo,bar\fR or \fB\-M\fR\f(BIMODULE\fR\fB=foo,bar\fR as a shortcut for +\&\fB'\-M\fR\f(BIMODULE\fR\fB qw(foo bar)'\fR. This avoids the need to use quotes when +importing symbols. The actual code generated by \fB\-M\fR\f(BIMODULE\fR\fB=foo,bar\fR is +\&\f(CW\*(C`use module split(/,/,q{foo,bar})\*(C'\fR. Note that the \f(CW\*(C`=\*(C'\fR form +removes the distinction between \fB\-m\fR and \fB\-M\fR; that is, +\&\fB\-m\fR\f(BIMODULE\fR\fB=foo,bar\fR is the same as \fB\-M\fR\f(BIMODULE\fR\fB=foo,bar\fR. +.Sp +A consequence of the \f(CW\*(C`split\*(C'\fR formulation +is that \fB\-M\fR\f(BIMODULE\fR\fB=number\fR never does a version check, +unless \f(CW\*(C`\fR\f(CIMODULE\fR\f(CW::import()\*(C'\fR itself is set up to do a version check, which +could happen for example if \fIMODULE\fR inherits from Exporter. +.IP \fB\-n\fR 5 +.IX Xref "-n" +.IX Item "-n" +causes Perl to assume the following loop around your program, which +makes it iterate over filename arguments somewhat like \fIsed \-n\fR or +\&\fIawk\fR: +.Sp +.Vb 4 +\& LINE: +\& while (<>) { +\& ... # your program goes here +\& } +.Ve +.Sp +Note that the lines are not printed by default. See "\-p" to have +lines printed. If a file named by an argument cannot be opened for +some reason, Perl warns you about it and moves on to the next file. +.Sp +Also note that \f(CW\*(C`<>\*(C'\fR passes command line arguments to +"open" in perlfunc, which doesn't necessarily interpret them as file names. +See perlop for possible security implications. +.Sp +Here is an efficient way to delete all files that haven't been modified for +at least a week: +.Sp +.Vb 1 +\& find . \-mtime +7 \-print | perl \-nle unlink +.Ve +.Sp +This is faster than using the \fB\-exec\fR switch of \fIfind\fR because you don't +have to start a process on every filename found (but it's not faster +than using the \fB\-delete\fR switch available in newer versions of \fIfind\fR. +It does suffer from the bug of mishandling newlines in pathnames, which +you can fix if you follow the example under +\&\-0. +.Sp +\&\f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`END\*(C'\fR blocks may be used to capture control before or after +the implicit program loop, just as in \fIawk\fR. +.IP \fB\-p\fR 5 +.IX Xref "-p" +.IX Item "-p" +causes Perl to assume the following loop around your program, which +makes it iterate over filename arguments somewhat like \fIsed\fR: +.Sp +.Vb 6 +\& LINE: +\& while (<>) { +\& ... # your program goes here +\& } continue { +\& print or die "\-p destination: $!\en"; +\& } +.Ve +.Sp +If a file named by an argument cannot be opened for some reason, Perl +warns you about it, and moves on to the next file. Note that the +lines are printed automatically. An error occurring during printing is +treated as fatal. To suppress printing use the "\-n" switch. A \fB\-p\fR +overrides a \fB\-n\fR switch. +.Sp +\&\f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`END\*(C'\fR blocks may be used to capture control before or after +the implicit loop, just as in \fIawk\fR. +.IP \fB\-s\fR 5 +.IX Xref "-s" +.IX Item "-s" +enables rudimentary switch parsing for switches on the command +line after the program name but before any filename arguments (or before +an argument of \fB\-\-\fR). Any switch found there is removed from \f(CW@ARGV\fR and sets the +corresponding variable in the Perl program, in the main package. The following program +prints "1" if the program is invoked with a \fB\-xyz\fR switch, and "abc" +if it is invoked with \fB\-xyz=abc\fR. +.Sp +.Vb 2 +\& #!/usr/bin/perl \-s +\& if ($xyz) { print "$xyz\en" } +.Ve +.Sp +Do note that a switch like \fB\-\-help\fR creates the variable \f(CW\*(C`${\-help}\*(C'\fR, which is +not compliant with \f(CW\*(C`use strict "refs"\*(C'\fR. Also, when using this option on a +script with warnings enabled you may get a lot of spurious "used only once" +warnings. For these reasons, use of \fB\-s\fR is discouraged. See Getopt::Long +for much more flexible switch parsing. +.IP \fB\-S\fR 5 +.IX Xref "-S" +.IX Item "-S" +makes Perl use the "PATH" environment variable to search for the +program unless the name of the program contains path separators. +.Sp +On some platforms, this also makes Perl append suffixes to the +filename while searching for it. For example, on Win32 platforms, +the ".bat" and ".cmd" suffixes are appended if a lookup for the +original name fails, and if the name does not already end in one +of those suffixes. If your Perl was compiled with \f(CW\*(C`DEBUGGING\*(C'\fR turned +on, using the \-Dp switch to Perl shows how the search +progresses. +.Sp +Typically this is used to emulate \f(CW\*(C`#!\*(C'\fR startup on platforms that don't +support \f(CW\*(C`#!\*(C'\fR. It's also convenient when debugging a script that uses \f(CW\*(C`#!\*(C'\fR, +and is thus normally found by the shell's \f(CW$PATH\fR search mechanism. +.Sp +This example works on many platforms that have a shell compatible with +Bourne shell: +.Sp +.Vb 3 +\& #!/usr/bin/perl +\& eval \*(Aqexec /usr/bin/perl \-wS $0 ${1+"$@"}\*(Aq +\& if 0; # ^ Run only under a shell +.Ve +.Sp +The system ignores the first line and feeds the program to \fI/bin/sh\fR, +which proceeds to try to execute the Perl program as a shell script. +The shell executes the second line as a normal shell command, and thus +starts up the Perl interpreter. On some systems \f(CW$0\fR doesn't always +contain the full pathname, so the "\-S" tells Perl to search for the +program if necessary. After Perl locates the program, it parses the +lines and ignores them because the check 'if 0' is never true. +If the program will be interpreted by csh, you will need +to replace \f(CW\*(C`${1+"$@"}\*(C'\fR with \f(CW$*\fR, even though that doesn't understand +embedded spaces (and such) in the argument list. To start up \fIsh\fR rather +than \fIcsh\fR, some systems may have to replace the \f(CW\*(C`#!\*(C'\fR line with a line +containing just a colon, which will be politely ignored by Perl. Other +systems can't control that, and need a totally devious construct that +will work under any of \fIcsh\fR, \fIsh\fR, or Perl, such as the following: +.Sp +.Vb 3 +\& eval \*(Aq(exit $?0)\*(Aq && eval \*(Aqexec perl \-wS $0 ${1+"$@"}\*(Aq +\& & eval \*(Aqexec /usr/bin/perl \-wS $0 $argv:q\*(Aq +\& if 0; # ^ Run only under a shell +.Ve +.Sp +If the filename supplied contains directory separators (and so is an +absolute or relative pathname), and if that file is not found, +platforms that append file extensions will do so and try to look +for the file with those extensions added, one by one. +.Sp +On DOS-like platforms, if the program does not contain directory +separators, it will first be searched for in the current directory +before being searched for on the PATH. On Unix platforms, the +program will be searched for strictly on the PATH. +.IP \fB\-t\fR 5 +.IX Xref "-t" +.IX Item "-t" +Like "\-T", but taint checks will issue warnings rather than fatal +errors. These warnings can now be controlled normally with \f(CWno warnings +qw(taint)\fR. +.Sp +\&\fBNote: This is not a substitute for \fR\f(CB\*(C`\-T\*(C'\fR\fB!\fR This is meant to be +used \fIonly\fR as a temporary development aid while securing legacy code: +for real production code and for new secure code written from scratch, +always use the real "\-T". +.Sp +This has no effect if your perl was built without taint support. +.IP \fB\-T\fR 5 +.IX Xref "-T" +.IX Item "-T" +turns on "taint" so you can test them. Ordinarily +these checks are done only when running setuid or setgid. It's a +good idea to turn them on explicitly for programs that run on behalf +of someone else whom you might not necessarily trust, such as CGI +programs or any internet servers you might write in Perl. See +perlsec for details. For security reasons, this option must be +seen by Perl quite early; usually this means it must appear early +on the command line or in the \f(CW\*(C`#!\*(C'\fR line for systems which support +that construct. +.IP \fB\-u\fR 5 +.IX Xref "-u" +.IX Item "-u" +This switch causes Perl to dump core after compiling your +program. You can then in theory take this core dump and turn it +into an executable file by using the \fIundump\fR program (not supplied). +This speeds startup at the expense of some disk space (which you +can minimize by stripping the executable). (Still, a "hello world" +executable comes out to about 200K on my machine.) If you want to +execute a portion of your program before dumping, use the \f(CWCORE::dump()\fR +function instead. Note: availability of \fIundump\fR is platform +specific and may not be available for a specific port of Perl. +.IP \fB\-U\fR 5 +.IX Xref "-U" +.IX Item "-U" +allows Perl to do unsafe operations. Currently the only "unsafe" +operations are attempting to unlink directories while running as superuser +and running setuid programs with fatal taint checks turned into warnings. +Note that warnings must be enabled along with this option to actually +\&\fIgenerate\fR the taint-check warnings. +.IP \fB\-v\fR 5 +.IX Xref "-v" +.IX Item "-v" +prints the version and patchlevel of your perl executable. +.IP \fB\-V\fR 5 +.IX Xref "-V" +.IX Item "-V" +prints summary of the major perl configuration values and the current +values of \f(CW@INC\fR. +.IP \fB\-V:\fR\fIconfigvar\fR 5 +.IX Item "-V:configvar" +Prints to STDOUT the value of the named configuration variable(s), +with multiples when your \f(CW\*(C`\fR\f(CIconfigvar\fR\f(CW\*(C'\fR argument looks like a regex (has +non-letters). For example: +.Sp +.Vb 12 +\& $ perl \-V:libc +\& libc=\*(Aq/lib/libc\-2.2.4.so\*(Aq; +\& $ perl \-V:lib. +\& libs=\*(Aq\-lnsl \-lgdbm \-ldb \-ldl \-lm \-lcrypt \-lutil \-lc\*(Aq; +\& libc=\*(Aq/lib/libc\-2.2.4.so\*(Aq; +\& $ perl \-V:lib.* +\& libpth=\*(Aq/usr/local/lib /lib /usr/lib\*(Aq; +\& libs=\*(Aq\-lnsl \-lgdbm \-ldb \-ldl \-lm \-lcrypt \-lutil \-lc\*(Aq; +\& lib_ext=\*(Aq.a\*(Aq; +\& libc=\*(Aq/lib/libc\-2.2.4.so\*(Aq; +\& libperl=\*(Aqlibperl.a\*(Aq; +\& .... +.Ve +.Sp +Additionally, extra colons can be used to control formatting. A +trailing colon suppresses the linefeed and terminator ";", allowing +you to embed queries into shell commands. (mnemonic: PATH separator +":".) +.Sp +.Vb 2 +\& $ echo "compression\-vars: " \`perl \-V:z.*: \` " are here !" +\& compression\-vars: zcat=\*(Aq\*(Aq zip=\*(Aqzip\*(Aq are here ! +.Ve +.Sp +A leading colon removes the "name=" part of the response, this allows +you to map to the name you need. (mnemonic: empty label) +.Sp +.Vb 2 +\& $ echo "goodvfork="\`./perl \-Ilib \-V::usevfork\` +\& goodvfork=false; +.Ve +.Sp +Leading and trailing colons can be used together if you need +positional parameter values without the names. Note that in the case +below, the \f(CW\*(C`PERL_API\*(C'\fR params are returned in alphabetical order. +.Sp +.Vb 2 +\& $ echo building_on \`perl \-V::osname: \-V::PERL_API_.*:\` now +\& building_on \*(Aqlinux\*(Aq \*(Aq5\*(Aq \*(Aq1\*(Aq \*(Aq9\*(Aq now +.Ve +.IP \fB\-w\fR 5 +.IX Xref "-w" +.IX Item "-w" +prints warnings about dubious constructs, such as variable names +mentioned only once and scalar variables used +before being set; redefined subroutines; references to undefined +filehandles; filehandles opened read-only that you are attempting +to write on; values used as a number that don't \fIlook\fR like numbers; +using an array as though it were a scalar; if your subroutines +recurse more than 100 deep; and innumerable other things. +.Sp +This switch really just enables the global \f(CW$^W\fR variable; normally, +the lexically scoped \f(CW\*(C`use warnings\*(C'\fR pragma is preferred. You +can disable or promote into fatal errors specific warnings using +\&\f(CW\*(C`_\|_WARN_\|_\*(C'\fR hooks, as described in perlvar and "warn" in perlfunc. +See also perldiag and perltrap. A fine-grained warning +facility is also available if you want to manipulate entire classes +of warnings; see warnings. +.IP \fB\-W\fR 5 +.IX Xref "-W" +.IX Item "-W" +Enables all warnings regardless of \f(CW\*(C`no warnings\*(C'\fR or \f(CW$^W\fR. +See warnings. +.IP \fB\-X\fR 5 +.IX Xref "-X" +.IX Item "-X" +Disables all warnings regardless of \f(CW\*(C`use warnings\*(C'\fR or \f(CW$^W\fR. +See warnings. +.Sp +Forbidden in \f(CW"PERL5OPT"\fR. +.IP \fB\-x\fR 5 +.IX Xref "-x" +.IX Item "-x" +.PD 0 +.IP \fB\-x\fR\fIdirectory\fR 5 +.IX Item "-xdirectory" +.PD +tells Perl that the program is embedded in a larger chunk of unrelated +text, such as in a mail message. Leading garbage will be +discarded until the first line that starts with \f(CW\*(C`#!\*(C'\fR and contains the +string "perl". Any meaningful switches on that line will be applied. +.Sp +All references to line numbers by the program (warnings, errors, ...) +will treat the \f(CW\*(C`#!\*(C'\fR line as the first line. +Thus a warning on the 2nd line of the program, which is on the 100th +line in the file will be reported as line 2, not as line 100. +This can be overridden by using the \f(CW\*(C`#line\*(C'\fR directive. +(See "Plain Old Comments (Not!)" in perlsyn) +.Sp +If a directory name is specified, Perl will switch to that directory +before running the program. The \fB\-x\fR switch controls only the +disposal of leading garbage. The program must be terminated with +\&\f(CW\*(C`_\|_END_\|_\*(C'\fR if there is trailing garbage to be ignored; the program +can process any or all of the trailing garbage via the \f(CW\*(C`DATA\*(C'\fR filehandle +if desired. +.Sp +The directory, if specified, must appear immediately following the \fB\-x\fR +with no intervening whitespace. +.SH ENVIRONMENT +.IX Xref "perl, environment variables" +.IX Header "ENVIRONMENT" +.IP HOME 12 +.IX Xref "HOME" +.IX Item "HOME" +Used if \f(CW\*(C`chdir\*(C'\fR has no argument. +.IP LOGDIR 12 +.IX Xref "LOGDIR" +.IX Item "LOGDIR" +Used if \f(CW\*(C`chdir\*(C'\fR has no argument and "HOME" is not set. +.IP PATH 12 +.IX Xref "PATH" +.IX Item "PATH" +Used in executing subprocesses, and in finding the program if "\-S" is +used. +.IP PERL5LIB 12 +.IX Xref "PERL5LIB" +.IX Item "PERL5LIB" +A list of directories in which to look for Perl library files before +looking in the standard library. +Any architecture-specific and version-specific directories, +such as \fIversion/archname/\fR, \fIversion/\fR, or \fIarchname/\fR under the +specified locations are automatically included if they exist, with this +lookup done at interpreter startup time. In addition, any directories +matching the entries in \f(CW$Config{inc_version_list}\fR are added. +(These typically would be for older compatible perl versions installed +in the same directory tree.) +.Sp +If PERL5LIB is not defined, "PERLLIB" is used. Directories are separated +(like in PATH) by a colon on Unixish platforms and by a semicolon on +Windows (the proper path separator being given by the command \f(CW\*(C`perl +\&\-V:\fR\f(CIpath_sep\fR\f(CW\*(C'\fR). +.Sp +When running taint checks, either because the program was running setuid or +setgid, or the "\-T" or "\-t" switch was specified, neither PERL5LIB nor +"PERLLIB" is consulted. The program should instead say: +.Sp +.Vb 1 +\& use lib "/my/directory"; +.Ve +.IP PERL5OPT 12 +.IX Xref "PERL5OPT" +.IX Item "PERL5OPT" +Command-line options (switches). Switches in this variable are treated +as if they were on every Perl command line. Only the \fB\-[CDIMTUWdmtw]\fR +switches are allowed. When running taint checks (either because the +program was running setuid or setgid, or because the "\-T" or "\-t" +switch was used), this variable is ignored. If PERL5OPT begins with +\&\fB\-T\fR, tainting will be enabled and subsequent options ignored. If +PERL5OPT begins with \fB\-t\fR, tainting will be enabled, a writable dot +removed from \f(CW@INC\fR, and subsequent options honored. +.IP PERLIO 12 +.IX Xref "PERLIO" +.IX Item "PERLIO" +A space (or colon) separated list of PerlIO layers. If perl is built +to use PerlIO system for IO (the default) these layers affect Perl's IO. +.Sp +It is conventional to start layer names with a colon (for example, \f(CW\*(C`:perlio\*(C'\fR) to +emphasize their similarity to variable "attributes". But the code that parses +layer specification strings, which is also used to decode the PERLIO +environment variable, treats the colon as a separator. +.Sp +An unset or empty PERLIO is equivalent to the default set of layers for +your platform; for example, \f(CW\*(C`:unix:perlio\*(C'\fR on Unix-like systems +and \f(CW\*(C`:unix:crlf\*(C'\fR on Windows and other DOS-like systems. +.Sp +The list becomes the default for \fIall\fR Perl's IO. Consequently only built-in +layers can appear in this list, as external layers (such as \f(CW:encoding()\fR) need +IO in order to load them! See "open pragma" for how to add external +encodings as defaults. +.Sp +Layers it makes sense to include in the PERLIO environment +variable are briefly summarized below. For more details see PerlIO. +.RS 12 +.IP :crlf 8 +.IX Xref ":crlf" +.IX Item ":crlf" +A layer which does CRLF to \f(CW"\en"\fR translation distinguishing "text" and +"binary" files in the manner of MS-DOS and similar operating systems, +and also provides buffering similar to \f(CW\*(C`:perlio\*(C'\fR on these architectures. +.IP :perlio 8 +.IX Xref ":perlio" +.IX Item ":perlio" +This is a re-implementation of stdio-like buffering written as a +PerlIO layer. As such it will call whatever layer is below it for +its operations, typically \f(CW\*(C`:unix\*(C'\fR. +.IP :stdio 8 +.IX Xref ":stdio" +.IX Item ":stdio" +This layer provides a PerlIO interface by wrapping system's ANSI C "stdio" +library calls. The layer provides both buffering and IO. +Note that the \f(CW\*(C`:stdio\*(C'\fR layer does \fInot\fR do CRLF translation even if that +is the platform's normal behaviour. You will need a \f(CW\*(C`:crlf\*(C'\fR layer above it +to do that. +.IP :unix 8 +.IX Xref ":unix" +.IX Item ":unix" +Low-level layer that calls \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`write\*(C'\fR, \f(CW\*(C`lseek\*(C'\fR, etc. +.RE +.RS 12 +.Sp +The default set of layers should give acceptable results on all platforms. +.Sp +For Unix platforms that will be the equivalent of ":unix:perlio" or ":stdio". +Configure is set up to prefer the ":stdio" implementation if the system's library +provides for fast access to the buffer (not common on modern architectures); +otherwise, it uses the ":unix:perlio" implementation. +.Sp +On Win32 the default in this release (5.30) is ":unix:crlf". Win32's ":stdio" +has a number of bugs/mis\-features for Perl IO which are somewhat depending +on the version and vendor of the C compiler. Using our own \f(CW\*(C`:crlf\*(C'\fR layer as +the buffer avoids those issues and makes things more uniform. +.Sp +This release (5.30) uses \f(CW\*(C`:unix\*(C'\fR as the bottom layer on Win32, and so still +uses the C compiler's numeric file descriptor routines. +.Sp +The PERLIO environment variable is completely ignored when Perl +is run in taint mode. +.RE +.IP PERLIO_DEBUG 12 +.IX Xref "PERLIO_DEBUG" +.IX Item "PERLIO_DEBUG" +If set to the name of a file or device when Perl is run with the +\&\-Di command-line switch, the logging of certain operations +of the PerlIO subsystem will be redirected to the specified file rather +than going to stderr, which is the default. The file is opened in append +mode. Typical uses are in Unix: +.Sp +.Vb 1 +\& % env PERLIO_DEBUG=/tmp/perlio.log perl \-Di script ... +.Ve +.Sp +and under Win32, the approximately equivalent: +.Sp +.Vb 2 +\& > set PERLIO_DEBUG=CON +\& perl \-Di script ... +.Ve +.Sp +This functionality is disabled for setuid scripts, for scripts run +with "\-T", and for scripts run on a Perl built without \f(CW\*(C`\-DDEBUGGING\*(C'\fR +support. +.IP PERLLIB 12 +.IX Xref "PERLLIB" +.IX Item "PERLLIB" +A list of directories in which to look for Perl library +files before looking in the standard library. +If "PERL5LIB" is defined, PERLLIB is not used. +.Sp +The PERLLIB environment variable is completely ignored when Perl +is run in taint mode. +.IP PERL5DB 12 +.IX Xref "PERL5DB" +.IX Item "PERL5DB" +The command used to load the debugger code. The default is: +.Sp +.Vb 1 +\& BEGIN { require "perl5db.pl" } +.Ve +.Sp +The PERL5DB environment variable is only used when Perl is started with +a bare "\-d" switch. +.IP PERL5DB_THREADED 12 +.IX Xref "PERL5DB_THREADED" +.IX Item "PERL5DB_THREADED" +If set to a true value, indicates to the debugger that the code being +debugged uses threads. +.IP "PERL5SHELL (specific to the Win32 port)" 12 +.IX Xref "PERL5SHELL" +.IX Item "PERL5SHELL (specific to the Win32 port)" +On Win32 ports only, may be set to an alternative shell that Perl must use +internally for executing "backtick" commands or \fBsystem()\fR. Default is +\&\f(CW\*(C`cmd.exe /x/d/c\*(C'\fR on WindowsNT and \f(CW\*(C`command.com /c\*(C'\fR on Windows95. The +value is considered space-separated. Precede any character that +needs to be protected, like a space or backslash, with another backslash. +.Sp +Note that Perl doesn't use COMSPEC for this purpose because +COMSPEC has a high degree of variability among users, leading to +portability concerns. Besides, Perl can use a shell that may not be +fit for interactive use, and setting COMSPEC to such a shell may +interfere with the proper functioning of other programs (which usually +look in COMSPEC to find a shell fit for interactive use). +.Sp +Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked +when running external commands. It is recommended that +you explicitly set (or delete) \f(CW$ENV{PERL5SHELL}\fR when running +in taint mode under Windows. +.IP "PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)" 12 +.IX Xref "PERL_ALLOW_NON_IFS_LSP" +.IX Item "PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)" +Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers). +Perl normally searches for an IFS-compatible LSP because this is required +for its emulation of Windows sockets as real filehandles. However, this may +cause problems if you have a firewall such as \fIMcAfee Guardian\fR, which requires +that all applications use its LSP but which is not IFS-compatible, because clearly +Perl will normally avoid using such an LSP. +.Sp +Setting this environment variable to 1 means that Perl will simply use the +first suitable LSP enumerated in the catalog, which keeps \fIMcAfee Guardian\fR +happy\-\-and in that particular case Perl still works too because \fIMcAfee +Guardian\fR's LSP actually plays other games which allow applications +requiring IFS compatibility to work. +.IP PERL_DEBUG_MSTATS 12 +.IX Xref "PERL_DEBUG_MSTATS" +.IX Item "PERL_DEBUG_MSTATS" +Relevant only if Perl is compiled with the \f(CW\*(C`malloc\*(C'\fR included with the Perl +distribution; that is, if \f(CW\*(C`perl \-V:d_mymalloc\*(C'\fR is "define". +.Sp +If set, this dumps out memory statistics after execution. If set +to an integer greater than one, also dumps out memory statistics +after compilation. +.IP PERL_DESTRUCT_LEVEL 12 +.IX Xref "PERL_DESTRUCT_LEVEL" +.IX Item "PERL_DESTRUCT_LEVEL" +Controls the behaviour of global destruction of objects and other +references. See "PERL_DESTRUCT_LEVEL" in perlhacktips for more information. +.IP PERL_DL_NONLAZY 12 +.IX Xref "PERL_DL_NONLAZY" +.IX Item "PERL_DL_NONLAZY" +Set to \f(CW"1"\fR to have Perl resolve \fIall\fR undefined symbols when it loads +a dynamic library. The default behaviour is to resolve symbols when +they are used. Setting this variable is useful during testing of +extensions, as it ensures that you get an error on misspelled function +names even if the test suite doesn't call them. +.IP PERL_ENCODING 12 +.IX Xref "PERL_ENCODING" +.IX Item "PERL_ENCODING" +If using the \f(CW\*(C`use encoding\*(C'\fR pragma without an explicit encoding name, the +PERL_ENCODING environment variable is consulted for an encoding name. +.IP PERL_HASH_SEED 12 +.IX Xref "PERL_HASH_SEED" +.IX Item "PERL_HASH_SEED" +(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override +the randomization of Perl's internal hash function. The value is expressed +in hexadecimal, and may include a leading 0x. Truncated patterns +are treated as though they are suffixed with sufficient 0's as required. +.Sp +If the option is provided, and \f(CW\*(C`PERL_PERTURB_KEYS\*(C'\fR is NOT set, then +a value of '0' implies \f(CW\*(C`PERL_PERTURB_KEYS=0\*(C'\fR/\f(CW\*(C`PERL_PERTURB_KEYS=NO\*(C'\fR +and any other value implies +\&\f(CW\*(C`PERL_PERTURB_KEYS=2\*(C'\fR/\f(CW\*(C`PERL_PERTURB_KEYS=DETERMINISTIC\*(C'\fR. See the +documentation for PERL_PERTURB_KEYS for important +caveats regarding the \f(CW\*(C`DETERMINISTIC\*(C'\fR mode. +.Sp +\&\fBPLEASE NOTE: The hash seed is sensitive information\fR. Hashes are +randomized to protect against local and remote attacks against Perl +code. By manually setting a seed, this protection may be partially or +completely lost. +.Sp +See "Algorithmic Complexity Attacks" in perlsec, "PERL_PERTURB_KEYS", and +"PERL_HASH_SEED_DEBUG" for more information. +.IP PERL_PERTURB_KEYS 12 +.IX Xref "PERL_PERTURB_KEYS" +.IX Item "PERL_PERTURB_KEYS" +(Since Perl 5.18.0) Set to \f(CW"0"\fR or \f(CW"NO"\fR then traversing keys +will be repeatable from run to run for the same \f(CW\*(C`PERL_HASH_SEED\*(C'\fR. +Insertion into a hash will not change the order, except to provide +for more space in the hash. When combined with setting PERL_HASH_SEED +this mode is as close to pre 5.18 behavior as you can get. +.Sp +When set to \f(CW"1"\fR or \f(CW"RANDOM"\fR then traversing keys will be randomized. +Every time a hash is inserted into the key order will change in a random +fashion. The order may not be repeatable in a following program run +even if the PERL_HASH_SEED has been specified. This is the default +mode for perl when no PERL_HASH_SEED has been explicitly provided. +.Sp +When set to \f(CW"2"\fR or \f(CW"DETERMINISTIC"\fR then inserting keys into a hash +will cause the key order to change, but in a way that is repeatable from +program run to program run, provided that the same hash seed is used, +and that the code does not itself perform any non-deterministic +operations and also provided exactly the same environment context. +Adding or removing an environment variable may and likely will change +the key order. If any part of the code builds a hash using non\- +deterministic keys, for instance a hash keyed by the stringified form of +a reference, or the address of the objects it contains, then this may +and likely will have a global effect on the key order of *every* hash in +the process. To work properly this setting MUST be coupled with the +PERL_HASH_SEED to produce deterministic results, +and in fact, if you do set the \f(CW\*(C`PERL_HASH_SEED\*(C'\fR explicitly you do not +need to set this as well, it will be automatically set to this mode. +.Sp +\&\fBNOTE:\fR Use of this option is considered insecure, and is intended only +for debugging non-deterministic behavior in Perl's hash function. Do +not use it in production. +.Sp +See "Algorithmic Complexity Attacks" in perlsec and "PERL_HASH_SEED" +and "PERL_HASH_SEED_DEBUG" for more information. You can get and set the +key traversal mask for a specific hash by using the \f(CWhash_traversal_mask()\fR +function from Hash::Util. +.IP PERL_HASH_SEED_DEBUG 12 +.IX Xref "PERL_HASH_SEED_DEBUG" +.IX Item "PERL_HASH_SEED_DEBUG" +(Since Perl 5.8.1.) Set to \f(CW"1"\fR to display (to STDERR) information +about the hash function, seed, and what type of key traversal +randomization is in effect at the beginning of execution. This, combined +with "PERL_HASH_SEED" and "PERL_PERTURB_KEYS" is intended to aid in +debugging nondeterministic behaviour caused by hash randomization. +.Sp +\&\fBNote\fR that any information about the hash function, especially the hash +seed is \fBsensitive information\fR: by knowing it, one can craft a denial-of-service +attack against Perl code, even remotely; see "Algorithmic Complexity Attacks" in perlsec +for more information. \fBDo not disclose the hash seed\fR to people who +don't need to know it. See also \f(CWhash_seed()\fR and +\&\f(CWhash_traversal_mask()\fR. +.Sp +An example output might be: +.Sp +.Vb 1 +\& HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM) +.Ve +.IP PERL_MEM_LOG 12 +.IX Xref "PERL_MEM_LOG" +.IX Item "PERL_MEM_LOG" +If your Perl was configured with \fB\-Accflags=\-DPERL_MEM_LOG\fR, setting +the environment variable \f(CW\*(C`PERL_MEM_LOG\*(C'\fR enables logging debug +messages. The value has the form \f(CW\*(C`<\fR\f(CInumber\fR\f(CW>[m][s][t]\*(C'\fR, where +\&\f(CW\*(C`\fR\f(CInumber\fR\f(CW\*(C'\fR is the file descriptor number you want to write to (2 is +default), and the combination of letters specifies that you want +information about (m)emory and/or (s)v, optionally with +(t)imestamps. For example, \f(CW\*(C`PERL_MEM_LOG=1mst\*(C'\fR logs all +information to stdout. You can write to other opened file descriptors +in a variety of ways: +.Sp +.Vb 1 +\& $ 3>foo3 PERL_MEM_LOG=3m perl ... +.Ve +.IP "PERL_ROOT (specific to the VMS port)" 12 +.IX Xref "PERL_ROOT" +.IX Item "PERL_ROOT (specific to the VMS port)" +A translation-concealed rooted logical name that contains Perl and the +logical device for the \f(CW@INC\fR path on VMS only. Other logical names that +affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and +SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in +perlvms and in \fIREADME.vms\fR in the Perl source distribution. +.IP PERL_SIGNALS 12 +.IX Xref "PERL_SIGNALS" +.IX Item "PERL_SIGNALS" +Available in Perls 5.8.1 and later. If set to \f(CW"unsafe"\fR, the pre\-Perl\-5.8.0 +signal behaviour (which is immediate but unsafe) is restored. If set +to \f(CW\*(C`safe\*(C'\fR, then safe (but deferred) signals are used. See +"Deferred Signals (Safe Signals)" in perlipc. +.IP PERL_UNICODE 12 +.IX Xref "PERL_UNICODE" +.IX Item "PERL_UNICODE" +Equivalent to the \-C command-line switch. Note +that this is not a boolean variable. Setting this to \f(CW"1"\fR is not the +right way to "enable Unicode" (whatever that would mean). You can use +\&\f(CW"0"\fR to "disable Unicode", though (or alternatively unset PERL_UNICODE +in your shell before starting Perl). See the description of the +\&\-C switch for more information. +.IP PERL_USE_UNSAFE_INC 12 +.IX Xref "PERL_USE_UNSAFE_INC" +.IX Item "PERL_USE_UNSAFE_INC" +If perl has been configured to not have the current directory in +\&\f(CW@INC\fR by default, this variable can be set to \f(CW"1"\fR +to reinstate it. It's primarily intended for use while building and +testing modules that have not been updated to deal with "." not being in +\&\f(CW@INC\fR and should not be set in the environment for day-to-day use. +.IP "SYS$LOGIN (specific to the VMS port)" 12 +.IX Xref "SYS$LOGIN" +.IX Item "SYS$LOGIN (specific to the VMS port)" +Used if chdir has no argument and "HOME" and "LOGDIR" are not set. +.IP PERL_INTERNAL_RAND_SEED 12 +.IX Xref "PERL_INTERNAL_RAND_SEED" +.IX Item "PERL_INTERNAL_RAND_SEED" +Set to a non-negative integer to seed the random number generator used +internally by perl for a variety of purposes. +.Sp +Ignored if perl is run setuid or setgid. Used only for some limited +startup randomization (hash keys) if \f(CW\*(C`\-T\*(C'\fR or \f(CW\*(C`\-t\*(C'\fR perl is started +with tainting enabled. +.Sp +Perl may be built to ignore this variable. +.IP PERL_RAND_SEED 12 +.IX Xref "PERL_RAND_SEED" +.IX Item "PERL_RAND_SEED" +When set to an integer value this value will be used to seed the perl +internal random number generator used for \f(CWrand()\fR when it is used +without an explicit \f(CWsrand()\fR call or for when an explicit no-argument +\&\f(CWsrand()\fR call is made. +.Sp +Normally calling \f(CWrand()\fR prior to calling \f(CWsrand()\fR or calling +\&\f(CWsrand()\fR explicitly with no arguments should result in the random +number generator using "best efforts" to seed the generator state with a +relatively high quality random seed. When this environment variable is +set then the seeds used will be deterministically computed from the +value provided in the env var in such a way that the application process +and any forks or threads should continue to have their own unique seed but +that the program may be run twice with identical results as far as +\&\f(CWrand()\fR goes (assuming all else is equal). +.Sp +PERL_RAND_SEED is intended for performance measurements and debugging +and is explicitly NOT intended for stable testing. The only guarantee is +that a specific perl executable will produce the same results twice in a +row, there is no guarantee that the results will be the same between +perl releases or on different architectures. +.Sp +Ignored if perl is run setuid or setgid. +.PP +Perl also has environment variables that control how Perl handles data +specific to particular natural languages; see perllocale. +.PP +Perl and its various modules and components, including its test frameworks, +may sometimes make use of certain other environment variables. Some of +these are specific to a particular platform. Please consult the +appropriate module documentation and any documentation for your platform +(like perlsolaris, perllinux, perlmacosx, perlwin32, etc) for +variables peculiar to those specific situations. +.PP +Perl makes all environment variables available to the program being +executed, and passes these along to any child processes it starts. +However, programs running setuid would do well to execute the following +lines before doing anything else, just to keep people honest: +.PP +.Vb 3 +\& $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need +\& $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL}; +\& delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; +.Ve +.SH "ORDER OF APPLICATION" +.IX Header "ORDER OF APPLICATION" +Some options, in particular \f(CW\*(C`\-I\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, \f(CW\*(C`PERL5LIB\*(C'\fR and \f(CW\*(C`PERL5OPT\*(C'\fR can +interact, and the order in which they are applied is important. +.PP +Note that this section does not document what \fIactually\fR happens inside the +perl interpreter, it documents what \fIeffectively\fR happens. +.IP \-I 4 +.IX Item "-I" +The effect of multiple \f(CW\*(C`\-I\*(C'\fR options is to \f(CW\*(C`unshift\*(C'\fR them onto \f(CW@INC\fR +from right to left. So for example: +.Sp +.Vb 1 +\& perl \-I 1 \-I 2 \-I 3 +.Ve +.Sp +will first prepend \f(CW3\fR onto the front of \f(CW@INC\fR, then prepend \f(CW2\fR, and +then prepend \f(CW1\fR. The result is that \f(CW@INC\fR begins with: +.Sp +.Vb 1 +\& qw(1 2 3) +.Ve +.IP \-M 4 +.IX Item "-M" +Multiple \f(CW\*(C`\-M\*(C'\fR options are processed from left to right. So this: +.Sp +.Vb 1 +\& perl \-Mlib=1 \-Mlib=2 \-Mlib=3 +.Ve +.Sp +will first use the lib pragma to prepend \f(CW1\fR to \f(CW@INC\fR, then +it will prepend \f(CW2\fR, then it will prepend \f(CW3\fR, resulting in an \f(CW@INC\fR +that begins with: +.Sp +.Vb 1 +\& qw(3 2 1) +.Ve +.IP "the PERL5LIB environment variable" 4 +.IX Item "the PERL5LIB environment variable" +This contains a list of directories, separated by colons. The entire list +is prepended to \f(CW@INC\fR in one go. This: +.Sp +.Vb 1 +\& PERL5LIB=1:2:3 perl +.Ve +.Sp +will result in an \f(CW@INC\fR that begins with: +.Sp +.Vb 1 +\& qw(1 2 3) +.Ve +.IP "combinations of \-I, \-M and PERL5LIB" 4 +.IX Item "combinations of -I, -M and PERL5LIB" +\&\f(CW\*(C`PERL5LIB\*(C'\fR is applied first, then all the \f(CW\*(C`\-I\*(C'\fR arguments, then all the +\&\f(CW\*(C`\-M\*(C'\fR arguments. This: +.Sp +.Vb 1 +\& PERL5LIB=e1:e2 perl \-I i1 \-Mlib=m1 \-I i2 \-Mlib=m2 +.Ve +.Sp +will result in an \f(CW@INC\fR that begins with: +.Sp +.Vb 1 +\& qw(m2 m1 i1 i2 e1 e2) +.Ve +.IP "the PERL5OPT environment variable" 4 +.IX Item "the PERL5OPT environment variable" +This contains a space separated list of switches. We only consider the +effects of \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-I\*(C'\fR in this section. +.Sp +After normal processing of \f(CW\*(C`\-I\*(C'\fR switches from the command line, all +the \f(CW\*(C`\-I\*(C'\fR switches in \f(CW\*(C`PERL5OPT\*(C'\fR are extracted. They are processed from +left to right instead of from right to left. Also note that while +whitespace is allowed between a \f(CW\*(C`\-I\*(C'\fR and its directory on the command +line, it is not allowed in \f(CW\*(C`PERL5OPT\*(C'\fR. +.Sp +After normal processing of \f(CW\*(C`\-M\*(C'\fR switches from the command line, all +the \f(CW\*(C`\-M\*(C'\fR switches in \f(CW\*(C`PERL5OPT\*(C'\fR are extracted. They are processed from +left to right, \fIi.e.\fR the same as those on the command line. +.Sp +An example may make this clearer: +.Sp +.Vb 3 +\& export PERL5OPT="\-Mlib=optm1 \-Iopti1 \-Mlib=optm2 \-Iopti2" +\& export PERL5LIB=e1:e2 +\& perl \-I i1 \-Mlib=m1 \-I i2 \-Mlib=m2 +.Ve +.Sp +will result in an \f(CW@INC\fR that begins with: +.Sp +.Vb 3 +\& qw( +\& optm2 +\& optm1 +\& +\& m2 +\& m1 +\& +\& opti2 +\& opti1 +\& +\& i1 +\& i2 +\& +\& e1 +\& e2 +\& ) +.Ve +.IP "Other complications" 4 +.IX Item "Other complications" +There are some complications that are ignored in the examples above: +.RS 4 +.IP "arch and version subdirs" 4 +.IX Item "arch and version subdirs" +All of \f(CW\*(C`\-I\*(C'\fR, \f(CW\*(C`PERL5LIB\*(C'\fR and \f(CW\*(C`use lib\*(C'\fR will also prepend arch and version +subdirs if they are present +.IP sitecustomize.pl 4 +.IX Item "sitecustomize.pl" +.RE +.RS 4 +.RE |