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