diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlvar.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlvar.1 | 2893 |
1 files changed, 2893 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlvar.1 b/upstream/mageia-cauldron/man1/perlvar.1 new file mode 100644 index 00000000..9b06d42d --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlvar.1 @@ -0,0 +1,2893 @@ +.\" -*- 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 "PERLVAR 1" +.TH PERLVAR 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 +perlvar \- Perl predefined variables +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS "The Syntax of Variable Names" +.IX Subsection "The Syntax of Variable Names" +Variable names in Perl can have several formats. Usually, they +must begin with a letter or underscore, in which case they can be +arbitrarily long (up to an internal limit of 251 characters) and +may contain letters, digits, underscores, or the special sequence +\&\f(CW\*(C`::\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR. In this case, the part before the last \f(CW\*(C`::\*(C'\fR or +\&\f(CW\*(C`\*(Aq\*(C'\fR is taken to be a \fIpackage qualifier\fR; see perlmod. +A Unicode letter that is not ASCII is not considered to be a letter +unless \f(CW"use\ utf8"\fR is in effect, and somewhat more complicated +rules apply; see "Identifier parsing" in perldata for details. +.PP +Perl variable names may also be a sequence of digits, a single +punctuation character, or the two-character sequence: \f(CW\*(C`^\*(C'\fR (caret or +CIRCUMFLEX ACCENT) followed by any one of the characters \f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR. +These names are all reserved for +special uses by Perl; for example, the all-digits names are used +to hold data captured by backreferences after a regular expression +match. +.PP +Since Perl v5.6.0, Perl variable names may also be alphanumeric strings +preceded by a caret. These must all be written using the demarcated +variable form using curly braces such as \f(CW\*(C`${^Foo}\*(C'\fR; +the braces are \fBnot\fR optional. \f(CW\*(C`${^Foo}\*(C'\fR denotes the scalar variable +whose name is considered to be a control\-\f(CW\*(C`F\*(C'\fR followed by two \f(CW\*(C`o\*(C'\fR's. +(See "Demarcated variable names using braces" in perldata for more +information on this form of spelling a variable name or specifying +access to an element of an array or a hash). +These variables are +reserved for future special uses by Perl, except for the ones that +begin with \f(CW\*(C`^_\*(C'\fR (caret-underscore). No +name that begins with \f(CW\*(C`^_\*(C'\fR will acquire a special +meaning in any future version of Perl; such names may therefore be +used safely in programs. \f(CW$^_\fR itself, however, \fIis\fR reserved. +.PP +Note that you also \fBmust\fR use the demarcated form to access subscripts +of variables of this type when interpolating, for instance to access the +first element of the \f(CW\*(C`@{^CAPTURE}\*(C'\fR variable inside of a double quoted +string you would write \f(CW"${^CAPTURE[0]}"\fR and NOT \f(CW"${^CAPTURE}[0]"\fR +which would mean to reference a scalar variable named \f(CW\*(C`${^CAPTURE}\*(C'\fR and +not index 0 of the magic \f(CW\*(C`@{^CAPTURE}\*(C'\fR array which is populated by the +regex engine. +.PP +Perl identifiers that begin with digits or +punctuation characters are exempt from the effects of the \f(CW\*(C`package\*(C'\fR +declaration and are always forced to be in package \f(CW\*(C`main\*(C'\fR; they are +also exempt from \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR errors. A few other names are also +exempt in these ways: +.PP +.Vb 5 +\& ENV STDIN +\& INC STDOUT +\& ARGV STDERR +\& ARGVOUT +\& SIG +.Ve +.PP +In particular, the special \f(CW\*(C`${^_XYZ}\*(C'\fR variables are always taken +to be in package \f(CW\*(C`main\*(C'\fR, regardless of any \f(CW\*(C`package\*(C'\fR declarations +presently in scope. +.SH "SPECIAL VARIABLES" +.IX Header "SPECIAL VARIABLES" +The following names have special meaning to Perl. Most punctuation +names have reasonable mnemonics, or analogs in the shells. +Nevertheless, if you wish to use long variable names, you need only say: +.PP +.Vb 1 +\& use English; +.Ve +.PP +at the top of your program. This aliases all the short names to the long +names in the current package. Some even have medium names, generally +borrowed from \fBawk\fR. For more info, please see English. +.PP +Before you continue, note the sort order for variables. In general, we +first list the variables in case-insensitive, almost-lexigraphical +order (ignoring the \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`^\*(C'\fR preceding words, as in \f(CW\*(C`${^UNICODE}\*(C'\fR +or \f(CW$^T\fR), although \f(CW$_\fR and \f(CW@_\fR move up to the top of the pile. +For variables with the same identifier, we list it in order of scalar, +array, hash, and bareword. +.SS "General Variables" +.IX Subsection "General Variables" +.ie n .IP $ARG 8 +.el .IP \f(CW$ARG\fR 8 +.IX Item "$ARG" +.PD 0 +.ie n .IP $_ 8 +.el .IP \f(CW$_\fR 8 +.IX Xref "$_ $ARG" +.IX Item "$_" +.PD +The default input and pattern-searching space. The following pairs are +equivalent: +.Sp +.Vb 2 +\& while (<>) {...} # equivalent only in while! +\& while (defined($_ = <>)) {...} +\& +\& /^Subject:/ +\& $_ =~ /^Subject:/ +\& +\& tr/a\-z/A\-Z/ +\& $_ =~ tr/a\-z/A\-Z/ +\& +\& chomp +\& chomp($_) +.Ve +.Sp +Here are the places where Perl will assume \f(CW$_\fR even if you don't use it: +.RS 8 +.IP \(bu 3 +The following functions use \f(CW$_\fR as a default argument: +.Sp +abs, alarm, chomp, chop, chr, chroot, +cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc, +lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf, +quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), +rmdir, say, sin, split (for its second +argument), sqrt, stat, study, uc, ucfirst, +unlink, unpack. +.IP \(bu 3 +All file tests (\f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-d\*(C'\fR) except for \f(CW\*(C`\-t\*(C'\fR, which defaults to STDIN. +See "\-X" in perlfunc +.IP \(bu 3 +The pattern matching operations \f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`s///\*(C'\fR and \f(CW\*(C`tr///\*(C'\fR (aka \f(CW\*(C`y///\*(C'\fR) +when used without an \f(CW\*(C`=~\*(C'\fR operator. +.IP \(bu 3 +The default iterator variable in a \f(CW\*(C`foreach\*(C'\fR loop if no other +variable is supplied. +.IP \(bu 3 +The implicit iterator variable in the \f(CWgrep()\fR and \f(CWmap()\fR functions. +.IP \(bu 3 +The implicit variable of \f(CWgiven()\fR. +.IP \(bu 3 +The default place to put the next value or input record +when a \f(CW\*(C`<FH>\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`readdir\*(C'\fR or \f(CW\*(C`each\*(C'\fR +operation's result is tested by itself as the sole criterion of a \f(CW\*(C`while\*(C'\fR +test. Outside a \f(CW\*(C`while\*(C'\fR test, this will not happen. +.RE +.RS 8 +.Sp +\&\f(CW$_\fR is a global variable. +.Sp +However, between perl v5.10.0 and v5.24.0, it could be used lexically by +writing \f(CW\*(C`my $_\*(C'\fR. Making \f(CW$_\fR refer to the global \f(CW$_\fR in the same scope +was then possible with \f(CW\*(C`our $_\*(C'\fR. This experimental feature was removed and is +now a fatal error, but you may encounter it in older code. +.Sp +Mnemonic: underline is understood in certain operations. +.RE +.ie n .IP @ARG 8 +.el .IP \f(CW@ARG\fR 8 +.IX Item "@ARG" +.PD 0 +.ie n .IP @_ 8 +.el .IP \f(CW@_\fR 8 +.IX Xref "@_ @ARG" +.IX Item "@_" +.PD +Within a subroutine the array \f(CW@_\fR contains the parameters passed to +that subroutine. Inside a subroutine, \f(CW@_\fR is the default array for +the array operators \f(CW\*(C`pop\*(C'\fR and \f(CW\*(C`shift\*(C'\fR. +.Sp +See perlsub. +.ie n .IP $LIST_SEPARATOR 8 +.el .IP \f(CW$LIST_SEPARATOR\fR 8 +.IX Item "$LIST_SEPARATOR" +.PD 0 +.IP "$""" 8 +.IX Xref "$"" $LIST_SEPARATOR" +.PD +When an array or an array slice is interpolated into a double-quoted +string or a similar context such as \f(CW\*(C`/.../\*(C'\fR, its elements are +separated by this value. Default is a space. For example, this: +.Sp +.Vb 1 +\& print "The array is: @array\en"; +.Ve +.Sp +is equivalent to this: +.Sp +.Vb 1 +\& print "The array is: " . join($", @array) . "\en"; +.Ve +.Sp +Mnemonic: works in double-quoted context. +.ie n .IP $PROCESS_ID 8 +.el .IP \f(CW$PROCESS_ID\fR 8 +.IX Item "$PROCESS_ID" +.PD 0 +.ie n .IP $PID 8 +.el .IP \f(CW$PID\fR 8 +.IX Item "$PID" +.IP $$ 8 +.IX Xref "$$ $PID $PROCESS_ID" +.PD +The process number of the Perl running this script. Though you \fIcan\fR set +this variable, doing so is generally discouraged, although it can be +invaluable for some testing purposes. It will be reset automatically +across \f(CWfork()\fR calls. +.Sp +Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl +would emulate POSIX semantics on Linux systems using LinuxThreads, a +partial implementation of POSIX Threads that has since been superseded +by the Native POSIX Thread Library (NPTL). +.Sp +LinuxThreads is now obsolete on Linux, and caching \f(CWgetpid()\fR +like this made embedding perl unnecessarily complex (since you'd have +to manually update the value of $$), so now \f(CW$$\fR and \f(CWgetppid()\fR +will always return the same values as the underlying C library. +.Sp +Debian GNU/kFreeBSD systems also used LinuxThreads up until and +including the 6.0 release, but after that moved to FreeBSD thread +semantics, which are POSIX-like. +.Sp +To see if your system is affected by this discrepancy check if +\&\f(CW\*(C`getconf GNU_LIBPTHREAD_VERSION | grep \-q NPTL\*(C'\fR returns a false +value. NTPL threads preserve the POSIX semantics. +.Sp +Mnemonic: same as shells. +.ie n .IP $PROGRAM_NAME 8 +.el .IP \f(CW$PROGRAM_NAME\fR 8 +.IX Item "$PROGRAM_NAME" +.PD 0 +.ie n .IP $0 8 +.el .IP \f(CW$0\fR 8 +.IX Xref "$0 $PROGRAM_NAME" +.IX Item "$0" +.PD +Contains the name of the program being executed. +.Sp +On some (but not all) operating systems assigning to \f(CW$0\fR modifies +the argument area that the \f(CW\*(C`ps\*(C'\fR program sees. On some platforms you +may have to use special \f(CW\*(C`ps\*(C'\fR options or a different \f(CW\*(C`ps\*(C'\fR to see the +changes. Modifying the \f(CW$0\fR is more useful as a way of indicating the +current program state than it is for hiding the program you're +running. +.Sp +Note that there are platform-specific limitations on the maximum +length of \f(CW$0\fR. In the most extreme case it may be limited to the +space occupied by the original \f(CW$0\fR. +.Sp +In some platforms there may be arbitrary amount of padding, for +example space characters, after the modified name as shown by \f(CW\*(C`ps\*(C'\fR. +In some platforms this padding may extend all the way to the original +length of the argument area, no matter what you do (this is the case +for example with Linux 2.2). +.Sp +Note for BSD users: setting \f(CW$0\fR does not completely remove "perl" +from the \fBps\fR\|(1) output. For example, setting \f(CW$0\fR to \f(CW"foobar"\fR may +result in \f(CW"perl: foobar (perl)"\fR (whether both the \f(CW"perl: "\fR prefix +and the " (perl)" suffix are shown depends on your exact BSD variant +and version). This is an operating system feature, Perl cannot help it. +.Sp +In multithreaded scripts Perl coordinates the threads so that any +thread may modify its copy of the \f(CW$0\fR and the change becomes visible +to \fBps\fR\|(1) (assuming the operating system plays along). Note that +the view of \f(CW$0\fR the other threads have will not change since they +have their own copies of it. +.Sp +If the program has been given to perl via the switches \f(CW\*(C`\-e\*(C'\fR or \f(CW\*(C`\-E\*(C'\fR, +\&\f(CW$0\fR will contain the string \f(CW"\-e"\fR. +.Sp +On Linux as of perl v5.14.0 the legacy process name will be set with +\&\f(CWprctl(2)\fR, in addition to altering the POSIX name via \f(CW\*(C`argv[0]\*(C'\fR as +perl has done since version 4.000. Now system utilities that read the +legacy process name such as ps, top and killall will recognize the +name you set when assigning to \f(CW$0\fR. The string you supply will be +cut off at 16 bytes, this is a limitation imposed by Linux. +.Sp +Wide characters are invalid in \f(CW$0\fR values. For historical reasons, +though, Perl accepts them and encodes them to UTF\-8. When this +happens a wide-character warning is triggered. +.Sp +Mnemonic: same as \fBsh\fR and \fBksh\fR. +.ie n .IP $REAL_GROUP_ID 8 +.el .IP \f(CW$REAL_GROUP_ID\fR 8 +.IX Item "$REAL_GROUP_ID" +.PD 0 +.ie n .IP $GID 8 +.el .IP \f(CW$GID\fR 8 +.IX Item "$GID" +.IP $( 8 +.IX Xref "$( $GID $REAL_GROUP_ID" +.PD +The real gid of this process. If you are on a machine that supports +membership in multiple groups simultaneously, gives a space separated +list of groups you are in. The first number is the one returned by +\&\f(CWgetgid()\fR, and the subsequent ones by \f(CWgetgroups()\fR, one of which may be +the same as the first number. +.Sp +However, a value assigned to \f(CW$(\fR must be a single number used to +set the real gid. So the value given by \f(CW$(\fR should \fInot\fR be assigned +back to \f(CW$(\fR without being forced numeric, such as by adding zero. Note +that this is different to the effective gid (\f(CW$)\fR) which does take a +list. +.Sp +You can change both the real gid and the effective gid at the same +time by using \f(CWPOSIX::setgid()\fR. Changes +to \f(CW$(\fR require a check to \f(CW$!\fR +to detect any possible errors after an attempted change. +.Sp +Mnemonic: parentheses are used to \fIgroup\fR things. The real gid is the +group you \fIleft\fR, if you're running setgid. +.ie n .IP $EFFECTIVE_GROUP_ID 8 +.el .IP \f(CW$EFFECTIVE_GROUP_ID\fR 8 +.IX Item "$EFFECTIVE_GROUP_ID" +.PD 0 +.ie n .IP $EGID 8 +.el .IP \f(CW$EGID\fR 8 +.IX Item "$EGID" +.IP $) 8 +.IX Xref "$) $EGID $EFFECTIVE_GROUP_ID" +.PD +The effective gid of this process. If you are on a machine that +supports membership in multiple groups simultaneously, gives a space +separated list of groups you are in. The first number is the one +returned by \f(CWgetegid()\fR, and the subsequent ones by \f(CWgetgroups()\fR, +one of which may be the same as the first number. +.Sp +Similarly, a value assigned to \f(CW$)\fR must also be a space-separated +list of numbers. The first number sets the effective gid, and +the rest (if any) are passed to \f(CWsetgroups()\fR. To get the effect of an +empty list for \f(CWsetgroups()\fR, just repeat the new effective gid; that is, +to force an effective gid of 5 and an effectively empty \f(CWsetgroups()\fR +list, say \f(CW\*(C` $) = "5 5" \*(C'\fR. +.Sp +You can change both the effective gid and the real gid at the same +time by using \f(CWPOSIX::setgid()\fR (use only a single numeric argument). +Changes to \f(CW$)\fR require a check to \f(CW$!\fR to detect any possible errors +after an attempted change. +.Sp +\&\f(CW$<\fR, \f(CW$>\fR, \f(CW$(\fR and \f(CW$)\fR can be set only on +machines that support the corresponding \fIset[re][ug]\fR\f(BIid()\fR routine. \f(CW$(\fR +and \f(CW$)\fR can be swapped only on machines supporting \f(CWsetregid()\fR. +.Sp +Mnemonic: parentheses are used to \fIgroup\fR things. The effective gid +is the group that's \fIright\fR for you, if you're running setgid. +.ie n .IP $REAL_USER_ID 8 +.el .IP \f(CW$REAL_USER_ID\fR 8 +.IX Item "$REAL_USER_ID" +.PD 0 +.ie n .IP $UID 8 +.el .IP \f(CW$UID\fR 8 +.IX Item "$UID" +.IP $< 8 +.IX Xref "$< $UID $REAL_USER_ID" +.PD +The real uid of this process. You can change both the real uid and the +effective uid at the same time by using \f(CWPOSIX::setuid()\fR. Since +changes to \f(CW$<\fR require a system call, check \f(CW$!\fR after a change +attempt to detect any possible errors. +.Sp +Mnemonic: it's the uid you came \fIfrom\fR, if you're running setuid. +.ie n .IP $EFFECTIVE_USER_ID 8 +.el .IP \f(CW$EFFECTIVE_USER_ID\fR 8 +.IX Item "$EFFECTIVE_USER_ID" +.PD 0 +.ie n .IP $EUID 8 +.el .IP \f(CW$EUID\fR 8 +.IX Item "$EUID" +.IP $> 8 +.IX Xref "$> $EUID $EFFECTIVE_USER_ID" +.PD +The effective uid of this process. For example: +.Sp +.Vb 2 +\& $< = $>; # set real to effective uid +\& ($<,$>) = ($>,$<); # swap real and effective uids +.Ve +.Sp +You can change both the effective uid and the real uid at the same +time by using \f(CWPOSIX::setuid()\fR. Changes to \f(CW$>\fR require a check +to \f(CW$!\fR to detect any possible errors after an attempted change. +.Sp +\&\f(CW$<\fR and \f(CW$>\fR can be swapped only on machines +supporting \f(CWsetreuid()\fR. +.Sp +Mnemonic: it's the uid you went \fIto\fR, if you're running setuid. +.ie n .IP $SUBSCRIPT_SEPARATOR 8 +.el .IP \f(CW$SUBSCRIPT_SEPARATOR\fR 8 +.IX Item "$SUBSCRIPT_SEPARATOR" +.PD 0 +.ie n .IP $SUBSEP 8 +.el .IP \f(CW$SUBSEP\fR 8 +.IX Item "$SUBSEP" +.IP $; 8 +.IX Xref "$; $SUBSEP SUBSCRIPT_SEPARATOR" +.PD +The subscript separator for multidimensional array emulation. If you +refer to a hash element as +.Sp +.Vb 1 +\& $foo{$x,$y,$z} +.Ve +.Sp +it really means +.Sp +.Vb 1 +\& $foo{join($;, $x, $y, $z)} +.Ve +.Sp +But don't put +.Sp +.Vb 1 +\& @foo{$x,$y,$z} # a slice\-\-note the @ +.Ve +.Sp +which means +.Sp +.Vb 1 +\& ($foo{$x},$foo{$y},$foo{$z}) +.Ve +.Sp +Default is "\e034", the same as SUBSEP in \fBawk\fR. If your keys contain +binary data there might not be any safe value for \f(CW$;\fR. +.Sp +Consider using "real" multidimensional arrays as described +in perllol. +.Sp +Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. +.ie n .IP $a 8 +.el .IP \f(CW$a\fR 8 +.IX Item "$a" +.PD 0 +.ie n .IP $b 8 +.el .IP \f(CW$b\fR 8 +.IX Xref "$a $b" +.IX Item "$b" +.PD +Special package variables when using \f(CWsort()\fR, see "sort" in perlfunc. +Because of this specialness \f(CW$a\fR and \f(CW$b\fR don't need to be declared +(using \f(CW\*(C`use vars\*(C'\fR, or \f(CWour()\fR) even when using the \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR +pragma. Don't lexicalize them with \f(CW\*(C`my $a\*(C'\fR or \f(CW\*(C`my $b\*(C'\fR if you want to +be able to use them in the \f(CWsort()\fR comparison block or function. +.ie n .IP %ENV 8 +.el .IP \f(CW%ENV\fR 8 +.IX Xref "%ENV" +.IX Item "%ENV" +The hash \f(CW%ENV\fR contains your current environment. Setting a +value in \f(CW\*(C`ENV\*(C'\fR changes the environment for any child processes +you subsequently \f(CWfork()\fR off. +.Sp +As of v5.18.0, both keys and values stored in \f(CW%ENV\fR are stringified. +.Sp +.Vb 7 +\& my $foo = 1; +\& $ENV{\*(Aqbar\*(Aq} = \e$foo; +\& if( ref $ENV{\*(Aqbar\*(Aq} ) { +\& say "Pre 5.18.0 Behaviour"; +\& } else { +\& say "Post 5.18.0 Behaviour"; +\& } +.Ve +.Sp +Previously, only child processes received stringified values: +.Sp +.Vb 2 +\& my $foo = 1; +\& $ENV{\*(Aqbar\*(Aq} = \e$foo; +\& +\& # Always printed \*(Aqnon ref\*(Aq +\& system($^X, \*(Aq\-e\*(Aq, +\& q/print ( ref $ENV{\*(Aqbar\*(Aq} ? \*(Aqref\*(Aq : \*(Aqnon ref\*(Aq ) /); +.Ve +.Sp +This happens because you can't really share arbitrary data structures with +foreign processes. +.ie n .IP $OLD_PERL_VERSION 8 +.el .IP \f(CW$OLD_PERL_VERSION\fR 8 +.IX Item "$OLD_PERL_VERSION" +.PD 0 +.IP $] 8 +.IX Xref "$] $OLD_PERL_VERSION" +.PD +The revision, version, and subversion of the Perl interpreter, represented +as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY +is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001". +.Sp +This variable can be used to determine whether the Perl interpreter +executing a script is in the right range of versions: +.Sp +.Vb 1 +\& warn "No PerlIO!\en" if "$]" < 5.008; +.Ve +.Sp +When comparing \f(CW$]\fR, numeric comparison operators should be used, but the +variable should be stringified first to avoid issues where its original +numeric value is inaccurate. +.Sp +See also the documentation of \f(CW\*(C`use VERSION\*(C'\fR and +\&\f(CW\*(C`require VERSION\*(C'\fR for a convenient way to fail if the running Perl +interpreter is too old. +.Sp +See "$^V" for a representation of the Perl version as a version +object, which allows more flexible string comparisons. +.Sp +The main advantage of \f(CW$]\fR over \f(CW$^V\fR is that it works the same on any +version of Perl. The disadvantages are that it can't easily be compared +to versions in other formats (e.g. literal v\-strings, "v1.2.3" or +version objects) and numeric comparisons are subject to the binary +floating point representation; it's good for numeric literal version +checks and bad for comparing to a variable that hasn't been +sanity-checked. +.Sp +The \f(CW$OLD_PERL_VERSION\fR form was added in Perl v5.20.0 for historical +reasons but its use is discouraged. (If your reason to use \f(CW$]\fR is to +run code on old perls then referring to it as \f(CW$OLD_PERL_VERSION\fR would +be self-defeating.) +.Sp +Mnemonic: Is this version of perl in the right bracket? +.ie n .IP $SYSTEM_FD_MAX 8 +.el .IP \f(CW$SYSTEM_FD_MAX\fR 8 +.IX Item "$SYSTEM_FD_MAX" +.PD 0 +.IP $^F 8 +.IX Xref "$^F $SYSTEM_FD_MAX" +.IX Item "$^F" +.PD +The maximum system file descriptor, ordinarily 2. System file +descriptors are passed to \f(CWexec()\fRed processes, while higher file +descriptors are not. Also, during an +\&\f(CWopen()\fR, system file descriptors are +preserved even if the \f(CWopen()\fR fails (ordinary file descriptors are +closed before the \f(CWopen()\fR is attempted). The close-on-exec +status of a file descriptor will be decided according to the value of +\&\f(CW$^F\fR when the corresponding file, pipe, or socket was opened, not the +time of the \f(CWexec()\fR. +.ie n .IP @F 8 +.el .IP \f(CW@F\fR 8 +.IX Xref "@F" +.IX Item "@F" +The array \f(CW@F\fR contains the fields of each line read in when autosplit +mode is turned on. See perlrun for the \fB\-a\fR switch. This +array is package-specific, and must be declared or given a full package +name if not in package main when running under \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR. +.ie n .IP @INC 8 +.el .IP \f(CW@INC\fR 8 +.IX Xref "@INC" +.IX Item "@INC" +The array \f(CW@INC\fR contains the list of places that the \f(CW\*(C`do EXPR\*(C'\fR, +\&\f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR constructs look for their library files. It +initially consists of the arguments to any \fB\-I\fR command-line +switches, followed by the default Perl library, probably +\&\fI/usr/local/lib/perl\fR. +Prior to Perl 5.26, \f(CW\*(C`.\*(C'\fR \-which represents the current directory, was included +in \f(CW@INC\fR; it has been removed. This change in behavior is documented +in \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR and it is +not recommended that \f(CW\*(C`.\*(C'\fR be re-added to \f(CW@INC\fR. +If you need to modify \f(CW@INC\fR at runtime, you should use the \f(CW\*(C`use lib\*(C'\fR pragma +to get the machine-dependent library properly loaded as well: +.Sp +.Vb 2 +\& use lib \*(Aq/mypath/libdir/\*(Aq; +\& use SomeMod; +.Ve +.Sp +You can also insert hooks into the file inclusion system by putting Perl +code directly into \f(CW@INC\fR. Those hooks may be subroutine references, +array references or blessed objects. See "require" in perlfunc for details. +.ie n .IP %INC 8 +.el .IP \f(CW%INC\fR 8 +.IX Xref "%INC" +.IX Item "%INC" +The hash \f(CW%INC\fR contains entries for each filename included via the +\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR operators. The key is the filename +you specified (with module names converted to pathnames), and the +value is the location of the file found. The \f(CW\*(C`require\*(C'\fR +operator uses this hash to determine whether a particular file has +already been included. +.Sp +If the file was loaded via a hook (e.g. a subroutine reference, see +"require" in perlfunc for a description of these hooks), this hook is +by default inserted into \f(CW%INC\fR in place of a filename. Note, however, +that the hook may have set the \f(CW%INC\fR entry by itself to provide some more +specific info. +.ie n .IP $INC 8 +.el .IP \f(CW$INC\fR 8 +.IX Xref "$INC" +.IX Item "$INC" +As of 5.37.7 when an \f(CW@INC\fR hook is executed the index of the \f(CW@INC\fR +array that holds the hook will be localized into the \f(CW$INC\fR variable. +When the hook returns the integer successor of its value will be used to +determine the next index in \f(CW@INC\fR that will be checked, thus if it is +set to \-1 (or \f(CW\*(C`undef\*(C'\fR) the traversal over the \f(CW@INC\fR array will be +restarted from its beginning. +.Sp +Normally traversal through the \f(CW@INC\fR array is from beginning to end +(\f(CW\*(C`0 .. $#INC\*(C'\fR), and if the \f(CW@INC\fR array is modified by the hook the +iterator may be left in a state where newly added entries are skipped. +Changing this value allows an \f(CW@INC\fR hook to rewrite the \f(CW@INC\fR array +and tell Perl where to continue afterwards. See "require" in perlfunc for +details on \f(CW@INC\fR hooks. +.ie n .IP $INPLACE_EDIT 8 +.el .IP \f(CW$INPLACE_EDIT\fR 8 +.IX Item "$INPLACE_EDIT" +.PD 0 +.IP $^I 8 +.IX Xref "$^I $INPLACE_EDIT" +.IX Item "$^I" +.PD +The current value of the inplace-edit extension. Use \f(CW\*(C`undef\*(C'\fR to disable +inplace editing. +.Sp +Mnemonic: value of \fB\-i\fR switch. +.ie n .IP @ISA 8 +.el .IP \f(CW@ISA\fR 8 +.IX Xref "@ISA" +.IX Item "@ISA" +Each package contains a special array called \f(CW@ISA\fR which contains a list +of that class's parent classes, if any. This array is simply a list of +scalars, each of which is a string that corresponds to a package name. The +array is examined when Perl does method resolution, which is covered in +perlobj. +.Sp +To load packages while adding them to \f(CW@ISA\fR, see the parent pragma. The +discouraged base pragma does this as well, but should not be used except +when compatibility with the discouraged fields pragma is required. +.IP $^M 8 +.IX Xref "$^M" +.IX Item "$^M" +By default, running out of memory is an untrappable, fatal error. +However, if suitably built, Perl can use the contents of \f(CW$^M\fR +as an emergency memory pool after \f(CWdie()\fRing. Suppose that your Perl +were compiled with \f(CW\*(C`\-DPERL_EMERGENCY_SBRK\*(C'\fR and used Perl's malloc. +Then +.Sp +.Vb 1 +\& $^M = \*(Aqa\*(Aq x (1 << 16); +.Ve +.Sp +would allocate a 64K buffer for use in an emergency. See the +INSTALL file in the Perl distribution for information on how to +add custom C compilation flags when compiling perl. To discourage casual +use of this advanced feature, there is no English long name for +this variable. +.Sp +This variable was added in Perl 5.004. +.IP ${^MAX_NESTED_EVAL_BEGIN_BLOCKS} 8 +.IX Item "${^MAX_NESTED_EVAL_BEGIN_BLOCKS}" +This variable determines the maximum number \f(CW\*(C`eval EXPR\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR or +\&\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR block nesting that is allowed. This means it also +controls the maximum nesting of \f(CW\*(C`use\*(C'\fR statements as well. +.Sp +The default of 1000 should be sufficiently large for normal working +purposes, and if you must raise it then you should be conservative +with your choice or you may encounter segfaults from exhaustion of +the C stack. It seems unlikely that real code has a use depth above +1000, but we have left this configurable just in case. +.Sp +When set to \f(CW0\fR then \f(CW\*(C`BEGIN\*(C'\fR blocks inside of \f(CW\*(C`eval EXPR\*(C'\fR or +\&\f(CW\*(C`require EXPR\*(C'\fR are forbidden entirely and will trigger an exception +which will terminate the compilation and in the case of \f(CW\*(C`require\*(C'\fR +will throw an exception, or in the case of \f(CW\*(C`eval\*(C'\fR return the error in +\&\f(CW$@\fR as usual. +.Sp +Consider the code +.Sp +.Vb 1 +\& perl \-le\*(Aqsub f { eval "BEGIN { f() }"; } f()\*(Aq +.Ve +.Sp +each invocation of \f(CWf()\fR will consume considerable C stack, and this +variable is used to cause code like this to die instead of exhausting +the C stack and triggering a segfault. Needless to say code like this is +unusual, it is unlikely you will actually need to raise the setting. +However it may be useful to set it to 0 for a limited time period to +prevent BEGIN{} blocks from being executed during an \f(CW\*(C`eval EXPR\*(C'\fR. +.Sp +Note that setting this to 1 would NOT affect code like this: +.Sp +.Vb 1 +\& BEGIN { $n += 1; BEGIN { $n += 2; BEGIN { $n += 4 } } } +.Ve +.Sp +The reason is that BEGIN blocks are executed immediately after they are +completed, thus the innermost will execute before the ones which contain +it have even finished compiling, and the depth will not go above 1. In +fact the above code is equivalent to +.Sp +.Vb 3 +\& BEGIN { $n+=4 } +\& BEGIN { $n+=2 } +\& BEGIN { $n+=1 } +.Ve +.Sp +which makes it obvious why a ${^MAX_EVAL_BEGIN_DEPTH} of 1 would not +block this code. +.Sp +Only \f(CW\*(C`BEGIN\*(C'\fR's executed inside of an \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR (possibly via +\&\f(CW\*(C`use\*(C'\fR) are affected. +.ie n .IP $OSNAME 8 +.el .IP \f(CW$OSNAME\fR 8 +.IX Item "$OSNAME" +.PD 0 +.IP $^O 8 +.IX Xref "$^O $OSNAME" +.IX Item "$^O" +.PD +The name of the operating system under which this copy of Perl was +built, as determined during the configuration process. For examples +see "PLATFORMS" in perlport. +.Sp +The value is identical to \f(CW$Config{\*(Aqosname\*(Aq}\fR. See also Config +and the \fB\-V\fR command-line switch documented in perlrun. +.Sp +In Windows platforms, \f(CW$^O\fR is not very helpful: since it is always +\&\f(CW\*(C`MSWin32\*(C'\fR, it doesn't tell the difference between +95/98/ME/NT/2000/XP/CE/.NET. Use \f(CWWin32::GetOSName()\fR or +\&\fBWin32::GetOSVersion()\fR (see Win32 and perlport) to distinguish +between the variants. +.Sp +This variable was added in Perl 5.003. +.ie n .IP %SIG 8 +.el .IP \f(CW%SIG\fR 8 +.IX Xref "%SIG" +.IX Item "%SIG" +The hash \f(CW%SIG\fR contains signal handlers for signals. For example: +.Sp +.Vb 6 +\& sub handler { # 1st argument is signal name +\& my($sig) = @_; +\& print "Caught a SIG$sig\-\-shutting down\en"; +\& close(LOG); +\& exit(0); +\& } +\& +\& $SIG{\*(AqINT\*(Aq} = \e&handler; +\& $SIG{\*(AqQUIT\*(Aq} = \e&handler; +\& ... +\& $SIG{\*(AqINT\*(Aq} = \*(AqDEFAULT\*(Aq; # restore default action +\& $SIG{\*(AqQUIT\*(Aq} = \*(AqIGNORE\*(Aq; # ignore SIGQUIT +.Ve +.Sp +Using a value of \f(CW\*(AqIGNORE\*(Aq\fR usually has the effect of ignoring the +signal, except for the \f(CW\*(C`CHLD\*(C'\fR signal. See perlipc for more about +this special case. Using an empty string or \f(CW\*(C`undef\*(C'\fR as the value has +the same effect as \f(CW\*(AqDEFAULT\*(Aq\fR. +.Sp +Here are some other examples: +.Sp +.Vb 7 +\& $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not +\& # recommended) +\& $SIG{"PIPE"} = \e&Plumber; # just fine; assume current +\& # Plumber +\& $SIG{"PIPE"} = *Plumber; # somewhat esoteric +\& $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() +\& # return?? +.Ve +.Sp +Be sure not to use a bareword as the name of a signal handler, +lest you inadvertently call it. +.Sp +Using a string that doesn't correspond to any existing function or a +glob that doesn't contain a code slot is equivalent to \f(CW\*(AqIGNORE\*(Aq\fR, +but a warning is emitted when the handler is being called (the warning +is not emitted for the internal hooks described below). +.Sp +If your system has the \f(CWsigaction()\fR function then signal handlers +are installed using it. This means you get reliable signal handling. +.Sp +The default delivery policy of signals changed in Perl v5.8.0 from +immediate (also known as "unsafe") to deferred, also known as "safe +signals". See perlipc for more information. +.Sp +Certain internal hooks can be also set using the \f(CW%SIG\fR hash. The +routine indicated by \f(CW$SIG{_\|_WARN_\|_}\fR is called when a warning +message is about to be printed. The warning message is passed as the +first argument. The presence of a \f(CW\*(C`_\|_WARN_\|_\*(C'\fR hook causes the +ordinary printing of warnings to \f(CW\*(C`STDERR\*(C'\fR to be suppressed. You can +use this to save warnings in a variable, or turn warnings into fatal +errors, like this: +.Sp +.Vb 2 +\& local $SIG{_\|_WARN_\|_} = sub { die $_[0] }; +\& eval $proggie; +.Ve +.Sp +As the \f(CW\*(AqIGNORE\*(Aq\fR hook is not supported by \f(CW\*(C`_\|_WARN_\|_\*(C'\fR, its effect is +the same as using \f(CW\*(AqDEFAULT\*(Aq\fR. You can disable warnings using the +empty subroutine: +.Sp +.Vb 1 +\& local $SIG{_\|_WARN_\|_} = sub {}; +.Ve +.Sp +The routine indicated by \f(CW$SIG{_\|_DIE_\|_}\fR is called when a fatal +exception is about to be thrown. The error message is passed as the +first argument. When a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR hook routine returns, the exception +processing continues as it would have in the absence of the hook, +unless the hook routine itself exits via a \f(CW\*(C`goto &sub\*(C'\fR, a loop exit, +or a \f(CWdie()\fR. The \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler is explicitly disabled during +the call, so that you can die from a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler. Similarly +for \f(CW\*(C`_\|_WARN_\|_\*(C'\fR. +.Sp +The \f(CW$SIG{_\|_DIE_\|_}\fR hook is called even inside an \f(CWeval()\fR. It was +never intended to happen this way, but an implementation glitch made +this possible. This used to be deprecated, as it allowed strange action +at a distance like rewriting a pending exception in \f(CW$@\fR. Plans to +rectify this have been scrapped, as users found that rewriting a +pending exception is actually a useful feature, and not a bug. +.Sp +The \f(CW$SIG{_\|_DIE_\|_}\fR doesn't support \f(CW\*(AqIGNORE\*(Aq\fR; it has the same +effect as \f(CW\*(AqDEFAULT\*(Aq\fR. +.Sp +\&\f(CW\*(C`_\|_DIE_\|_\*(C'\fR/\f(CW\*(C`_\|_WARN_\|_\*(C'\fR handlers are very special in one respect: they +may be called to report (probable) errors found by the parser. In such +a case the parser may be in inconsistent state, so any attempt to +evaluate Perl code from such a handler will probably result in a +segfault. This means that warnings or errors that result from parsing +Perl should be used with extreme caution, like this: +.Sp +.Vb 5 +\& require Carp if defined $^S; +\& Carp::confess("Something wrong") if defined &Carp::confess; +\& die "Something wrong, but could not load Carp to give " +\& . "backtrace...\en\et" +\& . "To see backtrace try starting Perl with \-MCarp switch"; +.Ve +.Sp +Here the first line will load \f(CW\*(C`Carp\*(C'\fR \fIunless\fR it is the parser who +called the handler. The second line will print backtrace and die if +\&\f(CW\*(C`Carp\*(C'\fR was available. The third line will be executed only if \f(CW\*(C`Carp\*(C'\fR was +not available. +.Sp +Having to even think about the \f(CW$^S\fR variable in your exception +handlers is simply wrong. \f(CW$SIG{_\|_DIE_\|_}\fR as currently implemented +invites grievous and difficult to track down errors. Avoid it +and use an \f(CW\*(C`END{}\*(C'\fR or CORE::GLOBAL::die override instead. +.Sp +See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and +warnings for additional information. +.IP %{^HOOK} 8 +.IX Xref "%{^HOOK}" +.IX Item "%{^HOOK}" +This hash contains coderefs which are called when various perl keywords +which are hard or impossible to wrap are called. The keys of this hash +are named after the keyword that is being hooked, followed by two +underbars and then a phase term; either "before" or "after". +.Sp +Perl will throw an error if you attempt modify a key which is not +documented to exist, or if you attempt to store anything other than a +code reference or undef in the hash. If you wish to use an object to +implement a hook you can use currying to embed the object into an +anonymous code reference. +.Sp +Currently there is only one keyword which can be hooked, \f(CW\*(C`require\*(C'\fR, but +it is expected that in future releases there will be additional keywords +with hook support. +.RS 8 +.IP require_\|_before 4 +.IX Item "require__before" +The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR is called by +\&\f(CW\*(C`require\*(C'\fR \fBbefore\fR it checks \f(CW%INC\fR, looks up \f(CW@INC\fR, calls INC +hooks, or compiles any code. It is called with a single argument, the +filename for the item being required (package names are converted to +paths). It may alter this filename to change what file is loaded. If +the hook dies during execution then it will block the require from executing. +.Sp +In order to make it easy to perform an action with shared state both +before and after the require keyword was executed the \f(CW\*(C`require_\|_before\*(C'\fR +hook may return a "post-action" coderef which will in turn be executed when +the \f(CW\*(C`require\*(C'\fR completes. This coderef will be executed regardless as to +whether the require completed succesfully or threw an exception. It will +be called with the filename that was required. You can check \f(CW%INC\fR to +determine if the require was successful. Any other return from the +\&\f(CW\*(C`require_\|_before\*(C'\fR hook will be silently ignored. +.Sp +\&\f(CW\*(C`require_\|_before\*(C'\fR hooks are called in FIFO order, and if the hook +returns a code reference those code references will be called in FILO +order. In other words if A requires B requires C, then +\&\f(CW\*(C`require_\|_before\*(C'\fR will be called first for A, then B and then C, and +the post-action code reference will executed first for C, then B and +then finally A. +.Sp +Well behaved code should ensure that when setting up a +\&\f(CW\*(C`require_\|_before\*(C'\fR hook that any prior installed hook will be called, +and that their return value, if a code reference, will be called as +well. See "require" in perlfunc for an example implementation. +.IP require_\|_after 4 +.IX Item "require__after" +The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_after}\*(C'\fR is called by +\&\f(CW\*(C`require\*(C'\fR \fBafter\fR the require completes. It is called with a single +argument, the filename for the item being required (package names are +converted to paths). It is executed when the \f(CW\*(C`require\*(C'\fR completes, +either via exception or via completion of the require statement, and you +can check \f(CW%INC\fR to determine if the require was successful. +.Sp +The \f(CW\*(C`require_\|_after\*(C'\fR hook is called for each required file in FILO +order. In other words if A requires B requires C, then \f(CW\*(C`require_\|_after\*(C'\fR +will be called first for C, then B and then A. +.RE +.RS 8 +.RE +.ie n .IP $BASETIME 8 +.el .IP \f(CW$BASETIME\fR 8 +.IX Item "$BASETIME" +.PD 0 +.IP $^T 8 +.IX Xref "$^T $BASETIME" +.IX Item "$^T" +.PD +The time at which the program began running, in seconds since the +epoch (beginning of 1970). The values returned by the \fB\-M\fR, \fB\-A\fR, +and \fB\-C\fR filetests are based on this value. +.ie n .IP $PERL_VERSION 8 +.el .IP \f(CW$PERL_VERSION\fR 8 +.IX Item "$PERL_VERSION" +.PD 0 +.IP $^V 8 +.IX Xref "$^V $PERL_VERSION" +.IX Item "$^V" +.PD +The revision, version, and subversion of the Perl interpreter, +represented as a version object. +.Sp +This variable first appeared in perl v5.6.0; earlier versions of perl +will see an undefined value. Before perl v5.10.0 \f(CW$^V\fR was represented +as a v\-string rather than a version object. +.Sp +\&\f(CW$^V\fR can be used to determine whether the Perl interpreter executing +a script is in the right range of versions. For example: +.Sp +.Vb 1 +\& warn "Hashes not randomized!\en" if !$^V or $^V lt v5.8.1 +.Ve +.Sp +While version objects overload stringification, to portably convert +\&\f(CW$^V\fR into its string representation, use \f(CWsprintf()\fR's \f(CW"%vd"\fR +conversion, which works for both v\-strings or version objects: +.Sp +.Vb 1 +\& printf "version is v%vd\en", $^V; # Perl\*(Aqs version +.Ve +.Sp +See the documentation of \f(CW\*(C`use VERSION\*(C'\fR and \f(CW\*(C`require VERSION\*(C'\fR +for a convenient way to fail if the running Perl interpreter is too old. +.Sp +See also \f(CW"$]"\fR for a decimal representation of the Perl version. +.Sp +The main advantage of \f(CW$^V\fR over \f(CW$]\fR is that, for Perl v5.10.0 or +later, it overloads operators, allowing easy comparison against other +version representations (e.g. decimal, literal v\-string, "v1.2.3", or +objects). The disadvantage is that prior to v5.10.0, it was only a +literal v\-string, which can't be easily printed or compared, whereas +the behavior of \f(CW$]\fR is unchanged on all versions of Perl. +.Sp +Mnemonic: use ^V for a version object. +.ie n .IP $EXECUTABLE_NAME 8 +.el .IP \f(CW$EXECUTABLE_NAME\fR 8 +.IX Item "$EXECUTABLE_NAME" +.PD 0 +.IP $^X 8 +.IX Xref "$^X $EXECUTABLE_NAME" +.IX Item "$^X" +.PD +The name used to execute the current copy of Perl, from C's +\&\f(CW\*(C`argv[0]\*(C'\fR or (where supported) \fI/proc/self/exe\fR. +.Sp +Depending on the host operating system, the value of \f(CW$^X\fR may be +a relative or absolute pathname of the perl program file, or may +be the string used to invoke perl but not the pathname of the +perl program file. Also, most operating systems permit invoking +programs that are not in the PATH environment variable, so there +is no guarantee that the value of \f(CW$^X\fR is in PATH. For VMS, the +value may or may not include a version number. +.Sp +You usually can use the value of \f(CW$^X\fR to re-invoke an independent +copy of the same perl that is currently running, e.g., +.Sp +.Vb 1 +\& @first_run = \`$^X \-le "print int rand 100 for 1..100"\`; +.Ve +.Sp +But recall that not all operating systems support forking or +capturing of the output of commands, so this complex statement +may not be portable. +.Sp +It is not safe to use the value of \f(CW$^X\fR as a path name of a file, +as some operating systems that have a mandatory suffix on +executable files do not require use of the suffix when invoking +a command. To convert the value of \f(CW$^X\fR to a path name, use the +following statements: +.Sp +.Vb 7 +\& # Build up a set of file names (not command names). +\& use Config; +\& my $this_perl = $^X; +\& if ($^O ne \*(AqVMS\*(Aq) { +\& $this_perl .= $Config{_exe} +\& unless $this_perl =~ m/$Config{_exe}$/i; +\& } +.Ve +.Sp +Because many operating systems permit anyone with read access to +the Perl program file to make a copy of it, patch the copy, and +then execute the copy, the security-conscious Perl programmer +should take care to invoke the installed copy of perl, not the +copy referenced by \f(CW$^X\fR. The following statements accomplish +this goal, and produce a pathname that can be invoked as a +command or referenced as a file. +.Sp +.Vb 6 +\& use Config; +\& my $secure_perl_path = $Config{perlpath}; +\& if ($^O ne \*(AqVMS\*(Aq) { +\& $secure_perl_path .= $Config{_exe} +\& unless $secure_perl_path =~ m/$Config{_exe}$/i; +\& } +.Ve +.SS "Variables related to regular expressions" +.IX Subsection "Variables related to regular expressions" +Most of the special variables related to regular expressions are side +effects. Perl sets these variables when it has completed a match +successfully, so you should check the match result before using them. +For instance: +.PP +.Vb 3 +\& if( /P(A)TT(ER)N/ ) { +\& print "I found $1 and $2\en"; +\& } +.Ve +.PP +These variables are read-only and behave similarly to a dynamically +scoped variable, with only a few exceptions which are explicitly +documented as behaving otherwise. See the following section for more +details. +.PP +\fIScoping Rules of Regex Variables\fR +.IX Subsection "Scoping Rules of Regex Variables" +.PP +Regular expression variables allow the programmer to access the state of +the most recent \fIsuccessful\fR regex match in the current dynamic scope. +.PP +The variables themselves are global and unscoped, but the data they +access is scoped similarly to dynamically scoped variables, in that +every successful match behaves as though it localizes a global state +object to the current block or file scope. +(See "Compound Statements" in perlsyn for more details on dynamic +scoping and the \f(CW\*(C`local\*(C'\fR keyword.) +.PP +A \fIsuccessful match\fR includes any successful match performed by the +search and replace operator \f(CW\*(C`s///\*(C'\fR as well as those performed by the +\&\f(CW\*(C`m//\*(C'\fR operator. +.PP +Consider the following code: +.PP +.Vb 7 +\& my @state; +\& sub matchit { +\& push @state, $1; # pushes "baz" +\& my $str = shift; +\& $str =~ /(zat)/; # matches "zat" +\& push @state, $1; # pushes "zat" +\& } +\& +\& { +\& $str = "foo bar baz blorp zat"; +\& $str =~ /(foo)/; # matches "foo" +\& push @state, $1; # pushes "foo" +\& { +\& $str =~ /(pizza)/; # does NOT match +\& push @state, $1; # pushes "foo" +\& $str =~ /(bar)/; # matches "bar" +\& push @state, $1; # pushes "bar" +\& $str =~ /(baz)/; # matches "baz" +\& matchit($str); # see above +\& push @state, $1; # pushes "baz" +\& } +\& $str =~ s/noodles/rice/; # does NOT match +\& push @state, $1; # pushes "foo" +\& $str =~ s/(blorp)/zwoop/; # matches "blorp" +\& push @state, $1; # pushes "blorp" +\& } +\& # the following prints "foo, foo, bar, baz, zat, baz, foo, blorp" +\& print join ",", @state; +.Ve +.PP +Notice that each successful match in the exact same scope overrides the +match context of the previous successful match, but that unsuccessful +matches do not. Also note that in an inner nested scope the previous +state from an outer dynamic scope persists until it has been overriden +by another successful match, but that when the inner nested scope exits +whatever match context was in effect before the inner successful match +is restored when the scope concludes. +.PP +It is a known issue that \f(CW\*(C`goto LABEL\*(C'\fR may interact poorly with the +dynamically scoped match context. This may not be fixable, and is +considered to be one of many good reasons to avoid \f(CW\*(C`goto LABEL\*(C'\fR. +.PP +\fIPerformance issues\fR +.IX Subsection "Performance issues" +.PP +Traditionally in Perl, any use of any of the three variables \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR +or \f(CW\*(C`$\*(Aq\*(C'\fR (or their \f(CW\*(C`use English\*(C'\fR equivalents) anywhere in the code, caused +all subsequent successful pattern matches to make a copy of the matched +string, in case the code might subsequently access one of those variables. +This imposed a considerable performance penalty across the whole program, +so generally the use of these variables has been discouraged. +.PP +In Perl 5.6.0 the \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR dynamic arrays were introduced that +supply the indices of successful matches. So you could for example do +this: +.PP +.Vb 1 +\& $str =~ /pattern/; +\& +\& print $\`, $&, $\*(Aq; # bad: performance hit +\& +\& print # good: no performance hit +\& substr($str, 0, $\-[0]), +\& substr($str, $\-[0], $+[0]\-$\-[0]), +\& substr($str, $+[0]); +.Ve +.PP +In Perl 5.10.0 the \f(CW\*(C`/p\*(C'\fR match operator flag and the \f(CW\*(C`${^PREMATCH}\*(C'\fR, +\&\f(CW\*(C`${^MATCH}\*(C'\fR, and \f(CW\*(C`${^POSTMATCH}\*(C'\fR variables were introduced, that allowed +you to suffer the penalties only on patterns marked with \f(CW\*(C`/p\*(C'\fR. +.PP +In Perl 5.18.0 onwards, perl started noting the presence of each of the +three variables separately, and only copied that part of the string +required; so in +.PP +.Vb 1 +\& $\`; $&; "abcdefgh" =~ /d/ +.Ve +.PP +perl would only copy the "abcd" part of the string. That could make a big +difference in something like +.PP +.Vb 3 +\& $str = \*(Aqx\*(Aq x 1_000_000; +\& $&; # whoops +\& $str =~ /x/g # one char copied a million times, not a million chars +.Ve +.PP +In Perl 5.20.0 a new copy-on-write system was enabled by default, which +finally fixes most of the performance issues with these three variables, and +makes them safe to use anywhere. +.PP +The \f(CW\*(C`Devel::NYTProf\*(C'\fR and \f(CW\*(C`Devel::FindAmpersand\*(C'\fR modules can help you +find uses of these problematic match variables in your code. +.ie n .IP "$<\fIdigits\fR> ($1, $2, ...)" 8 +.el .IP "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)" 8 +.IX Xref "$1 $2 $3 $\\f(ISdigits\\f(IE" +.IX Item "$<digits> ($1, $2, ...)" +Contains the subpattern from the corresponding set of capturing +parentheses from the last successful pattern match in the current +dynamic scope. (See "Scoping Rules of Regex Variables".) +.Sp +Note there is a distinction between a capture buffer which matches +the empty string a capture buffer which is optional. Eg, \f(CW\*(C`(x?)\*(C'\fR and +\&\f(CW\*(C`(x)?\*(C'\fR The latter may be undef, the former not. +.Sp +These variables are read-only. +.Sp +Mnemonic: like \edigits. +.IP @{^CAPTURE} 8 +.IX Xref "@{^CAPTURE} @^CAPTURE" +.IX Item "@{^CAPTURE}" +An array which exposes the contents of the capture buffers, if any, of +the last successful pattern match, not counting patterns matched +in nested blocks that have been exited already. +.Sp +Note that the 0 index of @{^CAPTURE} is equivalent to \f(CW$1\fR, the 1 index +is equivalent to \f(CW$2\fR, etc. +.Sp +.Vb 3 +\& if ("foal"=~/(.)(.)(.)(.)/) { +\& print join "\-", @{^CAPTURE}; +\& } +.Ve +.Sp +should output "f\-o-a-l". +.Sp +See also "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)", "%{^CAPTURE}" and +"%{^CAPTURE_ALL}". +.Sp +Note that unlike most other regex magic variables there is no single +letter equivalent to \f(CW\*(C`@{^CAPTURE}\*(C'\fR. Also be aware that when +interpolating subscripts of this array you \fBmust\fR use the demarcated +variable form, for instance +.Sp +.Vb 1 +\& print "${^CAPTURE[0]}" +.Ve +.Sp +see "Demarcated variable names using braces" in perldata for more +information on this form and its uses. +.Sp +This variable was added in 5.25.7 +.ie n .IP $MATCH 8 +.el .IP \f(CW$MATCH\fR 8 +.IX Item "$MATCH" +.PD 0 +.IP $& 8 +.IX Xref "$& $MATCH" +.PD +The string matched by the last successful pattern match. +(See "Scoping Rules of Regex Variables".) +.Sp +See "Performance issues" above for the serious performance implications +of using this variable (even once) in your code. +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +Mnemonic: like \f(CW\*(C`&\*(C'\fR in some editors. +.IP ${^MATCH} 8 +.IX Xref "${^MATCH}" +.IX Item "${^MATCH}" +It is only guaranteed to return a defined value when the pattern was +compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier. +.Sp +This is similar to \f(CW$&\fR (\f(CW$MATCH\fR) except that to use it you must +use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur +and performance penalty associated with that variable. +.Sp +See "Performance issues" above. +.Sp +This variable was added in Perl v5.10.0. +.Sp +This variable is read-only, and its value is dynamically scoped. +.ie n .IP $PREMATCH 8 +.el .IP \f(CW$PREMATCH\fR 8 +.IX Item "$PREMATCH" +.PD 0 +.IP $` 8 +.IX Xref "$` $PREMATCH" +.PD +The string preceding whatever was matched by the last successful +pattern match. (See "Scoping Rules of Regex Variables"). +.Sp +See "Performance issues" above for the serious performance implications +of using this variable (even once) in your code. +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +Mnemonic: \f(CW\*(C`\`\*(C'\fR often precedes a quoted string. +.IP ${^PREMATCH} 8 +.IX Xref "${^PREMATCH}" +.IX Item "${^PREMATCH}" +It is only guaranteed to return a defined value when the pattern was +executed with the \f(CW\*(C`/p\*(C'\fR modifier. +.Sp +This is similar to \f(CW\*(C`$\`\*(C'\fR ($PREMATCH) except that to use it you must +use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur +and performance penalty associated with that variable. +.Sp +See "Performance issues" above. +.Sp +This variable was added in Perl v5.10.0. +.Sp +This variable is read-only, and its value is dynamically scoped. +.ie n .IP $POSTMATCH 8 +.el .IP \f(CW$POSTMATCH\fR 8 +.IX Item "$POSTMATCH" +.PD 0 +.IP $' 8 +.IX Xref "$' $POSTMATCH @-" +.PD +The string following whatever was matched by the last successful +pattern match. (See "Scoping Rules of Regex Variables"). Example: +.Sp +.Vb 3 +\& local $_ = \*(Aqabcdefghi\*(Aq; +\& /def/; +\& print "$\`:$&:$\*(Aq\en"; # prints abc:def:ghi +.Ve +.Sp +See "Performance issues" above for the serious performance implications +of using this variable (even once) in your code. +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +Mnemonic: \f(CW\*(C`\*(Aq\*(C'\fR often follows a quoted string. +.IP ${^POSTMATCH} 8 +.IX Xref "${^POSTMATCH}" +.IX Item "${^POSTMATCH}" +It is only guaranteed to return a defined value when the pattern was +compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier. +.Sp +This is similar to \f(CW\*(C`$\*(Aq\*(C'\fR (\f(CW$POSTMATCH\fR) except that to use it you must +use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur +and performance penalty associated with that variable. +.Sp +See "Performance issues" above. +.Sp +This variable was added in Perl v5.10.0. +.Sp +This variable is read-only, and its value is dynamically scoped. +.ie n .IP $LAST_PAREN_MATCH 8 +.el .IP \f(CW$LAST_PAREN_MATCH\fR 8 +.IX Item "$LAST_PAREN_MATCH" +.PD 0 +.IP $+ 8 +.IX Xref "$+ $LAST_PAREN_MATCH" +.PD +The text matched by the highest used capture group of the last +successful search pattern. (See "Scoping Rules of Regex Variables"). +It is logically equivalent to the highest +numbered capture variable (\f(CW$1\fR, \f(CW$2\fR, ...) which has a defined value. +.Sp +This is useful if you don't know which one of a set of alternative patterns +matched. For example: +.Sp +.Vb 1 +\& /Version: (.*)|Revision: (.*)/ && ($rev = $+); +.Ve +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +Mnemonic: be positive and forward looking. +.ie n .IP $LAST_SUBMATCH_RESULT 8 +.el .IP \f(CW$LAST_SUBMATCH_RESULT\fR 8 +.IX Item "$LAST_SUBMATCH_RESULT" +.PD 0 +.IP $^N 8 +.IX Xref "$^N $LAST_SUBMATCH_RESULT" +.IX Item "$^N" +.PD +The text matched by the used group most-recently closed (i.e. the group +with the rightmost closing parenthesis) of the last successful match. +(See "Scoping Rules of Regex Variables"). +.Sp +This is subtly different from \f(CW$+\fR. For example in +.Sp +.Vb 1 +\& "ab" =~ /^((.)(.))$/ +.Ve +.Sp +we have +.Sp +.Vb 3 +\& $1,$^N have the value "ab" +\& $2 has the value "a" +\& $3,$+ have the value "b" +.Ve +.Sp +This is primarily used inside \f(CW\*(C`(?{...})\*(C'\fR blocks for examining text +recently matched. For example, to effectively capture text to a variable +(in addition to \f(CW$1\fR, \f(CW$2\fR, etc.), replace \f(CW\*(C`(...)\*(C'\fR with +.Sp +.Vb 1 +\& (?:(...)(?{ $var = $^N })) +.Ve +.Sp +By setting and then using \f(CW$var\fR in this way relieves you from having to +worry about exactly which numbered set of parentheses they are. +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +This variable was added in Perl v5.8.0. +.Sp +Mnemonic: the (possibly) Nested parenthesis that most recently closed. +.ie n .IP @LAST_MATCH_END 8 +.el .IP \f(CW@LAST_MATCH_END\fR 8 +.IX Item "@LAST_MATCH_END" +.PD 0 +.IP @+ 8 +.IX Xref "@+ @LAST_MATCH_END" +.PD +This array holds the offsets of the ends of the last successful +match and any matching capture buffers that the pattern contains. +(See "Scoping Rules of Regex Variables") +.Sp +The number of elements it contains will be one more than the number +of capture buffers in the pattern, regardless of which capture buffers +actually matched. You can use this to determine how many capture +buffers there are in the pattern. (As opposed to \f(CW\*(C`@\-\*(C'\fR which may +have fewer elements.) +.Sp +\&\f(CW$+[0]\fR is the offset into the string of the end of the entire match. +This is the same value as what the \f(CW\*(C`pos\*(C'\fR function returns when called +on the variable that was matched against. The \fIn\fRth element of this +array holds the offset of the \fIn\fRth submatch, so \f(CW$+[1]\fR is the offset +past where \f(CW$1\fR ends, \f(CW$+[2]\fR the offset past where \f(CW$2\fR ends, and so +on. You can use \f(CW$#+\fR to determine how many subgroups were in the last +successful match. See the examples given for the \f(CW\*(C`@\-\*(C'\fR variable. +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +This variable was added in Perl v5.6.0. +.IP %{^CAPTURE} 8 +.IX Item "%{^CAPTURE}" +.PD 0 +.ie n .IP %LAST_PAREN_MATCH 8 +.el .IP \f(CW%LAST_PAREN_MATCH\fR 8 +.IX Item "%LAST_PAREN_MATCH" +.IP %+ 8 +.IX Xref "%+ %LAST_PAREN_MATCH %{^CAPTURE}" +.PD +Similar to \f(CW\*(C`@+\*(C'\fR, the \f(CW\*(C`%+\*(C'\fR hash allows access to the named capture +buffers, should they exist, in the last successful match in the +currently active dynamic scope. (See "Scoping Rules of Regex Variables"). +.Sp +For example, \f(CW$+{foo}\fR is equivalent to \f(CW$1\fR after the following match: +.Sp +.Vb 1 +\& \*(Aqfoo\*(Aq =~ /(?<foo>foo)/; +.Ve +.Sp +The keys of the \f(CW\*(C`%+\*(C'\fR hash list only the names of buffers that have +captured (and that are thus associated to defined values). +.Sp +If multiple distinct capture groups have the same name, then +\&\f(CW$+{NAME}\fR will refer to the leftmost defined group in the match. +.Sp +The underlying behaviour of \f(CW\*(C`%+\*(C'\fR is provided by the +Tie::Hash::NamedCapture module. +.Sp +\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. +.Sp +This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE}\*(C'\fR alias was +added in 5.25.7. +.Sp +This variable is read-only, and its value is dynamically scoped. +.ie n .IP @LAST_MATCH_START 8 +.el .IP \f(CW@LAST_MATCH_START\fR 8 +.IX Item "@LAST_MATCH_START" +.PD 0 +.IP @\- 8 +.IX Xref "@- @LAST_MATCH_START" +.PD +This array holds the offsets of the beginnings of the last successful +match and any capture buffers it contains. +(See "Scoping Rules of Regex Variables"). +.Sp +The number of elements it contains will be one more than the number of +the highest capture buffers (also called a subgroup) that actually +matched something. (As opposed to \f(CW\*(C`@+\*(C'\fR which may have fewer elements.) +.Sp +\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset of the start of the last successful match. +\&\f(CW\*(C`$\-[\fR\f(CIn\fR\f(CW]\*(C'\fR is the offset of the start of the substring matched by +\&\fIn\fR\-th subpattern, or undef if the subpattern did not match. +.Sp +Thus, after a match against \f(CW$_\fR, \f(CW$&\fR coincides with +\&\f(CW\*(C`substr $_, $\-[0], $+[0] \- $\-[0]\*(C'\fR. Similarly, \f(CW\*(C`$\fR\f(CIn\fR\f(CW\*(C'\fR coincides +with \f(CW\*(C`substr $_, $\-[n], $+[n] \- $\-[n]\*(C'\fR if \f(CW\*(C`$\-[n]\*(C'\fR is defined, and +\&\f(CW$+\fR coincides with \f(CW\*(C`substr $_, $\-[$#\-], $+[$#\-] \- $\-[$#\-]\*(C'\fR. +One can use \f(CW\*(C`$#\-\*(C'\fR to find the last matched subgroup in the last +successful match. Contrast with \f(CW$#+\fR, the number of subgroups +in the regular expression. +.Sp +\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset into the string of the beginning of the +entire match. The \fIn\fRth element of this array holds the offset +of the \fIn\fRth submatch, so \f(CW\*(C`$\-[1]\*(C'\fR is the offset where \f(CW$1\fR +begins, \f(CW\*(C`$\-[2]\*(C'\fR the offset where \f(CW$2\fR begins, and so on. +.Sp +After a match against some variable \f(CW$var\fR: +.RS 8 +.ie n .IP """$\`"" is the same as ""substr($var, 0, $\-[0])""" 5 +.el .IP "\f(CW$\`\fR is the same as \f(CWsubstr($var, 0, $\-[0])\fR" 5 +.IX Item "$ is the same as substr($var, 0, $-[0])" +.PD 0 +.ie n .IP "$& is the same as ""substr($var, $\-[0], $+[0] \- $\-[0])""" 5 +.el .IP "\f(CW$&\fR is the same as \f(CWsubstr($var, $\-[0], $+[0] \- $\-[0])\fR" 5 +.IX Item "$& is the same as substr($var, $-[0], $+[0] - $-[0])" +.ie n .IP """$\*(Aq"" is the same as ""substr($var, $+[0])""" 5 +.el .IP "\f(CW$\*(Aq\fR is the same as \f(CWsubstr($var, $+[0])\fR" 5 +.IX Item "$ is the same as substr($var, $+[0])" +.ie n .IP "$1 is the same as ""substr($var, $\-[1], $+[1] \- $\-[1])""" 5 +.el .IP "\f(CW$1\fR is the same as \f(CWsubstr($var, $\-[1], $+[1] \- $\-[1])\fR" 5 +.IX Item "$1 is the same as substr($var, $-[1], $+[1] - $-[1])" +.ie n .IP "$2 is the same as ""substr($var, $\-[2], $+[2] \- $\-[2])""" 5 +.el .IP "\f(CW$2\fR is the same as \f(CWsubstr($var, $\-[2], $+[2] \- $\-[2])\fR" 5 +.IX Item "$2 is the same as substr($var, $-[2], $+[2] - $-[2])" +.ie n .IP "$3 is the same as ""substr($var, $\-[3], $+[3] \- $\-[3])""" 5 +.el .IP "\f(CW$3\fR is the same as \f(CWsubstr($var, $\-[3], $+[3] \- $\-[3])\fR" 5 +.IX Item "$3 is the same as substr($var, $-[3], $+[3] - $-[3])" +.RE +.RS 8 +.PD +.Sp +This variable is read-only, and its value is dynamically scoped. +.Sp +This variable was added in Perl v5.6.0. +.RE +.IP %{^CAPTURE_ALL} 8 +.IX Xref "%{^CAPTURE_ALL}" +.IX Item "%{^CAPTURE_ALL}" +.PD 0 +.IP %\- 8 +.IX Xref "%-" +.PD +Similar to \f(CW\*(C`%+\*(C'\fR, this variable allows access to the named capture +groups in the last successful match in the currently active dynamic +scope. (See "Scoping Rules of Regex Variables"). To each capture group +name found in the regular expression, it associates a reference to an +array containing the list of values captured by all buffers with that +name (should there be several of them), in the order where they appear. +.Sp +Here's an example: +.Sp +.Vb 12 +\& if (\*(Aq1234\*(Aq =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { +\& foreach my $bufname (sort keys %\-) { +\& my $ary = $\-{$bufname}; +\& foreach my $idx (0..$#$ary) { +\& print "\e$\-{$bufname}[$idx] : ", +\& (defined($ary\->[$idx]) +\& ? "\*(Aq$ary\->[$idx]\*(Aq" +\& : "undef"), +\& "\en"; +\& } +\& } +\& } +.Ve +.Sp +would print out: +.Sp +.Vb 4 +\& $\-{A}[0] : \*(Aq1\*(Aq +\& $\-{A}[1] : \*(Aq3\*(Aq +\& $\-{B}[0] : \*(Aq2\*(Aq +\& $\-{B}[1] : \*(Aq4\*(Aq +.Ve +.Sp +The keys of the \f(CW\*(C`%\-\*(C'\fR hash correspond to all buffer names found in +the regular expression. +.Sp +The behaviour of \f(CW\*(C`%\-\*(C'\fR is implemented via the +Tie::Hash::NamedCapture module. +.Sp +\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. See "Scoping Rules of Regex Variables". +.Sp +This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR alias was +added in 5.25.7. +.Sp +This variable is read-only, and its value is dynamically scoped. +.IP ${^LAST_SUCCESSFUL_PATTERN} 8 +.IX Item "${^LAST_SUCCESSFUL_PATTERN}" +The last successful pattern that matched in the current scope. The empty +pattern defaults to matching to this. For instance: +.Sp +.Vb 3 +\& if (m/foo/ || m/bar/) { +\& s//BLAH/; +\& } +.Ve +.Sp +and +.Sp +.Vb 3 +\& if (m/foo/ || m/bar/) { +\& s/${^LAST_SUCCESSFUL_PATTERN}/BLAH/; +\& } +.Ve +.Sp +are equivalent. +.Sp +You can use this to debug which pattern matched last, or to match with it again. +.Sp +Added in Perl 5.37.10. +.ie n .IP $LAST_REGEXP_CODE_RESULT 8 +.el .IP \f(CW$LAST_REGEXP_CODE_RESULT\fR 8 +.IX Item "$LAST_REGEXP_CODE_RESULT" +.PD 0 +.IP $^R 8 +.IX Xref "$^R $LAST_REGEXP_CODE_RESULT" +.IX Item "$^R" +.PD +The result of evaluation of the last successful \f(CW\*(C`(?{ code })\*(C'\fR +regular expression assertion (see perlre). +.Sp +This variable may be written to, and its value is scoped normally, +unlike most other regex variables. +.Sp +This variable was added in Perl 5.005. +.IP ${^RE_COMPILE_RECURSION_LIMIT} 8 +.IX Xref "${^RE_COMPILE_RECURSION_LIMIT}" +.IX Item "${^RE_COMPILE_RECURSION_LIMIT}" +The current value giving the maximum number of open but unclosed +parenthetical groups there may be at any point during a regular +expression compilation. The default is currently 1000 nested groups. +You may adjust it depending on your needs and the amount of memory +available. +.Sp +This variable was added in Perl v5.30.0. +.IP ${^RE_DEBUG_FLAGS} 8 +.IX Xref "${^RE_DEBUG_FLAGS}" +.IX Item "${^RE_DEBUG_FLAGS}" +The current value of the regex debugging flags. Set to 0 for no debug output +even when the \f(CW\*(C`re \*(Aqdebug\*(Aq\*(C'\fR module is loaded. See re for details. +.Sp +This variable was added in Perl v5.10.0. +.IP ${^RE_TRIE_MAXBUF} 8 +.IX Xref "${^RE_TRIE_MAXBUF}" +.IX Item "${^RE_TRIE_MAXBUF}" +Controls how certain regex optimisations are applied and how much memory they +utilize. This value by default is 65536 which corresponds to a 512kB +temporary cache. Set this to a higher value to trade +memory for speed when matching large alternations. Set +it to a lower value if you want the optimisations to +be as conservative of memory as possible but still occur, and set it to a +negative value to prevent the optimisation and conserve the most memory. +Under normal situations this variable should be of no interest to you. +.Sp +This variable was added in Perl v5.10.0. +.SS "Variables related to filehandles" +.IX Subsection "Variables related to filehandles" +Variables that depend on the currently selected filehandle may be set +by calling an appropriate object method on the \f(CW\*(C`IO::Handle\*(C'\fR object, +although this is less efficient than using the regular built-in +variables. (Summary lines below for this contain the word HANDLE.) +First you must say +.PP +.Vb 1 +\& use IO::Handle; +.Ve +.PP +after which you may use either +.PP +.Vb 1 +\& method HANDLE EXPR +.Ve +.PP +or more safely, +.PP +.Vb 1 +\& HANDLE\->method(EXPR) +.Ve +.PP +Each method returns the old value of the \f(CW\*(C`IO::Handle\*(C'\fR attribute. The +methods each take an optional EXPR, which, if supplied, specifies the +new value for the \f(CW\*(C`IO::Handle\*(C'\fR attribute in question. If not +supplied, most methods do nothing to the current value\-\-except for +\&\f(CWautoflush()\fR, which will assume a 1 for you, just to be different. +.PP +Because loading in the \f(CW\*(C`IO::Handle\*(C'\fR class is an expensive operation, +you should learn how to use the regular built-in variables. +.PP +A few of these variables are considered "read-only". This means that +if you try to assign to this variable, either directly or indirectly +through a reference, you'll raise a run-time exception. +.PP +You should be very careful when modifying the default values of most +special variables described in this document. In most cases you want +to localize these variables before changing them, since if you don't, +the change may affect other modules which rely on the default values +of the special variables that you have changed. This is one of the +correct ways to read the whole file at once: +.PP +.Vb 4 +\& open my $fh, "<", "foo" or die $!; +\& local $/; # enable localized slurp mode +\& my $content = <$fh>; +\& close $fh; +.Ve +.PP +But the following code is quite bad: +.PP +.Vb 4 +\& open my $fh, "<", "foo" or die $!; +\& undef $/; # enable slurp mode +\& my $content = <$fh>; +\& close $fh; +.Ve +.PP +since some other module, may want to read data from some file in the +default "line mode", so if the code we have just presented has been +executed, the global value of \f(CW$/\fR is now changed for any other code +running inside the same Perl interpreter. +.PP +Usually when a variable is localized you want to make sure that this +change affects the shortest scope possible. So unless you are already +inside some short \f(CW\*(C`{}\*(C'\fR block, you should create one yourself. For +example: +.PP +.Vb 7 +\& my $content = \*(Aq\*(Aq; +\& open my $fh, "<", "foo" or die $!; +\& { +\& local $/; +\& $content = <$fh>; +\& } +\& close $fh; +.Ve +.PP +Here is an example of how your own code can go broken: +.PP +.Vb 5 +\& for ( 1..3 ){ +\& $\e = "\er\en"; +\& nasty_break(); +\& print "$_"; +\& } +\& +\& sub nasty_break { +\& $\e = "\ef"; +\& # do something with $_ +\& } +.Ve +.PP +You probably expect this code to print the equivalent of +.PP +.Vb 1 +\& "1\er\en2\er\en3\er\en" +.Ve +.PP +but instead you get: +.PP +.Vb 1 +\& "1\ef2\ef3\ef" +.Ve +.PP +Why? Because \f(CWnasty_break()\fR modifies \f(CW\*(C`$\e\*(C'\fR without localizing it +first. The value you set in \f(CWnasty_break()\fR is still there when you +return. The fix is to add \f(CWlocal()\fR so the value doesn't leak out of +\&\f(CWnasty_break()\fR: +.PP +.Vb 1 +\& local $\e = "\ef"; +.Ve +.PP +It's easy to notice the problem in such a short example, but in more +complicated code you are looking for trouble if you don't localize +changes to the special variables. +.ie n .IP $ARGV 8 +.el .IP \f(CW$ARGV\fR 8 +.IX Xref "$ARGV" +.IX Item "$ARGV" +Contains the name of the current file when reading from \f(CW\*(C`<>\*(C'\fR. +.ie n .IP @ARGV 8 +.el .IP \f(CW@ARGV\fR 8 +.IX Xref "@ARGV" +.IX Item "@ARGV" +The array \f(CW@ARGV\fR contains the command-line arguments intended for +the script. \f(CW$#ARGV\fR is generally the number of arguments minus +one, because \f(CW$ARGV[0]\fR is the first argument, \fInot\fR the program's +command name itself. See "$0" for the command name. +.IP ARGV 8 +.IX Xref "ARGV" +.IX Item "ARGV" +The special filehandle that iterates over command-line filenames in +\&\f(CW@ARGV\fR. Usually written as the null filehandle in the angle operator +\&\f(CW\*(C`<>\*(C'\fR. Note that currently \f(CW\*(C`ARGV\*(C'\fR only has its magical effect +within the \f(CW\*(C`<>\*(C'\fR operator; elsewhere it is just a plain filehandle +corresponding to the last file opened by \f(CW\*(C`<>\*(C'\fR. In particular, +passing \f(CW\*(C`\e*ARGV\*(C'\fR as a parameter to a function that expects a filehandle +may not cause your function to automatically read the contents of all the +files in \f(CW@ARGV\fR. +.IP ARGVOUT 8 +.IX Xref "ARGVOUT" +.IX Item "ARGVOUT" +The special filehandle that points to the currently open output file +when doing edit-in-place processing with \fB\-i\fR. Useful when you have +to do a lot of inserting and don't want to keep modifying \f(CW$_\fR. See +perlrun for the \fB\-i\fR switch. +.IP "IO::Handle\->output_field_separator( EXPR )" 8 +.IX Item "IO::Handle->output_field_separator( EXPR )" +.PD 0 +.ie n .IP $OUTPUT_FIELD_SEPARATOR 8 +.el .IP \f(CW$OUTPUT_FIELD_SEPARATOR\fR 8 +.IX Item "$OUTPUT_FIELD_SEPARATOR" +.ie n .IP $OFS 8 +.el .IP \f(CW$OFS\fR 8 +.IX Item "$OFS" +.IP $, 8 +.IX Xref "$, $OFS $OUTPUT_FIELD_SEPARATOR" +.PD +The output field separator for the print operator. If defined, this +value is printed between each of print's arguments. Default is \f(CW\*(C`undef\*(C'\fR. +.Sp +You cannot call \f(CWoutput_field_separator()\fR on a handle, only as a +static method. See IO::Handle. +.Sp +Mnemonic: what is printed when there is a "," in your print statement. +.IP "HANDLE\->input_line_number( EXPR )" 8 +.IX Item "HANDLE->input_line_number( EXPR )" +.PD 0 +.ie n .IP $INPUT_LINE_NUMBER 8 +.el .IP \f(CW$INPUT_LINE_NUMBER\fR 8 +.IX Item "$INPUT_LINE_NUMBER" +.ie n .IP $NR 8 +.el .IP \f(CW$NR\fR 8 +.IX Item "$NR" +.IP $. 8 +.IX Xref "$. $NR $INPUT_LINE_NUMBER line number" +.PD +Current line number for the last filehandle accessed. +.Sp +Each filehandle in Perl counts the number of lines that have been read +from it. (Depending on the value of \f(CW$/\fR, Perl's idea of what +constitutes a line may not match yours.) When a line is read from a +filehandle (via \f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR), or when \f(CWtell()\fR or +\&\f(CWseek()\fR is called on it, \f(CW$.\fR becomes an alias to the line counter +for that filehandle. +.Sp +You can adjust the counter by assigning to \f(CW$.\fR, but this will not +actually move the seek pointer. \fILocalizing \fR\f(CI$.\fR\fI will not localize +the filehandle's line count\fR. Instead, it will localize perl's notion +of which filehandle \f(CW$.\fR is currently aliased to. +.Sp +\&\f(CW$.\fR is reset when the filehandle is closed, but \fBnot\fR when an open +filehandle is reopened without an intervening \f(CWclose()\fR. For more +details, see "I/O Operators" in perlop. Because \f(CW\*(C`<>\*(C'\fR never does +an explicit close, line numbers increase across \f(CW\*(C`ARGV\*(C'\fR files (but see +examples in "eof" in perlfunc). +.Sp +You can also use \f(CW\*(C`HANDLE\->input_line_number(EXPR)\*(C'\fR to access the +line counter for a given filehandle without having to worry about +which handle you last accessed. +.Sp +Mnemonic: many programs use "." to mean the current line number. +.IP "IO::Handle\->input_record_separator( EXPR )" 8 +.IX Item "IO::Handle->input_record_separator( EXPR )" +.PD 0 +.ie n .IP $INPUT_RECORD_SEPARATOR 8 +.el .IP \f(CW$INPUT_RECORD_SEPARATOR\fR 8 +.IX Item "$INPUT_RECORD_SEPARATOR" +.ie n .IP $RS 8 +.el .IP \f(CW$RS\fR 8 +.IX Item "$RS" +.IP $/ 8 +.IX Xref "$ $RS $INPUT_RECORD_SEPARATOR" +.PD +The input record separator, newline by default. This influences Perl's +idea of what a "line" is. Works like \fBawk\fR's RS variable, including +treating empty lines as a terminator if set to the null string (an +empty line cannot contain any spaces or tabs). You may set it to a +multi-character string to match a multi-character terminator, or to +\&\f(CW\*(C`undef\*(C'\fR to read through the end of file. Setting it to \f(CW"\en\en"\fR +means something slightly different than setting to \f(CW""\fR, if the file +contains consecutive empty lines. Setting to \f(CW""\fR will treat two or +more consecutive empty lines as a single empty line. Setting to +\&\f(CW"\en\en"\fR will blindly assume that the next input character belongs to +the next paragraph, even if it's a newline. +.Sp +.Vb 3 +\& local $/; # enable "slurp" mode +\& local $_ = <FH>; # whole file now here +\& s/\en[ \et]+/ /g; +.Ve +.Sp +Remember: the value of \f(CW$/\fR is a string, not a regex. \fBawk\fR has to +be better for something. :\-) +.Sp +Setting \f(CW$/\fR to an empty string \-\- the so-called \fIparagraph mode\fR \-\- merits +special attention. When \f(CW$/\fR is set to \f(CW""\fR and the entire file is read in +with that setting, any sequence of one or more consecutive newlines at the +beginning of the file is discarded. With the exception of the final record in +the file, each sequence of characters ending in two or more newlines is +treated as one record and is read in to end in exactly two newlines. If the +last record in the file ends in zero or one consecutive newlines, that record +is read in with that number of newlines. If the last record ends in two or +more consecutive newlines, it is read in with two newlines like all preceding +records. +.Sp +Suppose we wrote the following string to a file: +.Sp +.Vb 4 +\& my $string = "\en\en\en"; +\& $string .= "alpha beta\engamma delta\en\en\en"; +\& $string .= "epsilon zeta eta\en\en"; +\& $string .= "theta\en"; +\& +\& my $file = \*(Aqsimple_file.txt\*(Aq; +\& open my $OUT, \*(Aq>\*(Aq, $file or die; +\& print $OUT $string; +\& close $OUT or die; +.Ve +.Sp +Now we read that file in paragraph mode: +.Sp +.Vb 4 +\& local $/ = ""; # paragraph mode +\& open my $IN, \*(Aq<\*(Aq, $file or die; +\& my @records = <$IN>; +\& close $IN or die; +.Ve +.Sp +\&\f(CW@records\fR will consist of these 3 strings: +.Sp +.Vb 5 +\& ( +\& "alpha beta\engamma delta\en\en", +\& "epsilon zeta eta\en\en", +\& "theta\en", +\& ) +.Ve +.Sp +Setting \f(CW$/\fR to a reference to an integer, scalar containing an +integer, or scalar that's convertible to an integer will attempt to +read records instead of lines, with the maximum record size being the +referenced integer number of characters. So this: +.Sp +.Vb 3 +\& local $/ = \e32768; # or \e"32768", or \e$var_containing_32768 +\& open my $fh, "<", $myfile or die $!; +\& local $_ = <$fh>; +.Ve +.Sp +will read a record of no more than 32768 characters from \f(CW$fh\fR. If you're +not reading from a record-oriented file (or your OS doesn't have +record-oriented files), then you'll likely get a full chunk of data +with every read. If a record is larger than the record size you've +set, you'll get the record back in pieces. Trying to set the record +size to zero or less is deprecated and will cause $/ to have the value +of "undef", which will cause reading in the (rest of the) whole file. +.Sp +As of 5.19.9 setting \f(CW$/\fR to any other form of reference will throw a +fatal exception. This is in preparation for supporting new ways to set +\&\f(CW$/\fR in the future. +.Sp +On VMS only, record reads bypass PerlIO layers and any associated +buffering, so you must not mix record and non-record reads on the +same filehandle. Record mode mixes with line mode only when the +same buffering layer is in use for both modes. +.Sp +You cannot call \f(CWinput_record_separator()\fR on a handle, only as a +static method. See IO::Handle. +.Sp +See also "Newlines" in perlport. Also see "$.". +.Sp +Mnemonic: / delimits line boundaries when quoting poetry. +.IP "IO::Handle\->output_record_separator( EXPR )" 8 +.IX Item "IO::Handle->output_record_separator( EXPR )" +.PD 0 +.ie n .IP $OUTPUT_RECORD_SEPARATOR 8 +.el .IP \f(CW$OUTPUT_RECORD_SEPARATOR\fR 8 +.IX Item "$OUTPUT_RECORD_SEPARATOR" +.ie n .IP $ORS 8 +.el .IP \f(CW$ORS\fR 8 +.IX Item "$ORS" +.IP $\e 8 +.IX Xref "$\\ $ORS $OUTPUT_RECORD_SEPARATOR" +.IX Item "$" +.PD +The output record separator for the print operator. If defined, this +value is printed after the last of print's arguments. Default is \f(CW\*(C`undef\*(C'\fR. +.Sp +You cannot call \f(CWoutput_record_separator()\fR on a handle, only as a +static method. See IO::Handle. +.Sp +Mnemonic: you set \f(CW\*(C`$\e\*(C'\fR instead of adding "\en" at the end of the print. +Also, it's just like \f(CW$/\fR, but it's what you get "back" from Perl. +.IP "HANDLE\->autoflush( EXPR )" 8 +.IX Item "HANDLE->autoflush( EXPR )" +.PD 0 +.ie n .IP $OUTPUT_AUTOFLUSH 8 +.el .IP \f(CW$OUTPUT_AUTOFLUSH\fR 8 +.IX Item "$OUTPUT_AUTOFLUSH" +.IP $| 8 +.IX Xref "$| autoflush flush $OUTPUT_AUTOFLUSH" +.PD +If set to nonzero, forces a flush right away and after every write or +print on the currently selected output channel. Default is 0 +(regardless of whether the channel is really buffered by the system or +not; \f(CW$|\fR tells you only whether you've asked Perl explicitly to +flush after each write). STDOUT will typically be line buffered if +output is to the terminal and block buffered otherwise. Setting this +variable is useful primarily when you are outputting to a pipe or +socket, such as when you are running a Perl program under \fBrsh\fR and +want to see the output as it's happening. This has no effect on input +buffering. See "getc" in perlfunc for that. See "select" in perlfunc on +how to select the output channel. See also IO::Handle. +.Sp +Mnemonic: when you want your pipes to be piping hot. +.IP ${^LAST_FH} 8 +.IX Xref "${^LAST_FH}" +.IX Item "${^LAST_FH}" +This read-only variable contains a reference to the last-read filehandle. +This is set by \f(CW\*(C`<HANDLE>\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`eof\*(C'\fR and \f(CW\*(C`seek\*(C'\fR. +This is the same handle that \f(CW$.\fR and \f(CW\*(C`tell\*(C'\fR and \f(CW\*(C`eof\*(C'\fR without arguments +use. It is also the handle used when Perl appends ", <STDIN> line 1" to +an error or warning message. +.Sp +This variable was added in Perl v5.18.0. +.PP +\fIVariables related to formats\fR +.IX Subsection "Variables related to formats" +.PP +The special variables for formats are a subset of those for +filehandles. See perlform for more information about Perl's +formats. +.ie n .IP $ACCUMULATOR 8 +.el .IP \f(CW$ACCUMULATOR\fR 8 +.IX Item "$ACCUMULATOR" +.PD 0 +.IP $^A 8 +.IX Xref "$^A $ACCUMULATOR" +.IX Item "$^A" +.PD +The current value of the \f(CWwrite()\fR accumulator for \f(CWformat()\fR lines. +A format contains \f(CWformline()\fR calls that put their result into +\&\f(CW$^A\fR. After calling its format, \f(CWwrite()\fR prints out the contents +of \f(CW$^A\fR and empties. So you never really see the contents of \f(CW$^A\fR +unless you call \f(CWformline()\fR yourself and then look at it. See +perlform and "formline PICTURE,LIST" in perlfunc. +.IP IO::Handle\->format_formfeed(EXPR) 8 +.IX Item "IO::Handle->format_formfeed(EXPR)" +.PD 0 +.ie n .IP $FORMAT_FORMFEED 8 +.el .IP \f(CW$FORMAT_FORMFEED\fR 8 +.IX Item "$FORMAT_FORMFEED" +.IP $^L 8 +.IX Xref "$^L $FORMAT_FORMFEED" +.IX Item "$^L" +.PD +What formats output as a form feed. The default is \f(CW\*(C`\ef\*(C'\fR. +.Sp +You cannot call \f(CWformat_formfeed()\fR on a handle, only as a static +method. See IO::Handle. +.IP HANDLE\->format_page_number(EXPR) 8 +.IX Item "HANDLE->format_page_number(EXPR)" +.PD 0 +.ie n .IP $FORMAT_PAGE_NUMBER 8 +.el .IP \f(CW$FORMAT_PAGE_NUMBER\fR 8 +.IX Item "$FORMAT_PAGE_NUMBER" +.IP $% 8 +.IX Xref "$% $FORMAT_PAGE_NUMBER" +.PD +The current page number of the currently selected output channel. +.Sp +Mnemonic: \f(CW\*(C`%\*(C'\fR is page number in \fBnroff\fR. +.IP HANDLE\->format_lines_left(EXPR) 8 +.IX Item "HANDLE->format_lines_left(EXPR)" +.PD 0 +.ie n .IP $FORMAT_LINES_LEFT 8 +.el .IP \f(CW$FORMAT_LINES_LEFT\fR 8 +.IX Item "$FORMAT_LINES_LEFT" +.IP $\- 8 +.IX Xref "$- $FORMAT_LINES_LEFT" +.PD +The number of lines left on the page of the currently selected output +channel. +.Sp +Mnemonic: lines_on_page \- lines_printed. +.IP "IO::Handle\->format_line_break_characters EXPR" 8 +.IX Item "IO::Handle->format_line_break_characters EXPR" +.PD 0 +.ie n .IP $FORMAT_LINE_BREAK_CHARACTERS 8 +.el .IP \f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR 8 +.IX Item "$FORMAT_LINE_BREAK_CHARACTERS" +.ie n .IP $: 8 +.el .IP \f(CW$:\fR 8 +.IX Xref "$: FORMAT_LINE_BREAK_CHARACTERS" +.IX Item "$:" +.PD +The current set of characters after which a string may be broken to +fill continuation fields (starting with \f(CW\*(C`^\*(C'\fR) in a format. The default is +"\ \en\-", to break on a space, newline, or a hyphen. +.Sp +You cannot call \f(CWformat_line_break_characters()\fR on a handle, only as +a static method. See IO::Handle. +.Sp +Mnemonic: a "colon" in poetry is a part of a line. +.IP HANDLE\->format_lines_per_page(EXPR) 8 +.IX Item "HANDLE->format_lines_per_page(EXPR)" +.PD 0 +.ie n .IP $FORMAT_LINES_PER_PAGE 8 +.el .IP \f(CW$FORMAT_LINES_PER_PAGE\fR 8 +.IX Item "$FORMAT_LINES_PER_PAGE" +.IP $= 8 +.IX Xref "$= $FORMAT_LINES_PER_PAGE" +.PD +The current page length (printable lines) of the currently selected +output channel. The default is 60. +.Sp +Mnemonic: = has horizontal lines. +.IP HANDLE\->format_top_name(EXPR) 8 +.IX Item "HANDLE->format_top_name(EXPR)" +.PD 0 +.ie n .IP $FORMAT_TOP_NAME 8 +.el .IP \f(CW$FORMAT_TOP_NAME\fR 8 +.IX Item "$FORMAT_TOP_NAME" +.IP $^ 8 +.IX Xref "$^ $FORMAT_TOP_NAME" +.PD +The name of the current top-of-page format for the currently selected +output channel. The default is the name of the filehandle with \f(CW\*(C`_TOP\*(C'\fR +appended. For example, the default format top name for the \f(CW\*(C`STDOUT\*(C'\fR +filehandle is \f(CW\*(C`STDOUT_TOP\*(C'\fR. +.Sp +Mnemonic: points to top of page. +.IP HANDLE\->format_name(EXPR) 8 +.IX Item "HANDLE->format_name(EXPR)" +.PD 0 +.ie n .IP $FORMAT_NAME 8 +.el .IP \f(CW$FORMAT_NAME\fR 8 +.IX Item "$FORMAT_NAME" +.IP $~ 8 +.IX Xref "$~ $FORMAT_NAME" +.PD +The name of the current report format for the currently selected +output channel. The default format name is the same as the filehandle +name. For example, the default format name for the \f(CW\*(C`STDOUT\*(C'\fR +filehandle is just \f(CW\*(C`STDOUT\*(C'\fR. +.Sp +Mnemonic: brother to \f(CW$^\fR. +.SS "Error Variables" +.IX Xref "error exception" +.IX Subsection "Error Variables" +The variables \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, and \f(CW$?\fR contain information +about different types of error conditions that may appear during +execution of a Perl program. The variables are shown ordered by +the "distance" between the subsystem which reported the error and +the Perl process. They correspond to errors detected by the Perl +interpreter, C library, operating system, or an external program, +respectively. +.PP +To illustrate the differences between these variables, consider the +following Perl expression, which uses a single-quoted string. After +execution of this statement, perl may have set all four special error +variables: +.PP +.Vb 5 +\& eval q{ +\& open my $pipe, "/cdrom/install |" or die $!; +\& my @res = <$pipe>; +\& close $pipe or die "bad pipe: $?, $!"; +\& }; +.Ve +.PP +When perl executes the \f(CWeval()\fR expression, it translates the +\&\f(CWopen()\fR, \f(CW\*(C`<PIPE>\*(C'\fR, and \f(CW\*(C`close\*(C'\fR calls in the C run-time library +and thence to the operating system kernel. perl sets \f(CW$!\fR to +the C library's \f(CW\*(C`errno\*(C'\fR if one of these calls fails. +.PP +\&\f(CW$@\fR is set if the string to be \f(CW\*(C`eval\*(C'\fR\-ed did not compile (this may +happen if \f(CW\*(C`open\*(C'\fR or \f(CW\*(C`close\*(C'\fR were imported with bad prototypes), or +if Perl code executed during evaluation \f(CWdie()\fRd. In these cases the +value of \f(CW$@\fR is the compile error, or the argument to \f(CW\*(C`die\*(C'\fR (which +will interpolate \f(CW$!\fR and \f(CW$?\fR). (See also Fatal, though.) +.PP +Under a few operating systems, \f(CW$^E\fR may contain a more verbose error +indicator, such as in this case, "CDROM tray not closed." Systems that +do not support extended error messages leave \f(CW$^E\fR the same as \f(CW$!\fR. +.PP +Finally, \f(CW$?\fR may be set to a non\-0 value if the external program +\&\fI/cdrom/install\fR fails. The upper eight bits reflect specific error +conditions encountered by the program (the program's \f(CWexit()\fR value). +The lower eight bits reflect mode of failure, like signal death and +core dump information. See \fBwait\fR\|(2) for details. In contrast to +\&\f(CW$!\fR and \f(CW$^E\fR, which are set only if an error condition is detected, +the variable \f(CW$?\fR is set on each \f(CW\*(C`wait\*(C'\fR or pipe \f(CW\*(C`close\*(C'\fR, +overwriting the old value. This is more like \f(CW$@\fR, which on every +\&\f(CWeval()\fR is always set on failure and cleared on success. +.PP +For more details, see the individual descriptions at \f(CW$@\fR, \f(CW$!\fR, +\&\f(CW$^E\fR, and \f(CW$?\fR. +.IP ${^CHILD_ERROR_NATIVE} 8 +.IX Xref "$^CHILD_ERROR_NATIVE" +.IX Item "${^CHILD_ERROR_NATIVE}" +The native status returned by the last pipe close, backtick (\f(CW\`\`\fR) +command, successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the +\&\f(CWsystem()\fR operator. On POSIX-like systems this value can be decoded +with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, and +WSTOPSIG functions provided by the POSIX module. +.Sp +Under VMS this reflects the actual VMS exit status; i.e. it is the +same as \f(CW$?\fR when the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR is in effect. +.Sp +This variable was added in Perl v5.10.0. +.ie n .IP $EXTENDED_OS_ERROR 8 +.el .IP \f(CW$EXTENDED_OS_ERROR\fR 8 +.IX Item "$EXTENDED_OS_ERROR" +.PD 0 +.IP $^E 8 +.IX Xref "$^E $EXTENDED_OS_ERROR" +.IX Item "$^E" +.PD +Error information specific to the current operating system. At the +moment, this differs from \f(CW"$!"\fR under only VMS, OS/2, and Win32 (and +for MacPerl). On all other platforms, \f(CW$^E\fR is always just the same +as \f(CW$!\fR. +.Sp +Under VMS, \f(CW$^E\fR provides the VMS status value from the last system +error. This is more specific information about the last system error +than that provided by \f(CW$!\fR. This is particularly important when \f(CW$!\fR +is set to \fBEVMSERR\fR. +.Sp +Under OS/2, \f(CW$^E\fR is set to the error code of the last call to OS/2 +API either via CRT, or directly from perl. +.Sp +Under Win32, \f(CW$^E\fR always returns the last error information reported +by the Win32 call \f(CWGetLastError()\fR which describes the last error +from within the Win32 API. Most Win32\-specific code will report errors +via \f(CW$^E\fR. ANSI C and Unix-like calls set \f(CW\*(C`errno\*(C'\fR and so most +portable Perl code will report errors via \f(CW$!\fR. +.Sp +Caveats mentioned in the description of \f(CW"$!"\fR generally apply to +\&\f(CW$^E\fR, also. +.Sp +This variable was added in Perl 5.003. +.Sp +Mnemonic: Extra error explanation. +.ie n .IP $EXCEPTIONS_BEING_CAUGHT 8 +.el .IP \f(CW$EXCEPTIONS_BEING_CAUGHT\fR 8 +.IX Item "$EXCEPTIONS_BEING_CAUGHT" +.PD 0 +.IP $^S 8 +.IX Xref "$^S $EXCEPTIONS_BEING_CAUGHT" +.IX Item "$^S" +.PD +Current state of the interpreter. +.Sp +.Vb 5 +\& $^S State +\& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& undef Parsing module, eval, or main program +\& true (1) Executing an eval or try block +\& false (0) Otherwise +.Ve +.Sp +The first state may happen in \f(CW$SIG{_\|_DIE_\|_}\fR and \f(CW$SIG{_\|_WARN_\|_}\fR +handlers. +.Sp +The English name \f(CW$EXCEPTIONS_BEING_CAUGHT\fR is slightly misleading, because +the \f(CW\*(C`undef\*(C'\fR value does not indicate whether exceptions are being caught, +since compilation of the main program does not catch exceptions. +.Sp +This variable was added in Perl 5.004. +.ie n .IP $WARNING 8 +.el .IP \f(CW$WARNING\fR 8 +.IX Item "$WARNING" +.PD 0 +.IP $^W 8 +.IX Xref "$^W $WARNING" +.IX Item "$^W" +.PD +The current value of the warning switch, initially true if \fB\-w\fR was +used, false otherwise, but directly modifiable. +.Sp +See also warnings. +.Sp +Mnemonic: related to the \fB\-w\fR switch. +.IP ${^WARNING_BITS} 8 +.IX Xref "${^WARNING_BITS}" +.IX Item "${^WARNING_BITS}" +The current set of warning checks enabled by the \f(CW\*(C`use warnings\*(C'\fR pragma. +It has the same scoping as the \f(CW$^H\fR and \f(CW\*(C`%^H\*(C'\fR variables. The exact +values are considered internal to the warnings pragma and may change +between versions of Perl. +.Sp +Each time a statement completes being compiled, the current value of +\&\f(CW\*(C`${^WARNING_BITS}\*(C'\fR is stored with that statement, and can later be +retrieved via \f(CW\*(C`(caller($level))[9]\*(C'\fR. +.Sp +This variable was added in Perl v5.6.0. +.ie n .IP $OS_ERROR 8 +.el .IP \f(CW$OS_ERROR\fR 8 +.IX Item "$OS_ERROR" +.PD 0 +.ie n .IP $ERRNO 8 +.el .IP \f(CW$ERRNO\fR 8 +.IX Item "$ERRNO" +.IP $! 8 +.IX Xref "$! $ERRNO $OS_ERROR" +.PD +When referenced, \f(CW$!\fR retrieves the current value +of the C \f(CW\*(C`errno\*(C'\fR integer variable. +If \f(CW$!\fR is assigned a numerical value, that value is stored in \f(CW\*(C`errno\*(C'\fR. +When referenced as a string, \f(CW$!\fR yields the system error string +corresponding to \f(CW\*(C`errno\*(C'\fR. +.Sp +Many system or library calls set \f(CW\*(C`errno\*(C'\fR if they fail, +to indicate the cause of failure. They usually do \fBnot\fR +set \f(CW\*(C`errno\*(C'\fR to zero if they succeed and may set \f(CW\*(C`errno\*(C'\fR to a +non-zero value on success. This means \f(CW\*(C`errno\*(C'\fR, hence \f(CW$!\fR, is +meaningful only \fIimmediately\fR after a \fBfailure\fR: +.Sp +.Vb 11 +\& if (open my $fh, "<", $filename) { +\& # Here $! is meaningless. +\& ... +\& } +\& else { +\& # ONLY here is $! meaningful. +\& ... +\& # Already here $! might be meaningless. +\& } +\& # Since here we might have either success or failure, +\& # $! is meaningless. +.Ve +.Sp +Here, \fImeaningless\fR means that \f(CW$!\fR may be unrelated to the outcome +of the \f(CWopen()\fR operator. Assignment to \f(CW$!\fR is similarly ephemeral. +It can be used immediately before invoking the \f(CWdie()\fR operator, +to set the exit value, or to inspect the system error string +corresponding to error \fIn\fR, or to restore \f(CW$!\fR to a meaningful state. +.Sp +Perl itself may set \f(CW\*(C`errno\*(C'\fR to a non-zero on failure even if no +system call is performed. +.Sp +Mnemonic: What just went bang? +.ie n .IP %OS_ERROR 8 +.el .IP \f(CW%OS_ERROR\fR 8 +.IX Item "%OS_ERROR" +.PD 0 +.ie n .IP %ERRNO 8 +.el .IP \f(CW%ERRNO\fR 8 +.IX Item "%ERRNO" +.IP %! 8 +.IX Xref "%! %OS_ERROR %ERRNO" +.PD +Each element of \f(CW\*(C`%!\*(C'\fR has a true value only if \f(CW$!\fR is set to that +value. For example, \f(CW$!{ENOENT}\fR is true if and only if the current +value of \f(CW$!\fR is \f(CW\*(C`ENOENT\*(C'\fR; that is, if the most recent error was "No +such file or directory" (or its moral equivalent: not all operating +systems give that exact error, and certainly not all languages). The +specific true value is not guaranteed, but in the past has generally +been the numeric value of \f(CW$!\fR. To check if a particular key is +meaningful on your system, use \f(CW\*(C`exists $!{the_key}\*(C'\fR; for a list of legal +keys, use \f(CW\*(C`keys %!\*(C'\fR. See Errno for more information, and also see +"$!". +.Sp +This variable was added in Perl 5.005. +.ie n .IP $CHILD_ERROR 8 +.el .IP \f(CW$CHILD_ERROR\fR 8 +.IX Item "$CHILD_ERROR" +.PD 0 +.IP $? 8 +.IX Xref "$? $CHILD_ERROR" +.PD +The status returned by the last pipe close, backtick (\f(CW\`\`\fR) command, +successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the \f(CWsystem()\fR +operator. This is just the 16\-bit status word returned by the +traditional Unix \f(CWwait()\fR system call (or else is made up to look +like it). Thus, the exit value of the subprocess is really (\f(CW$? >> +8\fR), and \f(CW\*(C`$? & 127\*(C'\fR gives which signal, if any, the process died +from, and \f(CW\*(C`$? & 128\*(C'\fR reports whether there was a core dump. +.Sp +Additionally, if the \f(CW\*(C`h_errno\*(C'\fR variable is supported in C, its value +is returned via \f(CW$?\fR if any \f(CW\*(C`gethost*()\*(C'\fR function fails. +.Sp +If you have installed a signal handler for \f(CW\*(C`SIGCHLD\*(C'\fR, the +value of \f(CW$?\fR will usually be wrong outside that handler. +.Sp +Inside an \f(CW\*(C`END\*(C'\fR subroutine \f(CW$?\fR contains the value that is going to be +given to \f(CWexit()\fR. You can modify \f(CW$?\fR in an \f(CW\*(C`END\*(C'\fR subroutine to +change the exit status of your program. For example: +.Sp +.Vb 3 +\& END { +\& $? = 1 if $? == 255; # die would make it 255 +\& } +.Ve +.Sp +Under VMS, the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR makes \f(CW$?\fR reflect the +actual VMS exit status, instead of the default emulation of POSIX +status; see "$?" in perlvms for details. +.Sp +Mnemonic: similar to \fBsh\fR and \fBksh\fR. +.ie n .IP $EVAL_ERROR 8 +.el .IP \f(CW$EVAL_ERROR\fR 8 +.IX Item "$EVAL_ERROR" +.PD 0 +.IP $@ 8 +.IX Xref "$@ $EVAL_ERROR" +.PD +The Perl error from the last \f(CW\*(C`eval\*(C'\fR operator, i.e. the last exception that +was caught. For \f(CW\*(C`eval BLOCK\*(C'\fR, this is either a runtime error message or the +string or reference \f(CW\*(C`die\*(C'\fR was called with. The \f(CW\*(C`eval STRING\*(C'\fR form also +catches syntax errors and other compile time exceptions. +.Sp +If no error occurs, \f(CW\*(C`eval\*(C'\fR sets \f(CW$@\fR to the empty string. +.Sp +Warning messages are not collected in this variable. You can, however, +set up a routine to process warnings by setting \f(CW$SIG{_\|_WARN_\|_}\fR as +described in "%SIG". +.Sp +Mnemonic: Where was the error "at"? +.SS "Variables related to the interpreter state" +.IX Subsection "Variables related to the interpreter state" +These variables provide information about the current interpreter state. +.ie n .IP $COMPILING 8 +.el .IP \f(CW$COMPILING\fR 8 +.IX Item "$COMPILING" +.PD 0 +.IP $^C 8 +.IX Xref "$^C $COMPILING" +.IX Item "$^C" +.PD +The current value of the flag associated with the \fB\-c\fR switch. +Mainly of use with \fB\-MO=...\fR to allow code to alter its behavior +when being compiled, such as for example to \f(CW\*(C`AUTOLOAD\*(C'\fR at compile +time rather than normal, deferred loading. Setting +\&\f(CW\*(C`$^C = 1\*(C'\fR is similar to calling \f(CW\*(C`B::minus_c\*(C'\fR. +.Sp +This variable was added in Perl v5.6.0. +.ie n .IP $DEBUGGING 8 +.el .IP \f(CW$DEBUGGING\fR 8 +.IX Item "$DEBUGGING" +.PD 0 +.IP $^D 8 +.IX Xref "$^D $DEBUGGING" +.IX Item "$^D" +.PD +The current value of the debugging flags. May be read or set. Like its +command-line equivalent, you can use numeric +or symbolic values, e.g. \f(CW\*(C`$^D = 10\*(C'\fR or \f(CW\*(C`$^D = "st"\*(C'\fR. See +"\fB\-D\fR\fInumber\fR" in perlrun. The contents of this variable also affects the +debugger operation. See "Debugger Internals" in perldebguts. +.Sp +Mnemonic: value of \fB\-D\fR switch. +.IP ${^GLOBAL_PHASE} 8 +.IX Xref "${^GLOBAL_PHASE}" +.IX Item "${^GLOBAL_PHASE}" +The current phase of the perl interpreter. +.Sp +Possible values are: +.RS 8 +.IP CONSTRUCT 8 +.IX Item "CONSTRUCT" +The \f(CW\*(C`PerlInterpreter*\*(C'\fR is being constructed via \f(CW\*(C`perl_construct\*(C'\fR. This +value is mostly there for completeness and for use via the +underlying C variable \f(CW\*(C`PL_phase\*(C'\fR. It's not really possible for Perl +code to be executed unless construction of the interpreter is +finished. +.IP START 8 +.IX Item "START" +This is the global compile-time. That includes, basically, every +\&\f(CW\*(C`BEGIN\*(C'\fR block executed directly or indirectly from during the +compile-time of the top-level program. +.Sp +This phase is not called "BEGIN" to avoid confusion with +\&\f(CW\*(C`BEGIN\*(C'\fR\-blocks, as those are executed during compile-time of any +compilation unit, not just the top-level program. A new, localised +compile-time entered at run-time, for example by constructs as +\&\f(CW\*(C`eval "use SomeModule"\*(C'\fR are not global interpreter phases, and +therefore aren't reflected by \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR. +.IP CHECK 8 +.IX Item "CHECK" +Execution of any \f(CW\*(C`CHECK\*(C'\fR blocks. +.IP INIT 8 +.IX Item "INIT" +Similar to "CHECK", but for \f(CW\*(C`INIT\*(C'\fR\-blocks, not \f(CW\*(C`CHECK\*(C'\fR blocks. +.IP RUN 8 +.IX Item "RUN" +The main run-time, i.e. the execution of \f(CW\*(C`PL_main_root\*(C'\fR. +.IP END 8 +.IX Item "END" +Execution of any \f(CW\*(C`END\*(C'\fR blocks. +.IP DESTRUCT 8 +.IX Item "DESTRUCT" +Global destruction. +.RE +.RS 8 +.Sp +Also note that there's no value for UNITCHECK-blocks. That's because +those are run for each compilation unit individually, and therefore is +not a global interpreter phase. +.Sp +Not every program has to go through each of the possible phases, but +transition from one phase to another can only happen in the order +described in the above list. +.Sp +An example of all of the phases Perl code can see: +.Sp +.Vb 1 +\& BEGIN { print "compile\-time: ${^GLOBAL_PHASE}\en" } +\& +\& INIT { print "init\-time: ${^GLOBAL_PHASE}\en" } +\& +\& CHECK { print "check\-time: ${^GLOBAL_PHASE}\en" } +\& +\& { +\& package Print::Phase; +\& +\& sub new { +\& my ($class, $time) = @_; +\& return bless \e$time, $class; +\& } +\& +\& sub DESTROY { +\& my $self = shift; +\& print "$$self: ${^GLOBAL_PHASE}\en"; +\& } +\& } +\& +\& print "run\-time: ${^GLOBAL_PHASE}\en"; +\& +\& my $runtime = Print::Phase\->new( +\& "lexical variables are garbage collected before END" +\& ); +\& +\& END { print "end\-time: ${^GLOBAL_PHASE}\en" } +\& +\& our $destruct = Print::Phase\->new( +\& "package variables are garbage collected after END" +\& ); +.Ve +.Sp +This will print out +.Sp +.Vb 7 +\& compile\-time: START +\& check\-time: CHECK +\& init\-time: INIT +\& run\-time: RUN +\& lexical variables are garbage collected before END: RUN +\& end\-time: END +\& package variables are garbage collected after END: DESTRUCT +.Ve +.Sp +This variable was added in Perl 5.14.0. +.RE +.IP $^H 8 +.IX Xref "$^H" +.IX Item "$^H" +WARNING: This variable is strictly for +internal use only. Its availability, +behavior, and contents are subject to change without notice. +.Sp +This variable contains compile-time hints for the Perl interpreter. At the +end of compilation of a BLOCK the value of this variable is restored to the +value when the interpreter started to compile the BLOCK. +.Sp +Each time a statement completes being compiled, the current value of +\&\f(CW$^H\fR is stored with that statement, and can later be retrieved via +\&\f(CW\*(C`(caller($level))[8]\*(C'\fR. See "caller EXPR" in perlfunc. +.Sp +When perl begins to parse any block construct that provides a lexical scope +(e.g., eval body, required file, subroutine body, loop body, or conditional +block), the existing value of \f(CW$^H\fR is saved, but its value is left unchanged. +When the compilation of the block is completed, it regains the saved value. +Between the points where its value is saved and restored, code that +executes within BEGIN blocks is free to change the value of \f(CW$^H\fR. +.Sp +This behavior provides the semantic of lexical scoping, and is used in, +for instance, the \f(CW\*(C`use strict\*(C'\fR pragma. +.Sp +The contents should be an integer; different bits of it are used for +different pragmatic flags. Here's an example: +.Sp +.Vb 1 +\& sub add_100 { $^H |= 0x100 } +\& +\& sub foo { +\& BEGIN { add_100() } +\& bar\->baz($boon); +\& } +.Ve +.Sp +Consider what happens during execution of the BEGIN block. At this point +the BEGIN block has already been compiled, but the body of \f(CWfoo()\fR is still +being compiled. The new value of \f(CW$^H\fR +will therefore be visible only while +the body of \f(CWfoo()\fR is being compiled. +.Sp +Substitution of \f(CW\*(C`BEGIN { add_100() }\*(C'\fR block with: +.Sp +.Vb 1 +\& BEGIN { require strict; strict\->import(\*(Aqvars\*(Aq) } +.Ve +.Sp +demonstrates how \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR is implemented. Here's a conditional +version of the same lexical pragma: +.Sp +.Vb 3 +\& BEGIN { +\& require strict; strict\->import(\*(Aqvars\*(Aq) if $condition +\& } +.Ve +.Sp +This variable was added in Perl 5.003. +.IP %^H 8 +.IX Xref "%^H" +.IX Item "%^H" +The \f(CW\*(C`%^H\*(C'\fR hash provides the same scoping semantics as \f(CW$^H\fR. This +makes it useful for implementing lexically scoped pragmas. See perlpragma. +All the entries are stringified when accessed at runtime, so only simple values +can be accommodated. This means no references to objects, for example. +.Sp +Each time a statement completes being compiled, the current value of +\&\f(CW\*(C`%^H\*(C'\fR is stored with that statement, and can later be retrieved via +\&\f(CW\*(C`(caller($level))[10]\*(C'\fR. See "caller EXPR" in perlfunc. +.Sp +When putting items into \f(CW\*(C`%^H\*(C'\fR, in order to avoid conflicting with other +users of the hash there is a convention regarding which keys to use. +A module should use only keys that begin with the module's name (the +name of its main package) and a "/" character. For example, a module +\&\f(CW\*(C`Foo::Bar\*(C'\fR should use keys such as \f(CW\*(C`Foo::Bar/baz\*(C'\fR. +.Sp +This variable was added in Perl v5.6.0. +.IP ${^OPEN} 8 +.IX Xref "${^OPEN}" +.IX Item "${^OPEN}" +An internal variable used by PerlIO. A string in two parts, separated +by a \f(CW\*(C`\e0\*(C'\fR byte, the first part describes the input layers, the second +part describes the output layers. +.Sp +This is the mechanism that applies the lexical effects of the open +pragma, and the main program scope effects of the \f(CW\*(C`io\*(C'\fR or \f(CW\*(C`D\*(C'\fR options +for the \-C command-line switch and +PERL_UNICODE environment variable. +.Sp +The functions \f(CWaccept()\fR, \f(CWopen()\fR, \f(CWpipe()\fR, \f(CWreadpipe()\fR (as well +as the related \f(CW\*(C`qx\*(C'\fR and \f(CW\`STRING\`\fR operators), \f(CWsocket()\fR, +\&\f(CWsocketpair()\fR, and \f(CWsysopen()\fR are affected by the lexical value of +this variable. The implicit "ARGV" handle opened by \f(CWreadline()\fR (or +the related \f(CW\*(C`<>\*(C'\fR and \f(CW\*(C`<<>>\*(C'\fR operators) on passed filenames is +also affected (but not if it opens \f(CW\*(C`STDIN\*(C'\fR). If this variable is not +set, these functions will set the default layers as described in +"Defaults and how to override them" in PerlIO. +.Sp +\&\f(CWopen()\fR ignores this variable (and the default layers) when called with +3 arguments and explicit layers are specified. Indirect calls to these +functions via modules like IO::Handle are not affected as they occur +in a different lexical scope. Directory handles such as opened by +\&\f(CWopendir()\fR are not currently affected. +.Sp +This variable was added in Perl v5.8.0. +.ie n .IP $PERLDB 8 +.el .IP \f(CW$PERLDB\fR 8 +.IX Item "$PERLDB" +.PD 0 +.IP $^P 8 +.IX Xref "$^P $PERLDB" +.IX Item "$^P" +.PD +The internal variable for debugging support. The meanings of the +various bits are subject to change, but currently indicate: +.RS 8 +.IP 0x01 6 +.IX Item "0x01" +Debug subroutine enter/exit. +.IP 0x02 6 +.IX Item "0x02" +Line-by-line debugging. Causes \f(CWDB::DB()\fR subroutine to be called for +each statement executed. Also causes saving source code lines (like +0x400). +.IP 0x04 6 +.IX Item "0x04" +Switch off optimizations. +.IP 0x08 6 +.IX Item "0x08" +Preserve more data for future interactive inspections. +.IP 0x10 6 +.IX Item "0x10" +Keep info about source lines on which a subroutine is defined. +.IP 0x20 6 +.IX Item "0x20" +Start with single-step on. +.IP 0x40 6 +.IX Item "0x40" +Use subroutine address instead of name when reporting. +.IP 0x80 6 +.IX Item "0x80" +Report \f(CW\*(C`goto &subroutine\*(C'\fR as well. +.IP 0x100 6 +.IX Item "0x100" +Provide informative "file" names for evals based on the place they were compiled. +.IP 0x200 6 +.IX Item "0x200" +Provide informative names to anonymous subroutines based on the place they +were compiled. +.IP 0x400 6 +.IX Item "0x400" +Save source code lines into \f(CW\*(C`@{"_<$filename"}\*(C'\fR. +.IP 0x800 6 +.IX Item "0x800" +When saving source, include evals that generate no subroutines. +.IP 0x1000 6 +.IX Item "0x1000" +When saving source, include source that did not compile. +.RE +.RS 8 +.Sp +Some bits may be relevant at compile-time only, some at +run-time only. This is a new mechanism and the details may change. +See also perldebguts. +.RE +.IP ${^TAINT} 8 +.IX Xref "${^TAINT}" +.IX Item "${^TAINT}" +Reflects if taint mode is on or off. 1 for on (the program was run with +\&\fB\-T\fR), 0 for off, \-1 when only taint warnings are enabled (i.e. with +\&\fB\-t\fR or \fB\-TU\fR). +.Sp +Note: if your perl was built without taint support (see perlsec), +then \f(CW\*(C`${^TAINT}\*(C'\fR will always be 0, even if the program was run with \fB\-T\fR). +.Sp +This variable is read-only. +.Sp +This variable was added in Perl v5.8.0. +.IP ${^SAFE_LOCALES} 8 +.IX Xref "${^SAFE_LOCALES}" +.IX Item "${^SAFE_LOCALES}" +Reflects if safe locale operations are available to this perl (when the +value is 1) or not (the value is 0). This variable is always 1 if the +perl has been compiled without threads. It is also 1 if this perl is +using thread-safe locale operations. Note that an individual thread may +choose to use the global locale (generally unsafe) by calling +"switch_to_global_locale" in perlapi. This variable currently is still +set to 1 in such threads. +.Sp +This variable is read-only. +.Sp +This variable was added in Perl v5.28.0. +.IP ${^UNICODE} 8 +.IX Xref "${^UNICODE}" +.IX Item "${^UNICODE}" +Reflects certain Unicode settings of Perl. See +perlrun documentation for the \f(CW\*(C`\-C\*(C'\fR +switch for more information about the possible values. +.Sp +This variable is set during Perl startup and is thereafter read-only. +.Sp +This variable was added in Perl v5.8.2. +.IP ${^UTF8CACHE} 8 +.IX Xref "${^UTF8CACHE}" +.IX Item "${^UTF8CACHE}" +This variable controls the state of the internal UTF\-8 offset caching code. +1 for on (the default), 0 for off, \-1 to debug the caching code by checking +all its results against linear scans, and panicking on any discrepancy. +.Sp +This variable was added in Perl v5.8.9. It is subject to change or +removal without notice, but is currently used to avoid recalculating the +boundaries of multi-byte UTF\-8\-encoded characters. +.IP ${^UTF8LOCALE} 8 +.IX Xref "${^UTF8LOCALE}" +.IX Item "${^UTF8LOCALE}" +This variable indicates whether a UTF\-8 locale was detected by perl at +startup. This information is used by perl when it's in +adjust\-utf8ness\-to\-locale mode (as when run with the \f(CW\*(C`\-CL\*(C'\fR command-line +switch); see perlrun for more info on +this. +.Sp +This variable was added in Perl v5.8.8. +.SS "Deprecated and removed variables" +.IX Subsection "Deprecated and removed variables" +Deprecating a variable announces the intent of the perl maintainers to +eventually remove the variable from the language. It may still be +available despite its status. Using a deprecated variable triggers +a warning. +.PP +Once a variable is removed, its use triggers an error telling you +the variable is unsupported. +.PP +See perldiag for details about error messages. +.IP $# 8 +.IX Xref "$#" +\&\f(CW$#\fR was a variable that could be used to format printed numbers. +After a deprecation cycle, its magic was removed in Perl v5.10.0 and +using it now triggers a warning: \f(CW\*(C`$# is no longer supported\*(C'\fR. +.Sp +This is not the sigil you use in front of an array name to get the +last index, like \f(CW$#array\fR. That's still how you get the last index +of an array in Perl. The two have nothing to do with each other. +.Sp +Deprecated in Perl 5. +.Sp +Removed in Perl v5.10.0. +.IP $* 8 +.IX Xref "$*" +\&\f(CW$*\fR was a variable that you could use to enable multiline matching. +After a deprecation cycle, its magic was removed in Perl v5.10.0. +Using it now triggers a warning: \f(CW\*(C`$* is no longer supported\*(C'\fR. +You should use the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR regexp modifiers instead. +.Sp +Deprecated in Perl 5. +.Sp +Removed in Perl v5.10.0. +.IP $[ 8 +.IX Xref "$[" +This variable stores the index of the first element in an array, and +of the first character in a substring. The default is 0, but you could +theoretically set it to 1 to make Perl behave more like \fBawk\fR (or Fortran) +when subscripting and when evaluating the \fBindex()\fR and \fBsubstr()\fR functions. +.Sp +As of release 5 of Perl, assignment to \f(CW$[\fR is treated as a compiler +directive, and cannot influence the behavior of any other file. +(That's why you can only assign compile-time constants to it.) +Its use is highly discouraged. +.Sp +Prior to Perl v5.10.0, assignment to \f(CW$[\fR could be seen from outer lexical +scopes in the same file, unlike other compile-time directives (such as +strict). Using \fBlocal()\fR on it would bind its value strictly to a lexical +block. Now it is always lexically scoped. +.Sp +As of Perl v5.16.0, it is implemented by the arybase module. +.Sp +As of Perl v5.30.0, or under \f(CW\*(C`use v5.16\*(C'\fR, or \f(CW\*(C`no feature "array_base"\*(C'\fR, +\&\f(CW$[\fR no longer has any effect, and always contains 0. +Assigning 0 to it is permitted, but any other value will produce an error. +.Sp +Mnemonic: [ begins subscripts. +.Sp +Deprecated in Perl v5.12.0. +.IP ${^ENCODING} 8 +.IX Xref "${^ENCODING}" +.IX Item "${^ENCODING}" +This variable is no longer supported. +.Sp +It used to hold the \fIobject reference\fR to the \f(CW\*(C`Encode\*(C'\fR object that was +used to convert the source code to Unicode. +.Sp +Its purpose was to allow your non-ASCII Perl +scripts not to have to be written in UTF\-8; this was +useful before editors that worked on UTF\-8 encoded text were common, but +that was long ago. It caused problems, such as affecting the operation +of other modules that weren't expecting it, causing general mayhem. +.Sp +If you need something like this functionality, it is recommended that use +you a simple source filter, such as Filter::Encoding. +.Sp +If you are coming here because code of yours is being adversely affected +by someone's use of this variable, you can usually work around it by +doing this: +.Sp +.Vb 1 +\& local ${^ENCODING}; +.Ve +.Sp +near the beginning of the functions that are getting broken. This +undefines the variable during the scope of execution of the including +function. +.Sp +This variable was added in Perl 5.8.2 and removed in 5.26.0. +Setting it to anything other than \f(CW\*(C`undef\*(C'\fR was made fatal in Perl 5.28.0. +.IP ${^WIN32_SLOPPY_STAT} 8 +.IX Xref "${^WIN32_SLOPPY_STAT} sitecustomize sitecustomize.pl" +.IX Item "${^WIN32_SLOPPY_STAT}" +This variable no longer has any function. +.Sp +This variable was added in Perl v5.10.0 and removed in Perl v5.34.0. |