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