| 1 | =head1 NAME |
| 2 | |
| 3 | perlvar - Perl predefined variables |
| 4 | |
| 5 | =head1 DESCRIPTION |
| 6 | |
| 7 | =head2 Predefined Names |
| 8 | |
| 9 | The following names have special meaning to Perl. Most |
| 10 | punctuation names have reasonable mnemonics, or analogs in the |
| 11 | shells. Nevertheless, if you wish to use long variable names, |
| 12 | you need only say |
| 13 | |
| 14 | use English; |
| 15 | |
| 16 | at the top of your program. This aliases all the short names to the long |
| 17 | names in the current package. Some even have medium names, generally |
| 18 | borrowed from B<awk>. In general, it's best to use the |
| 19 | |
| 20 | use English '-no_match_vars'; |
| 21 | |
| 22 | invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids |
| 23 | a certain performance hit with the use of regular expressions. See |
| 24 | L<English>. |
| 25 | |
| 26 | Variables that depend on the currently selected filehandle may be set by |
| 27 | calling an appropriate object method on the IO::Handle object, although |
| 28 | this is less efficient than using the regular built-in variables. (Summary |
| 29 | lines below for this contain the word HANDLE.) First you must say |
| 30 | |
| 31 | use IO::Handle; |
| 32 | |
| 33 | after which you may use either |
| 34 | |
| 35 | method HANDLE EXPR |
| 36 | |
| 37 | or more safely, |
| 38 | |
| 39 | HANDLE->method(EXPR) |
| 40 | |
| 41 | Each method returns the old value of the IO::Handle attribute. |
| 42 | The methods each take an optional EXPR, which, if supplied, specifies the |
| 43 | new value for the IO::Handle attribute in question. If not supplied, |
| 44 | most methods do nothing to the current value--except for |
| 45 | autoflush(), which will assume a 1 for you, just to be different. |
| 46 | |
| 47 | Because loading in the IO::Handle class is an expensive operation, you should |
| 48 | learn how to use the regular built-in variables. |
| 49 | |
| 50 | A few of these variables are considered "read-only". This means that if |
| 51 | you try to assign to this variable, either directly or indirectly through |
| 52 | a reference, you'll raise a run-time exception. |
| 53 | |
| 54 | You should be very careful when modifying the default values of most |
| 55 | special variables described in this document. In most cases you want |
| 56 | to localize these variables before changing them, since if you don't, |
| 57 | the change may affect other modules which rely on the default values |
| 58 | of the special variables that you have changed. This is one of the |
| 59 | correct ways to read the whole file at once: |
| 60 | |
| 61 | open my $fh, "foo" or die $!; |
| 62 | local $/; # enable localized slurp mode |
| 63 | my $content = <$fh>; |
| 64 | close $fh; |
| 65 | |
| 66 | But the following code is quite bad: |
| 67 | |
| 68 | open my $fh, "foo" or die $!; |
| 69 | undef $/; # enable slurp mode |
| 70 | my $content = <$fh>; |
| 71 | close $fh; |
| 72 | |
| 73 | since some other module, may want to read data from some file in the |
| 74 | default "line mode", so if the code we have just presented has been |
| 75 | executed, the global value of C<$/> is now changed for any other code |
| 76 | running inside the same Perl interpreter. |
| 77 | |
| 78 | Usually when a variable is localized you want to make sure that this |
| 79 | change affects the shortest scope possible. So unless you are already |
| 80 | inside some short C<{}> block, you should create one yourself. For |
| 81 | example: |
| 82 | |
| 83 | my $content = ''; |
| 84 | open my $fh, "foo" or die $!; |
| 85 | { |
| 86 | local $/; |
| 87 | $content = <$fh>; |
| 88 | } |
| 89 | close $fh; |
| 90 | |
| 91 | Here is an example of how your own code can go broken: |
| 92 | |
| 93 | for (1..5){ |
| 94 | nasty_break(); |
| 95 | print "$_ "; |
| 96 | } |
| 97 | sub nasty_break { |
| 98 | $_ = 5; |
| 99 | # do something with $_ |
| 100 | } |
| 101 | |
| 102 | You probably expect this code to print: |
| 103 | |
| 104 | 1 2 3 4 5 |
| 105 | |
| 106 | but instead you get: |
| 107 | |
| 108 | 5 5 5 5 5 |
| 109 | |
| 110 | Why? Because nasty_break() modifies C<$_> without localizing it |
| 111 | first. The fix is to add local(): |
| 112 | |
| 113 | local $_ = 5; |
| 114 | |
| 115 | It's easy to notice the problem in such a short example, but in more |
| 116 | complicated code you are looking for trouble if you don't localize |
| 117 | changes to the special variables. |
| 118 | |
| 119 | The following list is ordered by scalar variables first, then the |
| 120 | arrays, then the hashes. |
| 121 | |
| 122 | =over 8 |
| 123 | |
| 124 | =item $ARG |
| 125 | |
| 126 | =item $_ |
| 127 | |
| 128 | The default input and pattern-searching space. The following pairs are |
| 129 | equivalent: |
| 130 | |
| 131 | while (<>) {...} # equivalent only in while! |
| 132 | while (defined($_ = <>)) {...} |
| 133 | |
| 134 | /^Subject:/ |
| 135 | $_ =~ /^Subject:/ |
| 136 | |
| 137 | tr/a-z/A-Z/ |
| 138 | $_ =~ tr/a-z/A-Z/ |
| 139 | |
| 140 | chomp |
| 141 | chomp($_) |
| 142 | |
| 143 | Here are the places where Perl will assume $_ even if you |
| 144 | don't use it: |
| 145 | |
| 146 | =over 3 |
| 147 | |
| 148 | =item * |
| 149 | |
| 150 | Various unary functions, including functions like ord() and int(), as well |
| 151 | as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to |
| 152 | STDIN. |
| 153 | |
| 154 | =item * |
| 155 | |
| 156 | Various list functions like print() and unlink(). |
| 157 | |
| 158 | =item * |
| 159 | |
| 160 | The pattern matching operations C<m//>, C<s///>, and C<tr///> when used |
| 161 | without an C<=~> operator. |
| 162 | |
| 163 | =item * |
| 164 | |
| 165 | The default iterator variable in a C<foreach> loop if no other |
| 166 | variable is supplied. |
| 167 | |
| 168 | =item * |
| 169 | |
| 170 | The implicit iterator variable in the grep() and map() functions. |
| 171 | |
| 172 | =item * |
| 173 | |
| 174 | The default place to put an input record when a C<< <FH> >> |
| 175 | operation's result is tested by itself as the sole criterion of a C<while> |
| 176 | test. Outside a C<while> test, this will not happen. |
| 177 | |
| 178 | =back |
| 179 | |
| 180 | (Mnemonic: underline is understood in certain operations.) |
| 181 | |
| 182 | =back |
| 183 | |
| 184 | =over 8 |
| 185 | |
| 186 | =item $a |
| 187 | |
| 188 | =item $b |
| 189 | |
| 190 | Special package variables when using sort(), see L<perlfunc/sort>. |
| 191 | Because of this specialness $a and $b don't need to be declared |
| 192 | (using use vars, or our()) even when using the C<strict 'vars'> pragma. |
| 193 | Don't lexicalize them with C<my $a> or C<my $b> if you want to be |
| 194 | able to use them in the sort() comparison block or function. |
| 195 | |
| 196 | =back |
| 197 | |
| 198 | =over 8 |
| 199 | |
| 200 | =item $<I<digits>> |
| 201 | |
| 202 | Contains the subpattern from the corresponding set of capturing |
| 203 | parentheses from the last pattern match, not counting patterns |
| 204 | matched in nested blocks that have been exited already. (Mnemonic: |
| 205 | like \digits.) These variables are all read-only and dynamically |
| 206 | scoped to the current BLOCK. |
| 207 | |
| 208 | =item $MATCH |
| 209 | |
| 210 | =item $& |
| 211 | |
| 212 | The string matched by the last successful pattern match (not counting |
| 213 | any matches hidden within a BLOCK or eval() enclosed by the current |
| 214 | BLOCK). (Mnemonic: like & in some editors.) This variable is read-only |
| 215 | and dynamically scoped to the current BLOCK. |
| 216 | |
| 217 | The use of this variable anywhere in a program imposes a considerable |
| 218 | performance penalty on all regular expression matches. See L</BUGS>. |
| 219 | |
| 220 | =item $PREMATCH |
| 221 | |
| 222 | =item $` |
| 223 | |
| 224 | The string preceding whatever was matched by the last successful |
| 225 | pattern match (not counting any matches hidden within a BLOCK or eval |
| 226 | enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted |
| 227 | string.) This variable is read-only. |
| 228 | |
| 229 | The use of this variable anywhere in a program imposes a considerable |
| 230 | performance penalty on all regular expression matches. See L</BUGS>. |
| 231 | |
| 232 | =item $POSTMATCH |
| 233 | |
| 234 | =item $' |
| 235 | |
| 236 | The string following whatever was matched by the last successful |
| 237 | pattern match (not counting any matches hidden within a BLOCK or eval() |
| 238 | enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted |
| 239 | string.) Example: |
| 240 | |
| 241 | local $_ = 'abcdefghi'; |
| 242 | /def/; |
| 243 | print "$`:$&:$'\n"; # prints abc:def:ghi |
| 244 | |
| 245 | This variable is read-only and dynamically scoped to the current BLOCK. |
| 246 | |
| 247 | The use of this variable anywhere in a program imposes a considerable |
| 248 | performance penalty on all regular expression matches. See L</BUGS>. |
| 249 | |
| 250 | =item $LAST_PAREN_MATCH |
| 251 | |
| 252 | =item $+ |
| 253 | |
| 254 | The text matched by the last bracket of the last successful search pattern. |
| 255 | This is useful if you don't know which one of a set of alternative patterns |
| 256 | matched. For example: |
| 257 | |
| 258 | /Version: (.*)|Revision: (.*)/ && ($rev = $+); |
| 259 | |
| 260 | (Mnemonic: be positive and forward looking.) |
| 261 | This variable is read-only and dynamically scoped to the current BLOCK. |
| 262 | |
| 263 | =item $^N |
| 264 | |
| 265 | The text matched by the used group most-recently closed (i.e. the group |
| 266 | with the rightmost closing parenthesis) of the last successful search |
| 267 | pattern. (Mnemonic: the (possibly) Nested parenthesis that most |
| 268 | recently closed.) |
| 269 | |
| 270 | This is primarily used inside C<(?{...})> blocks for examining text |
| 271 | recently matched. For example, to effectively capture text to a variable |
| 272 | (in addition to C<$1>, C<$2>, etc.), replace C<(...)> with |
| 273 | |
| 274 | (?:(...)(?{ $var = $^N })) |
| 275 | |
| 276 | By setting and then using C<$var> in this way relieves you from having to |
| 277 | worry about exactly which numbered set of parentheses they are. |
| 278 | |
| 279 | This variable is dynamically scoped to the current BLOCK. |
| 280 | |
| 281 | =item @LAST_MATCH_END |
| 282 | |
| 283 | =item @+ |
| 284 | |
| 285 | This array holds the offsets of the ends of the last successful |
| 286 | submatches in the currently active dynamic scope. C<$+[0]> is |
| 287 | the offset into the string of the end of the entire match. This |
| 288 | is the same value as what the C<pos> function returns when called |
| 289 | on the variable that was matched against. The I<n>th element |
| 290 | of this array holds the offset of the I<n>th submatch, so |
| 291 | C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset |
| 292 | past where $2 ends, and so on. You can use C<$#+> to determine |
| 293 | how many subgroups were in the last successful match. See the |
| 294 | examples given for the C<@-> variable. |
| 295 | |
| 296 | =item $* |
| 297 | |
| 298 | Set to a non-zero integer value to do multi-line matching within a |
| 299 | string, 0 (or undefined) to tell Perl that it can assume that strings |
| 300 | contain a single line, for the purpose of optimizing pattern matches. |
| 301 | Pattern matches on strings containing multiple newlines can produce |
| 302 | confusing results when C<$*> is 0 or undefined. Default is undefined. |
| 303 | (Mnemonic: * matches multiple things.) This variable influences the |
| 304 | interpretation of only C<^> and C<$>. A literal newline can be searched |
| 305 | for even when C<$* == 0>. |
| 306 | |
| 307 | Use of C<$*> is deprecated in modern Perl, supplanted by |
| 308 | the C</s> and C</m> modifiers on pattern matching. |
| 309 | |
| 310 | Assigning a non-numerical value to C<$*> triggers a warning (and makes |
| 311 | C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*> |
| 312 | makes that an implicit C<int> is applied on the value. |
| 313 | |
| 314 | =item HANDLE->input_line_number(EXPR) |
| 315 | |
| 316 | =item $INPUT_LINE_NUMBER |
| 317 | |
| 318 | =item $NR |
| 319 | |
| 320 | =item $. |
| 321 | |
| 322 | Current line number for the last filehandle accessed. |
| 323 | |
| 324 | Each filehandle in Perl counts the number of lines that have been read |
| 325 | from it. (Depending on the value of C<$/>, Perl's idea of what |
| 326 | constitutes a line may not match yours.) When a line is read from a |
| 327 | filehandle (via readline() or C<< <> >>), or when tell() or seek() is |
| 328 | called on it, C<$.> becomes an alias to the line counter for that |
| 329 | filehandle. |
| 330 | |
| 331 | You can adjust the counter by assigning to C<$.>, but this will not |
| 332 | actually move the seek pointer. I<Localizing C<$.> will not localize |
| 333 | the filehandle's line count>. Instead, it will localize perl's notion |
| 334 | of which filehandle C<$.> is currently aliased to. |
| 335 | |
| 336 | C<$.> is reset when the filehandle is closed, but B<not> when an open |
| 337 | filehandle is reopened without an intervening close(). For more |
| 338 | details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does |
| 339 | an explicit close, line numbers increase across ARGV files (but see |
| 340 | examples in L<perlfunc/eof>). |
| 341 | |
| 342 | You can also use C<< HANDLE->input_line_number(EXPR) >> to access the |
| 343 | line counter for a given filehandle without having to worry about |
| 344 | which handle you last accessed. |
| 345 | |
| 346 | (Mnemonic: many programs use "." to mean the current line number.) |
| 347 | |
| 348 | =item IO::Handle->input_record_separator(EXPR) |
| 349 | |
| 350 | =item $INPUT_RECORD_SEPARATOR |
| 351 | |
| 352 | =item $RS |
| 353 | |
| 354 | =item $/ |
| 355 | |
| 356 | The input record separator, newline by default. This |
| 357 | influences Perl's idea of what a "line" is. Works like B<awk>'s RS |
| 358 | variable, including treating empty lines as a terminator if set to |
| 359 | the null string. (An empty line cannot contain any spaces |
| 360 | or tabs.) You may set it to a multi-character string to match a |
| 361 | multi-character terminator, or to C<undef> to read through the end |
| 362 | of file. Setting it to C<"\n\n"> means something slightly |
| 363 | different than setting to C<"">, if the file contains consecutive |
| 364 | empty lines. Setting to C<""> will treat two or more consecutive |
| 365 | empty lines as a single empty line. Setting to C<"\n\n"> will |
| 366 | blindly assume that the next input character belongs to the next |
| 367 | paragraph, even if it's a newline. (Mnemonic: / delimits |
| 368 | line boundaries when quoting poetry.) |
| 369 | |
| 370 | local $/; # enable "slurp" mode |
| 371 | local $_ = <FH>; # whole file now here |
| 372 | s/\n[ \t]+/ /g; |
| 373 | |
| 374 | Remember: the value of C<$/> is a string, not a regex. B<awk> has to be |
| 375 | better for something. :-) |
| 376 | |
| 377 | Setting C<$/> to a reference to an integer, scalar containing an integer, or |
| 378 | scalar that's convertible to an integer will attempt to read records |
| 379 | instead of lines, with the maximum record size being the referenced |
| 380 | integer. So this: |
| 381 | |
| 382 | local $/ = \32768; # or \"32768", or \$var_containing_32768 |
| 383 | open my $fh, $myfile or die $!; |
| 384 | local $_ = <$fh>; |
| 385 | |
| 386 | will read a record of no more than 32768 bytes from FILE. If you're |
| 387 | not reading from a record-oriented file (or your OS doesn't have |
| 388 | record-oriented files), then you'll likely get a full chunk of data |
| 389 | with every read. If a record is larger than the record size you've |
| 390 | set, you'll get the record back in pieces. |
| 391 | |
| 392 | On VMS, record reads are done with the equivalent of C<sysread>, |
| 393 | so it's best not to mix record and non-record reads on the same |
| 394 | file. (This is unlikely to be a problem, because any file you'd |
| 395 | want to read in record mode is probably unusable in line mode.) |
| 396 | Non-VMS systems do normal I/O, so it's safe to mix record and |
| 397 | non-record reads of a file. |
| 398 | |
| 399 | See also L<perlport/"Newlines">. Also see C<$.>. |
| 400 | |
| 401 | =item HANDLE->autoflush(EXPR) |
| 402 | |
| 403 | =item $OUTPUT_AUTOFLUSH |
| 404 | |
| 405 | =item $| |
| 406 | |
| 407 | If set to nonzero, forces a flush right away and after every write |
| 408 | or print on the currently selected output channel. Default is 0 |
| 409 | (regardless of whether the channel is really buffered by the |
| 410 | system or not; C<$|> tells you only whether you've asked Perl |
| 411 | explicitly to flush after each write). STDOUT will |
| 412 | typically be line buffered if output is to the terminal and block |
| 413 | buffered otherwise. Setting this variable is useful primarily when |
| 414 | you are outputting to a pipe or socket, such as when you are running |
| 415 | a Perl program under B<rsh> and want to see the output as it's |
| 416 | happening. This has no effect on input buffering. See L<perlfunc/getc> |
| 417 | for that. (Mnemonic: when you want your pipes to be piping hot.) |
| 418 | |
| 419 | =item IO::Handle->output_field_separator EXPR |
| 420 | |
| 421 | =item $OUTPUT_FIELD_SEPARATOR |
| 422 | |
| 423 | =item $OFS |
| 424 | |
| 425 | =item $, |
| 426 | |
| 427 | The output field separator for the print operator. If defined, this |
| 428 | value is printed between each of print's arguments. Default is C<undef>. |
| 429 | (Mnemonic: what is printed when there is a "," in your print statement.) |
| 430 | |
| 431 | =item IO::Handle->output_record_separator EXPR |
| 432 | |
| 433 | =item $OUTPUT_RECORD_SEPARATOR |
| 434 | |
| 435 | =item $ORS |
| 436 | |
| 437 | =item $\ |
| 438 | |
| 439 | The output record separator for the print operator. If defined, this |
| 440 | value is printed after the last of print's arguments. Default is C<undef>. |
| 441 | (Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. |
| 442 | Also, it's just like C<$/>, but it's what you get "back" from Perl.) |
| 443 | |
| 444 | =item $LIST_SEPARATOR |
| 445 | |
| 446 | =item $" |
| 447 | |
| 448 | This is like C<$,> except that it applies to array and slice values |
| 449 | interpolated into a double-quoted string (or similar interpreted |
| 450 | string). Default is a space. (Mnemonic: obvious, I think.) |
| 451 | |
| 452 | =item $SUBSCRIPT_SEPARATOR |
| 453 | |
| 454 | =item $SUBSEP |
| 455 | |
| 456 | =item $; |
| 457 | |
| 458 | The subscript separator for multidimensional array emulation. If you |
| 459 | refer to a hash element as |
| 460 | |
| 461 | $foo{$a,$b,$c} |
| 462 | |
| 463 | it really means |
| 464 | |
| 465 | $foo{join($;, $a, $b, $c)} |
| 466 | |
| 467 | But don't put |
| 468 | |
| 469 | @foo{$a,$b,$c} # a slice--note the @ |
| 470 | |
| 471 | which means |
| 472 | |
| 473 | ($foo{$a},$foo{$b},$foo{$c}) |
| 474 | |
| 475 | Default is "\034", the same as SUBSEP in B<awk>. If your |
| 476 | keys contain binary data there might not be any safe value for C<$;>. |
| 477 | (Mnemonic: comma (the syntactic subscript separator) is a |
| 478 | semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already |
| 479 | taken for something more important.) |
| 480 | |
| 481 | Consider using "real" multidimensional arrays as described |
| 482 | in L<perllol>. |
| 483 | |
| 484 | =item $# |
| 485 | |
| 486 | The output format for printed numbers. This variable is a half-hearted |
| 487 | attempt to emulate B<awk>'s OFMT variable. There are times, however, |
| 488 | when B<awk> and Perl have differing notions of what counts as |
| 489 | numeric. The initial value is "%.I<n>g", where I<n> is the value |
| 490 | of the macro DBL_DIG from your system's F<float.h>. This is different from |
| 491 | B<awk>'s default OFMT setting of "%.6g", so you need to set C<$#> |
| 492 | explicitly to get B<awk>'s value. (Mnemonic: # is the number sign.) |
| 493 | |
| 494 | Use of C<$#> is deprecated. |
| 495 | |
| 496 | =item HANDLE->format_page_number(EXPR) |
| 497 | |
| 498 | =item $FORMAT_PAGE_NUMBER |
| 499 | |
| 500 | =item $% |
| 501 | |
| 502 | The current page number of the currently selected output channel. |
| 503 | Used with formats. |
| 504 | (Mnemonic: % is page number in B<nroff>.) |
| 505 | |
| 506 | =item HANDLE->format_lines_per_page(EXPR) |
| 507 | |
| 508 | =item $FORMAT_LINES_PER_PAGE |
| 509 | |
| 510 | =item $= |
| 511 | |
| 512 | The current page length (printable lines) of the currently selected |
| 513 | output channel. Default is 60. |
| 514 | Used with formats. |
| 515 | (Mnemonic: = has horizontal lines.) |
| 516 | |
| 517 | =item HANDLE->format_lines_left(EXPR) |
| 518 | |
| 519 | =item $FORMAT_LINES_LEFT |
| 520 | |
| 521 | =item $- |
| 522 | |
| 523 | The number of lines left on the page of the currently selected output |
| 524 | channel. |
| 525 | Used with formats. |
| 526 | (Mnemonic: lines_on_page - lines_printed.) |
| 527 | |
| 528 | =item @LAST_MATCH_START |
| 529 | |
| 530 | =item @- |
| 531 | |
| 532 | $-[0] is the offset of the start of the last successful match. |
| 533 | C<$-[>I<n>C<]> is the offset of the start of the substring matched by |
| 534 | I<n>-th subpattern, or undef if the subpattern did not match. |
| 535 | |
| 536 | Thus after a match against $_, $& coincides with C<substr $_, $-[0], |
| 537 | $+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n], |
| 538 | $+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with |
| 539 | C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last |
| 540 | matched subgroup in the last successful match. Contrast with |
| 541 | C<$#+>, the number of subgroups in the regular expression. Compare |
| 542 | with C<@+>. |
| 543 | |
| 544 | This array holds the offsets of the beginnings of the last |
| 545 | successful submatches in the currently active dynamic scope. |
| 546 | C<$-[0]> is the offset into the string of the beginning of the |
| 547 | entire match. The I<n>th element of this array holds the offset |
| 548 | of the I<n>th submatch, so C<$-[1]> is the offset where $1 |
| 549 | begins, C<$-[2]> the offset where $2 begins, and so on. |
| 550 | |
| 551 | After a match against some variable $var: |
| 552 | |
| 553 | =over 5 |
| 554 | |
| 555 | =item C<$`> is the same as C<substr($var, 0, $-[0])> |
| 556 | |
| 557 | =item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> |
| 558 | |
| 559 | =item C<$'> is the same as C<substr($var, $+[0])> |
| 560 | |
| 561 | =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> |
| 562 | |
| 563 | =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> |
| 564 | |
| 565 | =item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])> |
| 566 | |
| 567 | =back |
| 568 | |
| 569 | =item HANDLE->format_name(EXPR) |
| 570 | |
| 571 | =item $FORMAT_NAME |
| 572 | |
| 573 | =item $~ |
| 574 | |
| 575 | The name of the current report format for the currently selected output |
| 576 | channel. Default is the name of the filehandle. (Mnemonic: brother to |
| 577 | C<$^>.) |
| 578 | |
| 579 | =item HANDLE->format_top_name(EXPR) |
| 580 | |
| 581 | =item $FORMAT_TOP_NAME |
| 582 | |
| 583 | =item $^ |
| 584 | |
| 585 | The name of the current top-of-page format for the currently selected |
| 586 | output channel. Default is the name of the filehandle with _TOP |
| 587 | appended. (Mnemonic: points to top of page.) |
| 588 | |
| 589 | =item IO::Handle->format_line_break_characters EXPR |
| 590 | |
| 591 | =item $FORMAT_LINE_BREAK_CHARACTERS |
| 592 | |
| 593 | =item $: |
| 594 | |
| 595 | The current set of characters after which a string may be broken to |
| 596 | fill continuation fields (starting with ^) in a format. Default is |
| 597 | S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in |
| 598 | poetry is a part of a line.) |
| 599 | |
| 600 | =item IO::Handle->format_formfeed EXPR |
| 601 | |
| 602 | =item $FORMAT_FORMFEED |
| 603 | |
| 604 | =item $^L |
| 605 | |
| 606 | What formats output as a form feed. Default is \f. |
| 607 | |
| 608 | =item $ACCUMULATOR |
| 609 | |
| 610 | =item $^A |
| 611 | |
| 612 | The current value of the write() accumulator for format() lines. A format |
| 613 | contains formline() calls that put their result into C<$^A>. After |
| 614 | calling its format, write() prints out the contents of C<$^A> and empties. |
| 615 | So you never really see the contents of C<$^A> unless you call |
| 616 | formline() yourself and then look at it. See L<perlform> and |
| 617 | L<perlfunc/formline()>. |
| 618 | |
| 619 | =item $CHILD_ERROR |
| 620 | |
| 621 | =item $? |
| 622 | |
| 623 | The status returned by the last pipe close, backtick (C<``>) command, |
| 624 | successful call to wait() or waitpid(), or from the system() |
| 625 | operator. This is just the 16-bit status word returned by the |
| 626 | wait() system call (or else is made up to look like it). Thus, the |
| 627 | exit value of the subprocess is really (C<<< $? >> 8 >>>), and |
| 628 | C<$? & 127> gives which signal, if any, the process died from, and |
| 629 | C<$? & 128> reports whether there was a core dump. (Mnemonic: |
| 630 | similar to B<sh> and B<ksh>.) |
| 631 | |
| 632 | Additionally, if the C<h_errno> variable is supported in C, its value |
| 633 | is returned via $? if any C<gethost*()> function fails. |
| 634 | |
| 635 | If you have installed a signal handler for C<SIGCHLD>, the |
| 636 | value of C<$?> will usually be wrong outside that handler. |
| 637 | |
| 638 | Inside an C<END> subroutine C<$?> contains the value that is going to be |
| 639 | given to C<exit()>. You can modify C<$?> in an C<END> subroutine to |
| 640 | change the exit status of your program. For example: |
| 641 | |
| 642 | END { |
| 643 | $? = 1 if $? == 255; # die would make it 255 |
| 644 | } |
| 645 | |
| 646 | Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the |
| 647 | actual VMS exit status, instead of the default emulation of POSIX |
| 648 | status; see L<perlvms/$?> for details. |
| 649 | |
| 650 | Also see L<Error Indicators>. |
| 651 | |
| 652 | =item ${^ENCODING} |
| 653 | |
| 654 | The I<object reference> to the Encode object that is used to convert |
| 655 | the source code to Unicode. Thanks to this variable your perl script |
| 656 | does not have to be written in UTF-8. Default is I<undef>. The direct |
| 657 | manipulation of this variable is highly discouraged. See L<encoding> |
| 658 | for more details. |
| 659 | |
| 660 | =item $OS_ERROR |
| 661 | |
| 662 | =item $ERRNO |
| 663 | |
| 664 | =item $! |
| 665 | |
| 666 | If used numerically, yields the current value of the C C<errno> |
| 667 | variable, or in other words, if a system or library call fails, it |
| 668 | sets this variable. This means that the value of C<$!> is meaningful |
| 669 | only I<immediately> after a B<failure>: |
| 670 | |
| 671 | if (open(FH, $filename)) { |
| 672 | # Here $! is meaningless. |
| 673 | ... |
| 674 | } else { |
| 675 | # ONLY here is $! meaningful. |
| 676 | ... |
| 677 | # Already here $! might be meaningless. |
| 678 | } |
| 679 | # Since here we might have either success or failure, |
| 680 | # here $! is meaningless. |
| 681 | |
| 682 | In the above I<meaningless> stands for anything: zero, non-zero, |
| 683 | C<undef>. A successful system or library call does B<not> set |
| 684 | the variable to zero. |
| 685 | |
| 686 | If used as a string, yields the corresponding system error string. |
| 687 | You can assign a number to C<$!> to set I<errno> if, for instance, |
| 688 | you want C<"$!"> to return the string for error I<n>, or you want |
| 689 | to set the exit value for the die() operator. (Mnemonic: What just |
| 690 | went bang?) |
| 691 | |
| 692 | Also see L<Error Indicators>. |
| 693 | |
| 694 | =item %! |
| 695 | |
| 696 | Each element of C<%!> has a true value only if C<$!> is set to that |
| 697 | value. For example, C<$!{ENOENT}> is true if and only if the current |
| 698 | value of C<$!> is C<ENOENT>; that is, if the most recent error was |
| 699 | "No such file or directory" (or its moral equivalent: not all operating |
| 700 | systems give that exact error, and certainly not all languages). |
| 701 | To check if a particular key is meaningful on your system, use |
| 702 | C<exists $!{the_key}>; for a list of legal keys, use C<keys %!>. |
| 703 | See L<Errno> for more information, and also see above for the |
| 704 | validity of C<$!>. |
| 705 | |
| 706 | =item $EXTENDED_OS_ERROR |
| 707 | |
| 708 | =item $^E |
| 709 | |
| 710 | Error information specific to the current operating system. At |
| 711 | the moment, this differs from C<$!> under only VMS, OS/2, and Win32 |
| 712 | (and for MacPerl). On all other platforms, C<$^E> is always just |
| 713 | the same as C<$!>. |
| 714 | |
| 715 | Under VMS, C<$^E> provides the VMS status value from the last |
| 716 | system error. This is more specific information about the last |
| 717 | system error than that provided by C<$!>. This is particularly |
| 718 | important when C<$!> is set to B<EVMSERR>. |
| 719 | |
| 720 | Under OS/2, C<$^E> is set to the error code of the last call to |
| 721 | OS/2 API either via CRT, or directly from perl. |
| 722 | |
| 723 | Under Win32, C<$^E> always returns the last error information |
| 724 | reported by the Win32 call C<GetLastError()> which describes |
| 725 | the last error from within the Win32 API. Most Win32-specific |
| 726 | code will report errors via C<$^E>. ANSI C and Unix-like calls |
| 727 | set C<errno> and so most portable Perl code will report errors |
| 728 | via C<$!>. |
| 729 | |
| 730 | Caveats mentioned in the description of C<$!> generally apply to |
| 731 | C<$^E>, also. (Mnemonic: Extra error explanation.) |
| 732 | |
| 733 | Also see L<Error Indicators>. |
| 734 | |
| 735 | =item $EVAL_ERROR |
| 736 | |
| 737 | =item $@ |
| 738 | |
| 739 | The Perl syntax error message from the last eval() operator. |
| 740 | If $@ is the null string, the last eval() parsed and executed |
| 741 | correctly (although the operations you invoked may have failed in the |
| 742 | normal fashion). (Mnemonic: Where was the syntax error "at"?) |
| 743 | |
| 744 | Warning messages are not collected in this variable. You can, |
| 745 | however, set up a routine to process warnings by setting C<$SIG{__WARN__}> |
| 746 | as described below. |
| 747 | |
| 748 | Also see L<Error Indicators>. |
| 749 | |
| 750 | =item $PROCESS_ID |
| 751 | |
| 752 | =item $PID |
| 753 | |
| 754 | =item $$ |
| 755 | |
| 756 | The process number of the Perl running this script. You should |
| 757 | consider this variable read-only, although it will be altered |
| 758 | across fork() calls. (Mnemonic: same as shells.) |
| 759 | |
| 760 | Note for Linux users: on Linux, the C functions C<getpid()> and |
| 761 | C<getppid()> return different values from different threads. In order to |
| 762 | be portable, this behavior is not reflected by C<$$>, whose value remains |
| 763 | consistent across threads. If you want to call the underlying C<getpid()>, |
| 764 | you may use the CPAN module C<Linux::Pid>. |
| 765 | |
| 766 | =item $REAL_USER_ID |
| 767 | |
| 768 | =item $UID |
| 769 | |
| 770 | =item $< |
| 771 | |
| 772 | The real uid of this process. (Mnemonic: it's the uid you came I<from>, |
| 773 | if you're running setuid.) You can change both the real uid and |
| 774 | the effective uid at the same time by using POSIX::setuid(). Since |
| 775 | changes to $< require a system call, check $! after a change attempt to |
| 776 | detect any possible errors. |
| 777 | |
| 778 | =item $EFFECTIVE_USER_ID |
| 779 | |
| 780 | =item $EUID |
| 781 | |
| 782 | =item $> |
| 783 | |
| 784 | The effective uid of this process. Example: |
| 785 | |
| 786 | $< = $>; # set real to effective uid |
| 787 | ($<,$>) = ($>,$<); # swap real and effective uid |
| 788 | |
| 789 | You can change both the effective uid and the real uid at the same |
| 790 | time by using POSIX::setuid(). Changes to $> require a check to $! |
| 791 | to detect any possible errors after an attempted change. |
| 792 | |
| 793 | (Mnemonic: it's the uid you went I<to>, if you're running setuid.) |
| 794 | C<< $< >> and C<< $> >> can be swapped only on machines |
| 795 | supporting setreuid(). |
| 796 | |
| 797 | =item $REAL_GROUP_ID |
| 798 | |
| 799 | =item $GID |
| 800 | |
| 801 | =item $( |
| 802 | |
| 803 | The real gid of this process. If you are on a machine that supports |
| 804 | membership in multiple groups simultaneously, gives a space separated |
| 805 | list of groups you are in. The first number is the one returned by |
| 806 | getgid(), and the subsequent ones by getgroups(), one of which may be |
| 807 | the same as the first number. |
| 808 | |
| 809 | However, a value assigned to C<$(> must be a single number used to |
| 810 | set the real gid. So the value given by C<$(> should I<not> be assigned |
| 811 | back to C<$(> without being forced numeric, such as by adding zero. |
| 812 | |
| 813 | You can change both the real gid and the effective gid at the same |
| 814 | time by using POSIX::setgid(). Changes to $( require a check to $! |
| 815 | to detect any possible errors after an attempted change. |
| 816 | |
| 817 | (Mnemonic: parentheses are used to I<group> things. The real gid is the |
| 818 | group you I<left>, if you're running setgid.) |
| 819 | |
| 820 | =item $EFFECTIVE_GROUP_ID |
| 821 | |
| 822 | =item $EGID |
| 823 | |
| 824 | =item $) |
| 825 | |
| 826 | The effective gid of this process. If you are on a machine that |
| 827 | supports membership in multiple groups simultaneously, gives a space |
| 828 | separated list of groups you are in. The first number is the one |
| 829 | returned by getegid(), and the subsequent ones by getgroups(), one of |
| 830 | which may be the same as the first number. |
| 831 | |
| 832 | Similarly, a value assigned to C<$)> must also be a space-separated |
| 833 | list of numbers. The first number sets the effective gid, and |
| 834 | the rest (if any) are passed to setgroups(). To get the effect of an |
| 835 | empty list for setgroups(), just repeat the new effective gid; that is, |
| 836 | to force an effective gid of 5 and an effectively empty setgroups() |
| 837 | list, say C< $) = "5 5" >. |
| 838 | |
| 839 | You can change both the effective gid and the real gid at the same |
| 840 | time by using POSIX::setgid() (use only a single numeric argument). |
| 841 | Changes to $) require a check to $! to detect any possible errors |
| 842 | after an attempted change. |
| 843 | |
| 844 | (Mnemonic: parentheses are used to I<group> things. The effective gid |
| 845 | is the group that's I<right> for you, if you're running setgid.) |
| 846 | |
| 847 | C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on |
| 848 | machines that support the corresponding I<set[re][ug]id()> routine. C<$(> |
| 849 | and C<$)> can be swapped only on machines supporting setregid(). |
| 850 | |
| 851 | =item $PROGRAM_NAME |
| 852 | |
| 853 | =item $0 |
| 854 | |
| 855 | Contains the name of the program being executed. |
| 856 | |
| 857 | On some (read: not all) operating systems assigning to C<$0> modifies |
| 858 | the argument area that the C<ps> program sees. On some platforms you |
| 859 | may have to use special C<ps> options or a different C<ps> to see the |
| 860 | changes. Modifying the $0 is more useful as a way of indicating the |
| 861 | current program state than it is for hiding the program you're |
| 862 | running. (Mnemonic: same as B<sh> and B<ksh>.) |
| 863 | |
| 864 | Note that there are platform specific limitations on the maximum |
| 865 | length of C<$0>. In the most extreme case it may be limited to the |
| 866 | space occupied by the original C<$0>. |
| 867 | |
| 868 | In some platforms there may be arbitrary amount of padding, for |
| 869 | example space characters, after the modified name as shown by C<ps>. |
| 870 | In some platforms this padding may extend all the way to the original |
| 871 | length of the argument area, no matter what you do (this is the case |
| 872 | for example with Linux 2.2). |
| 873 | |
| 874 | Note for BSD users: setting C<$0> does not completely remove "perl" |
| 875 | from the ps(1) output. For example, setting C<$0> to C<"foobar"> may |
| 876 | result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix |
| 877 | and the " (perl)" suffix are shown depends on your exact BSD variant |
| 878 | and version). This is an operating system feature, Perl cannot help it. |
| 879 | |
| 880 | In multithreaded scripts Perl coordinates the threads so that any |
| 881 | thread may modify its copy of the C<$0> and the change becomes visible |
| 882 | to ps(1) (assuming the operating system plays along). Note that |
| 883 | the view of C<$0> the other threads have will not change since they |
| 884 | have their own copies of it. |
| 885 | |
| 886 | =item $[ |
| 887 | |
| 888 | The index of the first element in an array, and of the first character |
| 889 | in a substring. Default is 0, but you could theoretically set it |
| 890 | to 1 to make Perl behave more like B<awk> (or Fortran) when |
| 891 | subscripting and when evaluating the index() and substr() functions. |
| 892 | (Mnemonic: [ begins subscripts.) |
| 893 | |
| 894 | As of release 5 of Perl, assignment to C<$[> is treated as a compiler |
| 895 | directive, and cannot influence the behavior of any other file. |
| 896 | (That's why you can only assign compile-time constants to it.) |
| 897 | Its use is highly discouraged. |
| 898 | |
| 899 | Note that, unlike other compile-time directives (such as L<strict>), |
| 900 | assignment to C<$[> can be seen from outer lexical scopes in the same file. |
| 901 | However, you can use local() on it to strictly bind its value to a |
| 902 | lexical block. |
| 903 | |
| 904 | =item $] |
| 905 | |
| 906 | The version + patchlevel / 1000 of the Perl interpreter. This variable |
| 907 | can be used to determine whether the Perl interpreter executing a |
| 908 | script is in the right range of versions. (Mnemonic: Is this version |
| 909 | of perl in the right bracket?) Example: |
| 910 | |
| 911 | warn "No checksumming!\n" if $] < 3.019; |
| 912 | |
| 913 | See also the documentation of C<use VERSION> and C<require VERSION> |
| 914 | for a convenient way to fail if the running Perl interpreter is too old. |
| 915 | |
| 916 | When testing the variable, to steer clear of floating point |
| 917 | inaccuracies you might want to prefer the inequality tests C<< < >> |
| 918 | and C<< > >> to the tests containing equivalence: C<< <= >>, C<< == >>, |
| 919 | and C<< >= >>. |
| 920 | |
| 921 | The floating point representation can sometimes lead to inaccurate |
| 922 | numeric comparisons. See C<$^V> for a more modern representation of |
| 923 | the Perl version that allows accurate string comparisons. |
| 924 | |
| 925 | =item $COMPILING |
| 926 | |
| 927 | =item $^C |
| 928 | |
| 929 | The current value of the flag associated with the B<-c> switch. |
| 930 | Mainly of use with B<-MO=...> to allow code to alter its behavior |
| 931 | when being compiled, such as for example to AUTOLOAD at compile |
| 932 | time rather than normal, deferred loading. See L<perlcc>. Setting |
| 933 | C<$^C = 1> is similar to calling C<B::minus_c>. |
| 934 | |
| 935 | =item $DEBUGGING |
| 936 | |
| 937 | =item $^D |
| 938 | |
| 939 | The current value of the debugging flags. (Mnemonic: value of B<-D> |
| 940 | switch.) May be read or set. Like its command-line equivalent, you can use |
| 941 | numeric or symbolic values, eg C<$^D = 10> or C<$^D = "st">. |
| 942 | |
| 943 | =item $SYSTEM_FD_MAX |
| 944 | |
| 945 | =item $^F |
| 946 | |
| 947 | The maximum system file descriptor, ordinarily 2. System file |
| 948 | descriptors are passed to exec()ed processes, while higher file |
| 949 | descriptors are not. Also, during an open(), system file descriptors are |
| 950 | preserved even if the open() fails. (Ordinary file descriptors are |
| 951 | closed before the open() is attempted.) The close-on-exec |
| 952 | status of a file descriptor will be decided according to the value of |
| 953 | C<$^F> when the corresponding file, pipe, or socket was opened, not the |
| 954 | time of the exec(). |
| 955 | |
| 956 | =item $^H |
| 957 | |
| 958 | WARNING: This variable is strictly for internal use only. Its availability, |
| 959 | behavior, and contents are subject to change without notice. |
| 960 | |
| 961 | This variable contains compile-time hints for the Perl interpreter. At the |
| 962 | end of compilation of a BLOCK the value of this variable is restored to the |
| 963 | value when the interpreter started to compile the BLOCK. |
| 964 | |
| 965 | When perl begins to parse any block construct that provides a lexical scope |
| 966 | (e.g., eval body, required file, subroutine body, loop body, or conditional |
| 967 | block), the existing value of $^H is saved, but its value is left unchanged. |
| 968 | When the compilation of the block is completed, it regains the saved value. |
| 969 | Between the points where its value is saved and restored, code that |
| 970 | executes within BEGIN blocks is free to change the value of $^H. |
| 971 | |
| 972 | This behavior provides the semantic of lexical scoping, and is used in, |
| 973 | for instance, the C<use strict> pragma. |
| 974 | |
| 975 | The contents should be an integer; different bits of it are used for |
| 976 | different pragmatic flags. Here's an example: |
| 977 | |
| 978 | sub add_100 { $^H |= 0x100 } |
| 979 | |
| 980 | sub foo { |
| 981 | BEGIN { add_100() } |
| 982 | bar->baz($boon); |
| 983 | } |
| 984 | |
| 985 | Consider what happens during execution of the BEGIN block. At this point |
| 986 | the BEGIN block has already been compiled, but the body of foo() is still |
| 987 | being compiled. The new value of $^H will therefore be visible only while |
| 988 | the body of foo() is being compiled. |
| 989 | |
| 990 | Substitution of the above BEGIN block with: |
| 991 | |
| 992 | BEGIN { require strict; strict->import('vars') } |
| 993 | |
| 994 | demonstrates how C<use strict 'vars'> is implemented. Here's a conditional |
| 995 | version of the same lexical pragma: |
| 996 | |
| 997 | BEGIN { require strict; strict->import('vars') if $condition } |
| 998 | |
| 999 | =item %^H |
| 1000 | |
| 1001 | WARNING: This variable is strictly for internal use only. Its availability, |
| 1002 | behavior, and contents are subject to change without notice. |
| 1003 | |
| 1004 | The %^H hash provides the same scoping semantic as $^H. This makes it |
| 1005 | useful for implementation of lexically scoped pragmas. |
| 1006 | |
| 1007 | =item $INPLACE_EDIT |
| 1008 | |
| 1009 | =item $^I |
| 1010 | |
| 1011 | The current value of the inplace-edit extension. Use C<undef> to disable |
| 1012 | inplace editing. (Mnemonic: value of B<-i> switch.) |
| 1013 | |
| 1014 | =item $^M |
| 1015 | |
| 1016 | By default, running out of memory is an untrappable, fatal error. |
| 1017 | However, if suitably built, Perl can use the contents of C<$^M> |
| 1018 | as an emergency memory pool after die()ing. Suppose that your Perl |
| 1019 | were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. |
| 1020 | Then |
| 1021 | |
| 1022 | $^M = 'a' x (1 << 16); |
| 1023 | |
| 1024 | would allocate a 64K buffer for use in an emergency. See the |
| 1025 | F<INSTALL> file in the Perl distribution for information on how to |
| 1026 | add custom C compilation flags when compiling perl. To discourage casual |
| 1027 | use of this advanced feature, there is no L<English|English> long name for |
| 1028 | this variable. |
| 1029 | |
| 1030 | =item $OSNAME |
| 1031 | |
| 1032 | =item $^O |
| 1033 | |
| 1034 | The name of the operating system under which this copy of Perl was |
| 1035 | built, as determined during the configuration process. The value |
| 1036 | is identical to C<$Config{'osname'}>. See also L<Config> and the |
| 1037 | B<-V> command-line switch documented in L<perlrun>. |
| 1038 | |
| 1039 | In Windows platforms, $^O is not very helpful: since it is always |
| 1040 | C<MSWin32>, it doesn't tell the difference between |
| 1041 | 95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or |
| 1042 | Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish |
| 1043 | between the variants. |
| 1044 | |
| 1045 | =item ${^OPEN} |
| 1046 | |
| 1047 | An internal variable used by PerlIO. A string in two parts, separated |
| 1048 | by a C<\0> byte, the first part describes the input layers, the second |
| 1049 | part describes the output layers. |
| 1050 | |
| 1051 | =item $PERLDB |
| 1052 | |
| 1053 | =item $^P |
| 1054 | |
| 1055 | The internal variable for debugging support. The meanings of the |
| 1056 | various bits are subject to change, but currently indicate: |
| 1057 | |
| 1058 | =over 6 |
| 1059 | |
| 1060 | =item 0x01 |
| 1061 | |
| 1062 | Debug subroutine enter/exit. |
| 1063 | |
| 1064 | =item 0x02 |
| 1065 | |
| 1066 | Line-by-line debugging. |
| 1067 | |
| 1068 | =item 0x04 |
| 1069 | |
| 1070 | Switch off optimizations. |
| 1071 | |
| 1072 | =item 0x08 |
| 1073 | |
| 1074 | Preserve more data for future interactive inspections. |
| 1075 | |
| 1076 | =item 0x10 |
| 1077 | |
| 1078 | Keep info about source lines on which a subroutine is defined. |
| 1079 | |
| 1080 | =item 0x20 |
| 1081 | |
| 1082 | Start with single-step on. |
| 1083 | |
| 1084 | =item 0x40 |
| 1085 | |
| 1086 | Use subroutine address instead of name when reporting. |
| 1087 | |
| 1088 | =item 0x80 |
| 1089 | |
| 1090 | Report C<goto &subroutine> as well. |
| 1091 | |
| 1092 | =item 0x100 |
| 1093 | |
| 1094 | Provide informative "file" names for evals based on the place they were compiled. |
| 1095 | |
| 1096 | =item 0x200 |
| 1097 | |
| 1098 | Provide informative names to anonymous subroutines based on the place they |
| 1099 | were compiled. |
| 1100 | |
| 1101 | =item 0x400 |
| 1102 | |
| 1103 | Debug assertion subroutines enter/exit. |
| 1104 | |
| 1105 | =back |
| 1106 | |
| 1107 | Some bits may be relevant at compile-time only, some at |
| 1108 | run-time only. This is a new mechanism and the details may change. |
| 1109 | |
| 1110 | =item $LAST_REGEXP_CODE_RESULT |
| 1111 | |
| 1112 | =item $^R |
| 1113 | |
| 1114 | The result of evaluation of the last successful C<(?{ code })> |
| 1115 | regular expression assertion (see L<perlre>). May be written to. |
| 1116 | |
| 1117 | =item $EXCEPTIONS_BEING_CAUGHT |
| 1118 | |
| 1119 | =item $^S |
| 1120 | |
| 1121 | Current state of the interpreter. |
| 1122 | |
| 1123 | $^S State |
| 1124 | --------- ------------------- |
| 1125 | undef Parsing module/eval |
| 1126 | true (1) Executing an eval |
| 1127 | false (0) Otherwise |
| 1128 | |
| 1129 | The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers. |
| 1130 | |
| 1131 | =item $BASETIME |
| 1132 | |
| 1133 | =item $^T |
| 1134 | |
| 1135 | The time at which the program began running, in seconds since the |
| 1136 | epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, |
| 1137 | and B<-C> filetests are based on this value. |
| 1138 | |
| 1139 | =item ${^TAINT} |
| 1140 | |
| 1141 | Reflects if taint mode is on or off. 1 for on (the program was run with |
| 1142 | B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with |
| 1143 | B<-t> or B<-TU>). |
| 1144 | |
| 1145 | =item ${^UNICODE} |
| 1146 | |
| 1147 | Reflects certain Unicode settings of Perl. See L<perlrun> |
| 1148 | documentation for the C<-C> switch for more information about |
| 1149 | the possible values. This variable is set during Perl startup |
| 1150 | and is thereafter read-only. |
| 1151 | |
| 1152 | =item ${^UTF8LOCALE} |
| 1153 | |
| 1154 | This variable indicates whether an UTF-8 locale was detected by perl at |
| 1155 | startup. This information is used by perl when it's in |
| 1156 | adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line |
| 1157 | switch); see L<perlrun> for more info on this. |
| 1158 | |
| 1159 | =item $PERL_VERSION |
| 1160 | |
| 1161 | =item $^V |
| 1162 | |
| 1163 | The revision, version, and subversion of the Perl interpreter, represented |
| 1164 | as a string composed of characters with those ordinals. Thus in Perl v5.6.0 |
| 1165 | it equals C<chr(5) . chr(6) . chr(0)> and will return true for |
| 1166 | C<$^V eq v5.6.0>. Note that the characters in this string value can |
| 1167 | potentially be in Unicode range. |
| 1168 | |
| 1169 | This can be used to determine whether the Perl interpreter executing a |
| 1170 | script is in the right range of versions. (Mnemonic: use ^V for Version |
| 1171 | Control.) Example: |
| 1172 | |
| 1173 | warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; |
| 1174 | |
| 1175 | To convert C<$^V> into its string representation use sprintf()'s |
| 1176 | C<"%vd"> conversion: |
| 1177 | |
| 1178 | printf "version is v%vd\n", $^V; # Perl's version |
| 1179 | |
| 1180 | See the documentation of C<use VERSION> and C<require VERSION> |
| 1181 | for a convenient way to fail if the running Perl interpreter is too old. |
| 1182 | |
| 1183 | See also C<$]> for an older representation of the Perl version. |
| 1184 | |
| 1185 | =item $WARNING |
| 1186 | |
| 1187 | =item $^W |
| 1188 | |
| 1189 | The current value of the warning switch, initially true if B<-w> |
| 1190 | was used, false otherwise, but directly modifiable. (Mnemonic: |
| 1191 | related to the B<-w> switch.) See also L<warnings>. |
| 1192 | |
| 1193 | =item ${^WARNING_BITS} |
| 1194 | |
| 1195 | The current set of warning checks enabled by the C<use warnings> pragma. |
| 1196 | See the documentation of C<warnings> for more details. |
| 1197 | |
| 1198 | =item $EXECUTABLE_NAME |
| 1199 | |
| 1200 | =item $^X |
| 1201 | |
| 1202 | The name used to execute the current copy of Perl, from C's |
| 1203 | C<argv[0]> or (where supported) F</proc/self/exe>. |
| 1204 | |
| 1205 | Depending on the host operating system, the value of $^X may be |
| 1206 | a relative or absolute pathname of the perl program file, or may |
| 1207 | be the string used to invoke perl but not the pathname of the |
| 1208 | perl program file. Also, most operating systems permit invoking |
| 1209 | programs that are not in the PATH environment variable, so there |
| 1210 | is no guarantee that the value of $^X is in PATH. For VMS, the |
| 1211 | value may or may not include a version number. |
| 1212 | |
| 1213 | You usually can use the value of $^X to re-invoke an independent |
| 1214 | copy of the same perl that is currently running, e.g., |
| 1215 | |
| 1216 | @first_run = `$^X -le "print int rand 100 for 1..100"`; |
| 1217 | |
| 1218 | But recall that not all operating systems support forking or |
| 1219 | capturing of the output of commands, so this complex statement |
| 1220 | may not be portable. |
| 1221 | |
| 1222 | It is not safe to use the value of $^X as a path name of a file, |
| 1223 | as some operating systems that have a mandatory suffix on |
| 1224 | executable files do not require use of the suffix when invoking |
| 1225 | a command. To convert the value of $^X to a path name, use the |
| 1226 | following statements: |
| 1227 | |
| 1228 | # Build up a set of file names (not command names). |
| 1229 | use Config; |
| 1230 | $this_perl = $^X; |
| 1231 | if ($^O ne 'VMS') |
| 1232 | {$this_perl .= $Config{_exe} |
| 1233 | unless $this_perl =~ m/$Config{_exe}$/i;} |
| 1234 | |
| 1235 | Because many operating systems permit anyone with read access to |
| 1236 | the Perl program file to make a copy of it, patch the copy, and |
| 1237 | then execute the copy, the security-conscious Perl programmer |
| 1238 | should take care to invoke the installed copy of perl, not the |
| 1239 | copy referenced by $^X. The following statements accomplish |
| 1240 | this goal, and produce a pathname that can be invoked as a |
| 1241 | command or referenced as a file. |
| 1242 | |
| 1243 | use Config; |
| 1244 | $secure_perl_path = $Config{perlpath}; |
| 1245 | if ($^O ne 'VMS') |
| 1246 | {$secure_perl_path .= $Config{_exe} |
| 1247 | unless $secure_perl_path =~ m/$Config{_exe}$/i;} |
| 1248 | |
| 1249 | =item ARGV |
| 1250 | |
| 1251 | The special filehandle that iterates over command-line filenames in |
| 1252 | C<@ARGV>. Usually written as the null filehandle in the angle operator |
| 1253 | C<< <> >>. Note that currently C<ARGV> only has its magical effect |
| 1254 | within the C<< <> >> operator; elsewhere it is just a plain filehandle |
| 1255 | corresponding to the last file opened by C<< <> >>. In particular, |
| 1256 | passing C<\*ARGV> as a parameter to a function that expects a filehandle |
| 1257 | may not cause your function to automatically read the contents of all the |
| 1258 | files in C<@ARGV>. |
| 1259 | |
| 1260 | =item $ARGV |
| 1261 | |
| 1262 | contains the name of the current file when reading from <>. |
| 1263 | |
| 1264 | =item @ARGV |
| 1265 | |
| 1266 | The array @ARGV contains the command-line arguments intended for |
| 1267 | the script. C<$#ARGV> is generally the number of arguments minus |
| 1268 | one, because C<$ARGV[0]> is the first argument, I<not> the program's |
| 1269 | command name itself. See C<$0> for the command name. |
| 1270 | |
| 1271 | =item ARGVOUT |
| 1272 | |
| 1273 | The special filehandle that points to the currently open output file |
| 1274 | when doing edit-in-place processing with B<-i>. Useful when you have |
| 1275 | to do a lot of inserting and don't want to keep modifying $_. See |
| 1276 | L<perlrun> for the B<-i> switch. |
| 1277 | |
| 1278 | =item @F |
| 1279 | |
| 1280 | The array @F contains the fields of each line read in when autosplit |
| 1281 | mode is turned on. See L<perlrun> for the B<-a> switch. This array |
| 1282 | is package-specific, and must be declared or given a full package name |
| 1283 | if not in package main when running under C<strict 'vars'>. |
| 1284 | |
| 1285 | =item @INC |
| 1286 | |
| 1287 | The array @INC contains the list of places that the C<do EXPR>, |
| 1288 | C<require>, or C<use> constructs look for their library files. It |
| 1289 | initially consists of the arguments to any B<-I> command-line |
| 1290 | switches, followed by the default Perl library, probably |
| 1291 | F</usr/local/lib/perl>, followed by ".", to represent the current |
| 1292 | directory. ("." will not be appended if taint checks are enabled, either by |
| 1293 | C<-T> or by C<-t>.) If you need to modify this at runtime, you should use |
| 1294 | the C<use lib> pragma to get the machine-dependent library properly |
| 1295 | loaded also: |
| 1296 | |
| 1297 | use lib '/mypath/libdir/'; |
| 1298 | use SomeMod; |
| 1299 | |
| 1300 | You can also insert hooks into the file inclusion system by putting Perl |
| 1301 | code directly into @INC. Those hooks may be subroutine references, array |
| 1302 | references or blessed objects. See L<perlfunc/require> for details. |
| 1303 | |
| 1304 | =item @_ |
| 1305 | |
| 1306 | Within a subroutine the array @_ contains the parameters passed to that |
| 1307 | subroutine. See L<perlsub>. |
| 1308 | |
| 1309 | =item %INC |
| 1310 | |
| 1311 | The hash %INC contains entries for each filename included via the |
| 1312 | C<do>, C<require>, or C<use> operators. The key is the filename |
| 1313 | you specified (with module names converted to pathnames), and the |
| 1314 | value is the location of the file found. The C<require> |
| 1315 | operator uses this hash to determine whether a particular file has |
| 1316 | already been included. |
| 1317 | |
| 1318 | If the file was loaded via a hook (e.g. a subroutine reference, see |
| 1319 | L<perlfunc/require> for a description of these hooks), this hook is |
| 1320 | by default inserted into %INC in place of a filename. Note, however, |
| 1321 | that the hook may have set the %INC entry by itself to provide some more |
| 1322 | specific info. |
| 1323 | |
| 1324 | =item %ENV |
| 1325 | |
| 1326 | =item $ENV{expr} |
| 1327 | |
| 1328 | The hash %ENV contains your current environment. Setting a |
| 1329 | value in C<ENV> changes the environment for any child processes |
| 1330 | you subsequently fork() off. |
| 1331 | |
| 1332 | =item %SIG |
| 1333 | |
| 1334 | =item $SIG{expr} |
| 1335 | |
| 1336 | The hash %SIG contains signal handlers for signals. For example: |
| 1337 | |
| 1338 | sub handler { # 1st argument is signal name |
| 1339 | my($sig) = @_; |
| 1340 | print "Caught a SIG$sig--shutting down\n"; |
| 1341 | close(LOG); |
| 1342 | exit(0); |
| 1343 | } |
| 1344 | |
| 1345 | $SIG{'INT'} = \&handler; |
| 1346 | $SIG{'QUIT'} = \&handler; |
| 1347 | ... |
| 1348 | $SIG{'INT'} = 'DEFAULT'; # restore default action |
| 1349 | $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT |
| 1350 | |
| 1351 | Using a value of C<'IGNORE'> usually has the effect of ignoring the |
| 1352 | signal, except for the C<CHLD> signal. See L<perlipc> for more about |
| 1353 | this special case. |
| 1354 | |
| 1355 | Here are some other examples: |
| 1356 | |
| 1357 | $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) |
| 1358 | $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber |
| 1359 | $SIG{"PIPE"} = *Plumber; # somewhat esoteric |
| 1360 | $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? |
| 1361 | |
| 1362 | Be sure not to use a bareword as the name of a signal handler, |
| 1363 | lest you inadvertently call it. |
| 1364 | |
| 1365 | If your system has the sigaction() function then signal handlers are |
| 1366 | installed using it. This means you get reliable signal handling. |
| 1367 | |
| 1368 | The default delivery policy of signals changed in Perl 5.8.0 from |
| 1369 | immediate (also known as "unsafe") to deferred, also known as |
| 1370 | "safe signals". See L<perlipc> for more information. |
| 1371 | |
| 1372 | Certain internal hooks can be also set using the %SIG hash. The |
| 1373 | routine indicated by C<$SIG{__WARN__}> is called when a warning message is |
| 1374 | about to be printed. The warning message is passed as the first |
| 1375 | argument. The presence of a __WARN__ hook causes the ordinary printing |
| 1376 | of warnings to STDERR to be suppressed. You can use this to save warnings |
| 1377 | in a variable, or turn warnings into fatal errors, like this: |
| 1378 | |
| 1379 | local $SIG{__WARN__} = sub { die $_[0] }; |
| 1380 | eval $proggie; |
| 1381 | |
| 1382 | The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception |
| 1383 | is about to be thrown. The error message is passed as the first |
| 1384 | argument. When a __DIE__ hook routine returns, the exception |
| 1385 | processing continues as it would have in the absence of the hook, |
| 1386 | unless the hook routine itself exits via a C<goto>, a loop exit, or a die(). |
| 1387 | The C<__DIE__> handler is explicitly disabled during the call, so that you |
| 1388 | can die from a C<__DIE__> handler. Similarly for C<__WARN__>. |
| 1389 | |
| 1390 | Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called |
| 1391 | even inside an eval(). Do not use this to rewrite a pending exception |
| 1392 | in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die(). |
| 1393 | This strange action at a distance may be fixed in a future release |
| 1394 | so that C<$SIG{__DIE__}> is only called if your program is about |
| 1395 | to exit, as was the original intent. Any other use is deprecated. |
| 1396 | |
| 1397 | C<__DIE__>/C<__WARN__> handlers are very special in one respect: |
| 1398 | they may be called to report (probable) errors found by the parser. |
| 1399 | In such a case the parser may be in inconsistent state, so any |
| 1400 | attempt to evaluate Perl code from such a handler will probably |
| 1401 | result in a segfault. This means that warnings or errors that |
| 1402 | result from parsing Perl should be used with extreme caution, like |
| 1403 | this: |
| 1404 | |
| 1405 | require Carp if defined $^S; |
| 1406 | Carp::confess("Something wrong") if defined &Carp::confess; |
| 1407 | die "Something wrong, but could not load Carp to give backtrace... |
| 1408 | To see backtrace try starting Perl with -MCarp switch"; |
| 1409 | |
| 1410 | Here the first line will load Carp I<unless> it is the parser who |
| 1411 | called the handler. The second line will print backtrace and die if |
| 1412 | Carp was available. The third line will be executed only if Carp was |
| 1413 | not available. |
| 1414 | |
| 1415 | See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and |
| 1416 | L<warnings> for additional information. |
| 1417 | |
| 1418 | =back |
| 1419 | |
| 1420 | =head2 Error Indicators |
| 1421 | |
| 1422 | The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information |
| 1423 | about different types of error conditions that may appear during |
| 1424 | execution of a Perl program. The variables are shown ordered by |
| 1425 | the "distance" between the subsystem which reported the error and |
| 1426 | the Perl process. They correspond to errors detected by the Perl |
| 1427 | interpreter, C library, operating system, or an external program, |
| 1428 | respectively. |
| 1429 | |
| 1430 | To illustrate the differences between these variables, consider the |
| 1431 | following Perl expression, which uses a single-quoted string: |
| 1432 | |
| 1433 | eval q{ |
| 1434 | open my $pipe, "/cdrom/install |" or die $!; |
| 1435 | my @res = <$pipe>; |
| 1436 | close $pipe or die "bad pipe: $?, $!"; |
| 1437 | }; |
| 1438 | |
| 1439 | After execution of this statement all 4 variables may have been set. |
| 1440 | |
| 1441 | C<$@> is set if the string to be C<eval>-ed did not compile (this |
| 1442 | may happen if C<open> or C<close> were imported with bad prototypes), |
| 1443 | or if Perl code executed during evaluation die()d . In these cases |
| 1444 | the value of $@ is the compile error, or the argument to C<die> |
| 1445 | (which will interpolate C<$!> and C<$?>). (See also L<Fatal>, |
| 1446 | though.) |
| 1447 | |
| 1448 | When the eval() expression above is executed, open(), C<< <PIPE> >>, |
| 1449 | and C<close> are translated to calls in the C run-time library and |
| 1450 | thence to the operating system kernel. C<$!> is set to the C library's |
| 1451 | C<errno> if one of these calls fails. |
| 1452 | |
| 1453 | Under a few operating systems, C<$^E> may contain a more verbose |
| 1454 | error indicator, such as in this case, "CDROM tray not closed." |
| 1455 | Systems that do not support extended error messages leave C<$^E> |
| 1456 | the same as C<$!>. |
| 1457 | |
| 1458 | Finally, C<$?> may be set to non-0 value if the external program |
| 1459 | F</cdrom/install> fails. The upper eight bits reflect specific |
| 1460 | error conditions encountered by the program (the program's exit() |
| 1461 | value). The lower eight bits reflect mode of failure, like signal |
| 1462 | death and core dump information See wait(2) for details. In |
| 1463 | contrast to C<$!> and C<$^E>, which are set only if error condition |
| 1464 | is detected, the variable C<$?> is set on each C<wait> or pipe |
| 1465 | C<close>, overwriting the old value. This is more like C<$@>, which |
| 1466 | on every eval() is always set on failure and cleared on success. |
| 1467 | |
| 1468 | For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, |
| 1469 | and C<$?>. |
| 1470 | |
| 1471 | =head2 Technical Note on the Syntax of Variable Names |
| 1472 | |
| 1473 | Variable names in Perl can have several formats. Usually, they |
| 1474 | must begin with a letter or underscore, in which case they can be |
| 1475 | arbitrarily long (up to an internal limit of 251 characters) and |
| 1476 | may contain letters, digits, underscores, or the special sequence |
| 1477 | C<::> or C<'>. In this case, the part before the last C<::> or |
| 1478 | C<'> is taken to be a I<package qualifier>; see L<perlmod>. |
| 1479 | |
| 1480 | Perl variable names may also be a sequence of digits or a single |
| 1481 | punctuation or control character. These names are all reserved for |
| 1482 | special uses by Perl; for example, the all-digits names are used |
| 1483 | to hold data captured by backreferences after a regular expression |
| 1484 | match. Perl has a special syntax for the single-control-character |
| 1485 | names: It understands C<^X> (caret C<X>) to mean the control-C<X> |
| 1486 | character. For example, the notation C<$^W> (dollar-sign caret |
| 1487 | C<W>) is the scalar variable whose name is the single character |
| 1488 | control-C<W>. This is better than typing a literal control-C<W> |
| 1489 | into your program. |
| 1490 | |
| 1491 | Finally, new in Perl 5.6, Perl variable names may be alphanumeric |
| 1492 | strings that begin with control characters (or better yet, a caret). |
| 1493 | These variables must be written in the form C<${^Foo}>; the braces |
| 1494 | are not optional. C<${^Foo}> denotes the scalar variable whose |
| 1495 | name is a control-C<F> followed by two C<o>'s. These variables are |
| 1496 | reserved for future special uses by Perl, except for the ones that |
| 1497 | begin with C<^_> (control-underscore or caret-underscore). No |
| 1498 | control-character name that begins with C<^_> will acquire a special |
| 1499 | meaning in any future version of Perl; such names may therefore be |
| 1500 | used safely in programs. C<$^_> itself, however, I<is> reserved. |
| 1501 | |
| 1502 | Perl identifiers that begin with digits, control characters, or |
| 1503 | punctuation characters are exempt from the effects of the C<package> |
| 1504 | declaration and are always forced to be in package C<main>; they are |
| 1505 | also exempt from C<strict 'vars'> errors. A few other names are also |
| 1506 | exempt in these ways: |
| 1507 | |
| 1508 | ENV STDIN |
| 1509 | INC STDOUT |
| 1510 | ARGV STDERR |
| 1511 | ARGVOUT _ |
| 1512 | SIG |
| 1513 | |
| 1514 | In particular, the new special C<${^_XYZ}> variables are always taken |
| 1515 | to be in package C<main>, regardless of any C<package> declarations |
| 1516 | presently in scope. |
| 1517 | |
| 1518 | =head1 BUGS |
| 1519 | |
| 1520 | Due to an unfortunate accident of Perl's implementation, C<use |
| 1521 | English> imposes a considerable performance penalty on all regular |
| 1522 | expression matches in a program, regardless of whether they occur |
| 1523 | in the scope of C<use English>. For that reason, saying C<use |
| 1524 | English> in libraries is strongly discouraged. See the |
| 1525 | Devel::SawAmpersand module documentation from CPAN |
| 1526 | ( http://www.cpan.org/modules/by-module/Devel/ ) |
| 1527 | for more information. |
| 1528 | |
| 1529 | Having to even think about the C<$^S> variable in your exception |
| 1530 | handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented |
| 1531 | invites grievous and difficult to track down errors. Avoid it |
| 1532 | and use an C<END{}> or CORE::GLOBAL::die override instead. |