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