Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlvar - Perl predefined variables | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
b0c22438 | 7 | =head2 The Syntax of Variable Names |
8 | ||
9 | Variable names in Perl can have several formats. Usually, they | |
10 | must begin with a letter or underscore, in which case they can be | |
11 | arbitrarily long (up to an internal limit of 251 characters) and | |
12 | may contain letters, digits, underscores, or the special sequence | |
13 | C<::> or C<'>. In this case, the part before the last C<::> or | |
14 | C<'> is taken to be a I<package qualifier>; see L<perlmod>. | |
15 | ||
16 | Perl variable names may also be a sequence of digits or a single | |
17 | punctuation or control character. These names are all reserved for | |
18 | special uses by Perl; for example, the all-digits names are used | |
19 | to hold data captured by backreferences after a regular expression | |
20 | match. Perl has a special syntax for the single-control-character | |
21 | names: It understands C<^X> (caret C<X>) to mean the control-C<X> | |
22 | character. For example, the notation C<$^W> (dollar-sign caret | |
23 | C<W>) is the scalar variable whose name is the single character | |
24 | control-C<W>. This is better than typing a literal control-C<W> | |
25 | into your program. | |
26 | ||
27 | Since Perl 5.6, Perl variable names may be alphanumeric | |
28 | strings that begin with control characters (or better yet, a caret). | |
29 | These variables must be written in the form C<${^Foo}>; the braces | |
30 | are not optional. C<${^Foo}> denotes the scalar variable whose | |
31 | name is a control-C<F> followed by two C<o>'s. These variables are | |
32 | reserved for future special uses by Perl, except for the ones that | |
33 | begin with C<^_> (control-underscore or caret-underscore). No | |
34 | control-character name that begins with C<^_> will acquire a special | |
35 | meaning in any future version of Perl; such names may therefore be | |
36 | used safely in programs. C<$^_> itself, however, I<is> reserved. | |
37 | ||
38 | Perl identifiers that begin with digits, control characters, or | |
39 | punctuation characters are exempt from the effects of the C<package> | |
40 | declaration and are always forced to be in package C<main>; they are | |
41 | also exempt from C<strict 'vars'> errors. A few other names are also | |
42 | exempt in these ways: | |
43 | ||
44 | ENV STDIN | |
45 | INC STDOUT | |
46 | ARGV STDERR | |
47 | ARGVOUT _ | |
48 | SIG | |
49 | ||
50 | In particular, the new special C<${^_XYZ}> variables are always taken | |
51 | to be in package C<main>, regardless of any C<package> declarations | |
52 | presently in scope. | |
53 | ||
54 | =head1 SPECIAL VARIABLES | |
a0d0e21e | 55 | |
b0c18621 | 56 | The following names have special meaning to Perl. Most |
14218588 GS |
57 | punctuation names have reasonable mnemonics, or analogs in the |
58 | shells. Nevertheless, if you wish to use long variable names, | |
59 | you need only say | |
a0d0e21e LW |
60 | |
61 | use English; | |
62 | ||
a1ce9542 JF |
63 | at the top of your program. This aliases all the short names to the long |
64 | names in the current package. Some even have medium names, generally | |
65 | borrowed from B<awk>. In general, it's best to use the | |
a0d0e21e | 66 | |
a1ce9542 JF |
67 | use English '-no_match_vars'; |
68 | ||
69 | invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids | |
70 | a certain performance hit with the use of regular expressions. See | |
71 | L<English>. | |
72 | ||
b0c22438 | 73 | =head2 General Variables |
a0d0e21e LW |
74 | |
75 | =item $ARG | |
76 | ||
77 | =item $_ | |
a054c801 | 78 | X<$_> X<$ARG> |
a0d0e21e | 79 | |
b0c22438 | 80 | The default input and pattern-searching space. The following pairs are |
a0d0e21e LW |
81 | equivalent: |
82 | ||
19799a22 | 83 | while (<>) {...} # equivalent only in while! |
54310121 | 84 | while (defined($_ = <>)) {...} |
a0d0e21e LW |
85 | |
86 | /^Subject:/ | |
87 | $_ =~ /^Subject:/ | |
88 | ||
89 | tr/a-z/A-Z/ | |
90 | $_ =~ tr/a-z/A-Z/ | |
91 | ||
19799a22 GS |
92 | chomp |
93 | chomp($_) | |
a0d0e21e | 94 | |
b0c22438 | 95 | Here are the places where Perl will assume C<$_> even if you |
cb1a09d0 AD |
96 | don't use it: |
97 | ||
98 | =over 3 | |
99 | ||
100 | =item * | |
101 | ||
db1511c8 GS |
102 | The following functions: |
103 | ||
b0169937 GS |
104 | abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob, |
105 | hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, | |
106 | quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), | |
b0c18621 | 107 | rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst, |
b0169937 | 108 | unlink, unpack. |
cb1a09d0 AD |
109 | |
110 | =item * | |
111 | ||
db1511c8 GS |
112 | All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN. |
113 | See L<perlfunc/-X> | |
114 | ||
cb1a09d0 AD |
115 | |
116 | =item * | |
117 | ||
b0169937 GS |
118 | The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>) |
119 | when used without an C<=~> operator. | |
cb1a09d0 | 120 | |
54310121 | 121 | =item * |
cb1a09d0 AD |
122 | |
123 | The default iterator variable in a C<foreach> loop if no other | |
124 | variable is supplied. | |
125 | ||
54310121 | 126 | =item * |
cb1a09d0 | 127 | |
b0c22438 | 128 | The implicit iterator variable in the C<grep()> and C<map()> functions. |
cb1a09d0 | 129 | |
54310121 | 130 | =item * |
cb1a09d0 | 131 | |
b0c22438 | 132 | The implicit variable of C<given()>. |
db1511c8 GS |
133 | |
134 | =item * | |
135 | ||
c47ff5f1 | 136 | The default place to put an input record when a C<< <FH> >> |
cb1a09d0 | 137 | operation's result is tested by itself as the sole criterion of a C<while> |
b0c22438 | 138 | test. Outside a C<while> test, this will not happen. |
cb1a09d0 AD |
139 | |
140 | =back | |
141 | ||
59f00321 | 142 | As C<$_> is a global variable, this may lead in some cases to unwanted |
b0c22438 | 143 | side-effects. As of perl 5.9.1, you can now use a lexical version of |
144 | C<$_> by declaring it in a file or in a block with C<my>. Moreover, | |
4fd88bf8 | 145 | declaring C<our $_> restores the global C<$_> in the current scope. |
59f00321 | 146 | |
b0c22438 | 147 | Mnemonic: underline is understood in certain operations. |
a0d0e21e | 148 | |
6e2995f4 | 149 | =back |
150 | ||
151 | =over 8 | |
152 | ||
a1db74c9 JH |
153 | =item $a |
154 | ||
155 | =item $b | |
a054c801 | 156 | X<$a> X<$b> |
a1db74c9 | 157 | |
b0c22438 | 158 | Special package variables when using C<sort()>, see L<perlfunc/sort>. |
159 | Because of this specialness C<$a> and C<$b> don't need to be declared | |
160 | (using C<use vars>, or C<our()>) even when using the C<strict 'vars'> | |
161 | pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to | |
162 | be able to use them in the C<sort()> comparison block or function. | |
a1db74c9 | 163 | |
b0c22438 | 164 | =item $SUBSCRIPT_SEPARATOR |
a1db74c9 | 165 | |
b0c22438 | 166 | =item $SUBSEP |
a1db74c9 | 167 | |
b0c22438 | 168 | =item $; |
169 | X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR> | |
a0d0e21e | 170 | |
b0c22438 | 171 | The subscript separator for multidimensional array emulation. If you |
172 | refer to a hash element as | |
a0d0e21e | 173 | |
b0c22438 | 174 | $foo{$a,$b,$c} |
a0d0e21e | 175 | |
b0c22438 | 176 | it really means |
a0d0e21e | 177 | |
b0c22438 | 178 | $foo{join($;, $a, $b, $c)} |
a0d0e21e | 179 | |
b0c22438 | 180 | But don't put |
19ddd453 | 181 | |
b0c22438 | 182 | @foo{$a,$b,$c} # a slice--note the @ |
a054c801 | 183 | |
b0c22438 | 184 | which means |
cde0cee5 | 185 | |
b0c22438 | 186 | ($foo{$a},$foo{$b},$foo{$c}) |
cde0cee5 | 187 | |
b0c22438 | 188 | Default is "\034", the same as SUBSEP in B<awk>. If your |
189 | keys contain binary data there might not be any safe value for C<$;>. | |
a0d0e21e | 190 | |
b0c22438 | 191 | Consider using "real" multidimensional arrays as described |
192 | in L<perllol>. | |
a0d0e21e | 193 | |
b0c22438 | 194 | Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. |
a0d0e21e | 195 | |
b0c22438 | 196 | =item ${^ENCODING} |
197 | X<$^ENCODING> | |
19ddd453 | 198 | |
b0c22438 | 199 | The I<object reference> to the C<Encode> object that is used to convert |
200 | the source code to Unicode. Thanks to this variable your Perl script | |
201 | does not have to be written in UTF-8. Default is I<undef>. The direct | |
202 | manipulation of this variable is highly discouraged. | |
a054c801 | 203 | |
b0c22438 | 204 | This variable was added in Perl 5.8.2. |
cde0cee5 | 205 | |
b0c22438 | 206 | =item $PROCESS_ID |
cde0cee5 | 207 | |
b0c22438 | 208 | =item $PID |
a0d0e21e | 209 | |
b0c22438 | 210 | =item $$ |
211 | X<$$> X<$PID> X<$PROCESS_ID> | |
a0d0e21e | 212 | |
b0c22438 | 213 | The process number of the Perl running this script. You should |
214 | consider this variable read-only, although it will be altered | |
215 | across C<fork()> calls. | |
a0d0e21e | 216 | |
b0c22438 | 217 | Note for Linux users: on Linux, the C functions C<getpid()> and |
218 | C<getppid()> return different values from different threads. In order to | |
219 | be portable, this behavior is not reflected by C<$$>, whose value remains | |
220 | consistent across threads. If you want to call the underlying C<getpid()>, | |
221 | you may use the CPAN module C<Linux::Pid>. | |
a0d0e21e | 222 | |
b0c22438 | 223 | Mnemonic: same as shells. |
224 | ||
225 | =item $REAL_USER_ID | |
a0d0e21e | 226 | |
b0c22438 | 227 | =item $UID |
19ddd453 | 228 | |
b0c22438 | 229 | =item $< |
230 | X<< $< >> X<$UID> X<$REAL_USER_ID> | |
a054c801 | 231 | |
b0c22438 | 232 | The real uid of this process. You can change both the real uid and the |
233 | effective uid at the same time by using C<POSIX::setuid()>. Since | |
234 | changes to C<< $< >> require a system call, check C<$!> after a change | |
235 | attempt to detect any possible errors. | |
cde0cee5 | 236 | |
b0c22438 | 237 | Mnemonic: it's the uid you came I<from>, if you're running setuid. |
cde0cee5 | 238 | |
b0c22438 | 239 | =item $EFFECTIVE_USER_ID |
a0d0e21e | 240 | |
b0c22438 | 241 | =item $EUID |
a0d0e21e | 242 | |
b0c22438 | 243 | =item $> |
244 | X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> | |
a0d0e21e | 245 | |
b0c22438 | 246 | The effective uid of this process. For example: |
a0d0e21e | 247 | |
b0c22438 | 248 | $< = $>; # set real to effective uid |
249 | ($<,$>) = ($>,$<); # swap real and effective uid | |
a0d0e21e | 250 | |
b0c22438 | 251 | You can change both the effective uid and the real uid at the same |
252 | time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check | |
253 | to C<$!> to detect any possible errors after an attempted change. | |
daaddde1 | 254 | |
b0c22438 | 255 | C<< $< >> and C<< $> >> can be swapped only on machines |
256 | supporting C<setreuid()>. | |
a01268b5 | 257 | |
b0c22438 | 258 | Mnemonic: it's the uid you went I<to>, if you're running setuid. |
ad83b128 | 259 | |
b0c22438 | 260 | =item $REAL_GROUP_ID |
a01268b5 | 261 | |
b0c22438 | 262 | =item $GID |
a01268b5 | 263 | |
b0c22438 | 264 | =item $( |
265 | X<$(> X<$GID> X<$REAL_GROUP_ID> | |
a01268b5 | 266 | |
b0c22438 | 267 | The real gid of this process. If you are on a machine that supports |
268 | membership in multiple groups simultaneously, gives a space separated | |
269 | list of groups you are in. The first number is the one returned by | |
270 | C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be | |
271 | the same as the first number. | |
a01268b5 | 272 | |
b0c22438 | 273 | However, a value assigned to C<$(> must be a single number used to |
274 | set the real gid. So the value given by C<$(> should I<not> be assigned | |
275 | back to C<$(> without being forced numeric, such as by adding zero. Note | |
276 | that this is different to the effective gid (C<$)>) which does take a | |
277 | list. | |
fe307981 | 278 | |
b0c22438 | 279 | You can change both the real gid and the effective gid at the same |
280 | time by using C<POSIX::setgid()>. Changes to C<$(> require a check to C<$!> | |
281 | to detect any possible errors after an attempted change. | |
6cef1e77 | 282 | |
b0c22438 | 283 | Mnemonic: parentheses are used to I<group> things. The real gid is the |
284 | group you I<left>, if you're running setgid. | |
6cef1e77 | 285 | |
b0c22438 | 286 | =item $EFFECTIVE_GROUP_ID |
8e08999f | 287 | |
b0c22438 | 288 | =item $EGID |
81714fb9 | 289 | |
b0c22438 | 290 | =item $) |
291 | X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> | |
81714fb9 | 292 | |
b0c22438 | 293 | The effective gid of this process. If you are on a machine that |
294 | supports membership in multiple groups simultaneously, gives a space | |
295 | separated list of groups you are in. The first number is the one | |
296 | returned by C<getegid()>, and the subsequent ones by C<getgroups()>, | |
297 | one of which may be the same as the first number. | |
81714fb9 | 298 | |
b0c22438 | 299 | Similarly, a value assigned to C<$)> must also be a space-separated |
300 | list of numbers. The first number sets the effective gid, and | |
301 | the rest (if any) are passed to C<setgroups()>. To get the effect of an | |
302 | empty list for C<setgroups()>, just repeat the new effective gid; that is, | |
303 | to force an effective gid of 5 and an effectively empty C<setgroups()> | |
304 | list, say C< $) = "5 5" >. | |
81714fb9 | 305 | |
b0c22438 | 306 | You can change both the effective gid and the real gid at the same |
307 | time by using C<POSIX::setgid()> (use only a single numeric argument). | |
308 | Changes to C<$)> require a check to C<$!> to detect any possible errors | |
309 | after an attempted change. | |
44a2ac75 | 310 | |
b0c22438 | 311 | C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on |
312 | machines that support the corresponding I<set[re][ug]id()> routine. C<$(> | |
313 | and C<$)> can be swapped only on machines supporting C<setregid()>. | |
3195cf34 | 314 | |
b0c22438 | 315 | Mnemonic: parentheses are used to I<group> things. The effective gid |
316 | is the group that's I<right> for you, if you're running setgid. | |
44a2ac75 | 317 | |
b0c22438 | 318 | =item $PROGRAM_NAME |
a0d0e21e | 319 | |
b0c22438 | 320 | =item $0 |
321 | X<$0> X<$PROGRAM_NAME> | |
a0d0e21e | 322 | |
b0c22438 | 323 | Contains the name of the program being executed. |
a0d0e21e | 324 | |
b0c22438 | 325 | On some (read: not all) operating systems assigning to C<$0> modifies |
326 | the argument area that the C<ps> program sees. On some platforms you | |
327 | may have to use special C<ps> options or a different C<ps> to see the | |
328 | changes. Modifying the C<$0> is more useful as a way of indicating the | |
329 | current program state than it is for hiding the program you're | |
330 | running. | |
a0d0e21e | 331 | |
b0c22438 | 332 | Note that there are platform specific limitations on the maximum |
333 | length of C<$0>. In the most extreme case it may be limited to the | |
334 | space occupied by the original C<$0>. | |
fcc7d916 | 335 | |
b0c22438 | 336 | In some platforms there may be arbitrary amount of padding, for |
337 | example space characters, after the modified name as shown by C<ps>. | |
338 | In some platforms this padding may extend all the way to the original | |
339 | length of the argument area, no matter what you do (this is the case | |
340 | for example with Linux 2.2). | |
fcc7d916 | 341 | |
b0c22438 | 342 | Note for BSD users: setting C<$0> does not completely remove "perl" |
343 | from the ps(1) output. For example, setting C<$0> to C<"foobar"> may | |
344 | result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix | |
345 | and the " (perl)" suffix are shown depends on your exact BSD variant | |
346 | and version). This is an operating system feature, Perl cannot help it. | |
fcc7d916 | 347 | |
b0c22438 | 348 | In multithreaded scripts Perl coordinates the threads so that any |
349 | thread may modify its copy of the C<$0> and the change becomes visible | |
350 | to ps(1) (assuming the operating system plays along). Note that | |
351 | the view of C<$0> the other threads have will not change since they | |
352 | have their own copies of it. | |
fcc7d916 | 353 | |
b0c22438 | 354 | If the program has been given to perl via the switches C<-e> or C<-E>, |
355 | C<$0> will contain the string C<"-e">. | |
fcc7d916 | 356 | |
b0c22438 | 357 | On Linux as of perl 5.14 the legacy process name will be set with |
358 | L<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as | |
359 | perl has done since version 4.000. Now system utilities that read the | |
360 | legacy process name such as ps, top and killall will recognize the | |
361 | name you set when assigning to C<$0>. The string you supply will be | |
362 | cut off at 16 bytes, this is a limitation imposed by Linux. | |
fcc7d916 | 363 | |
b0c22438 | 364 | Mnemonic: same as B<sh> and B<ksh>. |
365 | ||
366 | =item $COMPILING | |
a0d0e21e | 367 | |
b0c22438 | 368 | =item $^C |
369 | X<$^C> X<$COMPILING> | |
a0d0e21e | 370 | |
b0c22438 | 371 | The current value of the flag associated with the B<-c> switch. |
372 | Mainly of use with B<-MO=...> to allow code to alter its behavior | |
373 | when being compiled, such as for example to C<AUTOLOAD> at compile | |
374 | time rather than normal, deferred loading. Setting | |
375 | C<$^C = 1> is similar to calling C<B::minus_c>. | |
a0d0e21e | 376 | |
b0c22438 | 377 | This variable was added in Perl 5.6. |
a0d0e21e | 378 | |
b0c22438 | 379 | =item $DEBUGGING |
a0d0e21e | 380 | |
b0c22438 | 381 | =item $^D |
382 | X<$^D> X<$DEBUGGING> | |
a0d0e21e | 383 | |
b0c22438 | 384 | The current value of the debugging flags. May be read or set. Like its |
385 | command-line equivalent, you can use numeric or symbolic values, eg | |
386 | C<$^D = 10> or C<$^D = "st">. | |
68dc0745 | 387 | |
b0c22438 | 388 | Mnemonic: value of B<-D> switch. |
5b2b9c68 | 389 | |
b0c22438 | 390 | =item $SYSTEM_FD_MAX |
5b2b9c68 | 391 | |
b0c22438 | 392 | =item $^F |
393 | X<$^F> X<$SYSTEM_FD_MAX> | |
5b2b9c68 | 394 | |
b0c22438 | 395 | The maximum system file descriptor, ordinarily 2. System file |
396 | descriptors are passed to C<exec()>ed processes, while higher file | |
397 | descriptors are not. Also, during an C<open()>, system file descriptors are | |
398 | preserved even if the C<open()> fails (ordinary file descriptors are | |
399 | closed before the C<open()> is attempted). The close-on-exec | |
400 | status of a file descriptor will be decided according to the value of | |
401 | C<$^F> when the corresponding file, pipe, or socket was opened, not the | |
402 | time of the C<exec()>. | |
5b2b9c68 | 403 | |
b0c22438 | 404 | =item $^H |
883faa13 | 405 | |
b0c22438 | 406 | WARNING: This variable is strictly for internal use only. Its availability, |
407 | behavior, and contents are subject to change without notice. | |
a0d0e21e | 408 | |
b0c22438 | 409 | This variable contains compile-time hints for the Perl interpreter. At the |
410 | end of compilation of a BLOCK the value of this variable is restored to the | |
411 | value when the interpreter started to compile the BLOCK. | |
a0d0e21e | 412 | |
b0c22438 | 413 | When perl begins to parse any block construct that provides a lexical scope |
414 | (e.g., eval body, required file, subroutine body, loop body, or conditional | |
415 | block), the existing value of C<$^H> is saved, but its value is left unchanged. | |
416 | When the compilation of the block is completed, it regains the saved value. | |
417 | Between the points where its value is saved and restored, code that | |
418 | executes within BEGIN blocks is free to change the value of C<$^H>. | |
a0d0e21e | 419 | |
b0c22438 | 420 | This behavior provides the semantic of lexical scoping, and is used in, |
421 | for instance, the C<use strict> pragma. | |
a0d0e21e | 422 | |
b0c22438 | 423 | The contents should be an integer; different bits of it are used for |
424 | different pragmatic flags. Here's an example: | |
a0d0e21e | 425 | |
b0c22438 | 426 | sub add_100 { $^H |= 0x100 } |
a0d0e21e | 427 | |
b0c22438 | 428 | sub foo { |
429 | BEGIN { add_100() } | |
430 | bar->baz($boon); | |
431 | } | |
a0d0e21e | 432 | |
b0c22438 | 433 | Consider what happens during execution of the BEGIN block. At this point |
434 | the BEGIN block has already been compiled, but the body of C<foo()> is still | |
435 | being compiled. The new value of C<$^H> will therefore be visible only while | |
436 | the body of C<foo()> is being compiled. | |
a0d0e21e | 437 | |
b0c22438 | 438 | Substitution of the above BEGIN block with: |
a0d0e21e | 439 | |
b0c22438 | 440 | BEGIN { require strict; strict->import('vars') } |
a0d0e21e | 441 | |
b0c22438 | 442 | demonstrates how C<use strict 'vars'> is implemented. Here's a conditional |
443 | version of the same lexical pragma: | |
a0d0e21e | 444 | |
b0c22438 | 445 | BEGIN { require strict; strict->import('vars') if $condition } |
a0d0e21e | 446 | |
b0c22438 | 447 | This variable was added in Perl 5.003. |
a0d0e21e | 448 | |
b0c22438 | 449 | =item %^H |
a0d0e21e | 450 | |
b0c22438 | 451 | The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes it |
452 | useful for implementation of lexically scoped pragmas. See L<perlpragma>. | |
a0d0e21e | 453 | |
b0c22438 | 454 | This variable was added in Perl 5.6. |
a0d0e21e | 455 | |
b0c22438 | 456 | =item $INPLACE_EDIT |
a0d0e21e | 457 | |
b0c22438 | 458 | =item $^I |
459 | X<$^I> X<$INPLACE_EDIT> | |
a0d0e21e | 460 | |
b0c22438 | 461 | The current value of the inplace-edit extension. Use C<undef> to disable |
462 | inplace editing. | |
a0d0e21e | 463 | |
b0c22438 | 464 | Mnemonic: value of B<-i> switch. |
a0d0e21e | 465 | |
b0c22438 | 466 | =item $^M |
467 | X<$^M> | |
a0d0e21e | 468 | |
b0c22438 | 469 | By default, running out of memory is an untrappable, fatal error. |
470 | However, if suitably built, Perl can use the contents of C<$^M> | |
471 | as an emergency memory pool after C<die()>ing. Suppose that your Perl | |
472 | were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. | |
473 | Then | |
a0d0e21e | 474 | |
b0c22438 | 475 | $^M = 'a' x (1 << 16); |
a0d0e21e | 476 | |
b0c22438 | 477 | would allocate a 64K buffer for use in an emergency. See the |
478 | F<INSTALL> file in the Perl distribution for information on how to | |
479 | add custom C compilation flags when compiling perl. To discourage casual | |
480 | use of this advanced feature, there is no L<English|English> long name for | |
481 | this variable. | |
a0d0e21e | 482 | |
b0c22438 | 483 | This variable was added in Perl 5.004. |
a0d0e21e | 484 | |
b0c22438 | 485 | =item $OSNAME |
a0d0e21e | 486 | |
b0c22438 | 487 | =item $^O |
488 | X<$^O> X<$OSNAME> | |
a0d0e21e | 489 | |
b0c22438 | 490 | The name of the operating system under which this copy of Perl was |
491 | built, as determined during the configuration process. For examples | |
492 | see L<perlport/PLATFORMS>. | |
a0d0e21e | 493 | |
b0c22438 | 494 | The value is identical to C<$Config{'osname'}>. See also L<Config> |
495 | and the B<-V> command-line switch documented in L<perlrun>. | |
a0d0e21e | 496 | |
b0c22438 | 497 | In Windows platforms, C<$^O> is not very helpful: since it is always |
498 | C<MSWin32>, it doesn't tell the difference between | |
499 | 95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or | |
500 | Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish | |
501 | between the variants. | |
a0d0e21e | 502 | |
b0c22438 | 503 | This variable was added in Perl 5.003. |
a0d0e21e | 504 | |
b0c22438 | 505 | =item ${^OPEN} |
a0d0e21e | 506 | |
b0c22438 | 507 | An internal variable used by PerlIO. A string in two parts, separated |
508 | by a C<\0> byte, the first part describes the input layers, the second | |
509 | part describes the output layers. | |
a0d0e21e | 510 | |
b0c22438 | 511 | This variable was added in Perl 5.8.2. |
a0d0e21e | 512 | |
b0c22438 | 513 | =item $PERLDB |
a0d0e21e | 514 | |
b0c22438 | 515 | =item $^P |
516 | X<$^P> X<$PERLDB> | |
a0d0e21e | 517 | |
b0c22438 | 518 | The internal variable for debugging support. The meanings of the |
519 | various bits are subject to change, but currently indicate: | |
a0d0e21e | 520 | |
b0c22438 | 521 | =over 6 |
a0d0e21e | 522 | |
b0c22438 | 523 | =item 0x01 |
a0d0e21e | 524 | |
b0c22438 | 525 | Debug subroutine enter/exit. |
a0d0e21e | 526 | |
b0c22438 | 527 | =item 0x02 |
a0d0e21e | 528 | |
b0c22438 | 529 | Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for each |
530 | statement executed. Also causes saving source code lines (like 0x400). | |
a0d0e21e | 531 | |
b0c22438 | 532 | =item 0x04 |
fe307981 | 533 | |
b0c22438 | 534 | Switch off optimizations. |
6cef1e77 | 535 | |
b0c22438 | 536 | =item 0x08 |
6cef1e77 | 537 | |
b0c22438 | 538 | Preserve more data for future interactive inspections. |
6cef1e77 | 539 | |
b0c22438 | 540 | =item 0x10 |
4ba05bdc | 541 | |
b0c22438 | 542 | Keep info about source lines on which a subroutine is defined. |
4ba05bdc | 543 | |
b0c22438 | 544 | =item 0x20 |
4ba05bdc | 545 | |
b0c22438 | 546 | Start with single-step on. |
4ba05bdc | 547 | |
b0c22438 | 548 | =item 0x40 |
4ba05bdc | 549 | |
b0c22438 | 550 | Use subroutine address instead of name when reporting. |
4ba05bdc | 551 | |
b0c22438 | 552 | =item 0x80 |
4ba05bdc | 553 | |
b0c22438 | 554 | Report C<goto &subroutine> as well. |
4ba05bdc | 555 | |
b0c22438 | 556 | =item 0x100 |
4ba05bdc | 557 | |
b0c22438 | 558 | Provide informative "file" names for evals based on the place they were compiled. |
4ba05bdc | 559 | |
b0c22438 | 560 | =item 0x200 |
44a2ac75 | 561 | |
b0c22438 | 562 | Provide informative names to anonymous subroutines based on the place they |
563 | were compiled. | |
44a2ac75 | 564 | |
b0c22438 | 565 | =item 0x400 |
44a2ac75 | 566 | |
b0c22438 | 567 | Save source code lines into C<@{"_<$filename"}>. |
44a2ac75 | 568 | |
b0c22438 | 569 | =back |
44a2ac75 | 570 | |
b0c22438 | 571 | Some bits may be relevant at compile-time only, some at |
572 | run-time only. This is a new mechanism and the details may change. | |
573 | See also L<perldebguts>. | |
3195cf34 | 574 | |
b0c22438 | 575 | =item @F |
576 | X<@F> | |
44a2ac75 | 577 | |
b0c22438 | 578 | The array C<@F> contains the fields of each line read in when autosplit |
579 | mode is turned on. See L<perlrun> for the B<-a> switch. This array | |
580 | is package-specific, and must be declared or given a full package name | |
581 | if not in package main when running under C<strict 'vars'>. | |
44a2ac75 | 582 | |
b0c22438 | 583 | =item @INC |
584 | X<@INC> | |
a0d0e21e | 585 | |
b0c22438 | 586 | The array C<@INC> contains the list of places that the C<do EXPR>, |
587 | C<require>, or C<use> constructs look for their library files. It | |
588 | initially consists of the arguments to any B<-I> command-line | |
589 | switches, followed by the default Perl library, probably | |
590 | F</usr/local/lib/perl>, followed by ".", to represent the current | |
591 | directory. ("." will not be appended if taint checks are enabled, | |
592 | either by C<-T> or by C<-t>.) If you need to modify this at runtime, | |
593 | you should use the C<use lib> pragma to get the machine-dependent | |
594 | library properly loaded also: | |
a0d0e21e | 595 | |
b0c22438 | 596 | use lib '/mypath/libdir/'; |
597 | use SomeMod; | |
a0d0e21e | 598 | |
b0c22438 | 599 | You can also insert hooks into the file inclusion system by putting Perl |
600 | code directly into C<@INC>. Those hooks may be subroutine references, array | |
601 | references or blessed objects. See L<perlfunc/require> for details. | |
a0d0e21e | 602 | |
b0c22438 | 603 | =item @ARG |
a0d0e21e | 604 | |
b0c22438 | 605 | =item @_ |
606 | X<@_> X<@ARG> | |
a0d0e21e | 607 | |
b0c22438 | 608 | Within a subroutine the array C<@_> contains the parameters passed to that |
609 | subroutine. See L<perlsub>. | |
a0d0e21e | 610 | |
b0c22438 | 611 | =item %INC |
612 | X<%INC> | |
a0d0e21e | 613 | |
b0c22438 | 614 | The hash C<%INC> contains entries for each filename included via the |
615 | C<do>, C<require>, or C<use> operators. The key is the filename | |
616 | you specified (with module names converted to pathnames), and the | |
617 | value is the location of the file found. The C<require> | |
618 | operator uses this hash to determine whether a particular file has | |
619 | already been included. | |
a0d0e21e | 620 | |
b0c22438 | 621 | If the file was loaded via a hook (e.g. a subroutine reference, see |
622 | L<perlfunc/require> for a description of these hooks), this hook is | |
623 | by default inserted into C<%INC> in place of a filename. Note, however, | |
624 | that the hook may have set the C<%INC> entry by itself to provide some more | |
625 | specific info. | |
a0d0e21e | 626 | |
b0c22438 | 627 | =item %ENV |
a0d0e21e | 628 | |
b0c22438 | 629 | =item $ENV{expr} |
630 | X<%ENV> | |
a0d0e21e | 631 | |
b0c22438 | 632 | The hash C<%ENV> contains your current environment. Setting a |
633 | value in C<ENV> changes the environment for any child processes | |
634 | you subsequently C<fork()> off. | |
a0d0e21e | 635 | |
b0c22438 | 636 | =item %SIG |
a0d0e21e | 637 | |
b0c22438 | 638 | =item $SIG{expr} |
639 | X<%SIG> | |
a0d0e21e | 640 | |
b0c22438 | 641 | The hash C<%SIG> contains signal handlers for signals. For example: |
a0d0e21e | 642 | |
b0c22438 | 643 | sub handler { # 1st argument is signal name |
644 | my($sig) = @_; | |
645 | print "Caught a SIG$sig--shutting down\n"; | |
646 | close(LOG); | |
647 | exit(0); | |
648 | } | |
a0d0e21e | 649 | |
b0c22438 | 650 | $SIG{'INT'} = \&handler; |
651 | $SIG{'QUIT'} = \&handler; | |
652 | ... | |
653 | $SIG{'INT'} = 'DEFAULT'; # restore default action | |
654 | $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT | |
a0d0e21e | 655 | |
b0c22438 | 656 | Using a value of C<'IGNORE'> usually has the effect of ignoring the |
657 | signal, except for the C<CHLD> signal. See L<perlipc> for more about | |
658 | this special case. | |
a0d0e21e | 659 | |
b0c22438 | 660 | Here are some other examples: |
a0d0e21e | 661 | |
b0c22438 | 662 | $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) |
663 | $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber | |
664 | $SIG{"PIPE"} = *Plumber; # somewhat esoteric | |
665 | $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? | |
a0d0e21e | 666 | |
b0c22438 | 667 | Be sure not to use a bareword as the name of a signal handler, |
668 | lest you inadvertently call it. | |
a0d0e21e | 669 | |
b0c22438 | 670 | If your system has the C<sigaction()> function then signal handlers |
671 | are installed using it. This means you get reliable signal handling. | |
7b8d334a | 672 | |
b0c22438 | 673 | The default delivery policy of signals changed in Perl 5.8.0 from |
674 | immediate (also known as "unsafe") to deferred, also known as "safe | |
675 | signals". See L<perlipc> for more information. | |
aa689395 | 676 | |
b0c22438 | 677 | Certain internal hooks can be also set using the C<%SIG> hash. The |
678 | routine indicated by C<$SIG{__WARN__}> is called when a warning | |
679 | message is about to be printed. The warning message is passed as the | |
680 | first argument. The presence of a C<__WARN__> hook causes the | |
681 | ordinary printing of warnings to C<STDERR> to be suppressed. You can | |
682 | use this to save warnings in a variable, or turn warnings into fatal | |
683 | errors, like this: | |
19799a22 | 684 | |
b0c22438 | 685 | local $SIG{__WARN__} = sub { die $_[0] }; |
686 | eval $proggie; | |
a8f8344d | 687 | |
b0c22438 | 688 | As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can |
689 | disable warnings using the empty subroutine: | |
f86702cc | 690 | |
b0c22438 | 691 | local $SIG{__WARN__} = sub {}; |
55602bd2 | 692 | |
b0c22438 | 693 | The routine indicated by C<$SIG{__DIE__}> is called when a fatal |
694 | exception is about to be thrown. The error message is passed as the | |
695 | first argument. When a C<__DIE__> hook routine returns, the exception | |
696 | processing continues as it would have in the absence of the hook, | |
697 | unless the hook routine itself exits via a C<goto>, a loop exit, or a | |
698 | C<die()>. The C<__DIE__> handler is explicitly disabled during the | |
699 | call, so that you can die from a C<__DIE__> handler. Similarly for | |
700 | C<__WARN__>. | |
e5218da5 | 701 | |
b0c22438 | 702 | Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called |
703 | even inside an C<eval()>. Do not use this to rewrite a pending | |
704 | exception in C<$@>, or as a bizarre substitute for overriding | |
705 | C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed | |
706 | in a future release so that C<$SIG{__DIE__}> is only called if your | |
707 | program is about to exit, as was the original intent. Any other use is | |
708 | deprecated. | |
709 | ||
710 | C<__DIE__>/C<__WARN__> handlers are very special in one respect: they | |
711 | may be called to report (probable) errors found by the parser. In such | |
712 | a case the parser may be in inconsistent state, so any attempt to | |
713 | evaluate Perl code from such a handler will probably result in a | |
714 | segfault. This means that warnings or errors that result from parsing | |
715 | Perl should be used with extreme caution, like this: | |
e5218da5 | 716 | |
b0c22438 | 717 | require Carp if defined $^S; |
718 | Carp::confess("Something wrong") if defined &Carp::confess; | |
719 | die "Something wrong, but could not load Carp to give backtrace... | |
720 | To see backtrace try starting Perl with -MCarp switch"; | |
e5218da5 | 721 | |
b0c22438 | 722 | Here the first line will load C<Carp> I<unless> it is the parser who |
723 | called the handler. The second line will print backtrace and die if | |
724 | C<Carp> was available. The third line will be executed only if C<Carp> was | |
725 | not available. | |
0a378802 | 726 | |
b0c22438 | 727 | See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and |
728 | L<warnings> for additional information. | |
0a378802 | 729 | |
b0c22438 | 730 | =back |
a0d0e21e | 731 | |
b0c22438 | 732 | =head2 Names that are no longer special |
a0d0e21e | 733 | |
b0c22438 | 734 | These variables had special meaning in prior versions of Perl but now |
735 | have no effect and will cause warnings if used. They are included | |
736 | here for historical reference. | |
a0d0e21e | 737 | |
b0c22438 | 738 | =over 8 |
6ab308ee | 739 | |
b0c22438 | 740 | =item $BASETIME |
6ab308ee | 741 | |
b0c22438 | 742 | =item $^T |
743 | X<$^T> X<$BASETIME> | |
6ab308ee | 744 | |
b0c22438 | 745 | The time at which the program began running, in seconds since the |
746 | epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, | |
747 | and B<-C> filetests are based on this value. | |
a0d0e21e | 748 | |
b0c22438 | 749 | =item ${^TAINT} |
55602bd2 | 750 | |
b0c22438 | 751 | Reflects if taint mode is on or off. 1 for on (the program was run with |
752 | B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with | |
753 | B<-t> or B<-TU>). | |
daaddde1 | 754 | |
b0c22438 | 755 | This variable is read-only. |
daaddde1 | 756 | |
b0c22438 | 757 | This variable was added in Perl 5.8. |
4c5cef9b | 758 | |
b0c22438 | 759 | =item ${^UNICODE} |
4c5cef9b | 760 | |
b0c22438 | 761 | Reflects certain Unicode settings of Perl. See L<perlrun> |
762 | documentation for the C<-C> switch for more information about | |
763 | the possible values. | |
5c055ba3 | 764 | |
b0c22438 | 765 | This variable is set during Perl startup and is thereafter read-only. |
5c055ba3 | 766 | |
b0c22438 | 767 | This variable was added in Perl 5.8.2. |
22fae026 | 768 | |
b0c22438 | 769 | =item ${^UTF8CACHE} |
22fae026 | 770 | |
b0c22438 | 771 | This variable controls the state of the internal UTF-8 offset caching code. |
772 | 1 for on (the default), 0 for off, -1 to debug the caching code by checking | |
773 | all its results against linear scans, and panicking on any discrepancy. | |
22fae026 | 774 | |
b0c22438 | 775 | This variable was added in Perl 5.8.9. |
22fae026 | 776 | |
b0c22438 | 777 | =item ${^UTF8LOCALE} |
5c055ba3 | 778 | |
b0c22438 | 779 | This variable indicates whether a UTF-8 locale was detected by perl at |
780 | startup. This information is used by perl when it's in | |
781 | adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line | |
782 | switch); see L<perlrun> for more info on this. | |
55602bd2 | 783 | |
b0c22438 | 784 | This variable was added in Perl 5.8.8. |
a0d0e21e | 785 | |
b0c22438 | 786 | =item $PERL_VERSION |
a0d0e21e | 787 | |
b0c22438 | 788 | =item $^V |
789 | X<$^V> X<$PERL_VERSION> | |
a0d0e21e | 790 | |
b0c22438 | 791 | The revision, version, and subversion of the Perl interpreter, |
792 | represented as a C<version> object. | |
748a9306 | 793 | |
b0c22438 | 794 | This variable first appeared in perl 5.6.0; earlier versions of perl |
795 | will see an undefined value. Before perl 5.10.0 C<$^V> was represented | |
796 | as a v-string. | |
55602bd2 | 797 | |
b0c22438 | 798 | C<$^V> can be used to determine whether the Perl interpreter executing |
799 | a script is in the right range of versions. For example: | |
a0d0e21e | 800 | |
b0c22438 | 801 | warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 |
a0d0e21e | 802 | |
b0c22438 | 803 | To convert C<$^V> into its string representation use C<sprintf()>'s |
804 | C<"%vd"> conversion: | |
a0d0e21e | 805 | |
b0c22438 | 806 | printf "version is v%vd\n", $^V; # Perl's version |
a0d0e21e | 807 | |
b0c22438 | 808 | See the documentation of C<use VERSION> and C<require VERSION> |
809 | for a convenient way to fail if the running Perl interpreter is too old. | |
4d76a344 | 810 | |
b0c22438 | 811 | See also C<$]> for an older representation of the Perl version. |
a0d0e21e | 812 | |
b0c22438 | 813 | This variable was added in Perl 5.6. |
a0d0e21e | 814 | |
b0c22438 | 815 | Mnemonic: use ^V for Version Control. |
a0d0e21e | 816 | |
b0c22438 | 817 | =item ${^WIN32_SLOPPY_STAT} |
818 | X<sitecustomize> X<sitecustomize.pl> | |
a0d0e21e | 819 | |
b0c22438 | 820 | If this variable is set to a true value, then C<stat()> on Windows will |
821 | not try to open the file. This means that the link count cannot be | |
822 | determined and file attributes may be out of date if additional | |
823 | hardlinks to the file exist. On the other hand, not opening the file | |
824 | is considerably faster, especially for files on network drives. | |
a0d0e21e | 825 | |
b0c22438 | 826 | This variable could be set in the F<sitecustomize.pl> file to |
827 | configure the local Perl installation to use "sloppy" C<stat()> by | |
828 | default. See the documentation for B<-f> in | |
829 | L<perlrun|perlrun/"Command Switches"> for more information about site | |
830 | customization. | |
a0d0e21e | 831 | |
b0c22438 | 832 | This variable was added in Perl 5.10. |
a0d0e21e | 833 | |
b0c22438 | 834 | =item $EXECUTABLE_NAME |
a0d0e21e | 835 | |
b0c22438 | 836 | =item $^X |
837 | X<$^X> X<$EXECUTABLE_NAME> | |
a0d0e21e | 838 | |
b0c22438 | 839 | The name used to execute the current copy of Perl, from C's |
840 | C<argv[0]> or (where supported) F</proc/self/exe>. | |
a043a685 | 841 | |
b0c22438 | 842 | Depending on the host operating system, the value of C<$^X> may be |
843 | a relative or absolute pathname of the perl program file, or may | |
844 | be the string used to invoke perl but not the pathname of the | |
845 | perl program file. Also, most operating systems permit invoking | |
846 | programs that are not in the PATH environment variable, so there | |
847 | is no guarantee that the value of C<$^X> is in PATH. For VMS, the | |
848 | value may or may not include a version number. | |
a0d0e21e | 849 | |
b0c22438 | 850 | You usually can use the value of C<$^X> to re-invoke an independent |
851 | copy of the same perl that is currently running, e.g., | |
a0d0e21e | 852 | |
b0c22438 | 853 | @first_run = `$^X -le "print int rand 100 for 1..100"`; |
a0d0e21e | 854 | |
b0c22438 | 855 | But recall that not all operating systems support forking or |
856 | capturing of the output of commands, so this complex statement | |
857 | may not be portable. | |
a0d0e21e | 858 | |
b0c22438 | 859 | It is not safe to use the value of C<$^X> as a path name of a file, |
860 | as some operating systems that have a mandatory suffix on | |
861 | executable files do not require use of the suffix when invoking | |
862 | a command. To convert the value of C<$^X> to a path name, use the | |
863 | following statements: | |
8cc95fdb | 864 | |
b0c22438 | 865 | # Build up a set of file names (not command names). |
866 | use Config; | |
867 | $this_perl = $^X; | |
868 | if ($^O ne 'VMS') | |
869 | {$this_perl .= $Config{_exe} | |
870 | unless $this_perl =~ m/$Config{_exe}$/i;} | |
8cc95fdb | 871 | |
b0c22438 | 872 | Because many operating systems permit anyone with read access to |
873 | the Perl program file to make a copy of it, patch the copy, and | |
874 | then execute the copy, the security-conscious Perl programmer | |
875 | should take care to invoke the installed copy of perl, not the | |
876 | copy referenced by C<$^X>. The following statements accomplish | |
877 | this goal, and produce a pathname that can be invoked as a | |
878 | command or referenced as a file. | |
a043a685 | 879 | |
b0c22438 | 880 | use Config; |
881 | $secure_perl_path = $Config{perlpath}; | |
882 | if ($^O ne 'VMS') | |
883 | {$secure_perl_path .= $Config{_exe} | |
884 | unless $secure_perl_path =~ m/$Config{_exe}$/i;} | |
a0d0e21e | 885 | |
b0c22438 | 886 | =back |
a0d0e21e | 887 | |
b0c22438 | 888 | =head2 Variables related to regular expressions |
889 | ||
890 | Most of the special variables related to regular expressions are side | |
891 | effects. Perl sets these variables when it has a successful match, so | |
892 | you should check the match result before using them. For instance: | |
893 | ||
894 | if( /P(A)TT(ER)N/ ) { | |
895 | print "I found $1 and $2\n"; | |
896 | } | |
897 | ||
898 | These variables are read-only and dynamically-scoped, unless we note | |
899 | otherwise. | |
900 | ||
901 | The dynamic nature of the regular expression variables means that their value | |
902 | is limited to the block that they are in, as demonstrated by this bit of code: | |
903 | ||
904 | my $outer = 'Wallace and Grommit'; | |
905 | my $inner = 'Mutt and Jeff'; | |
906 | ||
907 | my $pattern = qr/(\S+) and (\S+)/; | |
908 | ||
909 | sub show_n { print "\$1 is $1; \$2 is $2\n" } | |
910 | ||
911 | { | |
912 | OUTER: | |
913 | show_n() if $outer =~ m/$pattern/; | |
914 | ||
915 | INNER: { | |
916 | show_n() if $inner =~ m/$pattern/; | |
917 | } | |
918 | ||
919 | show_n(); | |
920 | } | |
921 | ||
922 | The output shows that while in the C<OUTER> block, the values of C<$1> and C<$2> | |
923 | are from the match against C<$outer>. Inside the C<INNER> block, the values of | |
924 | C<$1> and C<$2> are from the match against C<$inner>, but only until the end of the | |
925 | block (i.e. the dynamic scope). After the C<INNER> block completes, the values of | |
926 | C<$1> and C<$2> return to the values for the match against C<$outer> even though | |
927 | we have not made another match: | |
928 | ||
929 | $1 is Wallace; $2 is Grommit | |
930 | $1 is Mutt; $2 is Jeff | |
931 | $1 is Wallace; $2 is Grommit | |
a0d0e21e | 932 | |
b0c22438 | 933 | =over 8 |
a0d0e21e | 934 | |
b0c22438 | 935 | =item $<I<digits>> ($1, $2, ...) |
936 | X<$1> X<$2> X<$3> | |
8cc95fdb | 937 | |
b0c22438 | 938 | Contains the subpattern from the corresponding set of capturing |
939 | parentheses from the last successful pattern match, not counting patterns | |
940 | matched in nested blocks that have been exited already. | |
8cc95fdb | 941 | |
b0c22438 | 942 | These variables are read-only and dynamically-scoped. |
a043a685 | 943 | |
b0c22438 | 944 | Mnemonic: like \digits. |
a0d0e21e | 945 | |
b0c22438 | 946 | =item $MATCH |
a0d0e21e | 947 | |
b0c22438 | 948 | =item $& |
949 | X<$&> X<$MATCH> | |
a0d0e21e | 950 | |
b0c22438 | 951 | The string matched by the last successful pattern match (not counting |
952 | any matches hidden within a BLOCK or C<eval()> enclosed by the current | |
953 | BLOCK). | |
a0d0e21e | 954 | |
b0c22438 | 955 | The use of this variable anywhere in a program imposes a considerable |
956 | performance penalty on all regular expression matches. See L</BUGS>. | |
957 | To avoid this penatly, you can extract the same substring by | |
958 | using L</@->. Starting with Perl 5.10, you can use the </p> match flag | |
959 | and the C<${^MATCH}> variable to do the same thing for particular | |
960 | match operations. | |
80bca1b4 | 961 | |
b0c22438 | 962 | This variable is read-only and dynamically-scoped. |
f9cbb277 | 963 | |
b0c22438 | 964 | Mnemonic: like C<&> in some editors. |
965 | ||
966 | =item ${^MATCH} | |
967 | X<${^MATCH}> | |
a0d0e21e | 968 | |
b0c22438 | 969 | This is similar to C<$&> (C<$MATCH>) except that it does not incur the |
970 | performance penalty associated with that variable, and is only guaranteed | |
971 | to return a defined value when the pattern was compiled or executed with | |
972 | the C</p> modifier. | |
80bca1b4 | 973 | |
b0c22438 | 974 | This variable was added in Perl 5.10. |
4bc88a62 | 975 | |
b0c22438 | 976 | This variable is read-only and dynamically-scoped. |
e2975953 | 977 | |
b0c22438 | 978 | =item $PREMATCH |
52c447a8 | 979 | |
b0c22438 | 980 | =item $` |
981 | X<$`> X<$PREMATCH> | |
7636ea95 | 982 | |
b0c22438 | 983 | The string preceding whatever was matched by the last successful |
984 | pattern match, not counting any matches hidden within a BLOCK or C<eval> | |
985 | enclosed by the current BLOCK. | |
a0d0e21e | 986 | |
b0c22438 | 987 | The use of this variable anywhere in a program imposes a considerable |
988 | performance penalty on all regular expression matches. See L</BUGS>. | |
989 | To avoid this penatly, you can extract the same substring by | |
990 | using L</@->. Starting with Perl 5.10, you can use the </p> match flag | |
991 | and the C<${^PREMATCH}> variable to do the same thing for particular | |
992 | match operations. | |
a0d0e21e | 993 | |
b0c22438 | 994 | This variable is read-only and dynamically-scoped. |
a0d0e21e | 995 | |
b0c22438 | 996 | Mnemonic: C<`> often precedes a quoted string. |
f83ed198 | 997 | |
b0c22438 | 998 | =item ${^PREMATCH} |
999 | X<${^PREMATCH}> | |
a0d0e21e | 1000 | |
b0c22438 | 1001 | This is similar to C<$`> ($PREMATCH) except that it does not incur the |
1002 | performance penalty associated with that variable, and is only guaranteed | |
1003 | to return a defined value when the pattern was compiled or executed with | |
1004 | the C</p> modifier. | |
a0d0e21e | 1005 | |
b0c22438 | 1006 | This variable was added in Perl 5.10 |
a0d0e21e | 1007 | |
b0c22438 | 1008 | This variable is read-only and dynamically-scoped. |
a0d0e21e | 1009 | |
b0c22438 | 1010 | =item $POSTMATCH |
16070b82 | 1011 | |
b0c22438 | 1012 | =item $' |
1013 | X<$'> X<$POSTMATCH> | |
305aace0 | 1014 | |
b0c22438 | 1015 | The string following whatever was matched by the last successful |
1016 | pattern match (not counting any matches hidden within a BLOCK or C<eval()> | |
1017 | enclosed by the current BLOCK). Example: | |
305aace0 | 1018 | |
b0c22438 | 1019 | local $_ = 'abcdefghi'; |
1020 | /def/; | |
1021 | print "$`:$&:$'\n"; # prints abc:def:ghi | |
305aace0 | 1022 | |
b0c22438 | 1023 | The use of this variable anywhere in a program imposes a considerable |
1024 | performance penalty on all regular expression matches. See L</BUGS>. | |
1025 | To avoid this penatly, you can extract the same substring by | |
1026 | using L</@->. Starting with Perl 5.10, you can use the </p> match flag | |
1027 | and the C<${^POSTMATCH}> variable to do the same thing for particular | |
1028 | match operations. | |
a0d0e21e | 1029 | |
b0c22438 | 1030 | This variable is read-only and dynamically-scoped. |
1031 | ||
1032 | Mnemonic: C<'> often follows a quoted string. | |
1033 | ||
1034 | =item ${^POSTMATCH} | |
1035 | X<${^POSTMATCH}> | |
1036 | ||
1037 | This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the | |
1038 | performance penalty associated with that variable, and is only guaranteed | |
1039 | to return a defined value when the pattern was compiled or executed with | |
1040 | the C</p> modifier. | |
1041 | ||
1042 | This variable was added in Perl 5.10. | |
1043 | ||
1044 | This variable is read-only and dynamically-scoped. | |
1045 | ||
1046 | =item $LAST_PAREN_MATCH | |
1047 | ||
1048 | =item $+ | |
1049 | X<$+> X<$LAST_PAREN_MATCH> | |
1050 | ||
1051 | The text matched by the last bracket of the last successful search pattern. | |
1052 | This is useful if you don't know which one of a set of alternative patterns | |
1053 | matched. For example: | |
1054 | ||
1055 | /Version: (.*)|Revision: (.*)/ && ($rev = $+); | |
1056 | ||
1057 | This variable is read-only and dynamically-scoped. | |
1058 | ||
1059 | Mnemonic: be positive and forward looking. | |
1060 | ||
1061 | =item $LAST_SUBMATCH_RESULT | |
1062 | ||
1063 | =item $^N | |
1064 | X<$^N> | |
1065 | ||
1066 | The text matched by the used group most-recently closed (i.e. the group | |
1067 | with the rightmost closing parenthesis) of the last successful search | |
1068 | pattern. | |
1069 | ||
1070 | This is primarily used inside C<(?{...})> blocks for examining text | |
1071 | recently matched. For example, to effectively capture text to a variable | |
1072 | (in addition to C<$1>, C<$2>, etc.), replace C<(...)> with | |
1073 | ||
1074 | (?:(...)(?{ $var = $^N })) | |
1075 | ||
1076 | By setting and then using C<$var> in this way relieves you from having to | |
1077 | worry about exactly which numbered set of parentheses they are. | |
1078 | ||
1079 | This variable was added in Perl 5.8. | |
1080 | ||
1081 | Mnemonic: the (possibly) Nested parenthesis that most recently closed. | |
1082 | ||
1083 | =item @LAST_MATCH_END | |
1084 | ||
1085 | =item @+ | |
1086 | X<@+> X<@LAST_MATCH_END> | |
1087 | ||
1088 | This array holds the offsets of the ends of the last successful | |
1089 | submatches in the currently active dynamic scope. C<$+[0]> is | |
1090 | the offset into the string of the end of the entire match. This | |
1091 | is the same value as what the C<pos> function returns when called | |
1092 | on the variable that was matched against. The I<n>th element | |
1093 | of this array holds the offset of the I<n>th submatch, so | |
1094 | C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset | |
1095 | past where C<$2> ends, and so on. You can use C<$#+> to determine | |
1096 | how many subgroups were in the last successful match. See the | |
1097 | examples given for the C<@-> variable. | |
1098 | ||
1099 | This variable was added in Perl 5.6. | |
1100 | ||
1101 | =item %LAST_PAREN_MATCH | |
1102 | ||
1103 | =item %+ | |
1104 | X<%+> | |
1105 | ||
1106 | Similar to C<@+>, the C<%+> hash allows access to the named capture | |
1107 | buffers, should they exist, in the last successful match in the | |
1108 | currently active dynamic scope. | |
1109 | ||
1110 | For example, C<$+{foo}> is equivalent to C<$1> after the following match: | |
1111 | ||
1112 | 'foo' =~ /(?<foo>foo)/; | |
1113 | ||
1114 | The keys of the C<%+> hash list only the names of buffers that have | |
1115 | captured (and that are thus associated to defined values). | |
1116 | ||
1117 | The underlying behaviour of C<%+> is provided by the | |
1118 | L<Tie::Hash::NamedCapture> module. | |
1119 | ||
1120 | B<Note:> C<%-> and C<%+> are tied views into a common internal hash | |
1121 | associated with the last successful regular expression. Therefore mixing | |
1122 | iterative access to them via C<each> may have unpredictable results. | |
1123 | Likewise, if the last successful match changes, then the results may be | |
1124 | surprising. | |
1125 | ||
1126 | This variable was added in Perl 5.10. | |
a0d0e21e | 1127 | |
b0c22438 | 1128 | This variable is read-only and dynamically-scoped. |
1129 | ||
1130 | =item @LAST_MATCH_START | |
1131 | ||
1132 | =item @- | |
1133 | X<@-> X<@LAST_MATCH_START> | |
1134 | ||
1135 | C<$-[0]> is the offset of the start of the last successful match. | |
1136 | C<$-[>I<n>C<]> is the offset of the start of the substring matched by | |
1137 | I<n>-th subpattern, or undef if the subpattern did not match. | |
1138 | ||
1139 | Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0], | |
1140 | $+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n], | |
1141 | $+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with | |
1142 | C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last | |
1143 | matched subgroup in the last successful match. Contrast with | |
1144 | C<$#+>, the number of subgroups in the regular expression. Compare | |
1145 | with C<@+>. | |
1146 | ||
1147 | This array holds the offsets of the beginnings of the last | |
1148 | successful submatches in the currently active dynamic scope. | |
1149 | C<$-[0]> is the offset into the string of the beginning of the | |
1150 | entire match. The I<n>th element of this array holds the offset | |
1151 | of the I<n>th submatch, so C<$-[1]> is the offset where C<$1> | |
1152 | begins, C<$-[2]> the offset where C<$2> begins, and so on. | |
1153 | ||
1154 | After a match against some variable C<$var>: | |
1155 | ||
1156 | =over 5 | |
1157 | ||
1158 | =item C<$`> is the same as C<substr($var, 0, $-[0])> | |
1159 | ||
1160 | =item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> | |
1161 | ||
1162 | =item C<$'> is the same as C<substr($var, $+[0])> | |
1163 | ||
1164 | =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> | |
1165 | ||
1166 | =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> | |
1167 | ||
1168 | =item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])> | |
1169 | ||
1170 | =back | |
1171 | ||
1172 | This variable was added in Perl 5.6. | |
1173 | ||
1174 | =item %- | |
1175 | X<%-> | |
1176 | ||
1177 | Similar to C<%+>, this variable allows access to the named capture groups | |
1178 | in the last successful match in the currently active dynamic scope. To | |
1179 | each capture group name found in the regular expression, it associates a | |
1180 | reference to an array containing the list of values captured by all | |
1181 | buffers with that name (should there be several of them), in the order | |
1182 | where they appear. | |
1183 | ||
1184 | Here's an example: | |
1185 | ||
1186 | if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { | |
1187 | foreach my $bufname (sort keys %-) { | |
1188 | my $ary = $-{$bufname}; | |
1189 | foreach my $idx (0..$#$ary) { | |
1190 | print "\$-{$bufname}[$idx] : ", | |
1191 | (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), | |
1192 | "\n"; | |
1193 | } | |
1194 | } | |
1195 | } | |
1196 | ||
1197 | would print out: | |
1198 | ||
1199 | $-{A}[0] : '1' | |
1200 | $-{A}[1] : '3' | |
1201 | $-{B}[0] : '2' | |
1202 | $-{B}[1] : '4' | |
1203 | ||
1204 | The keys of the C<%-> hash correspond to all buffer names found in | |
1205 | the regular expression. | |
1206 | ||
1207 | The behaviour of C<%-> is implemented via the | |
1208 | L<Tie::Hash::NamedCapture> module. | |
1209 | ||
1210 | B<Note:> C<%-> and C<%+> are tied views into a common internal hash | |
1211 | associated with the last successful regular expression. Therefore mixing | |
1212 | iterative access to them via C<each> may have unpredictable results. | |
1213 | Likewise, if the last successful match changes, then the results may be | |
1214 | surprising. | |
1215 | ||
1216 | This variable was added in Perl 5.10 | |
1217 | ||
1218 | This variable is read-only and dynamically-scoped. | |
1219 | ||
1220 | =item $LAST_REGEXP_CODE_RESULT | |
1221 | ||
1222 | =item $^R | |
1223 | X<$^R> X<$LAST_REGEXP_CODE_RESULT> | |
1224 | ||
1225 | The result of evaluation of the last successful C<(?{ code })> | |
1226 | regular expression assertion (see L<perlre>). May be written to. | |
1227 | ||
1228 | This variable was added in Perl 5.005. | |
a0d0e21e | 1229 | |
a3621e74 YO |
1230 | =item ${^RE_DEBUG_FLAGS} |
1231 | ||
1232 | The current value of the regex debugging flags. Set to 0 for no debug output | |
b0c22438 | 1233 | even when the C<re 'debug'> module is loaded. See L<re> for details. |
1234 | ||
1235 | This variable was added in Perl 5.10. | |
a3621e74 | 1236 | |
0111c4fd | 1237 | =item ${^RE_TRIE_MAXBUF} |
a3621e74 YO |
1238 | |
1239 | Controls how certain regex optimisations are applied and how much memory they | |
1240 | utilize. This value by default is 65536 which corresponds to a 512kB temporary | |
1241 | cache. Set this to a higher value to trade memory for speed when matching | |
1242 | large alternations. Set it to a lower value if you want the optimisations to | |
1243 | be as conservative of memory as possible but still occur, and set it to a | |
1244 | negative value to prevent the optimisation and conserve the most memory. | |
1245 | Under normal situations this variable should be of no interest to you. | |
1246 | ||
b0c22438 | 1247 | This variable was added in Perl 5.10. |
a0d0e21e | 1248 | |
b0c22438 | 1249 | =back |
a0d0e21e | 1250 | |
b0c22438 | 1251 | =head2 Variables related to filehandles |
a0d0e21e | 1252 | |
b0c22438 | 1253 | Variables that depend on the currently selected filehandle may be set |
1254 | by calling an appropriate object method on the C<IO::Handle> object, | |
1255 | although this is less efficient than using the regular built-in | |
1256 | variables. (Summary lines below for this contain the word HANDLE.) | |
1257 | First you must say | |
6e2995f4 | 1258 | |
b0c22438 | 1259 | use IO::Handle; |
0462a1ab | 1260 | |
b0c22438 | 1261 | after which you may use either |
0462a1ab | 1262 | |
b0c22438 | 1263 | method HANDLE EXPR |
0462a1ab | 1264 | |
b0c22438 | 1265 | or more safely, |
0462a1ab | 1266 | |
b0c22438 | 1267 | HANDLE->method(EXPR) |
0462a1ab | 1268 | |
b0c22438 | 1269 | Each method returns the old value of the C<IO::Handle> attribute. The |
1270 | methods each take an optional EXPR, which, if supplied, specifies the | |
1271 | new value for the C<IO::Handle> attribute in question. If not | |
1272 | supplied, most methods do nothing to the current value--except for | |
1273 | C<autoflush()>, which will assume a 1 for you, just to be different. | |
0462a1ab | 1274 | |
b0c22438 | 1275 | Because loading in the C<IO::Handle> class is an expensive operation, |
1276 | you should learn how to use the regular built-in variables. | |
1277 | ||
1278 | A few of these variables are considered "read-only". This means that | |
1279 | if you try to assign to this variable, either directly or indirectly | |
1280 | through a reference, you'll raise a run-time exception. | |
1281 | ||
1282 | You should be very careful when modifying the default values of most | |
1283 | special variables described in this document. In most cases you want | |
1284 | to localize these variables before changing them, since if you don't, | |
1285 | the change may affect other modules which rely on the default values | |
1286 | of the special variables that you have changed. This is one of the | |
1287 | correct ways to read the whole file at once: | |
1288 | ||
1289 | open my $fh, "<", "foo" or die $!; | |
1290 | local $/; # enable localized slurp mode | |
1291 | my $content = <$fh>; | |
1292 | close $fh; | |
1293 | ||
1294 | But the following code is quite bad: | |
1295 | ||
1296 | open my $fh, "<", "foo" or die $!; | |
1297 | undef $/; # enable slurp mode | |
1298 | my $content = <$fh>; | |
1299 | close $fh; | |
1300 | ||
1301 | since some other module, may want to read data from some file in the | |
1302 | default "line mode", so if the code we have just presented has been | |
1303 | executed, the global value of C<$/> is now changed for any other code | |
1304 | running inside the same Perl interpreter. | |
1305 | ||
1306 | Usually when a variable is localized you want to make sure that this | |
1307 | change affects the shortest scope possible. So unless you are already | |
1308 | inside some short C<{}> block, you should create one yourself. For | |
1309 | example: | |
1310 | ||
1311 | my $content = ''; | |
1312 | open my $fh, "<", "foo" or die $!; | |
1313 | { | |
1314 | local $/; | |
1315 | $content = <$fh>; | |
0462a1ab | 1316 | } |
b0c22438 | 1317 | close $fh; |
0462a1ab | 1318 | |
b0c22438 | 1319 | Here is an example of how your own code can go broken: |
0462a1ab | 1320 | |
b0c22438 | 1321 | for (1..5){ |
1322 | nasty_break(); | |
1323 | print "$_ "; | |
1324 | } | |
1325 | sub nasty_break { | |
1326 | $_ = 5; | |
1327 | # do something with $_ | |
1328 | } | |
0462a1ab | 1329 | |
b0c22438 | 1330 | You probably expect this code to print: |
0462a1ab | 1331 | |
b0c22438 | 1332 | 1 2 3 4 5 |
0462a1ab | 1333 | |
b0c22438 | 1334 | but instead you get: |
0462a1ab | 1335 | |
b0c22438 | 1336 | 5 5 5 5 5 |
0462a1ab | 1337 | |
b0c22438 | 1338 | Why? Because C<nasty_break()> modifies C<$_> without localizing it |
1339 | first. The fix is to add C<local()>: | |
6e2995f4 | 1340 | |
b0c22438 | 1341 | local $_ = 5; |
a0d0e21e | 1342 | |
b0c22438 | 1343 | It's easy to notice the problem in such a short example, but in more |
1344 | complicated code you are looking for trouble if you don't localize | |
1345 | changes to the special variables. | |
a0d0e21e | 1346 | |
b0c22438 | 1347 | =over 8 |
a0d0e21e | 1348 | |
b0c22438 | 1349 | =item ARGV |
1350 | X<ARGV> | |
fb73857a | 1351 | |
b0c22438 | 1352 | The special filehandle that iterates over command-line filenames in |
1353 | C<@ARGV>. Usually written as the null filehandle in the angle operator | |
1354 | C<< <> >>. Note that currently C<ARGV> only has its magical effect | |
1355 | within the C<< <> >> operator; elsewhere it is just a plain filehandle | |
1356 | corresponding to the last file opened by C<< <> >>. In particular, | |
1357 | passing C<\*ARGV> as a parameter to a function that expects a filehandle | |
1358 | may not cause your function to automatically read the contents of all the | |
1359 | files in C<@ARGV>. | |
fb73857a | 1360 | |
b0c22438 | 1361 | =item $ARGV |
1362 | X<$ARGV> | |
fb73857a | 1363 | |
b0c22438 | 1364 | contains the name of the current file when reading from <>. |
1365 | ||
1366 | =item @ARGV | |
1367 | X<@ARGV> | |
1368 | ||
1369 | The array @ARGV contains the command-line arguments intended for | |
1370 | the script. C<$#ARGV> is generally the number of arguments minus | |
1371 | one, because C<$ARGV[0]> is the first argument, I<not> the program's | |
1372 | command name itself. See C<$0> for the command name. | |
1373 | ||
1374 | =item ARGVOUT | |
1375 | X<ARGVOUT> | |
1376 | ||
1377 | The special filehandle that points to the currently open output file | |
1378 | when doing edit-in-place processing with B<-i>. Useful when you have | |
1379 | to do a lot of inserting and don't want to keep modifying C<$_>. See | |
1380 | L<perlrun> for the B<-i> switch. | |
1381 | ||
1382 | =item HANDLE->input_line_number(EXPR) | |
1383 | ||
1384 | =item $INPUT_LINE_NUMBER | |
1385 | ||
1386 | =item $NR | |
1387 | ||
1388 | =item $. | |
1389 | X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number> | |
1390 | ||
1391 | Current line number for the last filehandle accessed. | |
1392 | ||
1393 | Each filehandle in Perl counts the number of lines that have been read | |
1394 | from it. (Depending on the value of C<$/>, Perl's idea of what | |
1395 | constitutes a line may not match yours.) When a line is read from a | |
1396 | filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or | |
1397 | C<seek()> is called on it, C<$.> becomes an alias to the line counter | |
1398 | for that filehandle. | |
1399 | ||
1400 | You can adjust the counter by assigning to C<$.>, but this will not | |
1401 | actually move the seek pointer. I<Localizing C<$.> will not localize | |
1402 | the filehandle's line count>. Instead, it will localize perl's notion | |
1403 | of which filehandle C<$.> is currently aliased to. | |
1404 | ||
1405 | C<$.> is reset when the filehandle is closed, but B<not> when an open | |
1406 | filehandle is reopened without an intervening C<close()>. For more | |
1407 | details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does | |
1408 | an explicit close, line numbers increase across C<ARGV> files (but see | |
1409 | examples in L<perlfunc/eof>). | |
1410 | ||
1411 | You can also use C<< HANDLE->input_line_number(EXPR) >> to access the | |
1412 | line counter for a given filehandle without having to worry about | |
1413 | which handle you last accessed. | |
1414 | ||
1415 | Mnemonic: many programs use "." to mean the current line number. | |
1416 | ||
1417 | =item IO::Handle->input_record_separator(EXPR) | |
1418 | ||
1419 | =item $INPUT_RECORD_SEPARATOR | |
1420 | ||
1421 | =item $RS | |
1422 | ||
1423 | =item $/ | |
1424 | X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> | |
1425 | ||
1426 | The input record separator, newline by default. This | |
1427 | influences Perl's idea of what a "line" is. Works like B<awk>'s RS | |
1428 | variable, including treating empty lines as a terminator if set to | |
1429 | the null string (an empty line cannot contain any spaces | |
1430 | or tabs). You may set it to a multi-character string to match a | |
1431 | multi-character terminator, or to C<undef> to read through the end | |
1432 | of file. Setting it to C<"\n\n"> means something slightly | |
1433 | different than setting to C<"">, if the file contains consecutive | |
1434 | empty lines. Setting to C<""> will treat two or more consecutive | |
1435 | empty lines as a single empty line. Setting to C<"\n\n"> will | |
1436 | blindly assume that the next input character belongs to the next | |
1437 | paragraph, even if it's a newline. | |
1438 | ||
1439 | local $/; # enable "slurp" mode | |
1440 | local $_ = <FH>; # whole file now here | |
1441 | s/\n[ \t]+/ /g; | |
1442 | ||
1443 | Remember: the value of C<$/> is a string, not a regex. B<awk> has to | |
1444 | be better for something. :-) | |
1445 | ||
1446 | Setting C<$/> to a reference to an integer, scalar containing an | |
1447 | integer, or scalar that's convertible to an integer will attempt to | |
1448 | read records instead of lines, with the maximum record size being the | |
1449 | referenced integer. So this: | |
1450 | ||
1451 | local $/ = \32768; # or \"32768", or \$var_containing_32768 | |
1452 | open my $fh, "<", $myfile or die $!; | |
1453 | local $_ = <$fh>; | |
fb73857a | 1454 | |
b0c22438 | 1455 | will read a record of no more than 32768 bytes from FILE. If you're |
1456 | not reading from a record-oriented file (or your OS doesn't have | |
1457 | record-oriented files), then you'll likely get a full chunk of data | |
1458 | with every read. If a record is larger than the record size you've | |
1459 | set, you'll get the record back in pieces. Trying to set the record | |
1460 | size to zero or less will cause reading in the (rest of the) whole file. | |
6e2995f4 | 1461 | |
b0c22438 | 1462 | On VMS, record reads are done with the equivalent of C<sysread>, |
1463 | so it's best not to mix record and non-record reads on the same | |
1464 | file. (This is unlikely to be a problem, because any file you'd | |
1465 | want to read in record mode is probably unusable in line mode.) | |
1466 | Non-VMS systems do normal I/O, so it's safe to mix record and | |
1467 | non-record reads of a file. | |
5c055ba3 | 1468 | |
b0c22438 | 1469 | See also L<perlport/"Newlines">. Also see C<$.>. |
9bf22702 | 1470 | |
b0c22438 | 1471 | Mnemonic: / delimits line boundaries when quoting poetry. |
5c055ba3 | 1472 | |
b0c22438 | 1473 | =item HANDLE->autoflush(EXPR) |
916d64a3 | 1474 | |
b0c22438 | 1475 | =item $OUTPUT_AUTOFLUSH |
e2e27056 | 1476 | |
b0c22438 | 1477 | =item $| |
1478 | X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH> | |
e2e27056 | 1479 | |
b0c22438 | 1480 | If set to nonzero, forces a flush right away and after every write |
1481 | or print on the currently selected output channel. Default is 0 | |
1482 | (regardless of whether the channel is really buffered by the | |
1483 | system or not; C<$|> tells you only whether you've asked Perl | |
1484 | explicitly to flush after each write). STDOUT will | |
1485 | typically be line buffered if output is to the terminal and block | |
1486 | buffered otherwise. Setting this variable is useful primarily when | |
1487 | you are outputting to a pipe or socket, such as when you are running | |
1488 | a Perl program under B<rsh> and want to see the output as it's | |
1489 | happening. This has no effect on input buffering. See L<perlfunc/getc> | |
1490 | for that. See L<perldoc/select> on how to select the output channel. | |
1491 | See also L<IO::Handle>. | |
a0d0e21e | 1492 | |
b0c22438 | 1493 | Mnemonic: when you want your pipes to be piping hot. |
a0d0e21e | 1494 | |
b0c22438 | 1495 | =item IO::Handle->output_field_separator EXPR |
84902520 | 1496 | |
b0c22438 | 1497 | =item $OUTPUT_FIELD_SEPARATOR |
84902520 | 1498 | |
b0c22438 | 1499 | =item $OFS |
84902520 | 1500 | |
b0c22438 | 1501 | =item $, |
1502 | X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> | |
84902520 | 1503 | |
b0c22438 | 1504 | The output field separator for the print operator. If defined, this |
1505 | value is printed between each of print's arguments. Default is C<undef>. | |
84902520 | 1506 | |
b0c22438 | 1507 | Mnemonic: what is printed when there is a "," in your print statement. |
84902520 | 1508 | |
b0c22438 | 1509 | =item IO::Handle->output_record_separator EXPR |
84902520 | 1510 | |
b0c22438 | 1511 | =item $OUTPUT_RECORD_SEPARATOR |
84902520 | 1512 | |
b0c22438 | 1513 | =item $ORS |
84902520 | 1514 | |
b0c22438 | 1515 | =item $\ |
1516 | X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> | |
84902520 | 1517 | |
b0c22438 | 1518 | The output record separator for the print operator. If defined, this |
1519 | value is printed after the last of print's arguments. Default is C<undef>. | |
84902520 | 1520 | |
b0c22438 | 1521 | Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. |
1522 | Also, it's just like C<$/>, but it's what you get "back" from Perl. | |
84902520 | 1523 | |
b0c22438 | 1524 | =back |
84902520 | 1525 | |
84902520 | 1526 | |
b0c22438 | 1527 | =head3 Variables related to formats |
83ee9e09 | 1528 | |
b0c22438 | 1529 | The special variables for formats are a subset of those for |
1530 | filehandles so they have | |
83ee9e09 | 1531 | |
b0c22438 | 1532 | See L<perlform> for more information about Perl's formats. |
83ee9e09 | 1533 | |
b0c22438 | 1534 | =over 8 |
83ee9e09 | 1535 | |
b0c22438 | 1536 | =item HANDLE->format_page_number(EXPR) |
83ee9e09 | 1537 | |
b0c22438 | 1538 | =item $FORMAT_PAGE_NUMBER |
83ee9e09 | 1539 | |
b0c22438 | 1540 | =item $% |
1541 | X<$%> X<$FORMAT_PAGE_NUMBER> | |
83ee9e09 | 1542 | |
b0c22438 | 1543 | The current page number of the currently selected output channel. |
83ee9e09 | 1544 | |
b0c22438 | 1545 | Mnemonic: C<%> is page number in B<nroff>. |
7619c85e | 1546 | |
b0c22438 | 1547 | =item HANDLE->format_lines_per_page(EXPR) |
7619c85e | 1548 | |
b0c22438 | 1549 | =item $FORMAT_LINES_PER_PAGE |
84902520 | 1550 | |
b0c22438 | 1551 | =item $= |
1552 | X<$=> X<$FORMAT_LINES_PER_PAGE> | |
a0d0e21e | 1553 | |
b0c22438 | 1554 | The current page length (printable lines) of the currently selected |
1555 | output channel. The default is 60. | |
66558a10 | 1556 | |
b0c22438 | 1557 | Mnemonic: = has horizontal lines. |
b9ac3b5b | 1558 | |
b0c22438 | 1559 | =item HANDLE->format_lines_left(EXPR) |
b9ac3b5b | 1560 | |
b0c22438 | 1561 | =item $FORMAT_LINES_LEFT |
66558a10 | 1562 | |
b0c22438 | 1563 | =item $- |
1564 | X<$-> X<$FORMAT_LINES_LEFT> | |
fb73857a | 1565 | |
b0c22438 | 1566 | The number of lines left on the page of the currently selected output |
1567 | channel. | |
fa05a9fd | 1568 | |
b0c22438 | 1569 | Mnemonic: lines_on_page - lines_printed. |
fa05a9fd | 1570 | |
b0c22438 | 1571 | =item HANDLE->format_name(EXPR) |
fb73857a | 1572 | |
b0c22438 | 1573 | =item $FORMAT_NAME |
a0d0e21e | 1574 | |
b0c22438 | 1575 | =item $~ |
1576 | X<$~> X<$FORMAT_NAME> | |
a0d0e21e | 1577 | |
b0c22438 | 1578 | The name of the current report format for the currently selected |
1579 | output channel. The default format name is the same as the filehandle | |
1580 | name. For example, the default format name for the C<STDOUT> | |
1581 | filehandle is just C<STDOUT>. | |
a0d0e21e | 1582 | |
b0c22438 | 1583 | Mnemonic: brother to C<$^>. |
7c36658b | 1584 | |
b0c22438 | 1585 | =item HANDLE->format_top_name(EXPR) |
7c36658b | 1586 | |
b0c22438 | 1587 | =item $FORMAT_TOP_NAME |
a05d7ebb | 1588 | |
b0c22438 | 1589 | =item $^ |
1590 | X<$^> X<$FORMAT_TOP_NAME> | |
fde18df1 | 1591 | |
b0c22438 | 1592 | The name of the current top-of-page format for the currently selected |
1593 | output channel. The default is the name of the filehandle with C<_TOP> | |
1594 | appended. For example, the default format top name for the C<STDOUT> | |
1595 | filehanlde is C<STDOUT_TOP>. | |
e07ea26a | 1596 | |
b0c22438 | 1597 | Mnemonic: points to top of page. |
e07ea26a | 1598 | |
b0c22438 | 1599 | =item IO::Handle->format_line_break_characters EXPR |
ea8eae40 | 1600 | |
b0c22438 | 1601 | =item $FORMAT_LINE_BREAK_CHARACTERS |
ea8eae40 | 1602 | |
b0c22438 | 1603 | =item $: |
1604 | X<$:> X<FORMAT_LINE_BREAK_CHARACTERS> | |
b459063d | 1605 | |
b0c22438 | 1606 | The current set of characters after which a string may be broken to |
1607 | fill continuation fields (starting with C<^>) in a format. The default is | |
1608 | S<" \n-">, to break on a space, newline, or a hyphen. | |
16070b82 | 1609 | |
b0c22438 | 1610 | Mnemonic: a "colon" in poetry is a part of a line. |
16070b82 | 1611 | |
b0c22438 | 1612 | =item IO::Handle->format_formfeed EXPR |
7d2b1222 | 1613 | |
b0c22438 | 1614 | =item $FORMAT_FORMFEED |
16070b82 | 1615 | |
b0c22438 | 1616 | =item $^L |
1617 | X<$^L> X<$FORMAT_FORMFEED> | |
16070b82 | 1618 | |
b0c22438 | 1619 | What formats output as a form feed. The default is C<\f>. |
aa2f2a36 | 1620 | |
b0c22438 | 1621 | =item $ACCUMULATOR |
aa2f2a36 | 1622 | |
b0c22438 | 1623 | =item $^A |
1624 | X<$^A> X<$ACCUMULATOR> | |
16070b82 | 1625 | |
b0c22438 | 1626 | The current value of the C<write()> accumulator for C<format()> lines. |
1627 | A format contains C<formline()> calls that put their result into | |
1628 | C<$^A>. After calling its format, C<write()> prints out the contents | |
1629 | of C<$^A> and empties. So you never really see the contents of C<$^A> | |
1630 | unless you call C<formline()> yourself and then look at it. See | |
1631 | L<perlform> and L<perlfunc/formline()>. | |
16070b82 | 1632 | |
b0c22438 | 1633 | =back |
a0d0e21e | 1634 | |
b0c22438 | 1635 | =head2 Error Indicators |
1636 | X<error> X<exception> | |
a0d0e21e | 1637 | |
b0c22438 | 1638 | The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information |
1639 | about different types of error conditions that may appear during | |
1640 | execution of a Perl program. The variables are shown ordered by | |
1641 | the "distance" between the subsystem which reported the error and | |
1642 | the Perl process. They correspond to errors detected by the Perl | |
1643 | interpreter, C library, operating system, or an external program, | |
1644 | respectively. | |
4438c4b7 | 1645 | |
b0c22438 | 1646 | To illustrate the differences between these variables, consider the |
1647 | following Perl expression, which uses a single-quoted string: | |
4438c4b7 | 1648 | |
b0c22438 | 1649 | eval q{ |
1650 | open my $pipe, "/cdrom/install |" or die $!; | |
1651 | my @res = <$pipe>; | |
1652 | close $pipe or die "bad pipe: $?, $!"; | |
1653 | }; | |
a0d0e21e | 1654 | |
b0c22438 | 1655 | After execution of this statement all 4 variables may have been set. |
2a8c8378 | 1656 | |
b0c22438 | 1657 | C<$@> is set if the string to be C<eval>-ed did not compile (this |
1658 | may happen if C<open> or C<close> were imported with bad prototypes), | |
1659 | or if Perl code executed during evaluation die()d . In these cases | |
1660 | the value of $@ is the compile error, or the argument to C<die> | |
1661 | (which will interpolate C<$!> and C<$?>). (See also L<Fatal>, | |
1662 | though.) | |
2a8c8378 | 1663 | |
b0c22438 | 1664 | When the C<eval()> expression above is executed, C<open()>, C<< <PIPE> >>, |
1665 | and C<close> are translated to calls in the C run-time library and | |
1666 | thence to the operating system kernel. C<$!> is set to the C library's | |
1667 | C<errno> if one of these calls fails. | |
2a8c8378 | 1668 | |
b0c22438 | 1669 | Under a few operating systems, C<$^E> may contain a more verbose |
1670 | error indicator, such as in this case, "CDROM tray not closed." | |
1671 | Systems that do not support extended error messages leave C<$^E> | |
1672 | the same as C<$!>. | |
a0d0e21e | 1673 | |
b0c22438 | 1674 | Finally, C<$?> may be set to non-0 value if the external program |
1675 | F</cdrom/install> fails. The upper eight bits reflect specific | |
1676 | error conditions encountered by the program (the program's C<exit()> | |
1677 | value). The lower eight bits reflect mode of failure, like signal | |
1678 | death and core dump information. See C<wait(2)> for details. In | |
1679 | contrast to C<$!> and C<$^E>, which are set only if error condition | |
1680 | is detected, the variable C<$?> is set on each C<wait> or pipe | |
1681 | C<close>, overwriting the old value. This is more like C<$@>, which | |
1682 | on every C<eval()> is always set on failure and cleared on success. | |
a0d0e21e | 1683 | |
b0c22438 | 1684 | For more details, see the individual descriptions at C<$@>, C<$!>, |
1685 | C<$^E>, and C<$?>. | |
38e4f4ae | 1686 | |
b0c22438 | 1687 | =item $CHILD_ERROR |
38e4f4ae | 1688 | |
b0c22438 | 1689 | =item $? |
1690 | X<$?> X<$CHILD_ERROR> | |
e71940de | 1691 | |
b0c22438 | 1692 | The status returned by the last pipe close, backtick (C<``>) command, |
1693 | successful call to C<wait()> or C<waitpid()>, or from the C<system()> | |
1694 | operator. This is just the 16-bit status word returned by the | |
1695 | traditional Unix C<wait()> system call (or else is made up to look | |
1696 | like it). Thus, the exit value of the subprocess is really (C<<< $? >> | |
1697 | 8 >>>), and C<$? & 127> gives which signal, if any, the process died | |
1698 | from, and C<$? & 128> reports whether there was a core dump. | |
e71940de | 1699 | |
b0c22438 | 1700 | Additionally, if the C<h_errno> variable is supported in C, its value |
1701 | is returned via C<$?> if any C<gethost*()> function fails. | |
38e4f4ae | 1702 | |
b0c22438 | 1703 | If you have installed a signal handler for C<SIGCHLD>, the |
1704 | value of C<$?> will usually be wrong outside that handler. | |
e71940de | 1705 | |
b0c22438 | 1706 | Inside an C<END> subroutine C<$?> contains the value that is going to be |
1707 | given to C<exit()>. You can modify C<$?> in an C<END> subroutine to | |
1708 | change the exit status of your program. For example: | |
e71940de | 1709 | |
b0c22438 | 1710 | END { |
1711 | $? = 1 if $? == 255; # die would make it 255 | |
1712 | } | |
38e4f4ae | 1713 | |
b0c22438 | 1714 | Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the |
1715 | actual VMS exit status, instead of the default emulation of POSIX | |
1716 | status; see L<perlvms/$?> for details. | |
a0d0e21e | 1717 | |
b0c22438 | 1718 | Also see L<Error Indicators>. |
2d84a16a | 1719 | |
b0c22438 | 1720 | Mnemonic: similar to B<sh> and B<ksh>. |
2d84a16a | 1721 | |
b0c22438 | 1722 | =item ${^CHILD_ERROR_NATIVE} |
1723 | X<$^CHILD_ERROR_NATIVE> | |
a0d0e21e | 1724 | |
b0c22438 | 1725 | The native status returned by the last pipe close, backtick (C<``>) |
1726 | command, successful call to C<wait()> or C<waitpid()>, or from the | |
1727 | C<system()> operator. On POSIX-like systems this value can be decoded | |
1728 | with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, | |
1729 | WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module. | |
a0d0e21e | 1730 | |
b0c22438 | 1731 | Under VMS this reflects the actual VMS exit status; i.e. it is the |
1732 | same as C<$?> when the pragma C<use vmsish 'status'> is in effect. | |
a0d0e21e | 1733 | |
b0c22438 | 1734 | This variable was added in Perl 5.8.9. |
a0d0e21e | 1735 | |
b0c22438 | 1736 | =item $OS_ERROR |
5ccee41e | 1737 | |
b0c22438 | 1738 | =item $ERRNO |
5ccee41e | 1739 | |
b0c22438 | 1740 | =item $! |
1741 | X<$!> X<$ERRNO> X<$OS_ERROR> | |
9b0e6e7a | 1742 | |
b0c22438 | 1743 | If used numerically, yields the current value of the C C<errno> |
1744 | variable, or in other words, if a system or library call fails, it | |
1745 | sets this variable. This means that the value of C<$!> is meaningful | |
1746 | only I<immediately> after a B<failure>: | |
9b0e6e7a | 1747 | |
b0c22438 | 1748 | if (open my $fh, "<", $filename) { |
1749 | # Here $! is meaningless. | |
1750 | ... | |
1751 | } else { | |
1752 | # ONLY here is $! meaningful. | |
1753 | ... | |
1754 | # Already here $! might be meaningless. | |
1755 | } | |
1756 | # Since here we might have either success or failure, | |
1757 | # here $! is meaningless. | |
a0d0e21e | 1758 | |
b0c22438 | 1759 | In the above I<meaningless> stands for anything: zero, non-zero, |
1760 | C<undef>. A successful system or library call does B<not> set | |
1761 | the variable to zero. | |
a0d0e21e | 1762 | |
b0c22438 | 1763 | If used as a string, yields the corresponding system error string. |
1764 | You can assign a number to C<$!> to set I<errno> if, for instance, | |
1765 | you want C<"$!"> to return the string for error I<n>, or you want | |
1766 | to set the exit value for the C<die()> operator. | |
303f2f76 | 1767 | |
b0c22438 | 1768 | Also see L<Error Indicators>. |
d54b56d5 | 1769 | |
b0c22438 | 1770 | Mnemonic: What just went bang? |
314d39ce | 1771 | |
b0c22438 | 1772 | =item %OS_ERROR |
fb73857a | 1773 | |
b0c22438 | 1774 | =item %ERRNO |
fb73857a | 1775 | |
b0c22438 | 1776 | =item %! |
1777 | X<%!> | |
a0d0e21e | 1778 | |
b0c22438 | 1779 | Each element of C<%!> has a true value only if C<$!> is set to that |
1780 | value. For example, C<$!{ENOENT}> is true if and only if the current | |
1781 | value of C<$!> is C<ENOENT>; that is, if the most recent error was | |
1782 | "No such file or directory" (or its moral equivalent: not all operating | |
1783 | systems give that exact error, and certainly not all languages). | |
1784 | To check if a particular key is meaningful on your system, use | |
1785 | C<exists $!{the_key}>; for a list of legal keys, use C<keys %!>. | |
1786 | See L<Errno> for more information, and also see above for the | |
1787 | validity of C<$!>. | |
a0d0e21e | 1788 | |
b0c22438 | 1789 | This variable was added in Perl 5.005. |
44f0be63 | 1790 | |
b0c22438 | 1791 | =item $EXTENDED_OS_ERROR |
b687b08b | 1792 | |
b0c22438 | 1793 | =item $^E |
1794 | X<$^E> X<$EXTENDED_OS_ERROR> | |
a0d0e21e | 1795 | |
b0c22438 | 1796 | Error information specific to the current operating system. At |
1797 | the moment, this differs from C<$!> under only VMS, OS/2, and Win32 | |
1798 | (and for MacPerl). On all other platforms, C<$^E> is always just | |
1799 | the same as C<$!>. | |
a0d0e21e | 1800 | |
b0c22438 | 1801 | Under VMS, C<$^E> provides the VMS status value from the last |
1802 | system error. This is more specific information about the last | |
1803 | system error than that provided by C<$!>. This is particularly | |
1804 | important when C<$!> is set to B<EVMSERR>. | |
b687b08b | 1805 | |
b0c22438 | 1806 | Under OS/2, C<$^E> is set to the error code of the last call to |
1807 | OS/2 API either via CRT, or directly from perl. | |
a0d0e21e | 1808 | |
b0c22438 | 1809 | Under Win32, C<$^E> always returns the last error information |
1810 | reported by the Win32 call C<GetLastError()> which describes | |
1811 | the last error from within the Win32 API. Most Win32-specific | |
1812 | code will report errors via C<$^E>. ANSI C and Unix-like calls | |
1813 | set C<errno> and so most portable Perl code will report errors | |
1814 | via C<$!>. | |
a0d0e21e | 1815 | |
b0c22438 | 1816 | Caveats mentioned in the description of C<$!> generally apply to |
1817 | C<$^E>, also. | |
a0d0e21e | 1818 | |
b0c22438 | 1819 | This variable was added in Perl 5.003. |
a0d0e21e | 1820 | |
b0c22438 | 1821 | Mnemonic: Extra error explanation. |
1822 | ||
1823 | =item $EVAL_ERROR | |
f648820c | 1824 | |
b0c22438 | 1825 | =item $@ |
1826 | X<$@> X<$EVAL_ERROR> | |
a0d0e21e | 1827 | |
b0c22438 | 1828 | The Perl syntax error message from the last eval() operator. If $@ is |
1829 | the null string, the last eval() parsed and executed correctly | |
1830 | (although the operations you invoked may have failed in the normal | |
1831 | fashion). | |
a0d0e21e | 1832 | |
b0c22438 | 1833 | Warning messages are not collected in this variable. You can, however, |
1834 | set up a routine to process warnings by setting C<$SIG{__WARN__}> as | |
1835 | described below. | |
748a9306 | 1836 | |
b0c22438 | 1837 | Also see L<Error Indicators>. |
44a8e56a | 1838 | |
b0c22438 | 1839 | Mnemonic: Where was the syntax error "at"? |
1840 | ||
1841 | =item $EXCEPTIONS_BEING_CAUGHT | |
45c0772f | 1842 | |
b0c22438 | 1843 | =item $^S |
1844 | X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> | |
748a9306 | 1845 | |
b0c22438 | 1846 | Current state of the interpreter. |
748a9306 | 1847 | |
b0c22438 | 1848 | $^S State |
1849 | --------- ------------------- | |
1850 | undef Parsing module/eval | |
1851 | true (1) Executing an eval | |
1852 | false (0) Otherwise | |
efbd929d | 1853 | |
b0c22438 | 1854 | The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}> handlers. |
efbd929d | 1855 | |
b0c22438 | 1856 | This variable was added in Perl 5.004. |
fb73857a | 1857 | |
b0c22438 | 1858 | =item $WARNING |
fb73857a | 1859 | |
b0c22438 | 1860 | =item $^W |
1861 | X<$^W> X<$WARNING> | |
fb73857a | 1862 | |
b0c22438 | 1863 | The current value of the warning switch, initially true if B<-w> was |
1864 | used, false otherwise, but directly modifiable. | |
fb73857a | 1865 | |
b0c22438 | 1866 | See also L<warnings>. |
68dc0745 | 1867 | |
b0c22438 | 1868 | Mnemonic: related to the B<-w> switch. |
55602bd2 | 1869 | |
b0c22438 | 1870 | =item ${^WARNING_BITS} |
7f315d2e | 1871 | |
b0c22438 | 1872 | The current set of warning checks enabled by the C<use warnings> pragma. |
1873 | See the documentation of C<warnings> for more details. | |
7f315d2e | 1874 | |
b0c22438 | 1875 | This variable was added in Perl 5.10. |
7f315d2e | 1876 | |
b0c22438 | 1877 | =back |
7f315d2e | 1878 | |
b0c22438 | 1879 | =head2 Deprecated and removed variables |
7f315d2e | 1880 | |
b0c22438 | 1881 | Deprecating a variable announces the perl maintainers intent to |
1882 | eventually remove the varaible from the langauge. It may still be | |
1883 | available despite its status. Using a deprecated variable triggers | |
1884 | a warning. | |
7f315d2e | 1885 | |
b0c22438 | 1886 | Once the variable is removed, its use triggers an error telling you |
1887 | the variable is unsupported. | |
7f315d2e | 1888 | |
b0c22438 | 1889 | See L<perldiag> for details about the error messages. |
7f315d2e | 1890 | |
b0c22438 | 1891 | =over 8 |
7f315d2e CO |
1892 | |
1893 | =item $* | |
1894 | X<$*> | |
1895 | ||
1896 | C<$*> used to be a variable that enabled multiline matching. | |
1897 | After a deprecation cycle, its magic was removed in Perl 5.10. | |
1898 | Using it now triggers a warning: C<$* is no longer supported>. | |
1899 | Use the C</s> and C</m> regexp modifiers instead. | |
1900 | ||
b0c22438 | 1901 | Deprecated in Perl 5. |
7f315d2e | 1902 | |
b0c22438 | 1903 | Removed in Perl 5.10. |
7f315d2e | 1904 | |
b0c22438 | 1905 | =item $] |
1906 | X<$]> | |
55602bd2 | 1907 | |
b0c22438 | 1908 | The version + patchlevel / 1000 of the Perl interpreter. This variable |
1909 | can be used to determine whether the Perl interpreter executing a | |
1910 | script is in the right range of versions: | |
55602bd2 | 1911 | |
b0c22438 | 1912 | warn "No checksumming!\n" if $] < 3.019; |
55602bd2 | 1913 | |
b0c22438 | 1914 | See also the documentation of C<use VERSION> and C<require VERSION> |
1915 | for a convenient way to fail if the running Perl interpreter is too old. | |
55602bd2 | 1916 | |
b0c22438 | 1917 | The floating point representation can sometimes lead to inaccurate |
1918 | numeric comparisons. See C<$^V> for a more modern representation of | |
1919 | the Perl version that allows accurate string comparisons. | |
55602bd2 | 1920 | |
b0c22438 | 1921 | Mnemonic: Is this version of perl in the right bracket? |
19799a22 | 1922 | |
b0c22438 | 1923 | Deprecated in Perl 5.6. |
19799a22 | 1924 | |
b0c22438 | 1925 | =item $# |
1926 | X<$#> | |
19799a22 | 1927 | |
b0c22438 | 1928 | C<$#> used to be a variable that could be used to format printed numbers. |
1929 | After a deprecation cycle, its magic was removed in Perl 5.10 and using it | |
1930 | now triggers a warning: C<$# is no longer supported>. | |
2b92dfce | 1931 | |
b0c22438 | 1932 | This is not the sigil you use in front of an array name to get the |
1933 | last index, like C<$#array>. That's still how you get the last index | |
1934 | of an array in Perl. The two have nothing to do with each other. | |
2b92dfce | 1935 | |
b0c22438 | 1936 | Deprecated in Perl 5. |
2b92dfce | 1937 | |
b0c22438 | 1938 | Removed in Perl 5.10. |
2b92dfce | 1939 | |
b0c22438 | 1940 | =item $[ |
1941 | X<$[> | |
2b92dfce | 1942 | |
b0c22438 | 1943 | The index of the first element in an array, and of the first character |
1944 | in a substring. You use to be able to assign to this variable, but you | |
1945 | can't do that anymore. It's always 0, like God intended. | |
19799a22 | 1946 | |
b0c22438 | 1947 | Mnemonic: [ begins subscripts. |
2b92dfce | 1948 | |
b0c22438 | 1949 | Deprecated in Perl 5.12. |
2b92dfce | 1950 | |
b0c22438 | 1951 | =back |
2b92dfce | 1952 | |
19799a22 GS |
1953 | =head1 BUGS |
1954 | ||
1955 | Due to an unfortunate accident of Perl's implementation, C<use | |
1956 | English> imposes a considerable performance penalty on all regular | |
1957 | expression matches in a program, regardless of whether they occur | |
b0c22438 | 1958 | in the scope of C<use English>. For that reason, saying C<use |
1959 | English> in libraries is strongly discouraged. See the | |
19799a22 | 1960 | Devel::SawAmpersand module documentation from CPAN |
1577cd80 | 1961 | ( http://www.cpan.org/modules/by-module/Devel/ ) |
a054c801 GS |
1962 | for more information. Writing C<use English '-no_match_vars';> |
1963 | avoids the performance penalty. | |
2b92dfce | 1964 | |
19799a22 GS |
1965 | Having to even think about the C<$^S> variable in your exception |
1966 | handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented | |
b0c22438 | 1967 | invites grievous and difficult to track down errors. Avoid it |
19799a22 | 1968 | and use an C<END{}> or CORE::GLOBAL::die override instead. |