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