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