| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLVAR 1" |
| 58 |
.TH PERLVAR 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlvar \- Perl predefined variables |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
.SS "The Syntax of Variable Names" |
| 68 |
.IX Subsection "The Syntax of Variable Names" |
| 69 |
Variable names in Perl can have several formats. Usually, they |
| 70 |
must begin with a letter or underscore, in which case they can be |
| 71 |
arbitrarily long (up to an internal limit of 251 characters) and |
| 72 |
may contain letters, digits, underscores, or the special sequence |
| 73 |
\&\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 |
| 74 |
\&\f(CW\*(C`\*(Aq\*(C'\fR is taken to be a \fIpackage qualifier\fR; see perlmod. |
| 75 |
A Unicode letter that is not ASCII is not considered to be a letter |
| 76 |
unless \f(CW"use\ utf8"\fR is in effect, and somewhat more complicated |
| 77 |
rules apply; see "Identifier parsing" in perldata for details. |
| 78 |
.PP |
| 79 |
Perl variable names may also be a sequence of digits, a single |
| 80 |
punctuation character, or the two-character sequence: \f(CW\*(C`^\*(C'\fR (caret or |
| 81 |
CIRCUMFLEX ACCENT) followed by any one of the characters \f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR. |
| 82 |
These names are all reserved for |
| 83 |
special uses by Perl; for example, the all-digits names are used |
| 84 |
to hold data captured by backreferences after a regular expression |
| 85 |
match. |
| 86 |
.PP |
| 87 |
Since Perl v5.6.0, Perl variable names may also be alphanumeric strings |
| 88 |
preceded by a caret. These must all be written using the demarcated |
| 89 |
variable form using curly braces such as \f(CW\*(C`${^Foo}\*(C'\fR; |
| 90 |
the braces are \fBnot\fR optional. \f(CW\*(C`${^Foo}\*(C'\fR denotes the scalar variable |
| 91 |
whose name is considered to be a control\-\f(CW\*(C`F\*(C'\fR followed by two \f(CW\*(C`o\*(C'\fR's. |
| 92 |
(See "Demarcated variable names using braces" in perldata for more |
| 93 |
information on this form of spelling a variable name or specifying |
| 94 |
access to an element of an array or a hash). |
| 95 |
These variables are |
| 96 |
reserved for future special uses by Perl, except for the ones that |
| 97 |
begin with \f(CW\*(C`^_\*(C'\fR (caret-underscore). No |
| 98 |
name that begins with \f(CW\*(C`^_\*(C'\fR will acquire a special |
| 99 |
meaning in any future version of Perl; such names may therefore be |
| 100 |
used safely in programs. \f(CW$^_\fR itself, however, \fIis\fR reserved. |
| 101 |
.PP |
| 102 |
Note that you also \fBmust\fR use the demarcated form to access subscripts |
| 103 |
of variables of this type when interpolating, for instance to access the |
| 104 |
first element of the \f(CW\*(C`@{^CAPTURE}\*(C'\fR variable inside of a double quoted |
| 105 |
string you would write \f(CW"${^CAPTURE[0]}"\fR and NOT \f(CW"${^CAPTURE}[0]"\fR |
| 106 |
which would mean to reference a scalar variable named \f(CW\*(C`${^CAPTURE}\*(C'\fR and |
| 107 |
not index 0 of the magic \f(CW\*(C`@{^CAPTURE}\*(C'\fR array which is populated by the |
| 108 |
regex engine. |
| 109 |
.PP |
| 110 |
Perl identifiers that begin with digits or |
| 111 |
punctuation characters are exempt from the effects of the \f(CW\*(C`package\*(C'\fR |
| 112 |
declaration and are always forced to be in package \f(CW\*(C`main\*(C'\fR; they are |
| 113 |
also exempt from \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR errors. A few other names are also |
| 114 |
exempt in these ways: |
| 115 |
.PP |
| 116 |
.Vb 5 |
| 117 |
\& ENV STDIN |
| 118 |
\& INC STDOUT |
| 119 |
\& ARGV STDERR |
| 120 |
\& ARGVOUT |
| 121 |
\& SIG |
| 122 |
.Ve |
| 123 |
.PP |
| 124 |
In particular, the special \f(CW\*(C`${^_XYZ}\*(C'\fR variables are always taken |
| 125 |
to be in package \f(CW\*(C`main\*(C'\fR, regardless of any \f(CW\*(C`package\*(C'\fR declarations |
| 126 |
presently in scope. |
| 127 |
.SH "SPECIAL VARIABLES" |
| 128 |
.IX Header "SPECIAL VARIABLES" |
| 129 |
The following names have special meaning to Perl. Most punctuation |
| 130 |
names have reasonable mnemonics, or analogs in the shells. |
| 131 |
Nevertheless, if you wish to use long variable names, you need only say: |
| 132 |
.PP |
| 133 |
.Vb 1 |
| 134 |
\& use English; |
| 135 |
.Ve |
| 136 |
.PP |
| 137 |
at the top of your program. This aliases all the short names to the long |
| 138 |
names in the current package. Some even have medium names, generally |
| 139 |
borrowed from \fBawk\fR. For more info, please see English. |
| 140 |
.PP |
| 141 |
Before you continue, note the sort order for variables. In general, we |
| 142 |
first list the variables in case-insensitive, almost-lexigraphical |
| 143 |
order (ignoring the \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`^\*(C'\fR preceding words, as in \f(CW\*(C`${^UNICODE}\*(C'\fR |
| 144 |
or \f(CW$^T\fR), although \f(CW$_\fR and \f(CW@_\fR move up to the top of the pile. |
| 145 |
For variables with the same identifier, we list it in order of scalar, |
| 146 |
array, hash, and bareword. |
| 147 |
.SS "General Variables" |
| 148 |
.IX Subsection "General Variables" |
| 149 |
.ie n .IP $ARG 8 |
| 150 |
.el .IP \f(CW$ARG\fR 8 |
| 151 |
.IX Item "$ARG" |
| 152 |
.PD 0 |
| 153 |
.ie n .IP $_ 8 |
| 154 |
.el .IP \f(CW$_\fR 8 |
| 155 |
.IX Xref "$_ $ARG" |
| 156 |
.IX Item "$_" |
| 157 |
.PD |
| 158 |
The default input and pattern-searching space. The following pairs are |
| 159 |
equivalent: |
| 160 |
.Sp |
| 161 |
.Vb 2 |
| 162 |
\& while (<>) {...} # equivalent only in while! |
| 163 |
\& while (defined($_ = <>)) {...} |
| 164 |
\& |
| 165 |
\& /^Subject:/ |
| 166 |
\& $_ =~ /^Subject:/ |
| 167 |
\& |
| 168 |
\& tr/a\-z/A\-Z/ |
| 169 |
\& $_ =~ tr/a\-z/A\-Z/ |
| 170 |
\& |
| 171 |
\& chomp |
| 172 |
\& chomp($_) |
| 173 |
.Ve |
| 174 |
.Sp |
| 175 |
Here are the places where Perl will assume \f(CW$_\fR even if you don't use it: |
| 176 |
.RS 8 |
| 177 |
.IP \(bu 3 |
| 178 |
The following functions use \f(CW$_\fR as a default argument: |
| 179 |
.Sp |
| 180 |
abs, alarm, chomp, chop, chr, chroot, |
| 181 |
cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc, |
| 182 |
lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf, |
| 183 |
quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), |
| 184 |
rmdir, say, sin, split (for its second |
| 185 |
argument), sqrt, stat, study, uc, ucfirst, |
| 186 |
unlink, unpack. |
| 187 |
.IP \(bu 3 |
| 188 |
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. |
| 189 |
See "\-X" in perlfunc |
| 190 |
.IP \(bu 3 |
| 191 |
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) |
| 192 |
when used without an \f(CW\*(C`=~\*(C'\fR operator. |
| 193 |
.IP \(bu 3 |
| 194 |
The default iterator variable in a \f(CW\*(C`foreach\*(C'\fR loop if no other |
| 195 |
variable is supplied. |
| 196 |
.IP \(bu 3 |
| 197 |
The implicit iterator variable in the \f(CWgrep()\fR and \f(CWmap()\fR functions. |
| 198 |
.IP \(bu 3 |
| 199 |
The implicit variable of \f(CWgiven()\fR. |
| 200 |
.IP \(bu 3 |
| 201 |
The default place to put the next value or input record |
| 202 |
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 |
| 203 |
operation's result is tested by itself as the sole criterion of a \f(CW\*(C`while\*(C'\fR |
| 204 |
test. Outside a \f(CW\*(C`while\*(C'\fR test, this will not happen. |
| 205 |
.RE |
| 206 |
.RS 8 |
| 207 |
.Sp |
| 208 |
\&\f(CW$_\fR is a global variable. |
| 209 |
.Sp |
| 210 |
However, between perl v5.10.0 and v5.24.0, it could be used lexically by |
| 211 |
writing \f(CW\*(C`my $_\*(C'\fR. Making \f(CW$_\fR refer to the global \f(CW$_\fR in the same scope |
| 212 |
was then possible with \f(CW\*(C`our $_\*(C'\fR. This experimental feature was removed and is |
| 213 |
now a fatal error, but you may encounter it in older code. |
| 214 |
.Sp |
| 215 |
Mnemonic: underline is understood in certain operations. |
| 216 |
.RE |
| 217 |
.ie n .IP @ARG 8 |
| 218 |
.el .IP \f(CW@ARG\fR 8 |
| 219 |
.IX Item "@ARG" |
| 220 |
.PD 0 |
| 221 |
.ie n .IP @_ 8 |
| 222 |
.el .IP \f(CW@_\fR 8 |
| 223 |
.IX Xref "@_ @ARG" |
| 224 |
.IX Item "@_" |
| 225 |
.PD |
| 226 |
Within a subroutine the array \f(CW@_\fR contains the parameters passed to |
| 227 |
that subroutine. Inside a subroutine, \f(CW@_\fR is the default array for |
| 228 |
the array operators \f(CW\*(C`pop\*(C'\fR and \f(CW\*(C`shift\*(C'\fR. |
| 229 |
.Sp |
| 230 |
See perlsub. |
| 231 |
.ie n .IP $LIST_SEPARATOR 8 |
| 232 |
.el .IP \f(CW$LIST_SEPARATOR\fR 8 |
| 233 |
.IX Item "$LIST_SEPARATOR" |
| 234 |
.PD 0 |
| 235 |
.IP "$""" 8 |
| 236 |
.IX Xref "$"" $LIST_SEPARATOR" |
| 237 |
.PD |
| 238 |
When an array or an array slice is interpolated into a double-quoted |
| 239 |
string or a similar context such as \f(CW\*(C`/.../\*(C'\fR, its elements are |
| 240 |
separated by this value. Default is a space. For example, this: |
| 241 |
.Sp |
| 242 |
.Vb 1 |
| 243 |
\& print "The array is: @array\en"; |
| 244 |
.Ve |
| 245 |
.Sp |
| 246 |
is equivalent to this: |
| 247 |
.Sp |
| 248 |
.Vb 1 |
| 249 |
\& print "The array is: " . join($", @array) . "\en"; |
| 250 |
.Ve |
| 251 |
.Sp |
| 252 |
Mnemonic: works in double-quoted context. |
| 253 |
.ie n .IP $PROCESS_ID 8 |
| 254 |
.el .IP \f(CW$PROCESS_ID\fR 8 |
| 255 |
.IX Item "$PROCESS_ID" |
| 256 |
.PD 0 |
| 257 |
.ie n .IP $PID 8 |
| 258 |
.el .IP \f(CW$PID\fR 8 |
| 259 |
.IX Item "$PID" |
| 260 |
.IP $$ 8 |
| 261 |
.IX Xref "$$ $PID $PROCESS_ID" |
| 262 |
.PD |
| 263 |
The process number of the Perl running this script. Though you \fIcan\fR set |
| 264 |
this variable, doing so is generally discouraged, although it can be |
| 265 |
invaluable for some testing purposes. It will be reset automatically |
| 266 |
across \f(CWfork()\fR calls. |
| 267 |
.Sp |
| 268 |
Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl |
| 269 |
would emulate POSIX semantics on Linux systems using LinuxThreads, a |
| 270 |
partial implementation of POSIX Threads that has since been superseded |
| 271 |
by the Native POSIX Thread Library (NPTL). |
| 272 |
.Sp |
| 273 |
LinuxThreads is now obsolete on Linux, and caching \f(CWgetpid()\fR |
| 274 |
like this made embedding perl unnecessarily complex (since you'd have |
| 275 |
to manually update the value of $$), so now \f(CW$$\fR and \f(CWgetppid()\fR |
| 276 |
will always return the same values as the underlying C library. |
| 277 |
.Sp |
| 278 |
Debian GNU/kFreeBSD systems also used LinuxThreads up until and |
| 279 |
including the 6.0 release, but after that moved to FreeBSD thread |
| 280 |
semantics, which are POSIX-like. |
| 281 |
.Sp |
| 282 |
To see if your system is affected by this discrepancy check if |
| 283 |
\&\f(CW\*(C`getconf GNU_LIBPTHREAD_VERSION | grep \-q NPTL\*(C'\fR returns a false |
| 284 |
value. NTPL threads preserve the POSIX semantics. |
| 285 |
.Sp |
| 286 |
Mnemonic: same as shells. |
| 287 |
.ie n .IP $PROGRAM_NAME 8 |
| 288 |
.el .IP \f(CW$PROGRAM_NAME\fR 8 |
| 289 |
.IX Item "$PROGRAM_NAME" |
| 290 |
.PD 0 |
| 291 |
.ie n .IP $0 8 |
| 292 |
.el .IP \f(CW$0\fR 8 |
| 293 |
.IX Xref "$0 $PROGRAM_NAME" |
| 294 |
.IX Item "$0" |
| 295 |
.PD |
| 296 |
Contains the name of the program being executed. |
| 297 |
.Sp |
| 298 |
On some (but not all) operating systems assigning to \f(CW$0\fR modifies |
| 299 |
the argument area that the \f(CW\*(C`ps\*(C'\fR program sees. On some platforms you |
| 300 |
may have to use special \f(CW\*(C`ps\*(C'\fR options or a different \f(CW\*(C`ps\*(C'\fR to see the |
| 301 |
changes. Modifying the \f(CW$0\fR is more useful as a way of indicating the |
| 302 |
current program state than it is for hiding the program you're |
| 303 |
running. |
| 304 |
.Sp |
| 305 |
Note that there are platform-specific limitations on the maximum |
| 306 |
length of \f(CW$0\fR. In the most extreme case it may be limited to the |
| 307 |
space occupied by the original \f(CW$0\fR. |
| 308 |
.Sp |
| 309 |
In some platforms there may be arbitrary amount of padding, for |
| 310 |
example space characters, after the modified name as shown by \f(CW\*(C`ps\*(C'\fR. |
| 311 |
In some platforms this padding may extend all the way to the original |
| 312 |
length of the argument area, no matter what you do (this is the case |
| 313 |
for example with Linux 2.2). |
| 314 |
.Sp |
| 315 |
Note for BSD users: setting \f(CW$0\fR does not completely remove "perl" |
| 316 |
from the \fBps\fR\|(1) output. For example, setting \f(CW$0\fR to \f(CW"foobar"\fR may |
| 317 |
result in \f(CW"perl: foobar (perl)"\fR (whether both the \f(CW"perl: "\fR prefix |
| 318 |
and the " (perl)" suffix are shown depends on your exact BSD variant |
| 319 |
and version). This is an operating system feature, Perl cannot help it. |
| 320 |
.Sp |
| 321 |
In multithreaded scripts Perl coordinates the threads so that any |
| 322 |
thread may modify its copy of the \f(CW$0\fR and the change becomes visible |
| 323 |
to \fBps\fR\|(1) (assuming the operating system plays along). Note that |
| 324 |
the view of \f(CW$0\fR the other threads have will not change since they |
| 325 |
have their own copies of it. |
| 326 |
.Sp |
| 327 |
If the program has been given to perl via the switches \f(CW\*(C`\-e\*(C'\fR or \f(CW\*(C`\-E\*(C'\fR, |
| 328 |
\&\f(CW$0\fR will contain the string \f(CW"\-e"\fR. |
| 329 |
.Sp |
| 330 |
On Linux as of perl v5.14.0 the legacy process name will be set with |
| 331 |
\&\f(CWprctl(2)\fR, in addition to altering the POSIX name via \f(CW\*(C`argv[0]\*(C'\fR as |
| 332 |
perl has done since version 4.000. Now system utilities that read the |
| 333 |
legacy process name such as ps, top and killall will recognize the |
| 334 |
name you set when assigning to \f(CW$0\fR. The string you supply will be |
| 335 |
cut off at 16 bytes, this is a limitation imposed by Linux. |
| 336 |
.Sp |
| 337 |
Wide characters are invalid in \f(CW$0\fR values. For historical reasons, |
| 338 |
though, Perl accepts them and encodes them to UTF\-8. When this |
| 339 |
happens a wide-character warning is triggered. |
| 340 |
.Sp |
| 341 |
Mnemonic: same as \fBsh\fR and \fBksh\fR. |
| 342 |
.ie n .IP $REAL_GROUP_ID 8 |
| 343 |
.el .IP \f(CW$REAL_GROUP_ID\fR 8 |
| 344 |
.IX Item "$REAL_GROUP_ID" |
| 345 |
.PD 0 |
| 346 |
.ie n .IP $GID 8 |
| 347 |
.el .IP \f(CW$GID\fR 8 |
| 348 |
.IX Item "$GID" |
| 349 |
.IP $( 8 |
| 350 |
.IX Xref "$( $GID $REAL_GROUP_ID" |
| 351 |
.PD |
| 352 |
The real gid of this process. If you are on a machine that supports |
| 353 |
membership in multiple groups simultaneously, gives a space separated |
| 354 |
list of groups you are in. The first number is the one returned by |
| 355 |
\&\f(CWgetgid()\fR, and the subsequent ones by \f(CWgetgroups()\fR, one of which may be |
| 356 |
the same as the first number. |
| 357 |
.Sp |
| 358 |
However, a value assigned to \f(CW$(\fR must be a single number used to |
| 359 |
set the real gid. So the value given by \f(CW$(\fR should \fInot\fR be assigned |
| 360 |
back to \f(CW$(\fR without being forced numeric, such as by adding zero. Note |
| 361 |
that this is different to the effective gid (\f(CW$)\fR) which does take a |
| 362 |
list. |
| 363 |
.Sp |
| 364 |
You can change both the real gid and the effective gid at the same |
| 365 |
time by using \f(CWPOSIX::setgid()\fR. Changes |
| 366 |
to \f(CW$(\fR require a check to \f(CW$!\fR |
| 367 |
to detect any possible errors after an attempted change. |
| 368 |
.Sp |
| 369 |
Mnemonic: parentheses are used to \fIgroup\fR things. The real gid is the |
| 370 |
group you \fIleft\fR, if you're running setgid. |
| 371 |
.ie n .IP $EFFECTIVE_GROUP_ID 8 |
| 372 |
.el .IP \f(CW$EFFECTIVE_GROUP_ID\fR 8 |
| 373 |
.IX Item "$EFFECTIVE_GROUP_ID" |
| 374 |
.PD 0 |
| 375 |
.ie n .IP $EGID 8 |
| 376 |
.el .IP \f(CW$EGID\fR 8 |
| 377 |
.IX Item "$EGID" |
| 378 |
.IP $) 8 |
| 379 |
.IX Xref "$) $EGID $EFFECTIVE_GROUP_ID" |
| 380 |
.PD |
| 381 |
The effective gid of this process. If you are on a machine that |
| 382 |
supports membership in multiple groups simultaneously, gives a space |
| 383 |
separated list of groups you are in. The first number is the one |
| 384 |
returned by \f(CWgetegid()\fR, and the subsequent ones by \f(CWgetgroups()\fR, |
| 385 |
one of which may be the same as the first number. |
| 386 |
.Sp |
| 387 |
Similarly, a value assigned to \f(CW$)\fR must also be a space-separated |
| 388 |
list of numbers. The first number sets the effective gid, and |
| 389 |
the rest (if any) are passed to \f(CWsetgroups()\fR. To get the effect of an |
| 390 |
empty list for \f(CWsetgroups()\fR, just repeat the new effective gid; that is, |
| 391 |
to force an effective gid of 5 and an effectively empty \f(CWsetgroups()\fR |
| 392 |
list, say \f(CW\*(C` $) = "5 5" \*(C'\fR. |
| 393 |
.Sp |
| 394 |
You can change both the effective gid and the real gid at the same |
| 395 |
time by using \f(CWPOSIX::setgid()\fR (use only a single numeric argument). |
| 396 |
Changes to \f(CW$)\fR require a check to \f(CW$!\fR to detect any possible errors |
| 397 |
after an attempted change. |
| 398 |
.Sp |
| 399 |
\&\f(CW$<\fR, \f(CW$>\fR, \f(CW$(\fR and \f(CW$)\fR can be set only on |
| 400 |
machines that support the corresponding \fIset[re][ug]\fR\f(BIid()\fR routine. \f(CW$(\fR |
| 401 |
and \f(CW$)\fR can be swapped only on machines supporting \f(CWsetregid()\fR. |
| 402 |
.Sp |
| 403 |
Mnemonic: parentheses are used to \fIgroup\fR things. The effective gid |
| 404 |
is the group that's \fIright\fR for you, if you're running setgid. |
| 405 |
.ie n .IP $REAL_USER_ID 8 |
| 406 |
.el .IP \f(CW$REAL_USER_ID\fR 8 |
| 407 |
.IX Item "$REAL_USER_ID" |
| 408 |
.PD 0 |
| 409 |
.ie n .IP $UID 8 |
| 410 |
.el .IP \f(CW$UID\fR 8 |
| 411 |
.IX Item "$UID" |
| 412 |
.IP $< 8 |
| 413 |
.IX Xref "$< $UID $REAL_USER_ID" |
| 414 |
.PD |
| 415 |
The real uid of this process. You can change both the real uid and the |
| 416 |
effective uid at the same time by using \f(CWPOSIX::setuid()\fR. Since |
| 417 |
changes to \f(CW$<\fR require a system call, check \f(CW$!\fR after a change |
| 418 |
attempt to detect any possible errors. |
| 419 |
.Sp |
| 420 |
Mnemonic: it's the uid you came \fIfrom\fR, if you're running setuid. |
| 421 |
.ie n .IP $EFFECTIVE_USER_ID 8 |
| 422 |
.el .IP \f(CW$EFFECTIVE_USER_ID\fR 8 |
| 423 |
.IX Item "$EFFECTIVE_USER_ID" |
| 424 |
.PD 0 |
| 425 |
.ie n .IP $EUID 8 |
| 426 |
.el .IP \f(CW$EUID\fR 8 |
| 427 |
.IX Item "$EUID" |
| 428 |
.IP $> 8 |
| 429 |
.IX Xref "$> $EUID $EFFECTIVE_USER_ID" |
| 430 |
.PD |
| 431 |
The effective uid of this process. For example: |
| 432 |
.Sp |
| 433 |
.Vb 2 |
| 434 |
\& $< = $>; # set real to effective uid |
| 435 |
\& ($<,$>) = ($>,$<); # swap real and effective uids |
| 436 |
.Ve |
| 437 |
.Sp |
| 438 |
You can change both the effective uid and the real uid at the same |
| 439 |
time by using \f(CWPOSIX::setuid()\fR. Changes to \f(CW$>\fR require a check |
| 440 |
to \f(CW$!\fR to detect any possible errors after an attempted change. |
| 441 |
.Sp |
| 442 |
\&\f(CW$<\fR and \f(CW$>\fR can be swapped only on machines |
| 443 |
supporting \f(CWsetreuid()\fR. |
| 444 |
.Sp |
| 445 |
Mnemonic: it's the uid you went \fIto\fR, if you're running setuid. |
| 446 |
.ie n .IP $SUBSCRIPT_SEPARATOR 8 |
| 447 |
.el .IP \f(CW$SUBSCRIPT_SEPARATOR\fR 8 |
| 448 |
.IX Item "$SUBSCRIPT_SEPARATOR" |
| 449 |
.PD 0 |
| 450 |
.ie n .IP $SUBSEP 8 |
| 451 |
.el .IP \f(CW$SUBSEP\fR 8 |
| 452 |
.IX Item "$SUBSEP" |
| 453 |
.IP $; 8 |
| 454 |
.IX Xref "$; $SUBSEP SUBSCRIPT_SEPARATOR" |
| 455 |
.PD |
| 456 |
The subscript separator for multidimensional array emulation. If you |
| 457 |
refer to a hash element as |
| 458 |
.Sp |
| 459 |
.Vb 1 |
| 460 |
\& $foo{$x,$y,$z} |
| 461 |
.Ve |
| 462 |
.Sp |
| 463 |
it really means |
| 464 |
.Sp |
| 465 |
.Vb 1 |
| 466 |
\& $foo{join($;, $x, $y, $z)} |
| 467 |
.Ve |
| 468 |
.Sp |
| 469 |
But don't put |
| 470 |
.Sp |
| 471 |
.Vb 1 |
| 472 |
\& @foo{$x,$y,$z} # a slice\-\-note the @ |
| 473 |
.Ve |
| 474 |
.Sp |
| 475 |
which means |
| 476 |
.Sp |
| 477 |
.Vb 1 |
| 478 |
\& ($foo{$x},$foo{$y},$foo{$z}) |
| 479 |
.Ve |
| 480 |
.Sp |
| 481 |
Default is "\e034", the same as SUBSEP in \fBawk\fR. If your keys contain |
| 482 |
binary data there might not be any safe value for \f(CW$;\fR. |
| 483 |
.Sp |
| 484 |
Consider using "real" multidimensional arrays as described |
| 485 |
in perllol. |
| 486 |
.Sp |
| 487 |
Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. |
| 488 |
.ie n .IP $a 8 |
| 489 |
.el .IP \f(CW$a\fR 8 |
| 490 |
.IX Item "$a" |
| 491 |
.PD 0 |
| 492 |
.ie n .IP $b 8 |
| 493 |
.el .IP \f(CW$b\fR 8 |
| 494 |
.IX Xref "$a $b" |
| 495 |
.IX Item "$b" |
| 496 |
.PD |
| 497 |
Special package variables when using \f(CWsort()\fR, see "sort" in perlfunc. |
| 498 |
Because of this specialness \f(CW$a\fR and \f(CW$b\fR don't need to be declared |
| 499 |
(using \f(CW\*(C`use vars\*(C'\fR, or \f(CWour()\fR) even when using the \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR |
| 500 |
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 |
| 501 |
be able to use them in the \f(CWsort()\fR comparison block or function. |
| 502 |
.ie n .IP %ENV 8 |
| 503 |
.el .IP \f(CW%ENV\fR 8 |
| 504 |
.IX Xref "%ENV" |
| 505 |
.IX Item "%ENV" |
| 506 |
The hash \f(CW%ENV\fR contains your current environment. Setting a |
| 507 |
value in \f(CW\*(C`ENV\*(C'\fR changes the environment for any child processes |
| 508 |
you subsequently \f(CWfork()\fR off. |
| 509 |
.Sp |
| 510 |
As of v5.18.0, both keys and values stored in \f(CW%ENV\fR are stringified. |
| 511 |
.Sp |
| 512 |
.Vb 7 |
| 513 |
\& my $foo = 1; |
| 514 |
\& $ENV{\*(Aqbar\*(Aq} = \e$foo; |
| 515 |
\& if( ref $ENV{\*(Aqbar\*(Aq} ) { |
| 516 |
\& say "Pre 5.18.0 Behaviour"; |
| 517 |
\& } else { |
| 518 |
\& say "Post 5.18.0 Behaviour"; |
| 519 |
\& } |
| 520 |
.Ve |
| 521 |
.Sp |
| 522 |
Previously, only child processes received stringified values: |
| 523 |
.Sp |
| 524 |
.Vb 2 |
| 525 |
\& my $foo = 1; |
| 526 |
\& $ENV{\*(Aqbar\*(Aq} = \e$foo; |
| 527 |
\& |
| 528 |
\& # Always printed \*(Aqnon ref\*(Aq |
| 529 |
\& system($^X, \*(Aq\-e\*(Aq, |
| 530 |
\& q/print ( ref $ENV{\*(Aqbar\*(Aq} ? \*(Aqref\*(Aq : \*(Aqnon ref\*(Aq ) /); |
| 531 |
.Ve |
| 532 |
.Sp |
| 533 |
This happens because you can't really share arbitrary data structures with |
| 534 |
foreign processes. |
| 535 |
.ie n .IP $OLD_PERL_VERSION 8 |
| 536 |
.el .IP \f(CW$OLD_PERL_VERSION\fR 8 |
| 537 |
.IX Item "$OLD_PERL_VERSION" |
| 538 |
.PD 0 |
| 539 |
.IP $] 8 |
| 540 |
.IX Xref "$] $OLD_PERL_VERSION" |
| 541 |
.PD |
| 542 |
The revision, version, and subversion of the Perl interpreter, represented |
| 543 |
as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY |
| 544 |
is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001". |
| 545 |
.Sp |
| 546 |
This variable can be used to determine whether the Perl interpreter |
| 547 |
executing a script is in the right range of versions: |
| 548 |
.Sp |
| 549 |
.Vb 1 |
| 550 |
\& warn "No PerlIO!\en" if "$]" < 5.008; |
| 551 |
.Ve |
| 552 |
.Sp |
| 553 |
When comparing \f(CW$]\fR, numeric comparison operators should be used, but the |
| 554 |
variable should be stringified first to avoid issues where its original |
| 555 |
numeric value is inaccurate. |
| 556 |
.Sp |
| 557 |
See also the documentation of \f(CW\*(C`use VERSION\*(C'\fR and |
| 558 |
\&\f(CW\*(C`require VERSION\*(C'\fR for a convenient way to fail if the running Perl |
| 559 |
interpreter is too old. |
| 560 |
.Sp |
| 561 |
See "$^V" for a representation of the Perl version as a version |
| 562 |
object, which allows more flexible string comparisons. |
| 563 |
.Sp |
| 564 |
The main advantage of \f(CW$]\fR over \f(CW$^V\fR is that it works the same on any |
| 565 |
version of Perl. The disadvantages are that it can't easily be compared |
| 566 |
to versions in other formats (e.g. literal v\-strings, "v1.2.3" or |
| 567 |
version objects) and numeric comparisons are subject to the binary |
| 568 |
floating point representation; it's good for numeric literal version |
| 569 |
checks and bad for comparing to a variable that hasn't been |
| 570 |
sanity-checked. |
| 571 |
.Sp |
| 572 |
The \f(CW$OLD_PERL_VERSION\fR form was added in Perl v5.20.0 for historical |
| 573 |
reasons but its use is discouraged. (If your reason to use \f(CW$]\fR is to |
| 574 |
run code on old perls then referring to it as \f(CW$OLD_PERL_VERSION\fR would |
| 575 |
be self-defeating.) |
| 576 |
.Sp |
| 577 |
Mnemonic: Is this version of perl in the right bracket? |
| 578 |
.ie n .IP $SYSTEM_FD_MAX 8 |
| 579 |
.el .IP \f(CW$SYSTEM_FD_MAX\fR 8 |
| 580 |
.IX Item "$SYSTEM_FD_MAX" |
| 581 |
.PD 0 |
| 582 |
.IP $^F 8 |
| 583 |
.IX Xref "$^F $SYSTEM_FD_MAX" |
| 584 |
.IX Item "$^F" |
| 585 |
.PD |
| 586 |
The maximum system file descriptor, ordinarily 2. System file |
| 587 |
descriptors are passed to \f(CWexec()\fRed processes, while higher file |
| 588 |
descriptors are not. Also, during an |
| 589 |
\&\f(CWopen()\fR, system file descriptors are |
| 590 |
preserved even if the \f(CWopen()\fR fails (ordinary file descriptors are |
| 591 |
closed before the \f(CWopen()\fR is attempted). The close-on-exec |
| 592 |
status of a file descriptor will be decided according to the value of |
| 593 |
\&\f(CW$^F\fR when the corresponding file, pipe, or socket was opened, not the |
| 594 |
time of the \f(CWexec()\fR. |
| 595 |
.ie n .IP @F 8 |
| 596 |
.el .IP \f(CW@F\fR 8 |
| 597 |
.IX Xref "@F" |
| 598 |
.IX Item "@F" |
| 599 |
The array \f(CW@F\fR contains the fields of each line read in when autosplit |
| 600 |
mode is turned on. See perlrun for the \fB\-a\fR switch. This |
| 601 |
array is package-specific, and must be declared or given a full package |
| 602 |
name if not in package main when running under \f(CW\*(C`strict \*(Aqvars\*(Aq\*(C'\fR. |
| 603 |
.ie n .IP @INC 8 |
| 604 |
.el .IP \f(CW@INC\fR 8 |
| 605 |
.IX Xref "@INC" |
| 606 |
.IX Item "@INC" |
| 607 |
The array \f(CW@INC\fR contains the list of places that the \f(CW\*(C`do EXPR\*(C'\fR, |
| 608 |
\&\f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR constructs look for their library files. It |
| 609 |
initially consists of the arguments to any \fB\-I\fR command-line |
| 610 |
switches, followed by the default Perl library, probably |
| 611 |
\&\fI/usr/local/lib/perl\fR. |
| 612 |
Prior to Perl 5.26, \f(CW\*(C`.\*(C'\fR \-which represents the current directory, was included |
| 613 |
in \f(CW@INC\fR; it has been removed. This change in behavior is documented |
| 614 |
in \f(CW\*(C`PERL_USE_UNSAFE_INC\*(C'\fR and it is |
| 615 |
not recommended that \f(CW\*(C`.\*(C'\fR be re-added to \f(CW@INC\fR. |
| 616 |
If you need to modify \f(CW@INC\fR at runtime, you should use the \f(CW\*(C`use lib\*(C'\fR pragma |
| 617 |
to get the machine-dependent library properly loaded as well: |
| 618 |
.Sp |
| 619 |
.Vb 2 |
| 620 |
\& use lib \*(Aq/mypath/libdir/\*(Aq; |
| 621 |
\& use SomeMod; |
| 622 |
.Ve |
| 623 |
.Sp |
| 624 |
You can also insert hooks into the file inclusion system by putting Perl |
| 625 |
code directly into \f(CW@INC\fR. Those hooks may be subroutine references, |
| 626 |
array references or blessed objects. See "require" in perlfunc for details. |
| 627 |
.ie n .IP %INC 8 |
| 628 |
.el .IP \f(CW%INC\fR 8 |
| 629 |
.IX Xref "%INC" |
| 630 |
.IX Item "%INC" |
| 631 |
The hash \f(CW%INC\fR contains entries for each filename included via the |
| 632 |
\&\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 |
| 633 |
you specified (with module names converted to pathnames), and the |
| 634 |
value is the location of the file found. The \f(CW\*(C`require\*(C'\fR |
| 635 |
operator uses this hash to determine whether a particular file has |
| 636 |
already been included. |
| 637 |
.Sp |
| 638 |
If the file was loaded via a hook (e.g. a subroutine reference, see |
| 639 |
"require" in perlfunc for a description of these hooks), this hook is |
| 640 |
by default inserted into \f(CW%INC\fR in place of a filename. Note, however, |
| 641 |
that the hook may have set the \f(CW%INC\fR entry by itself to provide some more |
| 642 |
specific info. |
| 643 |
.ie n .IP $INC 8 |
| 644 |
.el .IP \f(CW$INC\fR 8 |
| 645 |
.IX Xref "$INC" |
| 646 |
.IX Item "$INC" |
| 647 |
As of 5.37.7 when an \f(CW@INC\fR hook is executed the index of the \f(CW@INC\fR |
| 648 |
array that holds the hook will be localized into the \f(CW$INC\fR variable. |
| 649 |
When the hook returns the integer successor of its value will be used to |
| 650 |
determine the next index in \f(CW@INC\fR that will be checked, thus if it is |
| 651 |
set to \-1 (or \f(CW\*(C`undef\*(C'\fR) the traversal over the \f(CW@INC\fR array will be |
| 652 |
restarted from its beginning. |
| 653 |
.Sp |
| 654 |
Normally traversal through the \f(CW@INC\fR array is from beginning to end |
| 655 |
(\f(CW\*(C`0 .. $#INC\*(C'\fR), and if the \f(CW@INC\fR array is modified by the hook the |
| 656 |
iterator may be left in a state where newly added entries are skipped. |
| 657 |
Changing this value allows an \f(CW@INC\fR hook to rewrite the \f(CW@INC\fR array |
| 658 |
and tell Perl where to continue afterwards. See "require" in perlfunc for |
| 659 |
details on \f(CW@INC\fR hooks. |
| 660 |
.ie n .IP $INPLACE_EDIT 8 |
| 661 |
.el .IP \f(CW$INPLACE_EDIT\fR 8 |
| 662 |
.IX Item "$INPLACE_EDIT" |
| 663 |
.PD 0 |
| 664 |
.IP $^I 8 |
| 665 |
.IX Xref "$^I $INPLACE_EDIT" |
| 666 |
.IX Item "$^I" |
| 667 |
.PD |
| 668 |
The current value of the inplace-edit extension. Use \f(CW\*(C`undef\*(C'\fR to disable |
| 669 |
inplace editing. |
| 670 |
.Sp |
| 671 |
Mnemonic: value of \fB\-i\fR switch. |
| 672 |
.ie n .IP @ISA 8 |
| 673 |
.el .IP \f(CW@ISA\fR 8 |
| 674 |
.IX Xref "@ISA" |
| 675 |
.IX Item "@ISA" |
| 676 |
Each package contains a special array called \f(CW@ISA\fR which contains a list |
| 677 |
of that class's parent classes, if any. This array is simply a list of |
| 678 |
scalars, each of which is a string that corresponds to a package name. The |
| 679 |
array is examined when Perl does method resolution, which is covered in |
| 680 |
perlobj. |
| 681 |
.Sp |
| 682 |
To load packages while adding them to \f(CW@ISA\fR, see the parent pragma. The |
| 683 |
discouraged base pragma does this as well, but should not be used except |
| 684 |
when compatibility with the discouraged fields pragma is required. |
| 685 |
.IP $^M 8 |
| 686 |
.IX Xref "$^M" |
| 687 |
.IX Item "$^M" |
| 688 |
By default, running out of memory is an untrappable, fatal error. |
| 689 |
However, if suitably built, Perl can use the contents of \f(CW$^M\fR |
| 690 |
as an emergency memory pool after \f(CWdie()\fRing. Suppose that your Perl |
| 691 |
were compiled with \f(CW\*(C`\-DPERL_EMERGENCY_SBRK\*(C'\fR and used Perl's malloc. |
| 692 |
Then |
| 693 |
.Sp |
| 694 |
.Vb 1 |
| 695 |
\& $^M = \*(Aqa\*(Aq x (1 << 16); |
| 696 |
.Ve |
| 697 |
.Sp |
| 698 |
would allocate a 64K buffer for use in an emergency. See the |
| 699 |
INSTALL file in the Perl distribution for information on how to |
| 700 |
add custom C compilation flags when compiling perl. To discourage casual |
| 701 |
use of this advanced feature, there is no English long name for |
| 702 |
this variable. |
| 703 |
.Sp |
| 704 |
This variable was added in Perl 5.004. |
| 705 |
.IP ${^MAX_NESTED_EVAL_BEGIN_BLOCKS} 8 |
| 706 |
.IX Item "${^MAX_NESTED_EVAL_BEGIN_BLOCKS}" |
| 707 |
This variable determines the maximum number \f(CW\*(C`eval EXPR\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR or |
| 708 |
\&\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`BEGIN\*(C'\fR block nesting that is allowed. This means it also |
| 709 |
controls the maximum nesting of \f(CW\*(C`use\*(C'\fR statements as well. |
| 710 |
.Sp |
| 711 |
The default of 1000 should be sufficiently large for normal working |
| 712 |
purposes, and if you must raise it then you should be conservative |
| 713 |
with your choice or you may encounter segfaults from exhaustion of |
| 714 |
the C stack. It seems unlikely that real code has a use depth above |
| 715 |
1000, but we have left this configurable just in case. |
| 716 |
.Sp |
| 717 |
When set to \f(CW0\fR then \f(CW\*(C`BEGIN\*(C'\fR blocks inside of \f(CW\*(C`eval EXPR\*(C'\fR or |
| 718 |
\&\f(CW\*(C`require EXPR\*(C'\fR are forbidden entirely and will trigger an exception |
| 719 |
which will terminate the compilation and in the case of \f(CW\*(C`require\*(C'\fR |
| 720 |
will throw an exception, or in the case of \f(CW\*(C`eval\*(C'\fR return the error in |
| 721 |
\&\f(CW$@\fR as usual. |
| 722 |
.Sp |
| 723 |
Consider the code |
| 724 |
.Sp |
| 725 |
.Vb 1 |
| 726 |
\& perl \-le\*(Aqsub f { eval "BEGIN { f() }"; } f()\*(Aq |
| 727 |
.Ve |
| 728 |
.Sp |
| 729 |
each invocation of \f(CWf()\fR will consume considerable C stack, and this |
| 730 |
variable is used to cause code like this to die instead of exhausting |
| 731 |
the C stack and triggering a segfault. Needless to say code like this is |
| 732 |
unusual, it is unlikely you will actually need to raise the setting. |
| 733 |
However it may be useful to set it to 0 for a limited time period to |
| 734 |
prevent BEGIN{} blocks from being executed during an \f(CW\*(C`eval EXPR\*(C'\fR. |
| 735 |
.Sp |
| 736 |
Note that setting this to 1 would NOT affect code like this: |
| 737 |
.Sp |
| 738 |
.Vb 1 |
| 739 |
\& BEGIN { $n += 1; BEGIN { $n += 2; BEGIN { $n += 4 } } } |
| 740 |
.Ve |
| 741 |
.Sp |
| 742 |
The reason is that BEGIN blocks are executed immediately after they are |
| 743 |
completed, thus the innermost will execute before the ones which contain |
| 744 |
it have even finished compiling, and the depth will not go above 1. In |
| 745 |
fact the above code is equivalent to |
| 746 |
.Sp |
| 747 |
.Vb 3 |
| 748 |
\& BEGIN { $n+=4 } |
| 749 |
\& BEGIN { $n+=2 } |
| 750 |
\& BEGIN { $n+=1 } |
| 751 |
.Ve |
| 752 |
.Sp |
| 753 |
which makes it obvious why a ${^MAX_EVAL_BEGIN_DEPTH} of 1 would not |
| 754 |
block this code. |
| 755 |
.Sp |
| 756 |
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 |
| 757 |
\&\f(CW\*(C`use\*(C'\fR) are affected. |
| 758 |
.ie n .IP $OSNAME 8 |
| 759 |
.el .IP \f(CW$OSNAME\fR 8 |
| 760 |
.IX Item "$OSNAME" |
| 761 |
.PD 0 |
| 762 |
.IP $^O 8 |
| 763 |
.IX Xref "$^O $OSNAME" |
| 764 |
.IX Item "$^O" |
| 765 |
.PD |
| 766 |
The name of the operating system under which this copy of Perl was |
| 767 |
built, as determined during the configuration process. For examples |
| 768 |
see "PLATFORMS" in perlport. |
| 769 |
.Sp |
| 770 |
The value is identical to \f(CW$Config{\*(Aqosname\*(Aq}\fR. See also Config |
| 771 |
and the \fB\-V\fR command-line switch documented in perlrun. |
| 772 |
.Sp |
| 773 |
In Windows platforms, \f(CW$^O\fR is not very helpful: since it is always |
| 774 |
\&\f(CW\*(C`MSWin32\*(C'\fR, it doesn't tell the difference between |
| 775 |
95/98/ME/NT/2000/XP/CE/.NET. Use \f(CWWin32::GetOSName()\fR or |
| 776 |
\&\fBWin32::GetOSVersion()\fR (see Win32 and perlport) to distinguish |
| 777 |
between the variants. |
| 778 |
.Sp |
| 779 |
This variable was added in Perl 5.003. |
| 780 |
.ie n .IP %SIG 8 |
| 781 |
.el .IP \f(CW%SIG\fR 8 |
| 782 |
.IX Xref "%SIG" |
| 783 |
.IX Item "%SIG" |
| 784 |
The hash \f(CW%SIG\fR contains signal handlers for signals. For example: |
| 785 |
.Sp |
| 786 |
.Vb 6 |
| 787 |
\& sub handler { # 1st argument is signal name |
| 788 |
\& my($sig) = @_; |
| 789 |
\& print "Caught a SIG$sig\-\-shutting down\en"; |
| 790 |
\& close(LOG); |
| 791 |
\& exit(0); |
| 792 |
\& } |
| 793 |
\& |
| 794 |
\& $SIG{\*(AqINT\*(Aq} = \e&handler; |
| 795 |
\& $SIG{\*(AqQUIT\*(Aq} = \e&handler; |
| 796 |
\& ... |
| 797 |
\& $SIG{\*(AqINT\*(Aq} = \*(AqDEFAULT\*(Aq; # restore default action |
| 798 |
\& $SIG{\*(AqQUIT\*(Aq} = \*(AqIGNORE\*(Aq; # ignore SIGQUIT |
| 799 |
.Ve |
| 800 |
.Sp |
| 801 |
Using a value of \f(CW\*(AqIGNORE\*(Aq\fR usually has the effect of ignoring the |
| 802 |
signal, except for the \f(CW\*(C`CHLD\*(C'\fR signal. See perlipc for more about |
| 803 |
this special case. Using an empty string or \f(CW\*(C`undef\*(C'\fR as the value has |
| 804 |
the same effect as \f(CW\*(AqDEFAULT\*(Aq\fR. |
| 805 |
.Sp |
| 806 |
Here are some other examples: |
| 807 |
.Sp |
| 808 |
.Vb 7 |
| 809 |
\& $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not |
| 810 |
\& # recommended) |
| 811 |
\& $SIG{"PIPE"} = \e&Plumber; # just fine; assume current |
| 812 |
\& # Plumber |
| 813 |
\& $SIG{"PIPE"} = *Plumber; # somewhat esoteric |
| 814 |
\& $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() |
| 815 |
\& # return?? |
| 816 |
.Ve |
| 817 |
.Sp |
| 818 |
Be sure not to use a bareword as the name of a signal handler, |
| 819 |
lest you inadvertently call it. |
| 820 |
.Sp |
| 821 |
Using a string that doesn't correspond to any existing function or a |
| 822 |
glob that doesn't contain a code slot is equivalent to \f(CW\*(AqIGNORE\*(Aq\fR, |
| 823 |
but a warning is emitted when the handler is being called (the warning |
| 824 |
is not emitted for the internal hooks described below). |
| 825 |
.Sp |
| 826 |
If your system has the \f(CWsigaction()\fR function then signal handlers |
| 827 |
are installed using it. This means you get reliable signal handling. |
| 828 |
.Sp |
| 829 |
The default delivery policy of signals changed in Perl v5.8.0 from |
| 830 |
immediate (also known as "unsafe") to deferred, also known as "safe |
| 831 |
signals". See perlipc for more information. |
| 832 |
.Sp |
| 833 |
Certain internal hooks can be also set using the \f(CW%SIG\fR hash. The |
| 834 |
routine indicated by \f(CW$SIG{_\|_WARN_\|_}\fR is called when a warning |
| 835 |
message is about to be printed. The warning message is passed as the |
| 836 |
first argument. The presence of a \f(CW\*(C`_\|_WARN_\|_\*(C'\fR hook causes the |
| 837 |
ordinary printing of warnings to \f(CW\*(C`STDERR\*(C'\fR to be suppressed. You can |
| 838 |
use this to save warnings in a variable, or turn warnings into fatal |
| 839 |
errors, like this: |
| 840 |
.Sp |
| 841 |
.Vb 2 |
| 842 |
\& local $SIG{_\|_WARN_\|_} = sub { die $_[0] }; |
| 843 |
\& eval $proggie; |
| 844 |
.Ve |
| 845 |
.Sp |
| 846 |
As the \f(CW\*(AqIGNORE\*(Aq\fR hook is not supported by \f(CW\*(C`_\|_WARN_\|_\*(C'\fR, its effect is |
| 847 |
the same as using \f(CW\*(AqDEFAULT\*(Aq\fR. You can disable warnings using the |
| 848 |
empty subroutine: |
| 849 |
.Sp |
| 850 |
.Vb 1 |
| 851 |
\& local $SIG{_\|_WARN_\|_} = sub {}; |
| 852 |
.Ve |
| 853 |
.Sp |
| 854 |
The routine indicated by \f(CW$SIG{_\|_DIE_\|_}\fR is called when a fatal |
| 855 |
exception is about to be thrown. The error message is passed as the |
| 856 |
first argument. When a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR hook routine returns, the exception |
| 857 |
processing continues as it would have in the absence of the hook, |
| 858 |
unless the hook routine itself exits via a \f(CW\*(C`goto &sub\*(C'\fR, a loop exit, |
| 859 |
or a \f(CWdie()\fR. The \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler is explicitly disabled during |
| 860 |
the call, so that you can die from a \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler. Similarly |
| 861 |
for \f(CW\*(C`_\|_WARN_\|_\*(C'\fR. |
| 862 |
.Sp |
| 863 |
The \f(CW$SIG{_\|_DIE_\|_}\fR hook is called even inside an \f(CWeval()\fR. It was |
| 864 |
never intended to happen this way, but an implementation glitch made |
| 865 |
this possible. This used to be deprecated, as it allowed strange action |
| 866 |
at a distance like rewriting a pending exception in \f(CW$@\fR. Plans to |
| 867 |
rectify this have been scrapped, as users found that rewriting a |
| 868 |
pending exception is actually a useful feature, and not a bug. |
| 869 |
.Sp |
| 870 |
The \f(CW$SIG{_\|_DIE_\|_}\fR doesn't support \f(CW\*(AqIGNORE\*(Aq\fR; it has the same |
| 871 |
effect as \f(CW\*(AqDEFAULT\*(Aq\fR. |
| 872 |
.Sp |
| 873 |
\&\f(CW\*(C`_\|_DIE_\|_\*(C'\fR/\f(CW\*(C`_\|_WARN_\|_\*(C'\fR handlers are very special in one respect: they |
| 874 |
may be called to report (probable) errors found by the parser. In such |
| 875 |
a case the parser may be in inconsistent state, so any attempt to |
| 876 |
evaluate Perl code from such a handler will probably result in a |
| 877 |
segfault. This means that warnings or errors that result from parsing |
| 878 |
Perl should be used with extreme caution, like this: |
| 879 |
.Sp |
| 880 |
.Vb 5 |
| 881 |
\& require Carp if defined $^S; |
| 882 |
\& Carp::confess("Something wrong") if defined &Carp::confess; |
| 883 |
\& die "Something wrong, but could not load Carp to give " |
| 884 |
\& . "backtrace...\en\et" |
| 885 |
\& . "To see backtrace try starting Perl with \-MCarp switch"; |
| 886 |
.Ve |
| 887 |
.Sp |
| 888 |
Here the first line will load \f(CW\*(C`Carp\*(C'\fR \fIunless\fR it is the parser who |
| 889 |
called the handler. The second line will print backtrace and die if |
| 890 |
\&\f(CW\*(C`Carp\*(C'\fR was available. The third line will be executed only if \f(CW\*(C`Carp\*(C'\fR was |
| 891 |
not available. |
| 892 |
.Sp |
| 893 |
Having to even think about the \f(CW$^S\fR variable in your exception |
| 894 |
handlers is simply wrong. \f(CW$SIG{_\|_DIE_\|_}\fR as currently implemented |
| 895 |
invites grievous and difficult to track down errors. Avoid it |
| 896 |
and use an \f(CW\*(C`END{}\*(C'\fR or CORE::GLOBAL::die override instead. |
| 897 |
.Sp |
| 898 |
See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and |
| 899 |
warnings for additional information. |
| 900 |
.IP %{^HOOK} 8 |
| 901 |
.IX Xref "%{^HOOK}" |
| 902 |
.IX Item "%{^HOOK}" |
| 903 |
This hash contains coderefs which are called when various perl keywords |
| 904 |
which are hard or impossible to wrap are called. The keys of this hash |
| 905 |
are named after the keyword that is being hooked, followed by two |
| 906 |
underbars and then a phase term; either "before" or "after". |
| 907 |
.Sp |
| 908 |
Perl will throw an error if you attempt modify a key which is not |
| 909 |
documented to exist, or if you attempt to store anything other than a |
| 910 |
code reference or undef in the hash. If you wish to use an object to |
| 911 |
implement a hook you can use currying to embed the object into an |
| 912 |
anonymous code reference. |
| 913 |
.Sp |
| 914 |
Currently there is only one keyword which can be hooked, \f(CW\*(C`require\*(C'\fR, but |
| 915 |
it is expected that in future releases there will be additional keywords |
| 916 |
with hook support. |
| 917 |
.RS 8 |
| 918 |
.IP require_\|_before 4 |
| 919 |
.IX Item "require__before" |
| 920 |
The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_before}\*(C'\fR is called by |
| 921 |
\&\f(CW\*(C`require\*(C'\fR \fBbefore\fR it checks \f(CW%INC\fR, looks up \f(CW@INC\fR, calls INC |
| 922 |
hooks, or compiles any code. It is called with a single argument, the |
| 923 |
filename for the item being required (package names are converted to |
| 924 |
paths). It may alter this filename to change what file is loaded. If |
| 925 |
the hook dies during execution then it will block the require from executing. |
| 926 |
.Sp |
| 927 |
In order to make it easy to perform an action with shared state both |
| 928 |
before and after the require keyword was executed the \f(CW\*(C`require_\|_before\*(C'\fR |
| 929 |
hook may return a "post-action" coderef which will in turn be executed when |
| 930 |
the \f(CW\*(C`require\*(C'\fR completes. This coderef will be executed regardless as to |
| 931 |
whether the require completed succesfully or threw an exception. It will |
| 932 |
be called with the filename that was required. You can check \f(CW%INC\fR to |
| 933 |
determine if the require was successful. Any other return from the |
| 934 |
\&\f(CW\*(C`require_\|_before\*(C'\fR hook will be silently ignored. |
| 935 |
.Sp |
| 936 |
\&\f(CW\*(C`require_\|_before\*(C'\fR hooks are called in FIFO order, and if the hook |
| 937 |
returns a code reference those code references will be called in FILO |
| 938 |
order. In other words if A requires B requires C, then |
| 939 |
\&\f(CW\*(C`require_\|_before\*(C'\fR will be called first for A, then B and then C, and |
| 940 |
the post-action code reference will executed first for C, then B and |
| 941 |
then finally A. |
| 942 |
.Sp |
| 943 |
Well behaved code should ensure that when setting up a |
| 944 |
\&\f(CW\*(C`require_\|_before\*(C'\fR hook that any prior installed hook will be called, |
| 945 |
and that their return value, if a code reference, will be called as |
| 946 |
well. See "require" in perlfunc for an example implementation. |
| 947 |
.IP require_\|_after 4 |
| 948 |
.IX Item "require__after" |
| 949 |
The routine indicated by \f(CW\*(C`${^HOOK}{require_\|_after}\*(C'\fR is called by |
| 950 |
\&\f(CW\*(C`require\*(C'\fR \fBafter\fR the require completes. It is called with a single |
| 951 |
argument, the filename for the item being required (package names are |
| 952 |
converted to paths). It is executed when the \f(CW\*(C`require\*(C'\fR completes, |
| 953 |
either via exception or via completion of the require statement, and you |
| 954 |
can check \f(CW%INC\fR to determine if the require was successful. |
| 955 |
.Sp |
| 956 |
The \f(CW\*(C`require_\|_after\*(C'\fR hook is called for each required file in FILO |
| 957 |
order. In other words if A requires B requires C, then \f(CW\*(C`require_\|_after\*(C'\fR |
| 958 |
will be called first for C, then B and then A. |
| 959 |
.RE |
| 960 |
.RS 8 |
| 961 |
.RE |
| 962 |
.ie n .IP $BASETIME 8 |
| 963 |
.el .IP \f(CW$BASETIME\fR 8 |
| 964 |
.IX Item "$BASETIME" |
| 965 |
.PD 0 |
| 966 |
.IP $^T 8 |
| 967 |
.IX Xref "$^T $BASETIME" |
| 968 |
.IX Item "$^T" |
| 969 |
.PD |
| 970 |
The time at which the program began running, in seconds since the |
| 971 |
epoch (beginning of 1970). The values returned by the \fB\-M\fR, \fB\-A\fR, |
| 972 |
and \fB\-C\fR filetests are based on this value. |
| 973 |
.ie n .IP $PERL_VERSION 8 |
| 974 |
.el .IP \f(CW$PERL_VERSION\fR 8 |
| 975 |
.IX Item "$PERL_VERSION" |
| 976 |
.PD 0 |
| 977 |
.IP $^V 8 |
| 978 |
.IX Xref "$^V $PERL_VERSION" |
| 979 |
.IX Item "$^V" |
| 980 |
.PD |
| 981 |
The revision, version, and subversion of the Perl interpreter, |
| 982 |
represented as a version object. |
| 983 |
.Sp |
| 984 |
This variable first appeared in perl v5.6.0; earlier versions of perl |
| 985 |
will see an undefined value. Before perl v5.10.0 \f(CW$^V\fR was represented |
| 986 |
as a v\-string rather than a version object. |
| 987 |
.Sp |
| 988 |
\&\f(CW$^V\fR can be used to determine whether the Perl interpreter executing |
| 989 |
a script is in the right range of versions. For example: |
| 990 |
.Sp |
| 991 |
.Vb 1 |
| 992 |
\& warn "Hashes not randomized!\en" if !$^V or $^V lt v5.8.1 |
| 993 |
.Ve |
| 994 |
.Sp |
| 995 |
While version objects overload stringification, to portably convert |
| 996 |
\&\f(CW$^V\fR into its string representation, use \f(CWsprintf()\fR's \f(CW"%vd"\fR |
| 997 |
conversion, which works for both v\-strings or version objects: |
| 998 |
.Sp |
| 999 |
.Vb 1 |
| 1000 |
\& printf "version is v%vd\en", $^V; # Perl\*(Aqs version |
| 1001 |
.Ve |
| 1002 |
.Sp |
| 1003 |
See the documentation of \f(CW\*(C`use VERSION\*(C'\fR and \f(CW\*(C`require VERSION\*(C'\fR |
| 1004 |
for a convenient way to fail if the running Perl interpreter is too old. |
| 1005 |
.Sp |
| 1006 |
See also \f(CW"$]"\fR for a decimal representation of the Perl version. |
| 1007 |
.Sp |
| 1008 |
The main advantage of \f(CW$^V\fR over \f(CW$]\fR is that, for Perl v5.10.0 or |
| 1009 |
later, it overloads operators, allowing easy comparison against other |
| 1010 |
version representations (e.g. decimal, literal v\-string, "v1.2.3", or |
| 1011 |
objects). The disadvantage is that prior to v5.10.0, it was only a |
| 1012 |
literal v\-string, which can't be easily printed or compared, whereas |
| 1013 |
the behavior of \f(CW$]\fR is unchanged on all versions of Perl. |
| 1014 |
.Sp |
| 1015 |
Mnemonic: use ^V for a version object. |
| 1016 |
.ie n .IP $EXECUTABLE_NAME 8 |
| 1017 |
.el .IP \f(CW$EXECUTABLE_NAME\fR 8 |
| 1018 |
.IX Item "$EXECUTABLE_NAME" |
| 1019 |
.PD 0 |
| 1020 |
.IP $^X 8 |
| 1021 |
.IX Xref "$^X $EXECUTABLE_NAME" |
| 1022 |
.IX Item "$^X" |
| 1023 |
.PD |
| 1024 |
The name used to execute the current copy of Perl, from C's |
| 1025 |
\&\f(CW\*(C`argv[0]\*(C'\fR or (where supported) \fI/proc/self/exe\fR. |
| 1026 |
.Sp |
| 1027 |
Depending on the host operating system, the value of \f(CW$^X\fR may be |
| 1028 |
a relative or absolute pathname of the perl program file, or may |
| 1029 |
be the string used to invoke perl but not the pathname of the |
| 1030 |
perl program file. Also, most operating systems permit invoking |
| 1031 |
programs that are not in the PATH environment variable, so there |
| 1032 |
is no guarantee that the value of \f(CW$^X\fR is in PATH. For VMS, the |
| 1033 |
value may or may not include a version number. |
| 1034 |
.Sp |
| 1035 |
You usually can use the value of \f(CW$^X\fR to re-invoke an independent |
| 1036 |
copy of the same perl that is currently running, e.g., |
| 1037 |
.Sp |
| 1038 |
.Vb 1 |
| 1039 |
\& @first_run = \`$^X \-le "print int rand 100 for 1..100"\`; |
| 1040 |
.Ve |
| 1041 |
.Sp |
| 1042 |
But recall that not all operating systems support forking or |
| 1043 |
capturing of the output of commands, so this complex statement |
| 1044 |
may not be portable. |
| 1045 |
.Sp |
| 1046 |
It is not safe to use the value of \f(CW$^X\fR as a path name of a file, |
| 1047 |
as some operating systems that have a mandatory suffix on |
| 1048 |
executable files do not require use of the suffix when invoking |
| 1049 |
a command. To convert the value of \f(CW$^X\fR to a path name, use the |
| 1050 |
following statements: |
| 1051 |
.Sp |
| 1052 |
.Vb 7 |
| 1053 |
\& # Build up a set of file names (not command names). |
| 1054 |
\& use Config; |
| 1055 |
\& my $this_perl = $^X; |
| 1056 |
\& if ($^O ne \*(AqVMS\*(Aq) { |
| 1057 |
\& $this_perl .= $Config{_exe} |
| 1058 |
\& unless $this_perl =~ m/$Config{_exe}$/i; |
| 1059 |
\& } |
| 1060 |
.Ve |
| 1061 |
.Sp |
| 1062 |
Because many operating systems permit anyone with read access to |
| 1063 |
the Perl program file to make a copy of it, patch the copy, and |
| 1064 |
then execute the copy, the security-conscious Perl programmer |
| 1065 |
should take care to invoke the installed copy of perl, not the |
| 1066 |
copy referenced by \f(CW$^X\fR. The following statements accomplish |
| 1067 |
this goal, and produce a pathname that can be invoked as a |
| 1068 |
command or referenced as a file. |
| 1069 |
.Sp |
| 1070 |
.Vb 6 |
| 1071 |
\& use Config; |
| 1072 |
\& my $secure_perl_path = $Config{perlpath}; |
| 1073 |
\& if ($^O ne \*(AqVMS\*(Aq) { |
| 1074 |
\& $secure_perl_path .= $Config{_exe} |
| 1075 |
\& unless $secure_perl_path =~ m/$Config{_exe}$/i; |
| 1076 |
\& } |
| 1077 |
.Ve |
| 1078 |
.SS "Variables related to regular expressions" |
| 1079 |
.IX Subsection "Variables related to regular expressions" |
| 1080 |
Most of the special variables related to regular expressions are side |
| 1081 |
effects. Perl sets these variables when it has completed a match |
| 1082 |
successfully, so you should check the match result before using them. |
| 1083 |
For instance: |
| 1084 |
.PP |
| 1085 |
.Vb 3 |
| 1086 |
\& if( /P(A)TT(ER)N/ ) { |
| 1087 |
\& print "I found $1 and $2\en"; |
| 1088 |
\& } |
| 1089 |
.Ve |
| 1090 |
.PP |
| 1091 |
These variables are read-only and behave similarly to a dynamically |
| 1092 |
scoped variable, with only a few exceptions which are explicitly |
| 1093 |
documented as behaving otherwise. See the following section for more |
| 1094 |
details. |
| 1095 |
.PP |
| 1096 |
\fIScoping Rules of Regex Variables\fR |
| 1097 |
.IX Xref "Scoping Rules of Regex Variables" |
| 1098 |
.IX Subsection "Scoping Rules of Regex Variables" |
| 1099 |
.PP |
| 1100 |
Regular expression variables allow the programmer to access the state of |
| 1101 |
the most recent \fIsuccessful\fR regex match in the current dynamic scope. |
| 1102 |
.PP |
| 1103 |
The variables themselves are global and unscoped, but the data they |
| 1104 |
access is scoped similarly to dynamically scoped variables, in that |
| 1105 |
every successful match behaves as though it localizes a global state |
| 1106 |
object to the current block or file scope. |
| 1107 |
(See "Compound Statements" in perlsyn for more details on dynamic |
| 1108 |
scoping and the \f(CW\*(C`local\*(C'\fR keyword.) |
| 1109 |
.PP |
| 1110 |
A \fIsuccessful match\fR includes any successful match performed by the |
| 1111 |
search and replace operator \f(CW\*(C`s///\*(C'\fR as well as those performed by the |
| 1112 |
\&\f(CW\*(C`m//\*(C'\fR operator. |
| 1113 |
.PP |
| 1114 |
Consider the following code: |
| 1115 |
.PP |
| 1116 |
.Vb 7 |
| 1117 |
\& my @state; |
| 1118 |
\& sub matchit { |
| 1119 |
\& push @state, $1; # pushes "baz" |
| 1120 |
\& my $str = shift; |
| 1121 |
\& $str =~ /(zat)/; # matches "zat" |
| 1122 |
\& push @state, $1; # pushes "zat" |
| 1123 |
\& } |
| 1124 |
\& |
| 1125 |
\& { |
| 1126 |
\& $str = "foo bar baz blorp zat"; |
| 1127 |
\& $str =~ /(foo)/; # matches "foo" |
| 1128 |
\& push @state, $1; # pushes "foo" |
| 1129 |
\& { |
| 1130 |
\& $str =~ /(pizza)/; # does NOT match |
| 1131 |
\& push @state, $1; # pushes "foo" |
| 1132 |
\& $str =~ /(bar)/; # matches "bar" |
| 1133 |
\& push @state, $1; # pushes "bar" |
| 1134 |
\& $str =~ /(baz)/; # matches "baz" |
| 1135 |
\& matchit($str); # see above |
| 1136 |
\& push @state, $1; # pushes "baz" |
| 1137 |
\& } |
| 1138 |
\& $str =~ s/noodles/rice/; # does NOT match |
| 1139 |
\& push @state, $1; # pushes "foo" |
| 1140 |
\& $str =~ s/(blorp)/zwoop/; # matches "blorp" |
| 1141 |
\& push @state, $1; # pushes "blorp" |
| 1142 |
\& } |
| 1143 |
\& # the following prints "foo, foo, bar, baz, zat, baz, foo, blorp" |
| 1144 |
\& print join ",", @state; |
| 1145 |
.Ve |
| 1146 |
.PP |
| 1147 |
Notice that each successful match in the exact same scope overrides the |
| 1148 |
match context of the previous successful match, but that unsuccessful |
| 1149 |
matches do not. Also note that in an inner nested scope the previous |
| 1150 |
state from an outer dynamic scope persists until it has been overriden |
| 1151 |
by another successful match, but that when the inner nested scope exits |
| 1152 |
whatever match context was in effect before the inner successful match |
| 1153 |
is restored when the scope concludes. |
| 1154 |
.PP |
| 1155 |
It is a known issue that \f(CW\*(C`goto LABEL\*(C'\fR may interact poorly with the |
| 1156 |
dynamically scoped match context. This may not be fixable, and is |
| 1157 |
considered to be one of many good reasons to avoid \f(CW\*(C`goto LABEL\*(C'\fR. |
| 1158 |
.PP |
| 1159 |
\fIPerformance issues\fR |
| 1160 |
.IX Subsection "Performance issues" |
| 1161 |
.PP |
| 1162 |
Traditionally in Perl, any use of any of the three variables \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR |
| 1163 |
or \f(CW\*(C`$\*(Aq\*(C'\fR (or their \f(CW\*(C`use English\*(C'\fR equivalents) anywhere in the code, caused |
| 1164 |
all subsequent successful pattern matches to make a copy of the matched |
| 1165 |
string, in case the code might subsequently access one of those variables. |
| 1166 |
This imposed a considerable performance penalty across the whole program, |
| 1167 |
so generally the use of these variables has been discouraged. |
| 1168 |
.PP |
| 1169 |
In Perl 5.6.0 the \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR dynamic arrays were introduced that |
| 1170 |
supply the indices of successful matches. So you could for example do |
| 1171 |
this: |
| 1172 |
.PP |
| 1173 |
.Vb 1 |
| 1174 |
\& $str =~ /pattern/; |
| 1175 |
\& |
| 1176 |
\& print $\`, $&, $\*(Aq; # bad: performance hit |
| 1177 |
\& |
| 1178 |
\& print # good: no performance hit |
| 1179 |
\& substr($str, 0, $\-[0]), |
| 1180 |
\& substr($str, $\-[0], $+[0]\-$\-[0]), |
| 1181 |
\& substr($str, $+[0]); |
| 1182 |
.Ve |
| 1183 |
.PP |
| 1184 |
In Perl 5.10.0 the \f(CW\*(C`/p\*(C'\fR match operator flag and the \f(CW\*(C`${^PREMATCH}\*(C'\fR, |
| 1185 |
\&\f(CW\*(C`${^MATCH}\*(C'\fR, and \f(CW\*(C`${^POSTMATCH}\*(C'\fR variables were introduced, that allowed |
| 1186 |
you to suffer the penalties only on patterns marked with \f(CW\*(C`/p\*(C'\fR. |
| 1187 |
.PP |
| 1188 |
In Perl 5.18.0 onwards, perl started noting the presence of each of the |
| 1189 |
three variables separately, and only copied that part of the string |
| 1190 |
required; so in |
| 1191 |
.PP |
| 1192 |
.Vb 1 |
| 1193 |
\& $\`; $&; "abcdefgh" =~ /d/ |
| 1194 |
.Ve |
| 1195 |
.PP |
| 1196 |
perl would only copy the "abcd" part of the string. That could make a big |
| 1197 |
difference in something like |
| 1198 |
.PP |
| 1199 |
.Vb 3 |
| 1200 |
\& $str = \*(Aqx\*(Aq x 1_000_000; |
| 1201 |
\& $&; # whoops |
| 1202 |
\& $str =~ /x/g # one char copied a million times, not a million chars |
| 1203 |
.Ve |
| 1204 |
.PP |
| 1205 |
In Perl 5.20.0 a new copy-on-write system was enabled by default, which |
| 1206 |
finally fixes most of the performance issues with these three variables, and |
| 1207 |
makes them safe to use anywhere. |
| 1208 |
.PP |
| 1209 |
The \f(CW\*(C`Devel::NYTProf\*(C'\fR and \f(CW\*(C`Devel::FindAmpersand\*(C'\fR modules can help you |
| 1210 |
find uses of these problematic match variables in your code. |
| 1211 |
.ie n .IP "$<\fIdigits\fR> ($1, $2, ...)" 8 |
| 1212 |
.el .IP "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)" 8 |
| 1213 |
.IX Xref "$1 $2 $3 $\\f(ISdigits\\f(IE" |
| 1214 |
.IX Item "$<digits> ($1, $2, ...)" |
| 1215 |
Contains the subpattern from the corresponding set of capturing |
| 1216 |
parentheses from the last successful pattern match in the current |
| 1217 |
dynamic scope. (See "Scoping Rules of Regex Variables".) |
| 1218 |
.Sp |
| 1219 |
Note there is a distinction between a capture buffer which matches |
| 1220 |
the empty string a capture buffer which is optional. Eg, \f(CW\*(C`(x?)\*(C'\fR and |
| 1221 |
\&\f(CW\*(C`(x)?\*(C'\fR The latter may be undef, the former not. |
| 1222 |
.Sp |
| 1223 |
These variables are read-only. |
| 1224 |
.Sp |
| 1225 |
Mnemonic: like \edigits. |
| 1226 |
.IP @{^CAPTURE} 8 |
| 1227 |
.IX Xref "@{^CAPTURE} @^CAPTURE" |
| 1228 |
.IX Item "@{^CAPTURE}" |
| 1229 |
An array which exposes the contents of the capture buffers, if any, of |
| 1230 |
the last successful pattern match, not counting patterns matched |
| 1231 |
in nested blocks that have been exited already. |
| 1232 |
.Sp |
| 1233 |
Note that the 0 index of \f(CW\*(C`@{^CAPTURE}\*(C'\fR is equivalent to \f(CW$1\fR, the 1 index |
| 1234 |
is equivalent to \f(CW$2\fR, etc. |
| 1235 |
.Sp |
| 1236 |
.Vb 3 |
| 1237 |
\& if ("foal"=~/(.)(.)(.)(.)/) { |
| 1238 |
\& print join "\-", @{^CAPTURE}; |
| 1239 |
\& } |
| 1240 |
.Ve |
| 1241 |
.Sp |
| 1242 |
should output "f\-o-a-l". |
| 1243 |
.Sp |
| 1244 |
See also "$<\fIdigits\fR> ($1, \f(CW$2\fR, ...)", "%{^CAPTURE}" and |
| 1245 |
"%{^CAPTURE_ALL}". |
| 1246 |
.Sp |
| 1247 |
Note that unlike most other regex magic variables there is no single |
| 1248 |
letter equivalent to \f(CW\*(C`@{^CAPTURE}\*(C'\fR. Also be aware that when |
| 1249 |
interpolating subscripts of this array you \fBmust\fR use the demarcated |
| 1250 |
variable form, for instance |
| 1251 |
.Sp |
| 1252 |
.Vb 1 |
| 1253 |
\& print "${^CAPTURE[0]}" |
| 1254 |
.Ve |
| 1255 |
.Sp |
| 1256 |
see "Demarcated variable names using braces" in perldata for more |
| 1257 |
information on this form and its uses. |
| 1258 |
.Sp |
| 1259 |
This variable was added in 5.25.7 |
| 1260 |
.Sp |
| 1261 |
If you need access to this functionality in older Perls you can use this |
| 1262 |
function immediately after your regexp. |
| 1263 |
.Sp |
| 1264 |
.Vb 2 |
| 1265 |
\& sub get_captures { |
| 1266 |
\& no strict \*(Aqrefs\*(Aq; |
| 1267 |
\& |
| 1268 |
\& my $last_idx = scalar(@\-) \- 1; |
| 1269 |
\& my @arr = 1 .. $last_idx; |
| 1270 |
\& my @ret = map { $$_; } @arr; |
| 1271 |
\& |
| 1272 |
\& return @ret; |
| 1273 |
\& } |
| 1274 |
.Ve |
| 1275 |
.ie n .IP $MATCH 8 |
| 1276 |
.el .IP \f(CW$MATCH\fR 8 |
| 1277 |
.IX Item "$MATCH" |
| 1278 |
.PD 0 |
| 1279 |
.IP $& 8 |
| 1280 |
.IX Xref "$& $MATCH" |
| 1281 |
.PD |
| 1282 |
The string matched by the last successful pattern match. |
| 1283 |
(See "Scoping Rules of Regex Variables".) |
| 1284 |
.Sp |
| 1285 |
See "Performance issues" above for the serious performance implications |
| 1286 |
of using this variable (even once) in your code. |
| 1287 |
.Sp |
| 1288 |
This variable is read-only, and its value is dynamically scoped. |
| 1289 |
.Sp |
| 1290 |
Mnemonic: like \f(CW\*(C`&\*(C'\fR in some editors. |
| 1291 |
.IP ${^MATCH} 8 |
| 1292 |
.IX Xref "${^MATCH}" |
| 1293 |
.IX Item "${^MATCH}" |
| 1294 |
It is only guaranteed to return a defined value when the pattern was |
| 1295 |
compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier. |
| 1296 |
.Sp |
| 1297 |
This is similar to \f(CW$&\fR (\f(CW$MATCH\fR) except that to use it you must |
| 1298 |
use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur |
| 1299 |
the performance penalty associated with that variable. |
| 1300 |
.Sp |
| 1301 |
See "Performance issues" above. |
| 1302 |
.Sp |
| 1303 |
This variable was added in Perl v5.10.0. |
| 1304 |
.Sp |
| 1305 |
This variable is read-only, and its value is dynamically scoped. |
| 1306 |
.ie n .IP $PREMATCH 8 |
| 1307 |
.el .IP \f(CW$PREMATCH\fR 8 |
| 1308 |
.IX Item "$PREMATCH" |
| 1309 |
.PD 0 |
| 1310 |
.IP $` 8 |
| 1311 |
.IX Xref "$` $PREMATCH" |
| 1312 |
.PD |
| 1313 |
The string preceding whatever was matched by the last successful |
| 1314 |
pattern match. (See "Scoping Rules of Regex Variables"). |
| 1315 |
.Sp |
| 1316 |
See "Performance issues" above for the serious performance implications |
| 1317 |
of using this variable (even once) in your code. |
| 1318 |
.Sp |
| 1319 |
This variable is read-only, and its value is dynamically scoped. |
| 1320 |
.Sp |
| 1321 |
Mnemonic: \f(CW\*(C`\`\*(C'\fR often precedes a quoted string. |
| 1322 |
.IP ${^PREMATCH} 8 |
| 1323 |
.IX Xref "${^PREMATCH}" |
| 1324 |
.IX Item "${^PREMATCH}" |
| 1325 |
It is only guaranteed to return a defined value when the pattern was |
| 1326 |
executed with the \f(CW\*(C`/p\*(C'\fR modifier. |
| 1327 |
.Sp |
| 1328 |
This is similar to \f(CW\*(C`$\`\*(C'\fR ($PREMATCH) except that to use it you must |
| 1329 |
use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur |
| 1330 |
the performance penalty associated with that variable. |
| 1331 |
.Sp |
| 1332 |
See "Performance issues" above. |
| 1333 |
.Sp |
| 1334 |
This variable was added in Perl v5.10.0. |
| 1335 |
.Sp |
| 1336 |
This variable is read-only, and its value is dynamically scoped. |
| 1337 |
.ie n .IP $POSTMATCH 8 |
| 1338 |
.el .IP \f(CW$POSTMATCH\fR 8 |
| 1339 |
.IX Item "$POSTMATCH" |
| 1340 |
.PD 0 |
| 1341 |
.IP $' 8 |
| 1342 |
.IX Xref "$' $POSTMATCH @-" |
| 1343 |
.PD |
| 1344 |
The string following whatever was matched by the last successful |
| 1345 |
pattern match. (See "Scoping Rules of Regex Variables"). Example: |
| 1346 |
.Sp |
| 1347 |
.Vb 3 |
| 1348 |
\& local $_ = \*(Aqabcdefghi\*(Aq; |
| 1349 |
\& /def/; |
| 1350 |
\& print "$\`:$&:$\*(Aq\en"; # prints abc:def:ghi |
| 1351 |
.Ve |
| 1352 |
.Sp |
| 1353 |
See "Performance issues" above for the serious performance implications |
| 1354 |
of using this variable (even once) in your code. |
| 1355 |
.Sp |
| 1356 |
This variable is read-only, and its value is dynamically scoped. |
| 1357 |
.Sp |
| 1358 |
Mnemonic: \f(CW\*(C`\*(Aq\*(C'\fR often follows a quoted string. |
| 1359 |
.IP ${^POSTMATCH} 8 |
| 1360 |
.IX Xref "${^POSTMATCH}" |
| 1361 |
.IX Item "${^POSTMATCH}" |
| 1362 |
It is only guaranteed to return a defined value when the pattern was |
| 1363 |
compiled or executed with the \f(CW\*(C`/p\*(C'\fR modifier. |
| 1364 |
.Sp |
| 1365 |
This is similar to \f(CW\*(C`$\*(Aq\*(C'\fR (\f(CW$POSTMATCH\fR) except that to use it you must |
| 1366 |
use the \f(CW\*(C`/p\*(C'\fR modifier when executing the pattern, and it does not incur |
| 1367 |
the performance penalty associated with that variable. |
| 1368 |
.Sp |
| 1369 |
See "Performance issues" above. |
| 1370 |
.Sp |
| 1371 |
This variable was added in Perl v5.10.0. |
| 1372 |
.Sp |
| 1373 |
This variable is read-only, and its value is dynamically scoped. |
| 1374 |
.ie n .IP $LAST_PAREN_MATCH 8 |
| 1375 |
.el .IP \f(CW$LAST_PAREN_MATCH\fR 8 |
| 1376 |
.IX Item "$LAST_PAREN_MATCH" |
| 1377 |
.PD 0 |
| 1378 |
.IP $+ 8 |
| 1379 |
.IX Xref "$+ $LAST_PAREN_MATCH" |
| 1380 |
.PD |
| 1381 |
The text matched by the highest used capture group of the last |
| 1382 |
successful search pattern. (See "Scoping Rules of Regex Variables"). |
| 1383 |
It is logically equivalent to the highest |
| 1384 |
numbered capture variable (\f(CW$1\fR, \f(CW$2\fR, ...) which has a defined value. |
| 1385 |
.Sp |
| 1386 |
This is useful if you don't know which one of a set of alternative patterns |
| 1387 |
matched. For example: |
| 1388 |
.Sp |
| 1389 |
.Vb 1 |
| 1390 |
\& /Version: (.*)|Revision: (.*)/ && ($rev = $+); |
| 1391 |
.Ve |
| 1392 |
.Sp |
| 1393 |
This variable is read-only, and its value is dynamically scoped. |
| 1394 |
.Sp |
| 1395 |
Mnemonic: be positive and forward looking. |
| 1396 |
.ie n .IP $LAST_SUBMATCH_RESULT 8 |
| 1397 |
.el .IP \f(CW$LAST_SUBMATCH_RESULT\fR 8 |
| 1398 |
.IX Item "$LAST_SUBMATCH_RESULT" |
| 1399 |
.PD 0 |
| 1400 |
.IP $^N 8 |
| 1401 |
.IX Xref "$^N $LAST_SUBMATCH_RESULT" |
| 1402 |
.IX Item "$^N" |
| 1403 |
.PD |
| 1404 |
The text matched by the used group most-recently closed (i.e. the group |
| 1405 |
with the rightmost closing parenthesis) of the last successful match. |
| 1406 |
(See "Scoping Rules of Regex Variables"). |
| 1407 |
.Sp |
| 1408 |
This is subtly different from \f(CW$+\fR. For example in |
| 1409 |
.Sp |
| 1410 |
.Vb 1 |
| 1411 |
\& "ab" =~ /^((.)(.))$/ |
| 1412 |
.Ve |
| 1413 |
.Sp |
| 1414 |
we have |
| 1415 |
.Sp |
| 1416 |
.Vb 3 |
| 1417 |
\& $1,$^N have the value "ab" |
| 1418 |
\& $2 has the value "a" |
| 1419 |
\& $3,$+ have the value "b" |
| 1420 |
.Ve |
| 1421 |
.Sp |
| 1422 |
This is primarily used inside \f(CW\*(C`(?{...})\*(C'\fR blocks for examining text |
| 1423 |
recently matched. For example, to effectively capture text to a variable |
| 1424 |
(in addition to \f(CW$1\fR, \f(CW$2\fR, etc.), replace \f(CW\*(C`(...)\*(C'\fR with |
| 1425 |
.Sp |
| 1426 |
.Vb 1 |
| 1427 |
\& (?:(...)(?{ $var = $^N })) |
| 1428 |
.Ve |
| 1429 |
.Sp |
| 1430 |
By setting and then using \f(CW$var\fR in this way relieves you from having to |
| 1431 |
worry about exactly which numbered set of parentheses they are. |
| 1432 |
.Sp |
| 1433 |
This variable is read-only, and its value is dynamically scoped. |
| 1434 |
.Sp |
| 1435 |
This variable was added in Perl v5.8.0. |
| 1436 |
.Sp |
| 1437 |
Mnemonic: the (possibly) Nested parenthesis that most recently closed. |
| 1438 |
.ie n .IP @LAST_MATCH_END 8 |
| 1439 |
.el .IP \f(CW@LAST_MATCH_END\fR 8 |
| 1440 |
.IX Item "@LAST_MATCH_END" |
| 1441 |
.PD 0 |
| 1442 |
.IP @+ 8 |
| 1443 |
.IX Xref "@+ @LAST_MATCH_END" |
| 1444 |
.PD |
| 1445 |
This array holds the offsets of the ends of the last successful |
| 1446 |
match and any matching capture buffers that the pattern contains. |
| 1447 |
(See "Scoping Rules of Regex Variables") |
| 1448 |
.Sp |
| 1449 |
The number of elements it contains will be one more than the number |
| 1450 |
of capture buffers in the pattern, regardless of which capture buffers |
| 1451 |
actually matched. You can use this to determine how many capture |
| 1452 |
buffers there are in the pattern. (As opposed to \f(CW\*(C`@\-\*(C'\fR which may |
| 1453 |
have fewer elements.) |
| 1454 |
.Sp |
| 1455 |
\&\f(CW$+[0]\fR is the offset into the string of the end of the entire match. |
| 1456 |
This is the same value as what the \f(CW\*(C`pos\*(C'\fR function returns when called |
| 1457 |
on the variable that was matched against. The \fIn\fRth element of this |
| 1458 |
array holds the offset of the \fIn\fRth submatch, so \f(CW$+[1]\fR is the offset |
| 1459 |
past where \f(CW$1\fR ends, \f(CW$+[2]\fR the offset past where \f(CW$2\fR ends, and so |
| 1460 |
on. You can use \f(CW$#+\fR to determine how many subgroups were in the last |
| 1461 |
successful match. See the examples given for the \f(CW\*(C`@\-\*(C'\fR variable. |
| 1462 |
.Sp |
| 1463 |
This variable is read-only, and its value is dynamically scoped. |
| 1464 |
.Sp |
| 1465 |
This variable was added in Perl v5.6.0. |
| 1466 |
.IP %{^CAPTURE} 8 |
| 1467 |
.IX Item "%{^CAPTURE}" |
| 1468 |
.PD 0 |
| 1469 |
.ie n .IP %LAST_PAREN_MATCH 8 |
| 1470 |
.el .IP \f(CW%LAST_PAREN_MATCH\fR 8 |
| 1471 |
.IX Item "%LAST_PAREN_MATCH" |
| 1472 |
.IP %+ 8 |
| 1473 |
.IX Xref "%+ %LAST_PAREN_MATCH %{^CAPTURE}" |
| 1474 |
.PD |
| 1475 |
Similar to \f(CW\*(C`@+\*(C'\fR, the \f(CW\*(C`%+\*(C'\fR hash allows access to the named capture |
| 1476 |
buffers, should they exist, in the last successful match in the |
| 1477 |
currently active dynamic scope. (See "Scoping Rules of Regex Variables"). |
| 1478 |
.Sp |
| 1479 |
For example, \f(CW$+{foo}\fR is equivalent to \f(CW$1\fR after the following match: |
| 1480 |
.Sp |
| 1481 |
.Vb 1 |
| 1482 |
\& \*(Aqfoo\*(Aq =~ /(?<foo>foo)/; |
| 1483 |
.Ve |
| 1484 |
.Sp |
| 1485 |
The keys of the \f(CW\*(C`%+\*(C'\fR hash list only the names of buffers that have |
| 1486 |
captured (and that are thus associated to defined values). |
| 1487 |
.Sp |
| 1488 |
If multiple distinct capture groups have the same name, then |
| 1489 |
\&\f(CW$+{NAME}\fR will refer to the leftmost defined group in the match. |
| 1490 |
.Sp |
| 1491 |
The underlying behaviour of \f(CW\*(C`%+\*(C'\fR is provided by the |
| 1492 |
Tie::Hash::NamedCapture module. |
| 1493 |
.Sp |
| 1494 |
\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash |
| 1495 |
associated with the last successful regular expression. Therefore mixing |
| 1496 |
iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results. |
| 1497 |
Likewise, if the last successful match changes, then the results may be |
| 1498 |
surprising. |
| 1499 |
.Sp |
| 1500 |
This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE}\*(C'\fR alias was |
| 1501 |
added in 5.25.7. |
| 1502 |
.Sp |
| 1503 |
This variable is read-only, and its value is dynamically scoped. |
| 1504 |
.ie n .IP @LAST_MATCH_START 8 |
| 1505 |
.el .IP \f(CW@LAST_MATCH_START\fR 8 |
| 1506 |
.IX Item "@LAST_MATCH_START" |
| 1507 |
.PD 0 |
| 1508 |
.IP @\- 8 |
| 1509 |
.IX Xref "@- @LAST_MATCH_START" |
| 1510 |
.PD |
| 1511 |
This array holds the offsets of the beginnings of the last successful |
| 1512 |
match and any capture buffers it contains. |
| 1513 |
(See "Scoping Rules of Regex Variables"). |
| 1514 |
.Sp |
| 1515 |
The number of elements it contains will be one more than the number of |
| 1516 |
the highest capture buffers (also called a subgroup) that actually |
| 1517 |
matched something. (As opposed to \f(CW\*(C`@+\*(C'\fR which may have more elements.) |
| 1518 |
.Sp |
| 1519 |
\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset of the start of the last successful match. |
| 1520 |
\&\f(CW\*(C`$\-[\fR\f(CIn\fR\f(CW]\*(C'\fR is the offset of the start of the substring matched by |
| 1521 |
\&\fIn\fR\-th subpattern, or undef if the subpattern did not match. |
| 1522 |
.Sp |
| 1523 |
Thus, after a match against \f(CW$_\fR, \f(CW$&\fR coincides with |
| 1524 |
\&\f(CW\*(C`substr $_, $\-[0], $+[0] \- $\-[0]\*(C'\fR. Similarly, \f(CW\*(C`$\fR\f(CIn\fR\f(CW\*(C'\fR coincides |
| 1525 |
with \f(CW\*(C`substr $_, $\-[n], $+[n] \- $\-[n]\*(C'\fR if \f(CW\*(C`$\-[n]\*(C'\fR is defined, and |
| 1526 |
\&\f(CW$+\fR coincides with \f(CW\*(C`substr $_, $\-[$#\-], $+[$#\-] \- $\-[$#\-]\*(C'\fR. |
| 1527 |
One can use \f(CW\*(C`$#\-\*(C'\fR to find the last matched subgroup in the last |
| 1528 |
successful match. Contrast with \f(CW$#+\fR, the number of subgroups |
| 1529 |
in the regular expression. |
| 1530 |
.Sp |
| 1531 |
\&\f(CW\*(C`$\-[0]\*(C'\fR is the offset into the string of the beginning of the |
| 1532 |
entire match. The \fIn\fRth element of this array holds the offset |
| 1533 |
of the \fIn\fRth submatch, so \f(CW\*(C`$\-[1]\*(C'\fR is the offset where \f(CW$1\fR |
| 1534 |
begins, \f(CW\*(C`$\-[2]\*(C'\fR the offset where \f(CW$2\fR begins, and so on. |
| 1535 |
.Sp |
| 1536 |
After a match against some variable \f(CW$var\fR: |
| 1537 |
.RS 8 |
| 1538 |
.ie n .IP """$\`"" is the same as ""substr($var, 0, $\-[0])""" 5 |
| 1539 |
.el .IP "\f(CW$\`\fR is the same as \f(CWsubstr($var, 0, $\-[0])\fR" 5 |
| 1540 |
.IX Item "$ is the same as substr($var, 0, $-[0])" |
| 1541 |
.PD 0 |
| 1542 |
.ie n .IP "$& is the same as ""substr($var, $\-[0], $+[0] \- $\-[0])""" 5 |
| 1543 |
.el .IP "\f(CW$&\fR is the same as \f(CWsubstr($var, $\-[0], $+[0] \- $\-[0])\fR" 5 |
| 1544 |
.IX Item "$& is the same as substr($var, $-[0], $+[0] - $-[0])" |
| 1545 |
.ie n .IP """$\*(Aq"" is the same as ""substr($var, $+[0])""" 5 |
| 1546 |
.el .IP "\f(CW$\*(Aq\fR is the same as \f(CWsubstr($var, $+[0])\fR" 5 |
| 1547 |
.IX Item "$ is the same as substr($var, $+[0])" |
| 1548 |
.ie n .IP "$1 is the same as ""substr($var, $\-[1], $+[1] \- $\-[1])""" 5 |
| 1549 |
.el .IP "\f(CW$1\fR is the same as \f(CWsubstr($var, $\-[1], $+[1] \- $\-[1])\fR" 5 |
| 1550 |
.IX Item "$1 is the same as substr($var, $-[1], $+[1] - $-[1])" |
| 1551 |
.ie n .IP "$2 is the same as ""substr($var, $\-[2], $+[2] \- $\-[2])""" 5 |
| 1552 |
.el .IP "\f(CW$2\fR is the same as \f(CWsubstr($var, $\-[2], $+[2] \- $\-[2])\fR" 5 |
| 1553 |
.IX Item "$2 is the same as substr($var, $-[2], $+[2] - $-[2])" |
| 1554 |
.ie n .IP "$3 is the same as ""substr($var, $\-[3], $+[3] \- $\-[3])""" 5 |
| 1555 |
.el .IP "\f(CW$3\fR is the same as \f(CWsubstr($var, $\-[3], $+[3] \- $\-[3])\fR" 5 |
| 1556 |
.IX Item "$3 is the same as substr($var, $-[3], $+[3] - $-[3])" |
| 1557 |
.RE |
| 1558 |
.RS 8 |
| 1559 |
.PD |
| 1560 |
.Sp |
| 1561 |
This variable is read-only, and its value is dynamically scoped. |
| 1562 |
.Sp |
| 1563 |
This variable was added in Perl v5.6.0. |
| 1564 |
.RE |
| 1565 |
.IP %{^CAPTURE_ALL} 8 |
| 1566 |
.IX Xref "%{^CAPTURE_ALL}" |
| 1567 |
.IX Item "%{^CAPTURE_ALL}" |
| 1568 |
.PD 0 |
| 1569 |
.IP %\- 8 |
| 1570 |
.IX Xref "%-" |
| 1571 |
.PD |
| 1572 |
Similar to \f(CW\*(C`%+\*(C'\fR, this variable allows access to the named capture |
| 1573 |
groups in the last successful match in the currently active dynamic |
| 1574 |
scope. (See "Scoping Rules of Regex Variables"). To each capture group |
| 1575 |
name found in the regular expression, it associates a reference to an |
| 1576 |
array containing the list of values captured by all buffers with that |
| 1577 |
name (should there be several of them), in the order where they appear. |
| 1578 |
.Sp |
| 1579 |
Here's an example: |
| 1580 |
.Sp |
| 1581 |
.Vb 12 |
| 1582 |
\& if (\*(Aq1234\*(Aq =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { |
| 1583 |
\& foreach my $bufname (sort keys %\-) { |
| 1584 |
\& my $ary = $\-{$bufname}; |
| 1585 |
\& foreach my $idx (0..$#$ary) { |
| 1586 |
\& print "\e$\-{$bufname}[$idx] : ", |
| 1587 |
\& (defined($ary\->[$idx]) |
| 1588 |
\& ? "\*(Aq$ary\->[$idx]\*(Aq" |
| 1589 |
\& : "undef"), |
| 1590 |
\& "\en"; |
| 1591 |
\& } |
| 1592 |
\& } |
| 1593 |
\& } |
| 1594 |
.Ve |
| 1595 |
.Sp |
| 1596 |
would print out: |
| 1597 |
.Sp |
| 1598 |
.Vb 4 |
| 1599 |
\& $\-{A}[0] : \*(Aq1\*(Aq |
| 1600 |
\& $\-{A}[1] : \*(Aq3\*(Aq |
| 1601 |
\& $\-{B}[0] : \*(Aq2\*(Aq |
| 1602 |
\& $\-{B}[1] : \*(Aq4\*(Aq |
| 1603 |
.Ve |
| 1604 |
.Sp |
| 1605 |
The keys of the \f(CW\*(C`%\-\*(C'\fR hash correspond to all buffer names found in |
| 1606 |
the regular expression. |
| 1607 |
.Sp |
| 1608 |
The behaviour of \f(CW\*(C`%\-\*(C'\fR is implemented via the |
| 1609 |
Tie::Hash::NamedCapture module. |
| 1610 |
.Sp |
| 1611 |
\&\fBNote:\fR \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`%+\*(C'\fR are tied views into a common internal hash |
| 1612 |
associated with the last successful regular expression. Therefore mixing |
| 1613 |
iterative access to them via \f(CW\*(C`each\*(C'\fR may have unpredictable results. |
| 1614 |
Likewise, if the last successful match changes, then the results may be |
| 1615 |
surprising. See "Scoping Rules of Regex Variables". |
| 1616 |
.Sp |
| 1617 |
This variable was added in Perl v5.10.0. The \f(CW\*(C`%{^CAPTURE_ALL}\*(C'\fR alias was |
| 1618 |
added in 5.25.7. |
| 1619 |
.Sp |
| 1620 |
This variable is read-only, and its value is dynamically scoped. |
| 1621 |
.IP ${^LAST_SUCCESSFUL_PATTERN} 8 |
| 1622 |
.IX Item "${^LAST_SUCCESSFUL_PATTERN}" |
| 1623 |
The last successful pattern that matched in the current scope. The empty |
| 1624 |
pattern defaults to matching to this. For instance: |
| 1625 |
.Sp |
| 1626 |
.Vb 3 |
| 1627 |
\& if (m/foo/ || m/bar/) { |
| 1628 |
\& s//BLAH/; |
| 1629 |
\& } |
| 1630 |
.Ve |
| 1631 |
.Sp |
| 1632 |
and |
| 1633 |
.Sp |
| 1634 |
.Vb 3 |
| 1635 |
\& if (m/foo/ || m/bar/) { |
| 1636 |
\& s/${^LAST_SUCCESSFUL_PATTERN}/BLAH/; |
| 1637 |
\& } |
| 1638 |
.Ve |
| 1639 |
.Sp |
| 1640 |
are equivalent. |
| 1641 |
.Sp |
| 1642 |
You can use this to debug which pattern matched last, or to match with it again. |
| 1643 |
.Sp |
| 1644 |
Added in Perl 5.37.10. |
| 1645 |
.ie n .IP $LAST_REGEXP_CODE_RESULT 8 |
| 1646 |
.el .IP \f(CW$LAST_REGEXP_CODE_RESULT\fR 8 |
| 1647 |
.IX Item "$LAST_REGEXP_CODE_RESULT" |
| 1648 |
.PD 0 |
| 1649 |
.IP $^R 8 |
| 1650 |
.IX Xref "$^R $LAST_REGEXP_CODE_RESULT" |
| 1651 |
.IX Item "$^R" |
| 1652 |
.PD |
| 1653 |
The result of evaluation of the last successful \f(CW\*(C`(?{ code })\*(C'\fR |
| 1654 |
regular expression assertion (see perlre). |
| 1655 |
.Sp |
| 1656 |
This variable may be written to, and its value is scoped normally, |
| 1657 |
unlike most other regex variables. |
| 1658 |
.Sp |
| 1659 |
This variable was added in Perl 5.005. |
| 1660 |
.IP ${^RE_COMPILE_RECURSION_LIMIT} 8 |
| 1661 |
.IX Xref "${^RE_COMPILE_RECURSION_LIMIT}" |
| 1662 |
.IX Item "${^RE_COMPILE_RECURSION_LIMIT}" |
| 1663 |
The current value giving the maximum number of open but unclosed |
| 1664 |
parenthetical groups there may be at any point during a regular |
| 1665 |
expression compilation. The default is currently 1000 nested groups. |
| 1666 |
You may adjust it depending on your needs and the amount of memory |
| 1667 |
available. |
| 1668 |
.Sp |
| 1669 |
This variable was added in Perl v5.30.0. |
| 1670 |
.IP ${^RE_DEBUG_FLAGS} 8 |
| 1671 |
.IX Xref "${^RE_DEBUG_FLAGS}" |
| 1672 |
.IX Item "${^RE_DEBUG_FLAGS}" |
| 1673 |
The current value of the regex debugging flags. Set to 0 for no debug output |
| 1674 |
even when the \f(CW\*(C`re \*(Aqdebug\*(Aq\*(C'\fR module is loaded. See re for details. |
| 1675 |
.Sp |
| 1676 |
This variable was added in Perl v5.10.0. |
| 1677 |
.IP ${^RE_TRIE_MAXBUF} 8 |
| 1678 |
.IX Xref "${^RE_TRIE_MAXBUF}" |
| 1679 |
.IX Item "${^RE_TRIE_MAXBUF}" |
| 1680 |
Controls how certain regex optimisations are applied and how much memory they |
| 1681 |
utilize. This value by default is 65536 which corresponds to a 512kB |
| 1682 |
temporary cache. Set this to a higher value to trade |
| 1683 |
memory for speed when matching large alternations. Set |
| 1684 |
it to a lower value if you want the optimisations to |
| 1685 |
be as conservative of memory as possible but still occur, and set it to a |
| 1686 |
negative value to prevent the optimisation and conserve the most memory. |
| 1687 |
Under normal situations this variable should be of no interest to you. |
| 1688 |
.Sp |
| 1689 |
This variable was added in Perl v5.10.0. |
| 1690 |
.SS "Variables related to filehandles" |
| 1691 |
.IX Subsection "Variables related to filehandles" |
| 1692 |
Variables that depend on the currently selected filehandle may be set |
| 1693 |
by calling an appropriate object method on the \f(CW\*(C`IO::Handle\*(C'\fR object, |
| 1694 |
although this is less efficient than using the regular built-in |
| 1695 |
variables. (Summary lines below for this contain the word HANDLE.) |
| 1696 |
First you must say |
| 1697 |
.PP |
| 1698 |
.Vb 1 |
| 1699 |
\& use IO::Handle; |
| 1700 |
.Ve |
| 1701 |
.PP |
| 1702 |
after which you may use either |
| 1703 |
.PP |
| 1704 |
.Vb 1 |
| 1705 |
\& method HANDLE EXPR |
| 1706 |
.Ve |
| 1707 |
.PP |
| 1708 |
or more safely, |
| 1709 |
.PP |
| 1710 |
.Vb 1 |
| 1711 |
\& HANDLE\->method(EXPR) |
| 1712 |
.Ve |
| 1713 |
.PP |
| 1714 |
Each method returns the old value of the \f(CW\*(C`IO::Handle\*(C'\fR attribute. The |
| 1715 |
methods each take an optional EXPR, which, if supplied, specifies the |
| 1716 |
new value for the \f(CW\*(C`IO::Handle\*(C'\fR attribute in question. If not |
| 1717 |
supplied, most methods do nothing to the current value\-\-except for |
| 1718 |
\&\f(CWautoflush()\fR, which will assume a 1 for you, just to be different. |
| 1719 |
.PP |
| 1720 |
Because loading in the \f(CW\*(C`IO::Handle\*(C'\fR class is an expensive operation, |
| 1721 |
you should learn how to use the regular built-in variables. |
| 1722 |
.PP |
| 1723 |
A few of these variables are considered "read-only". This means that |
| 1724 |
if you try to assign to this variable, either directly or indirectly |
| 1725 |
through a reference, you'll raise a run-time exception. |
| 1726 |
.PP |
| 1727 |
You should be very careful when modifying the default values of most |
| 1728 |
special variables described in this document. In most cases you want |
| 1729 |
to localize these variables before changing them, since if you don't, |
| 1730 |
the change may affect other modules which rely on the default values |
| 1731 |
of the special variables that you have changed. This is one of the |
| 1732 |
correct ways to read the whole file at once: |
| 1733 |
.PP |
| 1734 |
.Vb 4 |
| 1735 |
\& open my $fh, "<", "foo" or die $!; |
| 1736 |
\& local $/; # enable localized slurp mode |
| 1737 |
\& my $content = <$fh>; |
| 1738 |
\& close $fh; |
| 1739 |
.Ve |
| 1740 |
.PP |
| 1741 |
But the following code is quite bad: |
| 1742 |
.PP |
| 1743 |
.Vb 4 |
| 1744 |
\& open my $fh, "<", "foo" or die $!; |
| 1745 |
\& undef $/; # enable slurp mode |
| 1746 |
\& my $content = <$fh>; |
| 1747 |
\& close $fh; |
| 1748 |
.Ve |
| 1749 |
.PP |
| 1750 |
since some other module, may want to read data from some file in the |
| 1751 |
default "line mode", so if the code we have just presented has been |
| 1752 |
executed, the global value of \f(CW$/\fR is now changed for any other code |
| 1753 |
running inside the same Perl interpreter. |
| 1754 |
.PP |
| 1755 |
Usually when a variable is localized you want to make sure that this |
| 1756 |
change affects the shortest scope possible. So unless you are already |
| 1757 |
inside some short \f(CW\*(C`{}\*(C'\fR block, you should create one yourself. For |
| 1758 |
example: |
| 1759 |
.PP |
| 1760 |
.Vb 7 |
| 1761 |
\& my $content = \*(Aq\*(Aq; |
| 1762 |
\& open my $fh, "<", "foo" or die $!; |
| 1763 |
\& { |
| 1764 |
\& local $/; |
| 1765 |
\& $content = <$fh>; |
| 1766 |
\& } |
| 1767 |
\& close $fh; |
| 1768 |
.Ve |
| 1769 |
.PP |
| 1770 |
Here is an example of how your own code can go broken: |
| 1771 |
.PP |
| 1772 |
.Vb 5 |
| 1773 |
\& for ( 1..3 ){ |
| 1774 |
\& $\e = "\er\en"; |
| 1775 |
\& nasty_break(); |
| 1776 |
\& print "$_"; |
| 1777 |
\& } |
| 1778 |
\& |
| 1779 |
\& sub nasty_break { |
| 1780 |
\& $\e = "\ef"; |
| 1781 |
\& # do something with $_ |
| 1782 |
\& } |
| 1783 |
.Ve |
| 1784 |
.PP |
| 1785 |
You probably expect this code to print the equivalent of |
| 1786 |
.PP |
| 1787 |
.Vb 1 |
| 1788 |
\& "1\er\en2\er\en3\er\en" |
| 1789 |
.Ve |
| 1790 |
.PP |
| 1791 |
but instead you get: |
| 1792 |
.PP |
| 1793 |
.Vb 1 |
| 1794 |
\& "1\ef2\ef3\ef" |
| 1795 |
.Ve |
| 1796 |
.PP |
| 1797 |
Why? Because \f(CWnasty_break()\fR modifies \f(CW\*(C`$\e\*(C'\fR without localizing it |
| 1798 |
first. The value you set in \f(CWnasty_break()\fR is still there when you |
| 1799 |
return. The fix is to add \f(CWlocal()\fR so the value doesn't leak out of |
| 1800 |
\&\f(CWnasty_break()\fR: |
| 1801 |
.PP |
| 1802 |
.Vb 1 |
| 1803 |
\& local $\e = "\ef"; |
| 1804 |
.Ve |
| 1805 |
.PP |
| 1806 |
It's easy to notice the problem in such a short example, but in more |
| 1807 |
complicated code you are looking for trouble if you don't localize |
| 1808 |
changes to the special variables. |
| 1809 |
.ie n .IP $ARGV 8 |
| 1810 |
.el .IP \f(CW$ARGV\fR 8 |
| 1811 |
.IX Xref "$ARGV" |
| 1812 |
.IX Item "$ARGV" |
| 1813 |
Contains the name of the current file when reading from \f(CW\*(C`<>\*(C'\fR. |
| 1814 |
.ie n .IP @ARGV 8 |
| 1815 |
.el .IP \f(CW@ARGV\fR 8 |
| 1816 |
.IX Xref "@ARGV" |
| 1817 |
.IX Item "@ARGV" |
| 1818 |
The array \f(CW@ARGV\fR contains the command-line arguments intended for |
| 1819 |
the script. \f(CW$#ARGV\fR is generally the number of arguments minus |
| 1820 |
one, because \f(CW$ARGV[0]\fR is the first argument, \fInot\fR the program's |
| 1821 |
command name itself. See "$0" for the command name. |
| 1822 |
.IP ARGV 8 |
| 1823 |
.IX Xref "ARGV" |
| 1824 |
.IX Item "ARGV" |
| 1825 |
The special filehandle that iterates over command-line filenames in |
| 1826 |
\&\f(CW@ARGV\fR. Usually written as the null filehandle in the angle operator |
| 1827 |
\&\f(CW\*(C`<>\*(C'\fR. Note that currently \f(CW\*(C`ARGV\*(C'\fR only has its magical effect |
| 1828 |
within the \f(CW\*(C`<>\*(C'\fR operator; elsewhere it is just a plain filehandle |
| 1829 |
corresponding to the last file opened by \f(CW\*(C`<>\*(C'\fR. In particular, |
| 1830 |
passing \f(CW\*(C`\e*ARGV\*(C'\fR as a parameter to a function that expects a filehandle |
| 1831 |
may not cause your function to automatically read the contents of all the |
| 1832 |
files in \f(CW@ARGV\fR. |
| 1833 |
.IP ARGVOUT 8 |
| 1834 |
.IX Xref "ARGVOUT" |
| 1835 |
.IX Item "ARGVOUT" |
| 1836 |
The special filehandle that points to the currently open output file |
| 1837 |
when doing edit-in-place processing with \fB\-i\fR. Useful when you have |
| 1838 |
to do a lot of inserting and don't want to keep modifying \f(CW$_\fR. See |
| 1839 |
perlrun for the \fB\-i\fR switch. |
| 1840 |
.IP "IO::Handle\->output_field_separator( EXPR )" 8 |
| 1841 |
.IX Item "IO::Handle->output_field_separator( EXPR )" |
| 1842 |
.PD 0 |
| 1843 |
.ie n .IP $OUTPUT_FIELD_SEPARATOR 8 |
| 1844 |
.el .IP \f(CW$OUTPUT_FIELD_SEPARATOR\fR 8 |
| 1845 |
.IX Item "$OUTPUT_FIELD_SEPARATOR" |
| 1846 |
.ie n .IP $OFS 8 |
| 1847 |
.el .IP \f(CW$OFS\fR 8 |
| 1848 |
.IX Item "$OFS" |
| 1849 |
.IP $, 8 |
| 1850 |
.IX Xref "$, $OFS $OUTPUT_FIELD_SEPARATOR" |
| 1851 |
.PD |
| 1852 |
The output field separator for the print operator. If defined, this |
| 1853 |
value is printed between each of print's arguments. Default is \f(CW\*(C`undef\*(C'\fR. |
| 1854 |
.Sp |
| 1855 |
You cannot call \f(CWoutput_field_separator()\fR on a handle, only as a |
| 1856 |
static method. See IO::Handle. |
| 1857 |
.Sp |
| 1858 |
Mnemonic: what is printed when there is a "," in your print statement. |
| 1859 |
.IP "HANDLE\->input_line_number( EXPR )" 8 |
| 1860 |
.IX Item "HANDLE->input_line_number( EXPR )" |
| 1861 |
.PD 0 |
| 1862 |
.ie n .IP $INPUT_LINE_NUMBER 8 |
| 1863 |
.el .IP \f(CW$INPUT_LINE_NUMBER\fR 8 |
| 1864 |
.IX Item "$INPUT_LINE_NUMBER" |
| 1865 |
.ie n .IP $NR 8 |
| 1866 |
.el .IP \f(CW$NR\fR 8 |
| 1867 |
.IX Item "$NR" |
| 1868 |
.IP $. 8 |
| 1869 |
.IX Xref "$. $NR $INPUT_LINE_NUMBER line number" |
| 1870 |
.PD |
| 1871 |
Current line number for the last filehandle accessed. |
| 1872 |
.Sp |
| 1873 |
Each filehandle in Perl counts the number of lines that have been read |
| 1874 |
from it. (Depending on the value of \f(CW$/\fR, Perl's idea of what |
| 1875 |
constitutes a line may not match yours.) When a line is read from a |
| 1876 |
filehandle (via \f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR), or when \f(CWtell()\fR or |
| 1877 |
\&\f(CWseek()\fR is called on it, \f(CW$.\fR becomes an alias to the line counter |
| 1878 |
for that filehandle. |
| 1879 |
.Sp |
| 1880 |
You can adjust the counter by assigning to \f(CW$.\fR, but this will not |
| 1881 |
actually move the seek pointer. \fILocalizing \fR\f(CI$.\fR\fI will not localize |
| 1882 |
the filehandle's line count\fR. Instead, it will localize perl's notion |
| 1883 |
of which filehandle \f(CW$.\fR is currently aliased to. |
| 1884 |
.Sp |
| 1885 |
\&\f(CW$.\fR is reset when the filehandle is closed, but \fBnot\fR when an open |
| 1886 |
filehandle is reopened without an intervening \f(CWclose()\fR. For more |
| 1887 |
details, see "I/O Operators" in perlop. Because \f(CW\*(C`<>\*(C'\fR never does |
| 1888 |
an explicit close, line numbers increase across \f(CW\*(C`ARGV\*(C'\fR files (but see |
| 1889 |
examples in "eof" in perlfunc). |
| 1890 |
.Sp |
| 1891 |
You can also use \f(CW\*(C`HANDLE\->input_line_number(EXPR)\*(C'\fR to access the |
| 1892 |
line counter for a given filehandle without having to worry about |
| 1893 |
which handle you last accessed. |
| 1894 |
.Sp |
| 1895 |
Mnemonic: many programs use "." to mean the current line number. |
| 1896 |
.IP "IO::Handle\->input_record_separator( EXPR )" 8 |
| 1897 |
.IX Item "IO::Handle->input_record_separator( EXPR )" |
| 1898 |
.PD 0 |
| 1899 |
.ie n .IP $INPUT_RECORD_SEPARATOR 8 |
| 1900 |
.el .IP \f(CW$INPUT_RECORD_SEPARATOR\fR 8 |
| 1901 |
.IX Item "$INPUT_RECORD_SEPARATOR" |
| 1902 |
.ie n .IP $RS 8 |
| 1903 |
.el .IP \f(CW$RS\fR 8 |
| 1904 |
.IX Item "$RS" |
| 1905 |
.IP $/ 8 |
| 1906 |
.IX Xref "$ $RS $INPUT_RECORD_SEPARATOR" |
| 1907 |
.PD |
| 1908 |
The input record separator, newline by default. This influences Perl's |
| 1909 |
idea of what a "line" is. Works like \fBawk\fR's RS variable, including |
| 1910 |
treating empty lines as a terminator if set to the null string (an |
| 1911 |
empty line cannot contain any spaces or tabs). You may set it to a |
| 1912 |
multi-character string to match a multi-character terminator, or to |
| 1913 |
\&\f(CW\*(C`undef\*(C'\fR to read through the end of file. Setting it to \f(CW"\en\en"\fR |
| 1914 |
means something slightly different than setting to \f(CW""\fR, if the file |
| 1915 |
contains consecutive empty lines. Setting to \f(CW""\fR will treat two or |
| 1916 |
more consecutive empty lines as a single empty line. Setting to |
| 1917 |
\&\f(CW"\en\en"\fR will blindly assume that the next input character belongs to |
| 1918 |
the next paragraph, even if it's a newline. |
| 1919 |
.Sp |
| 1920 |
.Vb 3 |
| 1921 |
\& local $/; # enable "slurp" mode |
| 1922 |
\& local $_ = <FH>; # whole file now here |
| 1923 |
\& s/\en[ \et]+/ /g; |
| 1924 |
.Ve |
| 1925 |
.Sp |
| 1926 |
Remember: the value of \f(CW$/\fR is a string, not a regex. \fBawk\fR has to |
| 1927 |
be better for something. :\-) |
| 1928 |
.Sp |
| 1929 |
Setting \f(CW$/\fR to an empty string \-\- the so-called \fIparagraph mode\fR \-\- merits |
| 1930 |
special attention. When \f(CW$/\fR is set to \f(CW""\fR and the entire file is read in |
| 1931 |
with that setting, any sequence of one or more consecutive newlines at the |
| 1932 |
beginning of the file is discarded. With the exception of the final record in |
| 1933 |
the file, each sequence of characters ending in two or more newlines is |
| 1934 |
treated as one record and is read in to end in exactly two newlines. If the |
| 1935 |
last record in the file ends in zero or one consecutive newlines, that record |
| 1936 |
is read in with that number of newlines. If the last record ends in two or |
| 1937 |
more consecutive newlines, it is read in with two newlines like all preceding |
| 1938 |
records. |
| 1939 |
.Sp |
| 1940 |
Suppose we wrote the following string to a file: |
| 1941 |
.Sp |
| 1942 |
.Vb 4 |
| 1943 |
\& my $string = "\en\en\en"; |
| 1944 |
\& $string .= "alpha beta\engamma delta\en\en\en"; |
| 1945 |
\& $string .= "epsilon zeta eta\en\en"; |
| 1946 |
\& $string .= "theta\en"; |
| 1947 |
\& |
| 1948 |
\& my $file = \*(Aqsimple_file.txt\*(Aq; |
| 1949 |
\& open my $OUT, \*(Aq>\*(Aq, $file or die; |
| 1950 |
\& print $OUT $string; |
| 1951 |
\& close $OUT or die; |
| 1952 |
.Ve |
| 1953 |
.Sp |
| 1954 |
Now we read that file in paragraph mode: |
| 1955 |
.Sp |
| 1956 |
.Vb 4 |
| 1957 |
\& local $/ = ""; # paragraph mode |
| 1958 |
\& open my $IN, \*(Aq<\*(Aq, $file or die; |
| 1959 |
\& my @records = <$IN>; |
| 1960 |
\& close $IN or die; |
| 1961 |
.Ve |
| 1962 |
.Sp |
| 1963 |
\&\f(CW@records\fR will consist of these 3 strings: |
| 1964 |
.Sp |
| 1965 |
.Vb 5 |
| 1966 |
\& ( |
| 1967 |
\& "alpha beta\engamma delta\en\en", |
| 1968 |
\& "epsilon zeta eta\en\en", |
| 1969 |
\& "theta\en", |
| 1970 |
\& ) |
| 1971 |
.Ve |
| 1972 |
.Sp |
| 1973 |
Setting \f(CW$/\fR to a reference to an integer, scalar containing an |
| 1974 |
integer, or scalar that's convertible to an integer will attempt to |
| 1975 |
read records instead of lines, with the maximum record size being the |
| 1976 |
referenced integer number of characters. So this: |
| 1977 |
.Sp |
| 1978 |
.Vb 3 |
| 1979 |
\& local $/ = \e32768; # or \e"32768", or \e$var_containing_32768 |
| 1980 |
\& open my $fh, "<", $myfile or die $!; |
| 1981 |
\& local $_ = <$fh>; |
| 1982 |
.Ve |
| 1983 |
.Sp |
| 1984 |
will read a record of no more than 32768 characters from \f(CW$fh\fR. If you're |
| 1985 |
not reading from a record-oriented file (or your OS doesn't have |
| 1986 |
record-oriented files), then you'll likely get a full chunk of data |
| 1987 |
with every read. If a record is larger than the record size you've |
| 1988 |
set, you'll get the record back in pieces. Trying to set the record |
| 1989 |
size to zero or less is deprecated and will cause $/ to have the value |
| 1990 |
of "undef", which will cause reading in the (rest of the) whole file. |
| 1991 |
.Sp |
| 1992 |
As of 5.19.9 setting \f(CW$/\fR to any other form of reference will throw a |
| 1993 |
fatal exception. This is in preparation for supporting new ways to set |
| 1994 |
\&\f(CW$/\fR in the future. |
| 1995 |
.Sp |
| 1996 |
On VMS only, record reads bypass PerlIO layers and any associated |
| 1997 |
buffering, so you must not mix record and non-record reads on the |
| 1998 |
same filehandle. Record mode mixes with line mode only when the |
| 1999 |
same buffering layer is in use for both modes. |
| 2000 |
.Sp |
| 2001 |
You cannot call \f(CWinput_record_separator()\fR on a handle, only as a |
| 2002 |
static method. See IO::Handle. |
| 2003 |
.Sp |
| 2004 |
See also "Newlines" in perlport. Also see "$.". |
| 2005 |
.Sp |
| 2006 |
Mnemonic: / delimits line boundaries when quoting poetry. |
| 2007 |
.IP "IO::Handle\->output_record_separator( EXPR )" 8 |
| 2008 |
.IX Item "IO::Handle->output_record_separator( EXPR )" |
| 2009 |
.PD 0 |
| 2010 |
.ie n .IP $OUTPUT_RECORD_SEPARATOR 8 |
| 2011 |
.el .IP \f(CW$OUTPUT_RECORD_SEPARATOR\fR 8 |
| 2012 |
.IX Item "$OUTPUT_RECORD_SEPARATOR" |
| 2013 |
.ie n .IP $ORS 8 |
| 2014 |
.el .IP \f(CW$ORS\fR 8 |
| 2015 |
.IX Item "$ORS" |
| 2016 |
.IP $\e 8 |
| 2017 |
.IX Xref "$\\ $ORS $OUTPUT_RECORD_SEPARATOR" |
| 2018 |
.IX Item "$" |
| 2019 |
.PD |
| 2020 |
The output record separator for the print operator. If defined, this |
| 2021 |
value is printed after the last of print's arguments. Default is \f(CW\*(C`undef\*(C'\fR. |
| 2022 |
.Sp |
| 2023 |
You cannot call \f(CWoutput_record_separator()\fR on a handle, only as a |
| 2024 |
static method. See IO::Handle. |
| 2025 |
.Sp |
| 2026 |
Mnemonic: you set \f(CW\*(C`$\e\*(C'\fR instead of adding "\en" at the end of the print. |
| 2027 |
Also, it's just like \f(CW$/\fR, but it's what you get "back" from Perl. |
| 2028 |
.IP "HANDLE\->autoflush( EXPR )" 8 |
| 2029 |
.IX Item "HANDLE->autoflush( EXPR )" |
| 2030 |
.PD 0 |
| 2031 |
.ie n .IP $OUTPUT_AUTOFLUSH 8 |
| 2032 |
.el .IP \f(CW$OUTPUT_AUTOFLUSH\fR 8 |
| 2033 |
.IX Item "$OUTPUT_AUTOFLUSH" |
| 2034 |
.IP $| 8 |
| 2035 |
.IX Xref "$| autoflush flush $OUTPUT_AUTOFLUSH" |
| 2036 |
.PD |
| 2037 |
If set to nonzero, forces a flush right away and after every write or |
| 2038 |
print on the currently selected output channel. Default is 0 |
| 2039 |
(regardless of whether the channel is really buffered by the system or |
| 2040 |
not; \f(CW$|\fR tells you only whether you've asked Perl explicitly to |
| 2041 |
flush after each write). STDOUT will typically be line buffered if |
| 2042 |
output is to the terminal and block buffered otherwise. Setting this |
| 2043 |
variable is useful primarily when you are outputting to a pipe or |
| 2044 |
socket, such as when you are running a Perl program under \fBrsh\fR and |
| 2045 |
want to see the output as it's happening. This has no effect on input |
| 2046 |
buffering. See "getc" in perlfunc for that. See "select" in perlfunc on |
| 2047 |
how to select the output channel. See also IO::Handle. |
| 2048 |
.Sp |
| 2049 |
Mnemonic: when you want your pipes to be piping hot. |
| 2050 |
.IP ${^LAST_FH} 8 |
| 2051 |
.IX Xref "${^LAST_FH}" |
| 2052 |
.IX Item "${^LAST_FH}" |
| 2053 |
This read-only variable contains a reference to the last-read filehandle. |
| 2054 |
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. |
| 2055 |
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 |
| 2056 |
use. It is also the handle used when Perl appends ", <STDIN> line 1" to |
| 2057 |
an error or warning message. |
| 2058 |
.Sp |
| 2059 |
This variable was added in Perl v5.18.0. |
| 2060 |
.PP |
| 2061 |
\fIVariables related to formats\fR |
| 2062 |
.IX Subsection "Variables related to formats" |
| 2063 |
.PP |
| 2064 |
The special variables for formats are a subset of those for |
| 2065 |
filehandles. See perlform for more information about Perl's |
| 2066 |
formats. |
| 2067 |
.ie n .IP $ACCUMULATOR 8 |
| 2068 |
.el .IP \f(CW$ACCUMULATOR\fR 8 |
| 2069 |
.IX Item "$ACCUMULATOR" |
| 2070 |
.PD 0 |
| 2071 |
.IP $^A 8 |
| 2072 |
.IX Xref "$^A $ACCUMULATOR" |
| 2073 |
.IX Item "$^A" |
| 2074 |
.PD |
| 2075 |
The current value of the \f(CWwrite()\fR accumulator for \f(CWformat()\fR lines. |
| 2076 |
A format contains \f(CWformline()\fR calls that put their result into |
| 2077 |
\&\f(CW$^A\fR. After calling its format, \f(CWwrite()\fR prints out the contents |
| 2078 |
of \f(CW$^A\fR and empties. So you never really see the contents of \f(CW$^A\fR |
| 2079 |
unless you call \f(CWformline()\fR yourself and then look at it. See |
| 2080 |
perlform and "formline PICTURE,LIST" in perlfunc. |
| 2081 |
.IP IO::Handle\->format_formfeed(EXPR) 8 |
| 2082 |
.IX Item "IO::Handle->format_formfeed(EXPR)" |
| 2083 |
.PD 0 |
| 2084 |
.ie n .IP $FORMAT_FORMFEED 8 |
| 2085 |
.el .IP \f(CW$FORMAT_FORMFEED\fR 8 |
| 2086 |
.IX Item "$FORMAT_FORMFEED" |
| 2087 |
.IP $^L 8 |
| 2088 |
.IX Xref "$^L $FORMAT_FORMFEED" |
| 2089 |
.IX Item "$^L" |
| 2090 |
.PD |
| 2091 |
What formats output as a form feed. The default is \f(CW\*(C`\ef\*(C'\fR. |
| 2092 |
.Sp |
| 2093 |
You cannot call \f(CWformat_formfeed()\fR on a handle, only as a static |
| 2094 |
method. See IO::Handle. |
| 2095 |
.IP HANDLE\->format_page_number(EXPR) 8 |
| 2096 |
.IX Item "HANDLE->format_page_number(EXPR)" |
| 2097 |
.PD 0 |
| 2098 |
.ie n .IP $FORMAT_PAGE_NUMBER 8 |
| 2099 |
.el .IP \f(CW$FORMAT_PAGE_NUMBER\fR 8 |
| 2100 |
.IX Item "$FORMAT_PAGE_NUMBER" |
| 2101 |
.IP $% 8 |
| 2102 |
.IX Xref "$% $FORMAT_PAGE_NUMBER" |
| 2103 |
.PD |
| 2104 |
The current page number of the currently selected output channel. |
| 2105 |
.Sp |
| 2106 |
Mnemonic: \f(CW\*(C`%\*(C'\fR is page number in \fBnroff\fR. |
| 2107 |
.IP HANDLE\->format_lines_left(EXPR) 8 |
| 2108 |
.IX Item "HANDLE->format_lines_left(EXPR)" |
| 2109 |
.PD 0 |
| 2110 |
.ie n .IP $FORMAT_LINES_LEFT 8 |
| 2111 |
.el .IP \f(CW$FORMAT_LINES_LEFT\fR 8 |
| 2112 |
.IX Item "$FORMAT_LINES_LEFT" |
| 2113 |
.IP $\- 8 |
| 2114 |
.IX Xref "$- $FORMAT_LINES_LEFT" |
| 2115 |
.PD |
| 2116 |
The number of lines left on the page of the currently selected output |
| 2117 |
channel. |
| 2118 |
.Sp |
| 2119 |
Mnemonic: lines_on_page \- lines_printed. |
| 2120 |
.IP "IO::Handle\->format_line_break_characters EXPR" 8 |
| 2121 |
.IX Item "IO::Handle->format_line_break_characters EXPR" |
| 2122 |
.PD 0 |
| 2123 |
.ie n .IP $FORMAT_LINE_BREAK_CHARACTERS 8 |
| 2124 |
.el .IP \f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR 8 |
| 2125 |
.IX Item "$FORMAT_LINE_BREAK_CHARACTERS" |
| 2126 |
.ie n .IP $: 8 |
| 2127 |
.el .IP \f(CW$:\fR 8 |
| 2128 |
.IX Xref "$: FORMAT_LINE_BREAK_CHARACTERS" |
| 2129 |
.IX Item "$:" |
| 2130 |
.PD |
| 2131 |
The current set of characters after which a string may be broken to |
| 2132 |
fill continuation fields (starting with \f(CW\*(C`^\*(C'\fR) in a format. The default is |
| 2133 |
"\ \en\-", to break on a space, newline, or a hyphen. |
| 2134 |
.Sp |
| 2135 |
You cannot call \f(CWformat_line_break_characters()\fR on a handle, only as |
| 2136 |
a static method. See IO::Handle. |
| 2137 |
.Sp |
| 2138 |
Mnemonic: a "colon" in poetry is a part of a line. |
| 2139 |
.IP HANDLE\->format_lines_per_page(EXPR) 8 |
| 2140 |
.IX Item "HANDLE->format_lines_per_page(EXPR)" |
| 2141 |
.PD 0 |
| 2142 |
.ie n .IP $FORMAT_LINES_PER_PAGE 8 |
| 2143 |
.el .IP \f(CW$FORMAT_LINES_PER_PAGE\fR 8 |
| 2144 |
.IX Item "$FORMAT_LINES_PER_PAGE" |
| 2145 |
.IP $= 8 |
| 2146 |
.IX Xref "$= $FORMAT_LINES_PER_PAGE" |
| 2147 |
.PD |
| 2148 |
The current page length (printable lines) of the currently selected |
| 2149 |
output channel. The default is 60. |
| 2150 |
.Sp |
| 2151 |
Mnemonic: = has horizontal lines. |
| 2152 |
.IP HANDLE\->format_top_name(EXPR) 8 |
| 2153 |
.IX Item "HANDLE->format_top_name(EXPR)" |
| 2154 |
.PD 0 |
| 2155 |
.ie n .IP $FORMAT_TOP_NAME 8 |
| 2156 |
.el .IP \f(CW$FORMAT_TOP_NAME\fR 8 |
| 2157 |
.IX Item "$FORMAT_TOP_NAME" |
| 2158 |
.IP $^ 8 |
| 2159 |
.IX Xref "$^ $FORMAT_TOP_NAME" |
| 2160 |
.PD |
| 2161 |
The name of the current top-of-page format for the currently selected |
| 2162 |
output channel. The default is the name of the filehandle with \f(CW\*(C`_TOP\*(C'\fR |
| 2163 |
appended. For example, the default format top name for the \f(CW\*(C`STDOUT\*(C'\fR |
| 2164 |
filehandle is \f(CW\*(C`STDOUT_TOP\*(C'\fR. |
| 2165 |
.Sp |
| 2166 |
Mnemonic: points to top of page. |
| 2167 |
.IP HANDLE\->format_name(EXPR) 8 |
| 2168 |
.IX Item "HANDLE->format_name(EXPR)" |
| 2169 |
.PD 0 |
| 2170 |
.ie n .IP $FORMAT_NAME 8 |
| 2171 |
.el .IP \f(CW$FORMAT_NAME\fR 8 |
| 2172 |
.IX Item "$FORMAT_NAME" |
| 2173 |
.IP $~ 8 |
| 2174 |
.IX Xref "$~ $FORMAT_NAME" |
| 2175 |
.PD |
| 2176 |
The name of the current report format for the currently selected |
| 2177 |
output channel. The default format name is the same as the filehandle |
| 2178 |
name. For example, the default format name for the \f(CW\*(C`STDOUT\*(C'\fR |
| 2179 |
filehandle is just \f(CW\*(C`STDOUT\*(C'\fR. |
| 2180 |
.Sp |
| 2181 |
Mnemonic: brother to \f(CW$^\fR. |
| 2182 |
.SS "Error Variables" |
| 2183 |
.IX Xref "error exception" |
| 2184 |
.IX Subsection "Error Variables" |
| 2185 |
The variables \f(CW$@\fR, \f(CW$!\fR, \f(CW$^E\fR, and \f(CW$?\fR contain information |
| 2186 |
about different types of error conditions that may appear during |
| 2187 |
execution of a Perl program. The variables are shown ordered by |
| 2188 |
the "distance" between the subsystem which reported the error and |
| 2189 |
the Perl process. They correspond to errors detected by the Perl |
| 2190 |
interpreter, C library, operating system, or an external program, |
| 2191 |
respectively. |
| 2192 |
.PP |
| 2193 |
To illustrate the differences between these variables, consider the |
| 2194 |
following Perl expression, which uses a single-quoted string. After |
| 2195 |
execution of this statement, perl may have set all four special error |
| 2196 |
variables: |
| 2197 |
.PP |
| 2198 |
.Vb 5 |
| 2199 |
\& eval q{ |
| 2200 |
\& open my $pipe, "/cdrom/install |" or die $!; |
| 2201 |
\& my @res = <$pipe>; |
| 2202 |
\& close $pipe or die "bad pipe: $?, $!"; |
| 2203 |
\& }; |
| 2204 |
.Ve |
| 2205 |
.PP |
| 2206 |
When perl executes the \f(CWeval()\fR expression, it translates the |
| 2207 |
\&\f(CWopen()\fR, \f(CW\*(C`<PIPE>\*(C'\fR, and \f(CW\*(C`close\*(C'\fR calls in the C run-time library |
| 2208 |
and thence to the operating system kernel. perl sets \f(CW$!\fR to |
| 2209 |
the C library's \f(CW\*(C`errno\*(C'\fR if one of these calls fails. |
| 2210 |
.PP |
| 2211 |
\&\f(CW$@\fR is set if the string to be \f(CW\*(C`eval\*(C'\fR\-ed did not compile (this may |
| 2212 |
happen if \f(CW\*(C`open\*(C'\fR or \f(CW\*(C`close\*(C'\fR were imported with bad prototypes), or |
| 2213 |
if Perl code executed during evaluation \f(CWdie()\fRd. In these cases the |
| 2214 |
value of \f(CW$@\fR is the compile error, or the argument to \f(CW\*(C`die\*(C'\fR (which |
| 2215 |
will interpolate \f(CW$!\fR and \f(CW$?\fR). (See also Fatal, though.) |
| 2216 |
.PP |
| 2217 |
Under a few operating systems, \f(CW$^E\fR may contain a more verbose error |
| 2218 |
indicator, such as in this case, "CDROM tray not closed." Systems that |
| 2219 |
do not support extended error messages leave \f(CW$^E\fR the same as \f(CW$!\fR. |
| 2220 |
.PP |
| 2221 |
Finally, \f(CW$?\fR may be set to a non\-0 value if the external program |
| 2222 |
\&\fI/cdrom/install\fR fails. The upper eight bits reflect specific error |
| 2223 |
conditions encountered by the program (the program's \f(CWexit()\fR value). |
| 2224 |
The lower eight bits reflect mode of failure, like signal death and |
| 2225 |
core dump information. See \fBwait\fR\|(2) for details. In contrast to |
| 2226 |
\&\f(CW$!\fR and \f(CW$^E\fR, which are set only if an error condition is detected, |
| 2227 |
the variable \f(CW$?\fR is set on each \f(CW\*(C`wait\*(C'\fR or pipe \f(CW\*(C`close\*(C'\fR, |
| 2228 |
overwriting the old value. This is more like \f(CW$@\fR, which on every |
| 2229 |
\&\f(CWeval()\fR is always set on failure and cleared on success. |
| 2230 |
.PP |
| 2231 |
For more details, see the individual descriptions at \f(CW$@\fR, \f(CW$!\fR, |
| 2232 |
\&\f(CW$^E\fR, and \f(CW$?\fR. |
| 2233 |
.IP ${^CHILD_ERROR_NATIVE} 8 |
| 2234 |
.IX Xref "$^CHILD_ERROR_NATIVE" |
| 2235 |
.IX Item "${^CHILD_ERROR_NATIVE}" |
| 2236 |
The native status returned by the last pipe close, backtick (\f(CW\`\`\fR) |
| 2237 |
command, successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the |
| 2238 |
\&\f(CWsystem()\fR operator. On POSIX-like systems this value can be decoded |
| 2239 |
with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, and |
| 2240 |
WSTOPSIG functions provided by the POSIX module. |
| 2241 |
.Sp |
| 2242 |
Under VMS this reflects the actual VMS exit status; i.e. it is the |
| 2243 |
same as \f(CW$?\fR when the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR is in effect. |
| 2244 |
.Sp |
| 2245 |
This variable was added in Perl v5.10.0. |
| 2246 |
.ie n .IP $EXTENDED_OS_ERROR 8 |
| 2247 |
.el .IP \f(CW$EXTENDED_OS_ERROR\fR 8 |
| 2248 |
.IX Item "$EXTENDED_OS_ERROR" |
| 2249 |
.PD 0 |
| 2250 |
.IP $^E 8 |
| 2251 |
.IX Xref "$^E $EXTENDED_OS_ERROR" |
| 2252 |
.IX Item "$^E" |
| 2253 |
.PD |
| 2254 |
Error information specific to the current operating system. At the |
| 2255 |
moment, this differs from \f(CW"$!"\fR under only VMS, OS/2, and Win32 (and |
| 2256 |
for MacPerl). On all other platforms, \f(CW$^E\fR is always just the same |
| 2257 |
as \f(CW$!\fR. |
| 2258 |
.Sp |
| 2259 |
Under VMS, \f(CW$^E\fR provides the VMS status value from the last system |
| 2260 |
error. This is more specific information about the last system error |
| 2261 |
than that provided by \f(CW$!\fR. This is particularly important when \f(CW$!\fR |
| 2262 |
is set to \fBEVMSERR\fR. |
| 2263 |
.Sp |
| 2264 |
Under OS/2, \f(CW$^E\fR is set to the error code of the last call to OS/2 |
| 2265 |
API either via CRT, or directly from perl. |
| 2266 |
.Sp |
| 2267 |
Under Win32, \f(CW$^E\fR always returns the last error information reported |
| 2268 |
by the Win32 call \f(CWGetLastError()\fR which describes the last error |
| 2269 |
from within the Win32 API. Most Win32\-specific code will report errors |
| 2270 |
via \f(CW$^E\fR. ANSI C and Unix-like calls set \f(CW\*(C`errno\*(C'\fR and so most |
| 2271 |
portable Perl code will report errors via \f(CW$!\fR. |
| 2272 |
.Sp |
| 2273 |
Caveats mentioned in the description of \f(CW"$!"\fR generally apply to |
| 2274 |
\&\f(CW$^E\fR, also. |
| 2275 |
.Sp |
| 2276 |
This variable was added in Perl 5.003. |
| 2277 |
.Sp |
| 2278 |
Mnemonic: Extra error explanation. |
| 2279 |
.ie n .IP $EXCEPTIONS_BEING_CAUGHT 8 |
| 2280 |
.el .IP \f(CW$EXCEPTIONS_BEING_CAUGHT\fR 8 |
| 2281 |
.IX Item "$EXCEPTIONS_BEING_CAUGHT" |
| 2282 |
.PD 0 |
| 2283 |
.IP $^S 8 |
| 2284 |
.IX Xref "$^S $EXCEPTIONS_BEING_CAUGHT" |
| 2285 |
.IX Item "$^S" |
| 2286 |
.PD |
| 2287 |
Current state of the interpreter. |
| 2288 |
.Sp |
| 2289 |
.Vb 5 |
| 2290 |
\& $^S State |
| 2291 |
\& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 2292 |
\& undef Parsing module, eval, or main program |
| 2293 |
\& true (1) Executing an eval or try block |
| 2294 |
\& false (0) Otherwise |
| 2295 |
.Ve |
| 2296 |
.Sp |
| 2297 |
The first state may happen in \f(CW$SIG{_\|_DIE_\|_}\fR and \f(CW$SIG{_\|_WARN_\|_}\fR |
| 2298 |
handlers. |
| 2299 |
.Sp |
| 2300 |
The English name \f(CW$EXCEPTIONS_BEING_CAUGHT\fR is slightly misleading, because |
| 2301 |
the \f(CW\*(C`undef\*(C'\fR value does not indicate whether exceptions are being caught, |
| 2302 |
since compilation of the main program does not catch exceptions. |
| 2303 |
.Sp |
| 2304 |
This variable was added in Perl 5.004. |
| 2305 |
.ie n .IP $WARNING 8 |
| 2306 |
.el .IP \f(CW$WARNING\fR 8 |
| 2307 |
.IX Item "$WARNING" |
| 2308 |
.PD 0 |
| 2309 |
.IP $^W 8 |
| 2310 |
.IX Xref "$^W $WARNING" |
| 2311 |
.IX Item "$^W" |
| 2312 |
.PD |
| 2313 |
The current value of the warning switch, initially true if \fB\-w\fR was |
| 2314 |
used, false otherwise, but directly modifiable. |
| 2315 |
.Sp |
| 2316 |
See also warnings. |
| 2317 |
.Sp |
| 2318 |
Mnemonic: related to the \fB\-w\fR switch. |
| 2319 |
.IP ${^WARNING_BITS} 8 |
| 2320 |
.IX Xref "${^WARNING_BITS}" |
| 2321 |
.IX Item "${^WARNING_BITS}" |
| 2322 |
The current set of warning checks enabled by the \f(CW\*(C`use warnings\*(C'\fR pragma. |
| 2323 |
It has the same scoping as the \f(CW$^H\fR and \f(CW\*(C`%^H\*(C'\fR variables. The exact |
| 2324 |
values are considered internal to the warnings pragma and may change |
| 2325 |
between versions of Perl. |
| 2326 |
.Sp |
| 2327 |
Each time a statement completes being compiled, the current value of |
| 2328 |
\&\f(CW\*(C`${^WARNING_BITS}\*(C'\fR is stored with that statement, and can later be |
| 2329 |
retrieved via \f(CW\*(C`(caller($level))[9]\*(C'\fR. |
| 2330 |
.Sp |
| 2331 |
This variable was added in Perl v5.6.0. |
| 2332 |
.ie n .IP $OS_ERROR 8 |
| 2333 |
.el .IP \f(CW$OS_ERROR\fR 8 |
| 2334 |
.IX Item "$OS_ERROR" |
| 2335 |
.PD 0 |
| 2336 |
.ie n .IP $ERRNO 8 |
| 2337 |
.el .IP \f(CW$ERRNO\fR 8 |
| 2338 |
.IX Item "$ERRNO" |
| 2339 |
.IP $! 8 |
| 2340 |
.IX Xref "$! $ERRNO $OS_ERROR" |
| 2341 |
.PD |
| 2342 |
When referenced, \f(CW$!\fR retrieves the current value |
| 2343 |
of the C \f(CW\*(C`errno\*(C'\fR integer variable. |
| 2344 |
If \f(CW$!\fR is assigned a numerical value, that value is stored in \f(CW\*(C`errno\*(C'\fR. |
| 2345 |
When referenced as a string, \f(CW$!\fR yields the system error string |
| 2346 |
corresponding to \f(CW\*(C`errno\*(C'\fR. |
| 2347 |
.Sp |
| 2348 |
Many system or library calls set \f(CW\*(C`errno\*(C'\fR if they fail, |
| 2349 |
to indicate the cause of failure. They usually do \fBnot\fR |
| 2350 |
set \f(CW\*(C`errno\*(C'\fR to zero if they succeed and may set \f(CW\*(C`errno\*(C'\fR to a |
| 2351 |
non-zero value on success. This means \f(CW\*(C`errno\*(C'\fR, hence \f(CW$!\fR, is |
| 2352 |
meaningful only \fIimmediately\fR after a \fBfailure\fR: |
| 2353 |
.Sp |
| 2354 |
.Vb 11 |
| 2355 |
\& if (open my $fh, "<", $filename) { |
| 2356 |
\& # Here $! is meaningless. |
| 2357 |
\& ... |
| 2358 |
\& } |
| 2359 |
\& else { |
| 2360 |
\& # ONLY here is $! meaningful. |
| 2361 |
\& ... |
| 2362 |
\& # Already here $! might be meaningless. |
| 2363 |
\& } |
| 2364 |
\& # Since here we might have either success or failure, |
| 2365 |
\& # $! is meaningless. |
| 2366 |
.Ve |
| 2367 |
.Sp |
| 2368 |
Here, \fImeaningless\fR means that \f(CW$!\fR may be unrelated to the outcome |
| 2369 |
of the \f(CWopen()\fR operator. Assignment to \f(CW$!\fR is similarly ephemeral. |
| 2370 |
It can be used immediately before invoking the \f(CWdie()\fR operator, |
| 2371 |
to set the exit value, or to inspect the system error string |
| 2372 |
corresponding to error \fIn\fR, or to restore \f(CW$!\fR to a meaningful state. |
| 2373 |
.Sp |
| 2374 |
Perl itself may set \f(CW\*(C`errno\*(C'\fR to a non-zero on failure even if no |
| 2375 |
system call is performed. |
| 2376 |
.Sp |
| 2377 |
Mnemonic: What just went bang? |
| 2378 |
.ie n .IP %OS_ERROR 8 |
| 2379 |
.el .IP \f(CW%OS_ERROR\fR 8 |
| 2380 |
.IX Item "%OS_ERROR" |
| 2381 |
.PD 0 |
| 2382 |
.ie n .IP %ERRNO 8 |
| 2383 |
.el .IP \f(CW%ERRNO\fR 8 |
| 2384 |
.IX Item "%ERRNO" |
| 2385 |
.IP %! 8 |
| 2386 |
.IX Xref "%! %OS_ERROR %ERRNO" |
| 2387 |
.PD |
| 2388 |
Each element of \f(CW\*(C`%!\*(C'\fR has a true value only if \f(CW$!\fR is set to that |
| 2389 |
value. For example, \f(CW$!{ENOENT}\fR is true if and only if the current |
| 2390 |
value of \f(CW$!\fR is \f(CW\*(C`ENOENT\*(C'\fR; that is, if the most recent error was "No |
| 2391 |
such file or directory" (or its moral equivalent: not all operating |
| 2392 |
systems give that exact error, and certainly not all languages). The |
| 2393 |
specific true value is not guaranteed, but in the past has generally |
| 2394 |
been the numeric value of \f(CW$!\fR. To check if a particular key is |
| 2395 |
meaningful on your system, use \f(CW\*(C`exists $!{the_key}\*(C'\fR; for a list of legal |
| 2396 |
keys, use \f(CW\*(C`keys %!\*(C'\fR. See Errno for more information, and also see |
| 2397 |
"$!". |
| 2398 |
.Sp |
| 2399 |
This variable was added in Perl 5.005. |
| 2400 |
.ie n .IP $CHILD_ERROR 8 |
| 2401 |
.el .IP \f(CW$CHILD_ERROR\fR 8 |
| 2402 |
.IX Item "$CHILD_ERROR" |
| 2403 |
.PD 0 |
| 2404 |
.IP $? 8 |
| 2405 |
.IX Xref "$? $CHILD_ERROR" |
| 2406 |
.PD |
| 2407 |
The status returned by the last pipe close, backtick (\f(CW\`\`\fR) command, |
| 2408 |
successful call to \f(CWwait()\fR or \f(CWwaitpid()\fR, or from the \f(CWsystem()\fR |
| 2409 |
operator. This is just the 16\-bit status word returned by the |
| 2410 |
traditional Unix \f(CWwait()\fR system call (or else is made up to look |
| 2411 |
like it). Thus, the exit value of the subprocess is really (\f(CW$? >> |
| 2412 |
8\fR), and \f(CW\*(C`$? & 127\*(C'\fR gives which signal, if any, the process died |
| 2413 |
from, and \f(CW\*(C`$? & 128\*(C'\fR reports whether there was a core dump. |
| 2414 |
.Sp |
| 2415 |
Additionally, if the \f(CW\*(C`h_errno\*(C'\fR variable is supported in C, its value |
| 2416 |
is returned via \f(CW$?\fR if any \f(CW\*(C`gethost*()\*(C'\fR function fails. |
| 2417 |
.Sp |
| 2418 |
If you have installed a signal handler for \f(CW\*(C`SIGCHLD\*(C'\fR, the |
| 2419 |
value of \f(CW$?\fR will usually be wrong outside that handler. |
| 2420 |
.Sp |
| 2421 |
Inside an \f(CW\*(C`END\*(C'\fR subroutine \f(CW$?\fR contains the value that is going to be |
| 2422 |
given to \f(CWexit()\fR. You can modify \f(CW$?\fR in an \f(CW\*(C`END\*(C'\fR subroutine to |
| 2423 |
change the exit status of your program. For example: |
| 2424 |
.Sp |
| 2425 |
.Vb 3 |
| 2426 |
\& END { |
| 2427 |
\& $? = 1 if $? == 255; # die would make it 255 |
| 2428 |
\& } |
| 2429 |
.Ve |
| 2430 |
.Sp |
| 2431 |
Under VMS, the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR makes \f(CW$?\fR reflect the |
| 2432 |
actual VMS exit status, instead of the default emulation of POSIX |
| 2433 |
status; see "$?" in perlvms for details. |
| 2434 |
.Sp |
| 2435 |
Mnemonic: similar to \fBsh\fR and \fBksh\fR. |
| 2436 |
.ie n .IP $EVAL_ERROR 8 |
| 2437 |
.el .IP \f(CW$EVAL_ERROR\fR 8 |
| 2438 |
.IX Item "$EVAL_ERROR" |
| 2439 |
.PD 0 |
| 2440 |
.IP $@ 8 |
| 2441 |
.IX Xref "$@ $EVAL_ERROR" |
| 2442 |
.PD |
| 2443 |
The Perl error from the last \f(CW\*(C`eval\*(C'\fR operator, i.e. the last exception that |
| 2444 |
was caught. For \f(CW\*(C`eval BLOCK\*(C'\fR, this is either a runtime error message or the |
| 2445 |
string or reference \f(CW\*(C`die\*(C'\fR was called with. The \f(CW\*(C`eval STRING\*(C'\fR form also |
| 2446 |
catches syntax errors and other compile time exceptions. |
| 2447 |
.Sp |
| 2448 |
If no error occurs, \f(CW\*(C`eval\*(C'\fR sets \f(CW$@\fR to the empty string. |
| 2449 |
.Sp |
| 2450 |
Warning messages are not collected in this variable. You can, however, |
| 2451 |
set up a routine to process warnings by setting \f(CW$SIG{_\|_WARN_\|_}\fR as |
| 2452 |
described in "%SIG". |
| 2453 |
.Sp |
| 2454 |
Mnemonic: Where was the error "at"? |
| 2455 |
.SS "Variables related to the interpreter state" |
| 2456 |
.IX Subsection "Variables related to the interpreter state" |
| 2457 |
These variables provide information about the current interpreter state. |
| 2458 |
.ie n .IP $COMPILING 8 |
| 2459 |
.el .IP \f(CW$COMPILING\fR 8 |
| 2460 |
.IX Item "$COMPILING" |
| 2461 |
.PD 0 |
| 2462 |
.IP $^C 8 |
| 2463 |
.IX Xref "$^C $COMPILING" |
| 2464 |
.IX Item "$^C" |
| 2465 |
.PD |
| 2466 |
The current value of the flag associated with the \fB\-c\fR switch. |
| 2467 |
Mainly of use with \fB\-MO=...\fR to allow code to alter its behavior |
| 2468 |
when being compiled, such as for example to \f(CW\*(C`AUTOLOAD\*(C'\fR at compile |
| 2469 |
time rather than normal, deferred loading. Setting |
| 2470 |
\&\f(CW\*(C`$^C = 1\*(C'\fR is similar to calling \f(CW\*(C`B::minus_c\*(C'\fR. |
| 2471 |
.Sp |
| 2472 |
This variable was added in Perl v5.6.0. |
| 2473 |
.ie n .IP $DEBUGGING 8 |
| 2474 |
.el .IP \f(CW$DEBUGGING\fR 8 |
| 2475 |
.IX Item "$DEBUGGING" |
| 2476 |
.PD 0 |
| 2477 |
.IP $^D 8 |
| 2478 |
.IX Xref "$^D $DEBUGGING" |
| 2479 |
.IX Item "$^D" |
| 2480 |
.PD |
| 2481 |
The current value of the debugging flags. May be read or set. Like its |
| 2482 |
command-line equivalent, you can use numeric |
| 2483 |
or symbolic values, e.g. \f(CW\*(C`$^D = 10\*(C'\fR or \f(CW\*(C`$^D = "st"\*(C'\fR. See |
| 2484 |
"\fB\-D\fR\fInumber\fR" in perlrun. The contents of this variable also affects the |
| 2485 |
debugger operation. See "Debugger Internals" in perldebguts. |
| 2486 |
.Sp |
| 2487 |
Mnemonic: value of \fB\-D\fR switch. |
| 2488 |
.IP ${^GLOBAL_PHASE} 8 |
| 2489 |
.IX Xref "${^GLOBAL_PHASE}" |
| 2490 |
.IX Item "${^GLOBAL_PHASE}" |
| 2491 |
The current phase of the perl interpreter. |
| 2492 |
.Sp |
| 2493 |
Possible values are: |
| 2494 |
.RS 8 |
| 2495 |
.IP CONSTRUCT 8 |
| 2496 |
.IX Item "CONSTRUCT" |
| 2497 |
The \f(CW\*(C`PerlInterpreter*\*(C'\fR is being constructed via \f(CW\*(C`perl_construct\*(C'\fR. This |
| 2498 |
value is mostly there for completeness and for use via the |
| 2499 |
underlying C variable \f(CW\*(C`PL_phase\*(C'\fR. It's not really possible for Perl |
| 2500 |
code to be executed unless construction of the interpreter is |
| 2501 |
finished. |
| 2502 |
.IP START 8 |
| 2503 |
.IX Item "START" |
| 2504 |
This is the global compile-time. That includes, basically, every |
| 2505 |
\&\f(CW\*(C`BEGIN\*(C'\fR block executed directly or indirectly from during the |
| 2506 |
compile-time of the top-level program. |
| 2507 |
.Sp |
| 2508 |
This phase is not called "BEGIN" to avoid confusion with |
| 2509 |
\&\f(CW\*(C`BEGIN\*(C'\fR\-blocks, as those are executed during compile-time of any |
| 2510 |
compilation unit, not just the top-level program. A new, localised |
| 2511 |
compile-time entered at run-time, for example by constructs as |
| 2512 |
\&\f(CW\*(C`eval "use SomeModule"\*(C'\fR are not global interpreter phases, and |
| 2513 |
therefore aren't reflected by \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR. |
| 2514 |
.IP CHECK 8 |
| 2515 |
.IX Item "CHECK" |
| 2516 |
Execution of any \f(CW\*(C`CHECK\*(C'\fR blocks. |
| 2517 |
.IP INIT 8 |
| 2518 |
.IX Item "INIT" |
| 2519 |
Similar to "CHECK", but for \f(CW\*(C`INIT\*(C'\fR\-blocks, not \f(CW\*(C`CHECK\*(C'\fR blocks. |
| 2520 |
.IP RUN 8 |
| 2521 |
.IX Item "RUN" |
| 2522 |
The main run-time, i.e. the execution of \f(CW\*(C`PL_main_root\*(C'\fR. |
| 2523 |
.IP END 8 |
| 2524 |
.IX Item "END" |
| 2525 |
Execution of any \f(CW\*(C`END\*(C'\fR blocks. |
| 2526 |
.IP DESTRUCT 8 |
| 2527 |
.IX Item "DESTRUCT" |
| 2528 |
Global destruction. |
| 2529 |
.RE |
| 2530 |
.RS 8 |
| 2531 |
.Sp |
| 2532 |
Also note that there's no value for UNITCHECK-blocks. That's because |
| 2533 |
those are run for each compilation unit individually, and therefore is |
| 2534 |
not a global interpreter phase. |
| 2535 |
.Sp |
| 2536 |
Not every program has to go through each of the possible phases, but |
| 2537 |
transition from one phase to another can only happen in the order |
| 2538 |
described in the above list. |
| 2539 |
.Sp |
| 2540 |
An example of all of the phases Perl code can see: |
| 2541 |
.Sp |
| 2542 |
.Vb 1 |
| 2543 |
\& BEGIN { print "compile\-time: ${^GLOBAL_PHASE}\en" } |
| 2544 |
\& |
| 2545 |
\& INIT { print "init\-time: ${^GLOBAL_PHASE}\en" } |
| 2546 |
\& |
| 2547 |
\& CHECK { print "check\-time: ${^GLOBAL_PHASE}\en" } |
| 2548 |
\& |
| 2549 |
\& { |
| 2550 |
\& package Print::Phase; |
| 2551 |
\& |
| 2552 |
\& sub new { |
| 2553 |
\& my ($class, $time) = @_; |
| 2554 |
\& return bless \e$time, $class; |
| 2555 |
\& } |
| 2556 |
\& |
| 2557 |
\& sub DESTROY { |
| 2558 |
\& my $self = shift; |
| 2559 |
\& print "$$self: ${^GLOBAL_PHASE}\en"; |
| 2560 |
\& } |
| 2561 |
\& } |
| 2562 |
\& |
| 2563 |
\& print "run\-time: ${^GLOBAL_PHASE}\en"; |
| 2564 |
\& |
| 2565 |
\& my $runtime = Print::Phase\->new( |
| 2566 |
\& "lexical variables are garbage collected before END" |
| 2567 |
\& ); |
| 2568 |
\& |
| 2569 |
\& END { print "end\-time: ${^GLOBAL_PHASE}\en" } |
| 2570 |
\& |
| 2571 |
\& our $destruct = Print::Phase\->new( |
| 2572 |
\& "package variables are garbage collected after END" |
| 2573 |
\& ); |
| 2574 |
.Ve |
| 2575 |
.Sp |
| 2576 |
This will print out |
| 2577 |
.Sp |
| 2578 |
.Vb 7 |
| 2579 |
\& compile\-time: START |
| 2580 |
\& check\-time: CHECK |
| 2581 |
\& init\-time: INIT |
| 2582 |
\& run\-time: RUN |
| 2583 |
\& lexical variables are garbage collected before END: RUN |
| 2584 |
\& end\-time: END |
| 2585 |
\& package variables are garbage collected after END: DESTRUCT |
| 2586 |
.Ve |
| 2587 |
.Sp |
| 2588 |
This variable was added in Perl 5.14.0. |
| 2589 |
.RE |
| 2590 |
.IP $^H 8 |
| 2591 |
.IX Xref "$^H" |
| 2592 |
.IX Item "$^H" |
| 2593 |
WARNING: This variable is strictly for |
| 2594 |
internal use only. Its availability, |
| 2595 |
behavior, and contents are subject to change without notice. |
| 2596 |
.Sp |
| 2597 |
This variable contains compile-time hints for the Perl interpreter. At the |
| 2598 |
end of compilation of a BLOCK the value of this variable is restored to the |
| 2599 |
value when the interpreter started to compile the BLOCK. |
| 2600 |
.Sp |
| 2601 |
Each time a statement completes being compiled, the current value of |
| 2602 |
\&\f(CW$^H\fR is stored with that statement, and can later be retrieved via |
| 2603 |
\&\f(CW\*(C`(caller($level))[8]\*(C'\fR. See "caller EXPR" in perlfunc. |
| 2604 |
.Sp |
| 2605 |
When perl begins to parse any block construct that provides a lexical scope |
| 2606 |
(e.g., eval body, required file, subroutine body, loop body, or conditional |
| 2607 |
block), the existing value of \f(CW$^H\fR is saved, but its value is left unchanged. |
| 2608 |
When the compilation of the block is completed, it regains the saved value. |
| 2609 |
Between the points where its value is saved and restored, code that |
| 2610 |
executes within BEGIN blocks is free to change the value of \f(CW$^H\fR. |
| 2611 |
.Sp |
| 2612 |
This behavior provides the semantic of lexical scoping, and is used in, |
| 2613 |
for instance, the \f(CW\*(C`use strict\*(C'\fR pragma. |
| 2614 |
.Sp |
| 2615 |
The contents should be an integer; different bits of it are used for |
| 2616 |
different pragmatic flags. Here's an example: |
| 2617 |
.Sp |
| 2618 |
.Vb 1 |
| 2619 |
\& sub add_100 { $^H |= 0x100 } |
| 2620 |
\& |
| 2621 |
\& sub foo { |
| 2622 |
\& BEGIN { add_100() } |
| 2623 |
\& bar\->baz($boon); |
| 2624 |
\& } |
| 2625 |
.Ve |
| 2626 |
.Sp |
| 2627 |
Consider what happens during execution of the BEGIN block. At this point |
| 2628 |
the BEGIN block has already been compiled, but the body of \f(CWfoo()\fR is still |
| 2629 |
being compiled. The new value of \f(CW$^H\fR |
| 2630 |
will therefore be visible only while |
| 2631 |
the body of \f(CWfoo()\fR is being compiled. |
| 2632 |
.Sp |
| 2633 |
Substitution of \f(CW\*(C`BEGIN { add_100() }\*(C'\fR block with: |
| 2634 |
.Sp |
| 2635 |
.Vb 1 |
| 2636 |
\& BEGIN { require strict; strict\->import(\*(Aqvars\*(Aq) } |
| 2637 |
.Ve |
| 2638 |
.Sp |
| 2639 |
demonstrates how \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR is implemented. Here's a conditional |
| 2640 |
version of the same lexical pragma: |
| 2641 |
.Sp |
| 2642 |
.Vb 3 |
| 2643 |
\& BEGIN { |
| 2644 |
\& require strict; strict\->import(\*(Aqvars\*(Aq) if $condition |
| 2645 |
\& } |
| 2646 |
.Ve |
| 2647 |
.Sp |
| 2648 |
This variable was added in Perl 5.003. |
| 2649 |
.IP %^H 8 |
| 2650 |
.IX Xref "%^H" |
| 2651 |
.IX Item "%^H" |
| 2652 |
The \f(CW\*(C`%^H\*(C'\fR hash provides the same scoping semantics as \f(CW$^H\fR. This |
| 2653 |
makes it useful for implementing lexically scoped pragmas. See perlpragma. |
| 2654 |
All the entries are stringified when accessed at runtime, so only simple values |
| 2655 |
can be accommodated. This means no references to objects, for example. |
| 2656 |
.Sp |
| 2657 |
Each time a statement completes being compiled, the current value of |
| 2658 |
\&\f(CW\*(C`%^H\*(C'\fR is stored with that statement, and can later be retrieved via |
| 2659 |
\&\f(CW\*(C`(caller($level))[10]\*(C'\fR. See "caller EXPR" in perlfunc. |
| 2660 |
.Sp |
| 2661 |
When putting items into \f(CW\*(C`%^H\*(C'\fR, in order to avoid conflicting with other |
| 2662 |
users of the hash there is a convention regarding which keys to use. |
| 2663 |
A module should use only keys that begin with the module's name (the |
| 2664 |
name of its main package) and a "/" character. For example, a module |
| 2665 |
\&\f(CW\*(C`Foo::Bar\*(C'\fR should use keys such as \f(CW\*(C`Foo::Bar/baz\*(C'\fR. |
| 2666 |
.Sp |
| 2667 |
This variable was added in Perl v5.6.0. |
| 2668 |
.IP ${^OPEN} 8 |
| 2669 |
.IX Xref "${^OPEN}" |
| 2670 |
.IX Item "${^OPEN}" |
| 2671 |
An internal variable used by PerlIO. A string in two parts, separated |
| 2672 |
by a \f(CW\*(C`\e0\*(C'\fR byte, the first part describes the input layers, the second |
| 2673 |
part describes the output layers. |
| 2674 |
.Sp |
| 2675 |
This is the mechanism that applies the lexical effects of the open |
| 2676 |
pragma, and the main program scope effects of the \f(CW\*(C`io\*(C'\fR or \f(CW\*(C`D\*(C'\fR options |
| 2677 |
for the \-C command-line switch and |
| 2678 |
PERL_UNICODE environment variable. |
| 2679 |
.Sp |
| 2680 |
The functions \f(CWaccept()\fR, \f(CWopen()\fR, \f(CWpipe()\fR, \f(CWreadpipe()\fR (as well |
| 2681 |
as the related \f(CW\*(C`qx\*(C'\fR and \f(CW\`STRING\`\fR operators), \f(CWsocket()\fR, |
| 2682 |
\&\f(CWsocketpair()\fR, and \f(CWsysopen()\fR are affected by the lexical value of |
| 2683 |
this variable. The implicit "ARGV" handle opened by \f(CWreadline()\fR (or |
| 2684 |
the related \f(CW\*(C`<>\*(C'\fR and \f(CW\*(C`<<>>\*(C'\fR operators) on passed filenames is |
| 2685 |
also affected (but not if it opens \f(CW\*(C`STDIN\*(C'\fR). If this variable is not |
| 2686 |
set, these functions will set the default layers as described in |
| 2687 |
"Defaults and how to override them" in PerlIO. |
| 2688 |
.Sp |
| 2689 |
\&\f(CWopen()\fR ignores this variable (and the default layers) when called with |
| 2690 |
3 arguments and explicit layers are specified. Indirect calls to these |
| 2691 |
functions via modules like IO::Handle are not affected as they occur |
| 2692 |
in a different lexical scope. Directory handles such as opened by |
| 2693 |
\&\f(CWopendir()\fR are not currently affected. |
| 2694 |
.Sp |
| 2695 |
This variable was added in Perl v5.8.0. |
| 2696 |
.ie n .IP $PERLDB 8 |
| 2697 |
.el .IP \f(CW$PERLDB\fR 8 |
| 2698 |
.IX Item "$PERLDB" |
| 2699 |
.PD 0 |
| 2700 |
.IP $^P 8 |
| 2701 |
.IX Xref "$^P $PERLDB" |
| 2702 |
.IX Item "$^P" |
| 2703 |
.PD |
| 2704 |
The internal variable for debugging support. The meanings of the |
| 2705 |
various bits are subject to change, but currently indicate: |
| 2706 |
.RS 8 |
| 2707 |
.IP 0x01 6 |
| 2708 |
.IX Item "0x01" |
| 2709 |
Debug subroutine enter/exit. |
| 2710 |
.IP 0x02 6 |
| 2711 |
.IX Item "0x02" |
| 2712 |
Line-by-line debugging. Causes \f(CWDB::DB()\fR subroutine to be called for |
| 2713 |
each statement executed. Also causes saving source code lines (like |
| 2714 |
0x400). |
| 2715 |
.IP 0x04 6 |
| 2716 |
.IX Item "0x04" |
| 2717 |
Switch off optimizations. |
| 2718 |
.IP 0x08 6 |
| 2719 |
.IX Item "0x08" |
| 2720 |
Preserve more data for future interactive inspections. |
| 2721 |
.IP 0x10 6 |
| 2722 |
.IX Item "0x10" |
| 2723 |
Keep info about source lines on which a subroutine is defined. |
| 2724 |
.IP 0x20 6 |
| 2725 |
.IX Item "0x20" |
| 2726 |
Start with single-step on. |
| 2727 |
.IP 0x40 6 |
| 2728 |
.IX Item "0x40" |
| 2729 |
Use subroutine address instead of name when reporting. |
| 2730 |
.IP 0x80 6 |
| 2731 |
.IX Item "0x80" |
| 2732 |
Report \f(CW\*(C`goto &subroutine\*(C'\fR as well. |
| 2733 |
.IP 0x100 6 |
| 2734 |
.IX Item "0x100" |
| 2735 |
Provide informative "file" names for evals based on the place they were compiled. |
| 2736 |
.IP 0x200 6 |
| 2737 |
.IX Item "0x200" |
| 2738 |
Provide informative names to anonymous subroutines based on the place they |
| 2739 |
were compiled. |
| 2740 |
.IP 0x400 6 |
| 2741 |
.IX Item "0x400" |
| 2742 |
Save source code lines into \f(CW\*(C`@{"_<$filename"}\*(C'\fR. |
| 2743 |
.IP 0x800 6 |
| 2744 |
.IX Item "0x800" |
| 2745 |
When saving source, include evals that generate no subroutines. |
| 2746 |
.IP 0x1000 6 |
| 2747 |
.IX Item "0x1000" |
| 2748 |
When saving source, include source that did not compile. |
| 2749 |
.RE |
| 2750 |
.RS 8 |
| 2751 |
.Sp |
| 2752 |
Some bits may be relevant at compile-time only, some at |
| 2753 |
run-time only. This is a new mechanism and the details may change. |
| 2754 |
See also perldebguts. |
| 2755 |
.RE |
| 2756 |
.IP ${^TAINT} 8 |
| 2757 |
.IX Xref "${^TAINT}" |
| 2758 |
.IX Item "${^TAINT}" |
| 2759 |
Reflects if taint mode is on or off. 1 for on (the program was run with |
| 2760 |
\&\fB\-T\fR), 0 for off, \-1 when only taint warnings are enabled (i.e. with |
| 2761 |
\&\fB\-t\fR or \fB\-TU\fR). |
| 2762 |
.Sp |
| 2763 |
Note: if your perl was built without taint support (see perlsec), |
| 2764 |
then \f(CW\*(C`${^TAINT}\*(C'\fR will always be 0, even if the program was run with \fB\-T\fR). |
| 2765 |
.Sp |
| 2766 |
This variable is read-only. |
| 2767 |
.Sp |
| 2768 |
This variable was added in Perl v5.8.0. |
| 2769 |
.IP ${^SAFE_LOCALES} 8 |
| 2770 |
.IX Xref "${^SAFE_LOCALES}" |
| 2771 |
.IX Item "${^SAFE_LOCALES}" |
| 2772 |
Reflects if safe locale operations are available to this perl (when the |
| 2773 |
value is 1) or not (the value is 0). This variable is always 1 if the |
| 2774 |
perl has been compiled without threads. It is also 1 if this perl is |
| 2775 |
using thread-safe locale operations. Note that an individual thread may |
| 2776 |
choose to use the global locale (generally unsafe) by calling |
| 2777 |
"switch_to_global_locale" in perlapi. This variable currently is still |
| 2778 |
set to 1 in such threads. |
| 2779 |
.Sp |
| 2780 |
This variable is read-only. |
| 2781 |
.Sp |
| 2782 |
This variable was added in Perl v5.28.0. |
| 2783 |
.IP ${^UNICODE} 8 |
| 2784 |
.IX Xref "${^UNICODE}" |
| 2785 |
.IX Item "${^UNICODE}" |
| 2786 |
Reflects certain Unicode settings of Perl. See |
| 2787 |
perlrun documentation for the \f(CW\*(C`\-C\*(C'\fR |
| 2788 |
switch for more information about the possible values. |
| 2789 |
.Sp |
| 2790 |
This variable is set during Perl startup and is thereafter read-only. |
| 2791 |
.Sp |
| 2792 |
This variable was added in Perl v5.8.2. |
| 2793 |
.IP ${^UTF8CACHE} 8 |
| 2794 |
.IX Xref "${^UTF8CACHE}" |
| 2795 |
.IX Item "${^UTF8CACHE}" |
| 2796 |
This variable controls the state of the internal UTF\-8 offset caching code. |
| 2797 |
1 for on (the default), 0 for off, \-1 to debug the caching code by checking |
| 2798 |
all its results against linear scans, and panicking on any discrepancy. |
| 2799 |
.Sp |
| 2800 |
This variable was added in Perl v5.8.9. It is subject to change or |
| 2801 |
removal without notice, but is currently used to avoid recalculating the |
| 2802 |
boundaries of multi-byte UTF\-8\-encoded characters. |
| 2803 |
.IP ${^UTF8LOCALE} 8 |
| 2804 |
.IX Xref "${^UTF8LOCALE}" |
| 2805 |
.IX Item "${^UTF8LOCALE}" |
| 2806 |
This variable indicates whether a UTF\-8 locale was detected by perl at |
| 2807 |
startup. This information is used by perl when it's in |
| 2808 |
adjust\-utf8ness\-to\-locale mode (as when run with the \f(CW\*(C`\-CL\*(C'\fR command-line |
| 2809 |
switch); see perlrun for more info on |
| 2810 |
this. |
| 2811 |
.Sp |
| 2812 |
This variable was added in Perl v5.8.8. |
| 2813 |
.SS "Deprecated and removed variables" |
| 2814 |
.IX Subsection "Deprecated and removed variables" |
| 2815 |
Deprecating a variable announces the intent of the perl maintainers to |
| 2816 |
eventually remove the variable from the language. It may still be |
| 2817 |
available despite its status. Using a deprecated variable triggers |
| 2818 |
a warning. |
| 2819 |
.PP |
| 2820 |
Once a variable is removed, its use triggers an error telling you |
| 2821 |
the variable is unsupported. |
| 2822 |
.PP |
| 2823 |
See perldiag for details about error messages. |
| 2824 |
.IP $# 8 |
| 2825 |
.IX Xref "$#" |
| 2826 |
\&\f(CW$#\fR was a variable that could be used to format printed numbers. |
| 2827 |
After a deprecation cycle, its magic was removed in Perl v5.10.0 and |
| 2828 |
using it now triggers a warning: \f(CW\*(C`$# is no longer supported\*(C'\fR. |
| 2829 |
.Sp |
| 2830 |
This is not the sigil you use in front of an array name to get the |
| 2831 |
last index, like \f(CW$#array\fR. That's still how you get the last index |
| 2832 |
of an array in Perl. The two have nothing to do with each other. |
| 2833 |
.Sp |
| 2834 |
Deprecated in Perl 5. |
| 2835 |
.Sp |
| 2836 |
Removed in Perl v5.10.0. |
| 2837 |
.IP $* 8 |
| 2838 |
.IX Xref "$*" |
| 2839 |
\&\f(CW$*\fR was a variable that you could use to enable multiline matching. |
| 2840 |
After a deprecation cycle, its magic was removed in Perl v5.10.0. |
| 2841 |
Using it now triggers a warning: \f(CW\*(C`$* is no longer supported\*(C'\fR. |
| 2842 |
You should use the \f(CW\*(C`/s\*(C'\fR and \f(CW\*(C`/m\*(C'\fR regexp modifiers instead. |
| 2843 |
.Sp |
| 2844 |
Deprecated in Perl 5. |
| 2845 |
.Sp |
| 2846 |
Removed in Perl v5.10.0. |
| 2847 |
.IP $[ 8 |
| 2848 |
.IX Xref "$[" |
| 2849 |
This variable stores the index of the first element in an array, and |
| 2850 |
of the first character in a substring. The default is 0, but you could |
| 2851 |
theoretically set it to 1 to make Perl behave more like \fBawk\fR (or Fortran) |
| 2852 |
when subscripting and when evaluating the \fBindex()\fR and \fBsubstr()\fR functions. |
| 2853 |
.Sp |
| 2854 |
As of release 5 of Perl, assignment to \f(CW$[\fR is treated as a compiler |
| 2855 |
directive, and cannot influence the behavior of any other file. |
| 2856 |
(That's why you can only assign compile-time constants to it.) |
| 2857 |
Its use is highly discouraged. |
| 2858 |
.Sp |
| 2859 |
Prior to Perl v5.10.0, assignment to \f(CW$[\fR could be seen from outer lexical |
| 2860 |
scopes in the same file, unlike other compile-time directives (such as |
| 2861 |
strict). Using \fBlocal()\fR on it would bind its value strictly to a lexical |
| 2862 |
block. Now it is always lexically scoped. |
| 2863 |
.Sp |
| 2864 |
As of Perl v5.16.0, it is implemented by the arybase module. |
| 2865 |
.Sp |
| 2866 |
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, |
| 2867 |
\&\f(CW$[\fR no longer has any effect, and always contains 0. |
| 2868 |
Assigning 0 to it is permitted, but any other value will produce an error. |
| 2869 |
.Sp |
| 2870 |
Mnemonic: [ begins subscripts. |
| 2871 |
.Sp |
| 2872 |
Deprecated in Perl v5.12.0. |
| 2873 |
.IP ${^ENCODING} 8 |
| 2874 |
.IX Xref "${^ENCODING}" |
| 2875 |
.IX Item "${^ENCODING}" |
| 2876 |
This variable is no longer supported. |
| 2877 |
.Sp |
| 2878 |
It used to hold the \fIobject reference\fR to the \f(CW\*(C`Encode\*(C'\fR object that was |
| 2879 |
used to convert the source code to Unicode. |
| 2880 |
.Sp |
| 2881 |
Its purpose was to allow your non-ASCII Perl |
| 2882 |
scripts not to have to be written in UTF\-8; this was |
| 2883 |
useful before editors that worked on UTF\-8 encoded text were common, but |
| 2884 |
that was long ago. It caused problems, such as affecting the operation |
| 2885 |
of other modules that weren't expecting it, causing general mayhem. |
| 2886 |
.Sp |
| 2887 |
If you need something like this functionality, it is recommended that use |
| 2888 |
you a simple source filter, such as Filter::Encoding. |
| 2889 |
.Sp |
| 2890 |
If you are coming here because code of yours is being adversely affected |
| 2891 |
by someone's use of this variable, you can usually work around it by |
| 2892 |
doing this: |
| 2893 |
.Sp |
| 2894 |
.Vb 1 |
| 2895 |
\& local ${^ENCODING}; |
| 2896 |
.Ve |
| 2897 |
.Sp |
| 2898 |
near the beginning of the functions that are getting broken. This |
| 2899 |
undefines the variable during the scope of execution of the including |
| 2900 |
function. |
| 2901 |
.Sp |
| 2902 |
This variable was added in Perl 5.8.2 and removed in 5.26.0. |
| 2903 |
Setting it to anything other than \f(CW\*(C`undef\*(C'\fR was made fatal in Perl 5.28.0. |
| 2904 |
.IP ${^WIN32_SLOPPY_STAT} 8 |
| 2905 |
.IX Xref "${^WIN32_SLOPPY_STAT} sitecustomize sitecustomize.pl" |
| 2906 |
.IX Item "${^WIN32_SLOPPY_STAT}" |
| 2907 |
This variable no longer has any function. |
| 2908 |
.Sp |
| 2909 |
This variable was added in Perl v5.10.0 and removed in Perl v5.34.0. |