rename byte:: to bytes::
[p5sagit/p5-mst-13.2.git] / pod / perlvar.pod
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 will alias all the short names to the
17 long names in the current package.  Some even have medium names,
18 generally borrowed from B<awk>.
19
20 If you don't mind the performance hit, variables that depend on the
21 currently selected filehandle may instead be set by calling an
22 appropriate object method on the IO::Handle object.  (Summary lines
23 below for this contain the word HANDLE.)  First you must say
24
25     use IO::Handle;
26
27 after which you may use either
28
29     method HANDLE EXPR
30
31 or more safely,
32
33     HANDLE->method(EXPR)
34
35 Each method returns the old value of the IO::Handle attribute.
36 The methods each take an optional EXPR, which if supplied specifies the
37 new value for the IO::Handle attribute in question.  If not supplied,
38 most methods do nothing to the current value--except for
39 autoflush(), which will assume a 1 for you, just to be different.
40 Because loading in the IO::Handle class is an expensive operation, you should
41 learn how to use the regular built-in variables.
42
43 A few of these variables are considered "read-only".  This means that if
44 you try to assign to this variable, either directly or indirectly through
45 a reference, you'll raise a run-time exception.
46
47 The following list is ordered by scalar variables first, then the
48 arrays, then the hashes.
49
50 =over 8
51
52 =item $ARG
53
54 =item $_
55
56 The default input and pattern-searching space.  The following pairs are
57 equivalent:
58
59     while (<>) {...}    # equivalent only in while!
60     while (defined($_ = <>)) {...}
61
62     /^Subject:/
63     $_ =~ /^Subject:/
64
65     tr/a-z/A-Z/
66     $_ =~ tr/a-z/A-Z/
67
68     chomp
69     chomp($_)
70
71 Here are the places where Perl will assume $_ even if you
72 don't use it:
73
74 =over 3
75
76 =item *
77
78 Various unary functions, including functions like ord() and int(), as well
79 as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to
80 STDIN.
81
82 =item *
83
84 Various list functions like print() and unlink().
85
86 =item *
87
88 The pattern matching operations C<m//>, C<s///>, and C<tr///> when used
89 without an C<=~> operator.
90
91 =item *
92
93 The default iterator variable in a C<foreach> loop if no other
94 variable is supplied.
95
96 =item *
97
98 The implicit iterator variable in the grep() and map() functions.
99
100 =item *
101
102 The default place to put an input record when a C<E<lt>FHE<gt>>
103 operation's result is tested by itself as the sole criterion of a C<while>
104 test.  Outside a C<while> test, this will not happen.
105
106 =back
107
108 (Mnemonic: underline is understood in certain operations.)
109
110 =back
111
112 =over 8
113
114 =item $E<lt>I<digits>E<gt>
115
116 Contains the subpattern from the corresponding set of capturing
117 parentheses from the last pattern match, not counting patterns
118 matched in nested blocks that have been exited already.  (Mnemonic:
119 like \digits.)  These variables are all read-only and dynamically
120 scoped to the current BLOCK.
121
122 =item $MATCH
123
124 =item $&
125
126 The string matched by the last successful pattern match (not counting
127 any matches hidden within a BLOCK or eval() enclosed by the current
128 BLOCK).  (Mnemonic: like & in some editors.)  This variable is read-only
129 and dynamically scoped to the current BLOCK.
130
131 The use of this variable anywhere in a program imposes a considerable
132 performance penalty on all regular expression matches.  See L<BUGS>.
133
134 =item $PREMATCH
135
136 =item $`
137
138 The string preceding whatever was matched by the last successful
139 pattern match (not counting any matches hidden within a BLOCK or eval
140 enclosed by the current BLOCK).  (Mnemonic: C<`> often precedes a quoted
141 string.)  This variable is read-only.
142
143 The use of this variable anywhere in a program imposes a considerable
144 performance penalty on all regular expression matches.  See L<BUGS>.
145
146 =item $POSTMATCH
147
148 =item $'
149
150 The string following whatever was matched by the last successful
151 pattern match (not counting any matches hidden within a BLOCK or eval()
152 enclosed by the current BLOCK).  (Mnemonic: C<'> often follows a quoted
153 string.)  Example:
154
155     $_ = 'abcdefghi';
156     /def/;
157     print "$`:$&:$'\n";         # prints abc:def:ghi
158
159 This variable is read-only and dynamically scoped to the current BLOCK.
160
161 The use of this variable anywhere in a program imposes a considerable
162 performance penalty on all regular expression matches.  See L<BUGS>.
163
164 =item $LAST_PAREN_MATCH
165
166 =item $+
167
168 The last bracket matched by the last search pattern.  This is useful if
169 you don't know which one of a set of alternative patterns matched.  For
170 example:
171
172     /Version: (.*)|Revision: (.*)/ && ($rev = $+);
173
174 (Mnemonic: be positive and forward looking.)
175 This variable is read-only and dynamically scoped to the current BLOCK.
176
177 =item @+
178
179 $+[0] is the offset of the end of the last successful match.
180 C<$+[>I<n>C<]> is the offset of the end of the substring matched by
181 I<n>-th subpattern, or undef if the subpattern did not match.
182
183 Thus after a match against $_, $& coincides with C<substr $_, $-[0],
184 $+[0] - $-[0]>.  Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
185 $+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
186 C<substr $_, $-[$#-], $+[$#-]>.  One can use C<$#+> to find the number
187 of subgroups in the last successful match.  Contrast with
188 C<$#E<45>>, the last I<matched> subgroup.  Compare with C<@E<45>>.
189
190 =item $MULTILINE_MATCHING
191
192 =item $*
193
194 Set to 1 to do multi-line matching within a string, 0 to tell Perl
195 that it can assume that strings contain a single line, for the purpose
196 of optimizing pattern matches.  Pattern matches on strings containing
197 multiple newlines can produce confusing results when C<$*> is 0.  Default
198 is 0.  (Mnemonic: * matches multiple things.)  This variable
199 influences the interpretation of only C<^> and C<$>.  A literal newline can
200 be searched for even when C<$* == 0>.
201
202 Use of C<$*> is deprecated in modern Perl, supplanted by 
203 the C</s> and C</m> modifiers on pattern matching.
204
205 =item input_line_number HANDLE EXPR
206
207 =item $INPUT_LINE_NUMBER
208
209 =item $NR
210
211 =item $.
212
213 The current input record number for the last file handle from which
214 you just read() (or called a C<seek> or C<tell> on).  The value
215 may be different from the actual physical line number in the file,
216 depending on what notion of "line" is in effect--see C<$/> on how
217 to change that.  An explicit close on a filehandle resets the line
218 number.  Because C<E<lt>E<gt>> never does an explicit close, line
219 numbers increase across ARGV files (but see examples in L<perlfunc/eof>).
220 Consider this variable read-only: setting it does not reposition
221 the seek pointer; you'll have to do that on your own.  Localizing C<$.>
222 has the effect of also localizing Perl's notion of "the last read
223 filehandle".  (Mnemonic: many programs use "." to mean the current line
224 number.)
225
226 =item input_record_separator HANDLE EXPR
227
228 =item $INPUT_RECORD_SEPARATOR
229
230 =item $RS
231
232 =item $/
233
234 The input record separator, newline by default.  This 
235 influences Perl's idea of what a "line" is.  Works like B<awk>'s RS
236 variable, including treating empty lines as a terminator if set to
237 the null string.  (An empty line cannot contain any spaces
238 or tabs.)  You may set it to a multi-character string to match a
239 multi-character terminator, or to C<undef> to read through the end
240 of file.  Setting it to C<"\n\n"> means something slightly
241 different than setting to C<"">, if the file contains consecutive
242 empty lines.  Setting to C<""> will treat two or more consecutive
243 empty lines as a single empty line.  Setting to C<"\n\n"> will
244 blindly assume that the next input character belongs to the next
245 paragraph, even if it's a newline.  (Mnemonic: / delimits
246 line boundaries when quoting poetry.)
247
248     undef $/;           # enable "slurp" mode
249     $_ = <FH>;          # whole file now here
250     s/\n[ \t]+/ /g;
251
252 Remember: the value of C<$/> is a string, not a regex.  B<awk> has to be
253 better for something. :-)
254
255 Setting C<$/> to a reference to an integer, scalar containing an integer, or
256 scalar that's convertible to an integer will attempt to read records
257 instead of lines, with the maximum record size being the referenced
258 integer.  So this:
259
260     $/ = \32768; # or \"32768", or \$var_containing_32768
261     open(FILE, $myfile);
262     $_ = <FILE>;
263
264 will read a record of no more than 32768 bytes from FILE.  If you're
265 not reading from a record-oriented file (or your OS doesn't have
266 record-oriented files), then you'll likely get a full chunk of data
267 with every read.  If a record is larger than the record size you've
268 set, you'll get the record back in pieces.
269
270 On VMS, record reads are done with the equivalent of C<sysread>,
271 so it's best not to mix record and non-record reads on the same
272 file.  (This is unlikely to be a problem, because any file you'd
273 want to read in record mode is probably unusable in line mode.)
274 Non-VMS systems do normal I/O, so it's safe to mix record and
275 non-record reads of a file.
276
277 See also L<perlport/"Newlines">.  Also see C<$.>.
278
279 =item autoflush HANDLE EXPR
280
281 =item $OUTPUT_AUTOFLUSH
282
283 =item $|
284
285 If set to nonzero, forces a flush right away and after every write
286 or print on the currently selected output channel.  Default is 0
287 (regardless of whether the channel is really buffered by the
288 system or not; C<$|> tells you only whether you've asked Perl
289 explicitly to flush after each write).  STDOUT will
290 typically be line buffered if output is to the terminal and block
291 buffered otherwise.  Setting this variable is useful primarily when
292 you are outputting to a pipe or socket, such as when you are running
293 a Perl program under B<rsh> and want to see the output as it's
294 happening.  This has no effect on input buffering.  See L<perlfunc/getc>
295 for that.  (Mnemonic: when you want your pipes to be piping hot.)
296
297 =item output_field_separator HANDLE EXPR
298
299 =item $OUTPUT_FIELD_SEPARATOR
300
301 =item $OFS
302
303 =item $,
304
305 The output field separator for the print operator.  Ordinarily the
306 print operator simply prints out its arguments without further
307 adornment.  To get behavior more like B<awk>, set this variable as
308 you would set B<awk>'s OFS variable to specify what is printed
309 between fields.  (Mnemonic: what is printed when there is a "," in
310 your print statement.)
311
312 =item output_record_separator HANDLE EXPR
313
314 =item $OUTPUT_RECORD_SEPARATOR
315
316 =item $ORS
317
318 =item $\
319
320 The output record separator for the print operator.  Ordinarily the
321 print operator simply prints out its arguments as is, with no
322 trailing newline or other end-of-record string added.  To get
323 behavior more like B<awk>, set this variable as you would set
324 B<awk>'s ORS variable to specify what is printed at the end of the
325 print.  (Mnemonic: you set C<$\> instead of adding "\n" at the
326 end of the print.  Also, it's just like C<$/>, but it's what you
327 get "back" from Perl.)
328
329 =item $LIST_SEPARATOR
330
331 =item $"
332
333 This is like C<$,> except that it applies to array and slice values
334 interpolated into a double-quoted string (or similar interpreted
335 string).  Default is a space.  (Mnemonic: obvious, I think.)
336
337 =item $SUBSCRIPT_SEPARATOR
338
339 =item $SUBSEP
340
341 =item $;
342
343 The subscript separator for multidimensional array emulation.  If you
344 refer to a hash element as
345
346     $foo{$a,$b,$c}
347
348 it really means
349
350     $foo{join($;, $a, $b, $c)}
351
352 But don't put
353
354     @foo{$a,$b,$c}      # a slice--note the @
355
356 which means
357
358     ($foo{$a},$foo{$b},$foo{$c})
359
360 Default is "\034", the same as SUBSEP in B<awk>.  If your
361 keys contain binary data there might not be any safe value for C<$;>.
362 (Mnemonic: comma (the syntactic subscript separator) is a
363 semi-semicolon.  Yeah, I know, it's pretty lame, but C<$,> is already
364 taken for something more important.)
365
366 Consider using "real" multidimensional arrays as described
367 in L<perllol>.
368
369 =item $OFMT
370
371 =item $#
372
373 The output format for printed numbers.  This variable is a half-hearted
374 attempt to emulate B<awk>'s OFMT variable.  There are times, however,
375 when B<awk> and Perl have differing notions of what counts as 
376 numeric.  The initial value is "%.I<n>g", where I<n> is the value
377 of the macro DBL_DIG from your system's F<float.h>.  This is different from
378 B<awk>'s default OFMT setting of "%.6g", so you need to set C<$#>
379 explicitly to get B<awk>'s value.  (Mnemonic: # is the number sign.)
380
381 Use of C<$#> is deprecated.
382
383 =item format_page_number HANDLE EXPR
384
385 =item $FORMAT_PAGE_NUMBER
386
387 =item $%
388
389 The current page number of the currently selected output channel.
390 Used with formats.
391 (Mnemonic: % is page number in B<nroff>.)
392
393 =item format_lines_per_page HANDLE EXPR
394
395 =item $FORMAT_LINES_PER_PAGE
396
397 =item $=
398
399 The current page length (printable lines) of the currently selected
400 output channel.  Default is 60.  
401 Used with formats.
402 (Mnemonic: = has horizontal lines.)
403
404 =item format_lines_left HANDLE EXPR
405
406 =item $FORMAT_LINES_LEFT
407
408 =item $-
409
410 The number of lines left on the page of the currently selected output
411 channel.  
412 Used with formats.
413 (Mnemonic: lines_on_page - lines_printed.)
414
415 =item @-
416
417 $-[0] is the offset of the start of the last successful match.
418 C<$-[>I<n>C<]> is the offset of the start of the substring matched by
419 I<n>-th subpattern, or undef if the subpattern did not match.
420
421 Thus after a match against $_, $& coincides with C<substr $_, $-[0],
422 $+[0] - $-[0]>.  Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
423 $+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
424 C<substr $_, $-[$#-], $+[$#-]>.  One can use C<$#E<45>> to find the last
425 matched subgroup in the last successful match.  Contrast with
426 C<$#+>, the number of subgroups in the regular expression.  Compare
427 with C<@+>.
428
429 =item format_name HANDLE EXPR
430
431 =item $FORMAT_NAME
432
433 =item $~
434
435 The name of the current report format for the currently selected output
436 channel.  Default is the name of the filehandle.  (Mnemonic: brother to
437 C<$^>.)
438
439 =item format_top_name HANDLE EXPR
440
441 =item $FORMAT_TOP_NAME
442
443 =item $^
444
445 The name of the current top-of-page format for the currently selected
446 output channel.  Default is the name of the filehandle with _TOP
447 appended.  (Mnemonic: points to top of page.)
448
449 =item format_line_break_characters HANDLE EXPR
450
451 =item $FORMAT_LINE_BREAK_CHARACTERS
452
453 =item $:
454
455 The current set of characters after which a string may be broken to
456 fill continuation fields (starting with ^) in a format.  Default is
457 S<" \n-">, to break on whitespace or hyphens.  (Mnemonic: a "colon" in
458 poetry is a part of a line.)
459
460 =item format_formfeed HANDLE EXPR
461
462 =item $FORMAT_FORMFEED
463
464 =item $^L
465
466 What formats output as a form feed.  Default is \f.
467
468 =item $ACCUMULATOR
469
470 =item $^A
471
472 The current value of the write() accumulator for format() lines.  A format
473 contains formline() calls that put their result into C<$^A>.  After
474 calling its format, write() prints out the contents of C<$^A> and empties.
475 So you never really see the contents of C<$^A> unless you call
476 formline() yourself and then look at it.  See L<perlform> and
477 L<perlfunc/formline()>.
478
479 =item $CHILD_ERROR
480
481 =item $?
482
483 The status returned by the last pipe close, backtick (C<``>) command,
484 successful call to wait() or waitpid(), or from the system()
485 operator.  This is just the 16-bit status word returned by the
486 wait() system call (or else is made up to look like it).  Thus, the
487 exit value of the subprocess is really (C<$? E<gt>E<gt> 8>), and
488 C<$? & 127> gives which signal, if any, the process died from, and
489 C<$? & 128> reports whether there was a core dump.  (Mnemonic:
490 similar to B<sh> and B<ksh>.)
491
492 Additionally, if the C<h_errno> variable is supported in C, its value
493 is returned via $? if any C<gethost*()> function fails.
494
495 If you have installed a signal handler for C<SIGCHLD>, the
496 value of C<$?> will usually be wrong outside that handler.
497
498 Inside an C<END> subroutine C<$?> contains the value that is going to be
499 given to C<exit()>.  You can modify C<$?> in an C<END> subroutine to
500 change the exit status of your program.  For example:
501
502     END {
503         $? = 1 if $? == 255;  # die would make it 255
504     } 
505
506 Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
507 actual VMS exit status, instead of the default emulation of POSIX
508 status.
509
510 Also see L<Error Indicators>.
511
512 =item $OS_ERROR
513
514 =item $ERRNO
515
516 =item $!
517
518 If used numerically, yields the current value of the C C<errno>
519 variable, with all the usual caveats.  (This means that you shouldn't
520 depend on the value of C<$!> to be anything in particular unless
521 you've gotten a specific error return indicating a system error.)
522 If used an a string, yields the corresponding system error string.
523 You can assign a number to C<$!> to set I<errno> if, for instance,
524 you want C<"$!"> to return the string for error I<n>, or you want
525 to set the exit value for the die() operator.  (Mnemonic: What just
526 went bang?)
527
528 Also see L<Error Indicators>.
529
530 =item $EXTENDED_OS_ERROR
531
532 =item $^E
533
534 Error information specific to the current operating system.  At
535 the moment, this differs from C<$!> under only VMS, OS/2, and Win32
536 (and for MacPerl).  On all other platforms, C<$^E> is always just
537 the same as C<$!>.
538
539 Under VMS, C<$^E> provides the VMS status value from the last
540 system error.  This is more specific information about the last
541 system error than that provided by C<$!>.  This is particularly
542 important when C<$!> is set to B<EVMSERR>.
543
544 Under OS/2, C<$^E> is set to the error code of the last call to
545 OS/2 API either via CRT, or directly from perl.
546
547 Under Win32, C<$^E> always returns the last error information
548 reported by the Win32 call C<GetLastError()> which describes
549 the last error from within the Win32 API.  Most Win32-specific
550 code will report errors via C<$^E>.  ANSI C and Unix-like calls
551 set C<errno> and so most portable Perl code will report errors
552 via C<$!>. 
553
554 Caveats mentioned in the description of C<$!> generally apply to
555 C<$^E>, also.  (Mnemonic: Extra error explanation.)
556
557 Also see L<Error Indicators>.
558
559 =item $EVAL_ERROR
560
561 =item $@
562
563 The Perl syntax error message from the last eval() operator.  If null, the
564 last eval() parsed and executed correctly (although the operations you
565 invoked may have failed in the normal fashion).  (Mnemonic: Where was
566 the syntax error "at"?)
567
568 Warning messages are not collected in this variable.  You can,
569 however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
570 as described below.
571
572 Also see L<Error Indicators>.
573
574 =item $PROCESS_ID
575
576 =item $PID
577
578 =item $$
579
580 The process number of the Perl running this script.  You should
581 consider this variable read-only, although it will be altered
582 across fork() calls.  (Mnemonic: same as shells.)
583
584 =item $REAL_USER_ID
585
586 =item $UID
587
588 =item $<
589
590 The real uid of this process.  (Mnemonic: it's the uid you came I<from>,
591 if you're running setuid.)
592
593 =item $EFFECTIVE_USER_ID
594
595 =item $EUID
596
597 =item $>
598
599 The effective uid of this process.  Example:
600
601     $< = $>;            # set real to effective uid
602     ($<,$>) = ($>,$<);  # swap real and effective uid
603
604 (Mnemonic: it's the uid you went I<to>, if you're running setuid.)
605 C<$E<lt>> and C<$E<gt>> can be swapped only on machines
606 supporting setreuid().
607
608 =item $REAL_GROUP_ID
609
610 =item $GID
611
612 =item $(
613
614 The real gid of this process.  If you are on a machine that supports
615 membership in multiple groups simultaneously, gives a space separated
616 list of groups you are in.  The first number is the one returned by
617 getgid(), and the subsequent ones by getgroups(), one of which may be
618 the same as the first number.
619
620 However, a value assigned to C<$(> must be a single number used to
621 set the real gid.  So the value given by C<$(> should I<not> be assigned
622 back to C<$(> without being forced numeric, such as by adding zero.
623
624 (Mnemonic: parentheses are used to I<group> things.  The real gid is the
625 group you I<left>, if you're running setgid.)
626
627 =item $EFFECTIVE_GROUP_ID
628
629 =item $EGID
630
631 =item $)
632
633 The effective gid of this process.  If you are on a machine that
634 supports membership in multiple groups simultaneously, gives a space
635 separated list of groups you are in.  The first number is the one
636 returned by getegid(), and the subsequent ones by getgroups(), one of
637 which may be the same as the first number.
638
639 Similarly, a value assigned to C<$)> must also be a space-separated
640 list of numbers.  The first number sets the effective gid, and
641 the rest (if any) are passed to setgroups().  To get the effect of an
642 empty list for setgroups(), just repeat the new effective gid; that is,
643 to force an effective gid of 5 and an effectively empty setgroups()
644 list, say C< $) = "5 5" >.
645
646 (Mnemonic: parentheses are used to I<group> things.  The effective gid
647 is the group that's I<right> for you, if you're running setgid.)
648
649 C<$E<lt>>, C<$E<gt>>, C<$(> and C<$)> can be set only on
650 machines that support the corresponding I<set[re][ug]id()> routine.  C<$(>
651 and C<$)> can be swapped only on machines supporting setregid().
652
653 =item $PROGRAM_NAME
654
655 =item $0
656
657 Contains the name of the program being executed.  On some operating
658 systems assigning to C<$0> modifies the argument area that the B<ps>
659 program sees.  This is more useful as a way of indicating the current
660 program state than it is for hiding the program you're running.
661 (Mnemonic: same as B<sh> and B<ksh>.)
662
663 =item $[
664
665 The index of the first element in an array, and of the first character
666 in a substring.  Default is 0, but you could theoretically set it
667 to 1 to make Perl behave more like B<awk> (or Fortran) when
668 subscripting and when evaluating the index() and substr() functions.
669 (Mnemonic: [ begins subscripts.)
670
671 As of release 5 of Perl, assignment to C<$[> is treated as a compiler
672 directive, and cannot influence the behavior of any other file.
673 Its use is highly discouraged.
674
675 =item $PERL_VERSION
676
677 =item $]
678
679 The version + patchlevel / 1000 of the Perl interpreter.  This variable
680 can be used to determine whether the Perl interpreter executing a
681 script is in the right range of versions.  (Mnemonic: Is this version
682 of perl in the right bracket?)  Example:
683
684     warn "No checksumming!\n" if $] < 3.019;
685
686 See also the documentation of C<use VERSION> and C<require VERSION>
687 for a convenient way to fail if the running Perl interpreter is too old.
688
689 See C<$^V> for a more modern representation of the Perl version.
690
691 =item $COMPILING
692
693 =item $^C
694
695 The current value of the flag associated with the B<-c> switch.
696 Mainly of use with B<-MO=...> to allow code to alter its behavior
697 when being compiled, such as for example to AUTOLOAD at compile
698 time rather than normal, deferred loading.  See L<perlcc>.  Setting
699 C<$^C = 1> is similar to calling C<B::minus_c>.
700
701 =item $DEBUGGING
702
703 =item $^D
704
705 The current value of the debugging flags.  (Mnemonic: value of B<-D>
706 switch.)
707
708 =item $SYSTEM_FD_MAX
709
710 =item $^F
711
712 The maximum system file descriptor, ordinarily 2.  System file
713 descriptors are passed to exec()ed processes, while higher file
714 descriptors are not.  Also, during an open(), system file descriptors are
715 preserved even if the open() fails.  (Ordinary file descriptors are
716 closed before the open() is attempted.)  The close-on-exec
717 status of a file descriptor will be decided according to the value of
718 C<$^F> when the open() or pipe() was called, not the time of the exec().
719
720 =item $^H
721
722 WARNING: This variable is strictly for internal use only.  Its availability,
723 behavior, and contents are subject to change without notice.
724
725 This variable contains compile-time hints for the Perl interpreter.  At the
726 end of compilation of a BLOCK the value of this variable is restored to the
727 value when the interpreter started to compile the BLOCK.
728
729 When perl begins to parse any block construct that provides a lexical scope
730 (e.g., eval body, required file, subroutine body, loop body, or conditional
731 block), the existing value of $^H is saved, but its value is left unchanged.
732 When the compilation of the block is completed, it regains the saved value.
733 Between the points where its value is saved and restored, code that
734 executes within BEGIN blocks is free to change the value of $^H.
735
736 This behavior provides the semantic of lexical scoping, and is used in,
737 for instance, the C<use strict> pragma.
738
739 The contents should be an integer; different bits of it are used for
740 different pragmatic flags.  Here's an example:
741
742     sub add_100 { $^H |= 0x100 }
743
744     sub foo {
745         BEGIN { add_100() }
746         bar->baz($boon);
747     }
748
749 Consider what happens during execution of the BEGIN block.  At this point
750 the BEGIN block has already been compiled, but the body of foo() is still
751 being compiled.  The new value of $^H will therefore be visible only while
752 the body of foo() is being compiled.
753
754 Substitution of the above BEGIN block with:
755
756     BEGIN { require strict; strict->import('vars') }
757
758 demonstrates how C<use strict 'vars'> is implemented.  Here's a conditional
759 version of the same lexical pragma:
760
761     BEGIN { require strict; strict->import('vars') if $condition }
762
763 =item %^H
764
765 WARNING: This variable is strictly for internal use only.  Its availability,
766 behavior, and contents are subject to change without notice.
767
768 The %^H hash provides the same scoping semantic as $^H.  This makes it
769 useful for implementation of lexically scoped pragmas.
770
771 =item $INPLACE_EDIT
772
773 =item $^I
774
775 The current value of the inplace-edit extension.  Use C<undef> to disable
776 inplace editing.  (Mnemonic: value of B<-i> switch.)
777
778 =item $^M
779
780 By default, running out of memory is an untrappable, fatal error.
781 However, if suitably built, Perl can use the contents of C<$^M>
782 as an emergency memory pool after die()ing.  Suppose that your Perl
783 were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.
784 Then
785
786     $^M = 'a' x (1 << 16);
787
788 would allocate a 64K buffer for use when in emergency.  See the
789 F<INSTALL> file in the Perl distribution for information on how to
790 enable this option.  To discourage casual use of this advanced
791 feature, there is no L<English> long name for this variable.
792
793 =item $OSNAME
794
795 =item $^O
796
797 The name of the operating system under which this copy of Perl was
798 built, as determined during the configuration process.  The value
799 is identical to C<$Config{'osname'}>.  See also L<Config> and the 
800 B<-V> command-line switch documented in L<perlrun>.
801
802 =item $PERLDB
803
804 =item $^P
805
806 The internal variable for debugging support.  The meanings of the
807 various bits are subject to change, but currently indicate:
808
809 =over 6
810
811 =item 0x01
812
813 Debug subroutine enter/exit.
814
815 =item 0x02
816
817 Line-by-line debugging.
818
819 =item 0x04
820
821 Switch off optimizations.
822
823 =item 0x08
824
825 Preserve more data for future interactive inspections.
826
827 =item 0x10
828
829 Keep info about source lines on which a subroutine is defined.
830
831 =item 0x20
832
833 Start with single-step on.
834
835 =item 0x40
836
837 Use subroutine address instead of name when reporting.
838
839 =item 0x80
840
841 Report C<goto &subroutine> as well.
842
843 =item 0x100
844
845 Provide informative "file" names for evals based on the place they were compiled.
846
847 =item 0x200
848
849 Provide informative names to anonymous subroutines based on the place they
850 were compiled.
851
852 =back
853
854 Some bits may be relevant at compile-time only, some at
855 run-time only.  This is a new mechanism and the details may change.
856
857 =item $LAST_REGEXP_CODE_RESULT
858
859 =item $^R
860
861 The result of evaluation of the last successful C<(?{ code })>
862 regular expression assertion (see L<perlre>).  May be written to.
863
864 =item $EXCEPTIONS_BEING_CAUGHT
865
866 =item $^S
867
868 Current state of the interpreter.  Undefined if parsing of the current
869 module/eval is not finished (may happen in $SIG{__DIE__} and
870 $SIG{__WARN__} handlers).  True if inside an eval(), otherwise false.
871
872 =item $BASETIME
873
874 =item $^T
875
876 The time at which the program began running, in seconds since the
877 epoch (beginning of 1970).  The values returned by the B<-M>, B<-A>,
878 and B<-C> filetests are based on this value.
879
880 =item $PERL_VERSION_TUPLE
881
882 =item $^V
883
884 The revision, version, and subversion of the Perl interpreter, represented
885 as a "version tuple".  Version tuples have both a numeric value and a
886 string value.  The numeric value is a floating point number that amounts
887 to revision + version/1000 + subversion/1000000, and the string value
888 is made of characters possibly in the UTF-8 range:
889 C<chr($revision) . chr($version) . chr($subversion)>.
890
891 This can be used to determine whether the Perl interpreter executing a
892 script is in the right range of versions.  (Mnemonic: use ^V for Version
893 control.)  Example:
894
895     warn "No "our" declarations!\n" if $^V and $^V lt v5.6;
896
897 See also the documentation of C<use VERSION> and C<require VERSION>
898 for a convenient way to fail if the running Perl interpreter is too old.
899
900 See also C<$]> for an older representation of the Perl version.
901
902 =item $WARNING
903
904 =item $^W
905
906 The current value of the warning switch, initially true if B<-w>
907 was used, false otherwise, but directly modifiable.  (Mnemonic:
908 related to the B<-w> switch.)  See also L<warnings>.
909
910 =item ${^WARNING_BITS}
911
912 The current set of warning checks enabled by the C<use warnings> pragma.
913 See the documentation of C<warnings> for more details.
914
915 =item ${^WIDE_SYSTEM_CALLS}
916
917 Global flag that enables system calls made by Perl to use wide character
918 APIs native to the system, if available.  This is currently only implemented
919 on the Windows platform.
920
921 This can also be enabled from the command line using the C<-C> switch.
922
923 The initial value is typically C<0> for compatibility with Perl versions
924 earlier than 5.6, but may be automatically set to C<1> by Perl if the system
925 provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>).
926
927 The C<bytes> pragma always overrides the effect of this flag in the current
928 lexical scope.  See L<bytes>.
929
930 =item $EXECUTABLE_NAME
931
932 =item $^X
933
934 The name that the Perl binary itself was executed as, from C's C<argv[0]>.
935 This may not be a full pathname, nor even necessarily in your path.
936
937 =item $ARGV
938
939 contains the name of the current file when reading from E<lt>E<gt>.
940
941 =item @ARGV
942
943 The array @ARGV contains the command-line arguments intended for
944 the script.  C<$#ARGV> is generally the number of arguments minus
945 one, because C<$ARGV[0]> is the first argument, I<not> the program's
946 command name itself.  See C<$0> for the command name.
947
948 =item @INC
949
950 The array @INC contains the list of places that the C<do EXPR>,
951 C<require>, or C<use> constructs look for their library files.  It
952 initially consists of the arguments to any B<-I> command-line
953 switches, followed by the default Perl library, probably
954 F</usr/local/lib/perl>, followed by ".", to represent the current
955 directory.  If you need to modify this at runtime, you should use
956 the C<use lib> pragma to get the machine-dependent library properly
957 loaded also:
958
959     use lib '/mypath/libdir/';
960     use SomeMod;
961
962 =item @_
963
964 Within a subroutine the array @_ contains the parameters passed to that
965 subroutine.  See L<perlsub>.
966
967 =item %INC
968
969 The hash %INC contains entries for each filename included via the
970 C<do>, C<require>, or C<use> operators.  The key is the filename
971 you specified (with module names converted to pathnames), and the
972 value is the location of the file found.  The C<require>
973 operator uses this hash to determine whether a particular file has
974 already been included.
975
976 =item %ENV
977
978 =item $ENV{expr}
979
980 The hash %ENV contains your current environment.  Setting a
981 value in C<ENV> changes the environment for any child processes
982 you subsequently fork() off.
983
984 =item %SIG
985
986 =item $SIG{expr}
987
988 The hash %SIG contains signal handlers for signals.  For example:
989
990     sub handler {       # 1st argument is signal name
991         my($sig) = @_;
992         print "Caught a SIG$sig--shutting down\n";
993         close(LOG);
994         exit(0);
995     }
996
997     $SIG{'INT'}  = \&handler;
998     $SIG{'QUIT'} = \&handler;
999     ...
1000     $SIG{'INT'}  = 'DEFAULT';   # restore default action
1001     $SIG{'QUIT'} = 'IGNORE';    # ignore SIGQUIT
1002
1003 Using a value of C<'IGNORE'> usually has the effect of ignoring the
1004 signal, except for the C<CHLD> signal.  See L<perlipc> for more about
1005 this special case.
1006
1007 Here are some other examples:
1008
1009     $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not recommended)
1010     $SIG{"PIPE"} = \&Plumber;   # just fine; assume current Plumber
1011     $SIG{"PIPE"} = *Plumber;    # somewhat esoteric
1012     $SIG{"PIPE"} = Plumber();   # oops, what did Plumber() return??
1013
1014 Be sure not to use a bareword as the name of a signal handler,
1015 lest you inadvertently call it. 
1016
1017 If your system has the sigaction() function then signal handlers are
1018 installed using it.  This means you get reliable signal handling.  If
1019 your system has the SA_RESTART flag it is used when signals handlers are
1020 installed.  This means that system calls for which restarting is supported
1021 continue rather than returning when a signal arrives.  If you want your
1022 system calls to be interrupted by signal delivery then do something like
1023 this:
1024
1025     use POSIX ':signal_h';
1026
1027     my $alarm = 0;
1028     sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 }
1029         or die "Error setting SIGALRM handler: $!\n";
1030
1031 See L<POSIX>.
1032
1033 Certain internal hooks can be also set using the %SIG hash.  The
1034 routine indicated by C<$SIG{__WARN__}> is called when a warning message is
1035 about to be printed.  The warning message is passed as the first
1036 argument.  The presence of a __WARN__ hook causes the ordinary printing
1037 of warnings to STDERR to be suppressed.  You can use this to save warnings
1038 in a variable, or turn warnings into fatal errors, like this:
1039
1040     local $SIG{__WARN__} = sub { die $_[0] };
1041     eval $proggie;
1042
1043 The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception
1044 is about to be thrown.  The error message is passed as the first
1045 argument.  When a __DIE__ hook routine returns, the exception
1046 processing continues as it would have in the absence of the hook,
1047 unless the hook routine itself exits via a C<goto>, a loop exit, or a die().
1048 The C<__DIE__> handler is explicitly disabled during the call, so that you
1049 can die from a C<__DIE__> handler.  Similarly for C<__WARN__>.
1050
1051 Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
1052 even inside an eval().  Do not use this to rewrite a pending exception
1053 in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die().
1054 This strange action at a distance may be fixed in a future release
1055 so that C<$SIG{__DIE__}> is only called if your program is about
1056 to exit, as was the original intent.  Any other use is deprecated.
1057
1058 C<__DIE__>/C<__WARN__> handlers are very special in one respect:
1059 they may be called to report (probable) errors found by the parser.
1060 In such a case the parser may be in inconsistent state, so any
1061 attempt to evaluate Perl code from such a handler will probably
1062 result in a segfault.  This means that warnings or errors that
1063 result from parsing Perl should be used with extreme caution, like
1064 this:
1065
1066     require Carp if defined $^S;
1067     Carp::confess("Something wrong") if defined &Carp::confess;
1068     die "Something wrong, but could not load Carp to give backtrace...
1069          To see backtrace try starting Perl with -MCarp switch";
1070
1071 Here the first line will load Carp I<unless> it is the parser who
1072 called the handler.  The second line will print backtrace and die if
1073 Carp was available.  The third line will be executed only if Carp was
1074 not available.
1075
1076 See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
1077 L<warnings> for additional information.
1078
1079 =back
1080
1081 =head2 Error Indicators
1082
1083 The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
1084 about different types of error conditions that may appear during
1085 execution of a Perl program.  The variables are shown ordered by
1086 the "distance" between the subsystem which reported the error and
1087 the Perl process.  They correspond to errors detected by the Perl
1088 interpreter, C library, operating system, or an external program,
1089 respectively.
1090
1091 To illustrate the differences between these variables, consider the 
1092 following Perl expression, which uses a single-quoted string:
1093
1094     eval q{
1095         open PIPE, "/cdrom/install |";
1096         @res = <PIPE>;
1097         close PIPE or die "bad pipe: $?, $!";
1098     };
1099
1100 After execution of this statement all 4 variables may have been set.  
1101
1102 C<$@> is set if the string to be C<eval>-ed did not compile (this
1103 may happen if C<open> or C<close> were imported with bad prototypes),
1104 or if Perl code executed during evaluation die()d .  In these cases
1105 the value of $@ is the compile error, or the argument to C<die>
1106 (which will interpolate C<$!> and C<$?>!).  (See also L<Fatal>,
1107 though.)
1108
1109 When the eval() expression above is executed, open(), C<<PIPEE<gt>>,
1110 and C<close> are translated to calls in the C run-time library and
1111 thence to the operating system kernel.  C<$!> is set to the C library's
1112 C<errno> if one of these calls fails. 
1113
1114 Under a few operating systems, C<$^E> may contain a more verbose
1115 error indicator, such as in this case, "CDROM tray not closed."
1116 Systems that do not support extended error messages leave C<$^E>
1117 the same as C<$!>.
1118
1119 Finally, C<$?> may be set to non-0 value if the external program
1120 F</cdrom/install> fails.  The upper eight bits reflect specific
1121 error conditions encountered by the program (the program's exit()
1122 value).   The lower eight bits reflect mode of failure, like signal
1123 death and core dump information  See wait(2) for details.  In
1124 contrast to C<$!> and C<$^E>, which are set only if error condition
1125 is detected, the variable C<$?> is set on each C<wait> or pipe
1126 C<close>, overwriting the old value.  This is more like C<$@>, which
1127 on every eval() is always set on failure and cleared on success.
1128
1129 For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>,
1130 and C<$?>.
1131
1132 =head2 Technical Note on the Syntax of Variable Names
1133
1134 Variable names in Perl can have several formats.  Usually, they
1135 must begin with a letter or underscore, in which case they can be
1136 arbitrarily long (up to an internal limit of 251 characters) and
1137 may contain letters, digits, underscores, or the special sequence
1138 C<::> or C<'>.  In this case, the part before the last C<::> or
1139 C<'> is taken to be a I<package qualifier>; see L<perlmod>.
1140
1141 Perl variable names may also be a sequence of digits or a single
1142 punctuation or control character.  These names are all reserved for
1143 special uses by Perl; for example, the all-digits names are used
1144 to hold data captured by backreferences after a regular expression
1145 match.  Perl has a special syntax for the single-control-character
1146 names: It understands C<^X> (caret C<X>) to mean the control-C<X>
1147 character.  For example, the notation C<$^W> (dollar-sign caret
1148 C<W>) is the scalar variable whose name is the single character
1149 control-C<W>.  This is better than typing a literal control-C<W>
1150 into your program.
1151
1152 Finally, new in Perl 5.6, Perl variable names may be alphanumeric
1153 strings that begin with control characters (or better yet, a caret).
1154 These variables must be written in the form C<${^Foo}>; the braces
1155 are not optional.  C<${^Foo}> denotes the scalar variable whose
1156 name is a control-C<F> followed by two C<o>'s.  These variables are
1157 reserved for future special uses by Perl, except for the ones that
1158 begin with C<^_> (control-underscore or caret-underscore).  No
1159 control-character name that begins with C<^_> will acquire a special
1160 meaning in any future version of Perl; such names may therefore be
1161 used safely in programs.  C<$^_> itself, however, I<is> reserved.
1162
1163 Perl identifiers that begin with digits, control characters, or
1164 punctuation characters are exempt from the effects of the C<package>
1165 declaration and are always forced to be in package C<main>.  A few
1166 other names are also exempt:
1167
1168         ENV             STDIN
1169         INC             STDOUT
1170         ARGV            STDERR
1171         ARGVOUT
1172         SIG
1173
1174 In particular, the new special C<${^_XYZ}> variables are always taken
1175 to be in package C<main>, regardless of any C<package> declarations
1176 presently in scope.
1177
1178 =head1 BUGS
1179
1180 Due to an unfortunate accident of Perl's implementation, C<use
1181 English> imposes a considerable performance penalty on all regular
1182 expression matches in a program, regardless of whether they occur
1183 in the scope of C<use English>.  For that reason, saying C<use
1184 English> in libraries is strongly discouraged.  See the
1185 Devel::SawAmpersand module documentation from CPAN
1186 (http://www.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme)
1187 for more information.
1188
1189 Having to even think about the C<$^S> variable in your exception
1190 handlers is simply wrong.  C<$SIG{__DIE__}> as currently implemented
1191 invites grievous and difficult to track down errors.  Avoid it
1192 and use an C<END{}> or CORE::GLOBAL::die override instead.