X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/9bf2270250326fb85445d6849ed84a94434dd12c..5e220227379abcad75ff0534a6b23aa30c22c695:/pod/perlvar.pod diff --git a/pod/perlvar.pod b/pod/perlvar.pod index bcd8ecf..14324a5 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -4,120 +4,77 @@ perlvar - Perl predefined variables =head1 DESCRIPTION -=head2 Predefined Names +=head2 The Syntax of Variable Names -The following names have special meaning to Perl. Most -punctuation names have reasonable mnemonics, or analogs in the -shells. Nevertheless, if you wish to use long variable names, -you need only say - - use English; - -at the top of your program. This aliases all the short names to the long -names in the current package. Some even have medium names, generally -borrowed from B. In general, it's best to use the - - use English '-no_match_vars'; - -invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids -a certain performance hit with the use of regular expressions. See -L. - -Variables that depend on the currently selected filehandle may be set by -calling an appropriate object method on the IO::Handle object, although -this is less efficient than using the regular built-in variables. (Summary -lines below for this contain the word HANDLE.) First you must say - - use IO::Handle; - -after which you may use either - - method HANDLE EXPR - -or more safely, - - HANDLE->method(EXPR) - -Each method returns the old value of the IO::Handle attribute. -The methods each take an optional EXPR, which, if supplied, specifies the -new value for the IO::Handle attribute in question. If not supplied, -most methods do nothing to the current value--except for -autoflush(), which will assume a 1 for you, just to be different. - -Because loading in the IO::Handle class is an expensive operation, you should -learn how to use the regular built-in variables. - -A few of these variables are considered "read-only". This means that if -you try to assign to this variable, either directly or indirectly through -a reference, you'll raise a run-time exception. - -You should be very careful when modifying the default values of most -special variables described in this document. In most cases you want -to localize these variables before changing them, since if you don't, -the change may affect other modules which rely on the default values -of the special variables that you have changed. This is one of the -correct ways to read the whole file at once: - - open my $fh, "<", "foo" or die $!; - local $/; # enable localized slurp mode - my $content = <$fh>; - close $fh; - -But the following code is quite bad: - - open my $fh, "<", "foo" or die $!; - undef $/; # enable slurp mode - my $content = <$fh>; - close $fh; - -since some other module, may want to read data from some file in the -default "line mode", so if the code we have just presented has been -executed, the global value of C<$/> is now changed for any other code -running inside the same Perl interpreter. +Variable names in Perl can have several formats. Usually, they +must begin with a letter or underscore, in which case they can be +arbitrarily long (up to an internal limit of 251 characters) and +may contain letters, digits, underscores, or the special sequence +C<::> or C<'>. In this case, the part before the last C<::> or +C<'> is taken to be a I; see L. -Usually when a variable is localized you want to make sure that this -change affects the shortest scope possible. So unless you are already -inside some short C<{}> block, you should create one yourself. For -example: +Perl variable names may also be a sequence of digits or a single +punctuation or control character. These names are all reserved for +special uses by Perl; for example, the all-digits names are used +to hold data captured by backreferences after a regular expression +match. Perl has a special syntax for the single-control-character +names: It understands C<^X> (caret C) to mean the control-C +character. For example, the notation C<$^W> (dollar-sign caret +C) is the scalar variable whose name is the single character +control-C. This is better than typing a literal control-C +into your program. - my $content = ''; - open my $fh, "<", "foo" or die $!; - { - local $/; - $content = <$fh>; - } - close $fh; +Since Perl v5.6.0, Perl variable names may be alphanumeric +strings that begin with control characters (or better yet, a caret). +These variables must be written in the form C<${^Foo}>; the braces +are not optional. C<${^Foo}> denotes the scalar variable whose +name is a control-C followed by two C's. These variables are +reserved for future special uses by Perl, except for the ones that +begin with C<^_> (control-underscore or caret-underscore). No +control-character name that begins with C<^_> will acquire a special +meaning in any future version of Perl; such names may therefore be +used safely in programs. C<$^_> itself, however, I reserved. -Here is an example of how your own code can go broken: +Perl identifiers that begin with digits, control characters, or +punctuation characters are exempt from the effects of the C +declaration and are always forced to be in package C
; they are +also exempt from C errors. A few other names are also +exempt in these ways: - for (1..5){ - nasty_break(); - print "$_ "; - } - sub nasty_break { - $_ = 5; - # do something with $_ - } + ENV STDIN + INC STDOUT + ARGV STDERR + ARGVOUT + SIG -You probably expect this code to print: +In particular, the special C<${^_XYZ}> variables are always taken +to be in package C
, regardless of any C declarations +presently in scope. - 1 2 3 4 5 +=head1 SPECIAL VARIABLES -but instead you get: +The following names have special meaning to Perl. Most punctuation +names have reasonable mnemonics, or analogs in the shells. +Nevertheless, if you wish to use long variable names, you need only say: - 5 5 5 5 5 + use English; -Why? Because nasty_break() modifies C<$_> without localizing it -first. The fix is to add local(): +at the top of your program. This aliases all the short names to the long +names in the current package. Some even have medium names, generally +borrowed from B. To avoid a performance hit, if you don't need the +C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C +module without them: - local $_ = 5; + use English '-no_match_vars'; -It's easy to notice the problem in such a short example, but in more -complicated code you are looking for trouble if you don't localize -changes to the special variables. +Before you continue, note the sort order for variables. In general, we +first list the variables in case-insensitive, almost-lexigraphical +order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}> +or C<$^T>), although C<$_> and C<@_> move up to the top of the pile. +For variables with the same identifier, we list it in order of scalar, +array, hash, and bareword. -The following list is ordered by scalar variables first, then the -arrays, then the hashes. +=head2 General Variables =over 8 @@ -129,7 +86,7 @@ X<$_> X<$ARG> The default input and pattern-searching space. The following pairs are equivalent: - while (<>) {...} # equivalent only in while! + while (<>) {...} # equivalent only in while! while (defined($_ = <>)) {...} /^Subject:/ @@ -141,19 +98,20 @@ equivalent: chomp chomp($_) -Here are the places where Perl will assume $_ even if you -don't use it: +Here are the places where Perl will assume C<$_> even if you don't use it: =over 3 =item * -The following functions: +The following functions use C<$_> as a default argument: -abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob, -hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, +abs, alarm, chomp, chop, chr, chroot, +cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc, +lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf, quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), -rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst, +rmdir, say, sin, split (for its second +argument), sqrt, stat, study, uc, ucfirst, unlink, unpack. =item * @@ -161,7 +119,6 @@ unlink, unpack. All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN. See L - =item * The pattern matching operations C, C and C (aka C) @@ -174,434 +131,897 @@ variable is supplied. =item * -The implicit iterator variable in the grep() and map() functions. +The implicit iterator variable in the C and C functions. =item * -The implicit variable of given(). +The implicit variable of C. =item * -The default place to put an input record when a C<< >> +The default place to put the next value or input record +when a C<< >>, C, C or C operation's result is tested by itself as the sole criterion of a C test. Outside a C test, this will not happen. =back -As C<$_> is a global variable, this may lead in some cases to unwanted -side-effects. As of perl 5.9.1, you can now use a lexical version of +C<$_> is by default a global variable. However, as +of perl v5.10.0, you can use a lexical version of C<$_> by declaring it in a file or in a block with C. Moreover, -declaring C restores the global C<$_> in the current scope. +declaring C restores the global C<$_> in the current scope. Though +this seemed like a good idea at the time it was introduced, lexical C<$_> +actually causes more problems than it solves. If you call a function that +expects to be passed information via C<$_>, it may or may not work, +depending on how the function is written, there not being any easy way to +solve this. Just avoid lexical C<$_>, unless you are feeling particularly +masochistic. For this reason lexical C<$_> is still experimental and will +produce a warning unless warnings have been disabled. As with other +experimental features, the behavior of lexical C<$_> is subject to change +without notice, including change into a fatal error. + +Mnemonic: underline is understood in certain operations. -(Mnemonic: underline is understood in certain operations.) +=item @ARG -=back +=item @_ +X<@_> X<@ARG> -=over 8 +Within a subroutine the array C<@_> contains the parameters passed to +that subroutine. Inside a subroutine, C<@_> is the default array for +the array operators C, C, C, and C. -=item $a +See L. -=item $b -X<$a> X<$b> +=item $LIST_SEPARATOR -Special package variables when using sort(), see L. -Because of this specialness $a and $b don't need to be declared -(using use vars, or our()) even when using the C pragma. -Don't lexicalize them with C or C if you want to be -able to use them in the sort() comparison block or function. +=item $" +X<$"> X<$LIST_SEPARATOR> -=back +When an array or an array slice is interpolated into a double-quoted +string or a similar context such as C, its elements are +separated by this value. Default is a space. For example, this: -=over 8 + print "The array is: @array\n"; -=item $> ($1, $2, ...) -X<$1> X<$2> X<$3> +is equivalent to this: -Contains the subpattern from the corresponding set of capturing -parentheses from the last successful pattern match, not counting patterns -matched in nested blocks that have been exited already. (Mnemonic: -like \digits.) These variables are all read-only and dynamically -scoped to the current BLOCK. + print "The array is: " . join($", @array) . "\n"; -=item $MATCH +Mnemonic: works in double-quoted context. -=item $& -X<$&> X<$MATCH> +=item $PROCESS_ID -The string matched by the last successful pattern match (not counting -any matches hidden within a BLOCK or eval() enclosed by the current -BLOCK). (Mnemonic: like & in some editors.) This variable is read-only -and dynamically scoped to the current BLOCK. +=item $PID -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. +=item $$ +X<$$> X<$PID> X<$PROCESS_ID> -See L for a replacement. +The process number of the Perl running this script. Though you I set +this variable, doing so is generally discouraged, although it can be +invaluable for some testing purposes. It will be reset automatically +across C calls. -=item ${^MATCH} -X<${^MATCH}> +Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl +would emulate POSIX semantics on Linux systems using LinuxThreads, a +partial implementation of POSIX Threads that has since been superseded +by the Native POSIX Thread Library (NPTL). -This is similar to C<$&> (C<$MATCH>) except that it does not incur the -performance penalty associated with that variable, and is only guaranteed -to return a defined value when the pattern was compiled or executed with -the C

modifier. +LinuxThreads is now obsolete on Linux, and caching C +like this made embedding perl unnecessarily complex (since you'd have +to manually update the value of $$), so now C<$$> and C +will always return the same values as the underlying C library. -=item $PREMATCH +Debian GNU/kFreeBSD systems also used LinuxThreads up until and +including the 6.0 release, but after that moved to FreeBSD thread +semantics, which are POSIX-like. -=item $` -X<$`> X<$PREMATCH> +To see if your system is affected by this discrepancy check if +C returns a false +value. NTPL threads preserve the POSIX semantics. -The string preceding whatever was matched by the last successful -pattern match (not counting any matches hidden within a BLOCK or eval -enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted -string.) This variable is read-only. +Mnemonic: same as shells. -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. +=item $PROGRAM_NAME -See L for a replacement. +=item $0 +X<$0> X<$PROGRAM_NAME> -=item ${^PREMATCH} -X<${^PREMATCH}> +Contains the name of the program being executed. -This is similar to C<$`> ($PREMATCH) except that it does not incur the -performance penalty associated with that variable, and is only guaranteed -to return a defined value when the pattern was compiled or executed with -the C

modifier. +On some (but not all) operating systems assigning to C<$0> modifies +the argument area that the C program sees. On some platforms you +may have to use special C options or a different C to see the +changes. Modifying the C<$0> is more useful as a way of indicating the +current program state than it is for hiding the program you're +running. -=item $POSTMATCH +Note that there are platform-specific limitations on the maximum +length of C<$0>. In the most extreme case it may be limited to the +space occupied by the original C<$0>. -=item $' -X<$'> X<$POSTMATCH> +In some platforms there may be arbitrary amount of padding, for +example space characters, after the modified name as shown by C. +In some platforms this padding may extend all the way to the original +length of the argument area, no matter what you do (this is the case +for example with Linux 2.2). -The string following whatever was matched by the last successful -pattern match (not counting any matches hidden within a BLOCK or eval() -enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted -string.) Example: +Note for BSD users: setting C<$0> does not completely remove "perl" +from the ps(1) output. For example, setting C<$0> to C<"foobar"> may +result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix +and the " (perl)" suffix are shown depends on your exact BSD variant +and version). This is an operating system feature, Perl cannot help it. - local $_ = 'abcdefghi'; - /def/; - print "$`:$&:$'\n"; # prints abc:def:ghi +In multithreaded scripts Perl coordinates the threads so that any +thread may modify its copy of the C<$0> and the change becomes visible +to ps(1) (assuming the operating system plays along). Note that +the view of C<$0> the other threads have will not change since they +have their own copies of it. -This variable is read-only and dynamically scoped to the current BLOCK. +If the program has been given to perl via the switches C<-e> or C<-E>, +C<$0> will contain the string C<"-e">. -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. +On Linux as of perl v5.14.0 the legacy process name will be set with +C, in addition to altering the POSIX name via C as +perl has done since version 4.000. Now system utilities that read the +legacy process name such as ps, top and killall will recognize the +name you set when assigning to C<$0>. The string you supply will be +cut off at 16 bytes, this is a limitation imposed by Linux. -See L for a replacement. +Mnemonic: same as B and B. -=item ${^POSTMATCH} -X<${^POSTMATCH}> +=item $REAL_GROUP_ID -This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the -performance penalty associated with that variable, and is only guaranteed -to return a defined value when the pattern was compiled or executed with -the C

modifier. +=item $GID -=item $LAST_PAREN_MATCH +=item $( +X<$(> X<$GID> X<$REAL_GROUP_ID> -=item $+ -X<$+> X<$LAST_PAREN_MATCH> +The real gid of this process. If you are on a machine that supports +membership in multiple groups simultaneously, gives a space separated +list of groups you are in. The first number is the one returned by +C, and the subsequent ones by C, one of which may be +the same as the first number. -The text matched by the last bracket of the last successful search pattern. -This is useful if you don't know which one of a set of alternative patterns -matched. For example: +However, a value assigned to C<$(> must be a single number used to +set the real gid. So the value given by C<$(> should I be assigned +back to C<$(> without being forced numeric, such as by adding zero. Note +that this is different to the effective gid (C<$)>) which does take a +list. - /Version: (.*)|Revision: (.*)/ && ($rev = $+); +You can change both the real gid and the effective gid at the same +time by using C. Changes +to C<$(> require a check to C<$!> +to detect any possible errors after an attempted change. -(Mnemonic: be positive and forward looking.) -This variable is read-only and dynamically scoped to the current BLOCK. +Mnemonic: parentheses are used to I things. The real gid is the +group you I, if you're running setgid. -=item $LAST_SUBMATCH_RESULT +=item $EFFECTIVE_GROUP_ID -=item $^N -X<$^N> +=item $EGID -The text matched by the used group most-recently closed (i.e. the group -with the rightmost closing parenthesis) of the last successful search -pattern. (Mnemonic: the (possibly) Nested parenthesis that most -recently closed.) +=item $) +X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> -This is primarily used inside C<(?{...})> blocks for examining text -recently matched. For example, to effectively capture text to a variable -(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with +The effective gid of this process. If you are on a machine that +supports membership in multiple groups simultaneously, gives a space +separated list of groups you are in. The first number is the one +returned by C, and the subsequent ones by C, +one of which may be the same as the first number. - (?:(...)(?{ $var = $^N })) +Similarly, a value assigned to C<$)> must also be a space-separated +list of numbers. The first number sets the effective gid, and +the rest (if any) are passed to C. To get the effect of an +empty list for C, just repeat the new effective gid; that is, +to force an effective gid of 5 and an effectively empty C +list, say C< $) = "5 5" >. -By setting and then using C<$var> in this way relieves you from having to -worry about exactly which numbered set of parentheses they are. +You can change both the effective gid and the real gid at the same +time by using C (use only a single numeric argument). +Changes to C<$)> require a check to C<$!> to detect any possible errors +after an attempted change. -This variable is dynamically scoped to the current BLOCK. +C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on +machines that support the corresponding I routine. C<$(> +and C<$)> can be swapped only on machines supporting C. -=item @LAST_MATCH_END +Mnemonic: parentheses are used to I things. The effective gid +is the group that's I for you, if you're running setgid. -=item @+ -X<@+> X<@LAST_MATCH_END> +=item $REAL_USER_ID -This array holds the offsets of the ends of the last successful -submatches in the currently active dynamic scope. C<$+[0]> is -the offset into the string of the end of the entire match. This -is the same value as what the C function returns when called -on the variable that was matched against. The Ith element -of this array holds the offset of the Ith submatch, so -C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset -past where $2 ends, and so on. You can use C<$#+> to determine -how many subgroups were in the last successful match. See the -examples given for the C<@-> variable. +=item $UID -=item %LAST_PAREN_MATCH +=item $< +X<< $< >> X<$UID> X<$REAL_USER_ID> -=item %+ -X<%+> +The real uid of this process. You can change both the real uid and the +effective uid at the same time by using C. Since +changes to C<< $< >> require a system call, check C<$!> after a change +attempt to detect any possible errors. -Similar to C<@+>, the C<%+> hash allows access to the named capture -buffers, should they exist, in the last successful match in the -currently active dynamic scope. +Mnemonic: it's the uid you came I, if you're running setuid. -For example, C<$+{foo}> is equivalent to C<$1> after the following match: +=item $EFFECTIVE_USER_ID - 'foo' =~ /(?foo)/; +=item $EUID -The keys of the C<%+> hash list only the names of buffers that have -captured (and that are thus associated to defined values). +=item $> +X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> -The underlying behaviour of C<%+> is provided by the -L module. +The effective uid of this process. For example: -B C<%-> and C<%+> are tied views into a common internal hash -associated with the last successful regular expression. Therefore mixing -iterative access to them via C may have unpredictable results. -Likewise, if the last successful match changes, then the results may be -surprising. + $< = $>; # set real to effective uid + ($<,$>) = ($>,$<); # swap real and effective uids -=item HANDLE->input_line_number(EXPR) +You can change both the effective uid and the real uid at the same +time by using C. Changes to C<< $> >> require a check +to C<$!> to detect any possible errors after an attempted change. -=item $INPUT_LINE_NUMBER +C<< $< >> and C<< $> >> can be swapped only on machines +supporting C. -=item $NR +Mnemonic: it's the uid you went I, if you're running setuid. -=item $. -X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X +=item $SUBSCRIPT_SEPARATOR -Current line number for the last filehandle accessed. +=item $SUBSEP -Each filehandle in Perl counts the number of lines that have been read -from it. (Depending on the value of C<$/>, Perl's idea of what -constitutes a line may not match yours.) When a line is read from a -filehandle (via readline() or C<< <> >>), or when tell() or seek() is -called on it, C<$.> becomes an alias to the line counter for that -filehandle. +=item $; +X<$;> X<$SUBSEP> X -You can adjust the counter by assigning to C<$.>, but this will not -actually move the seek pointer. I will not localize -the filehandle's line count>. Instead, it will localize perl's notion -of which filehandle C<$.> is currently aliased to. +The subscript separator for multidimensional array emulation. If you +refer to a hash element as + + $foo{$a,$b,$c} + +it really means + + $foo{join($;, $a, $b, $c)} + +But don't put + + @foo{$a,$b,$c} # a slice--note the @ + +which means + + ($foo{$a},$foo{$b},$foo{$c}) + +Default is "\034", the same as SUBSEP in B. If your keys contain +binary data there might not be any safe value for C<$;>. + +Consider using "real" multidimensional arrays as described +in L. + +Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. + +=item $a + +=item $b +X<$a> X<$b> + +Special package variables when using C, see L. +Because of this specialness C<$a> and C<$b> don't need to be declared +(using C, or C) even when using the C +pragma. Don't lexicalize them with C or C if you want to +be able to use them in the C comparison block or function. + +=item %ENV +X<%ENV> + +The hash C<%ENV> contains your current environment. Setting a +value in C changes the environment for any child processes +you subsequently C off. + +=item $SYSTEM_FD_MAX + +=item $^F +X<$^F> X<$SYSTEM_FD_MAX> + +The maximum system file descriptor, ordinarily 2. System file +descriptors are passed to Ced processes, while higher file +descriptors are not. Also, during an +C, system file descriptors are +preserved even if the C fails (ordinary file descriptors are +closed before the C is attempted). The close-on-exec +status of a file descriptor will be decided according to the value of +C<$^F> when the corresponding file, pipe, or socket was opened, not the +time of the C. + +=item @F +X<@F> + +The array C<@F> contains the fields of each line read in when autosplit +mode is turned on. See L for the B<-a> switch. This array +is package-specific, and must be declared or given a full package name +if not in package main when running under C. + +=item @INC +X<@INC> + +The array C<@INC> contains the list of places that the C, +C, or C constructs look for their library files. It +initially consists of the arguments to any B<-I> command-line +switches, followed by the default Perl library, probably +F, followed by ".", to represent the current +directory. ("." will not be appended if taint checks are enabled, +either by C<-T> or by C<-t>.) If you need to modify this at runtime, +you should use the C pragma to get the machine-dependent +library properly loaded also: + + use lib '/mypath/libdir/'; + use SomeMod; + +You can also insert hooks into the file inclusion system by putting Perl +code directly into C<@INC>. Those hooks may be subroutine references, +array references or blessed objects. See L for details. + +=item %INC +X<%INC> + +The hash C<%INC> contains entries for each filename included via the +C, C, or C operators. The key is the filename +you specified (with module names converted to pathnames), and the +value is the location of the file found. The C +operator uses this hash to determine whether a particular file has +already been included. + +If the file was loaded via a hook (e.g. a subroutine reference, see +L for a description of these hooks), this hook is +by default inserted into C<%INC> in place of a filename. Note, however, +that the hook may have set the C<%INC> entry by itself to provide some more +specific info. + +=item $INPLACE_EDIT + +=item $^I +X<$^I> X<$INPLACE_EDIT> + +The current value of the inplace-edit extension. Use C to disable +inplace editing. + +Mnemonic: value of B<-i> switch. + +=item $^M +X<$^M> + +By default, running out of memory is an untrappable, fatal error. +However, if suitably built, Perl can use the contents of C<$^M> +as an emergency memory pool after Cing. Suppose that your Perl +were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. +Then + + $^M = 'a' x (1 << 16); + +would allocate a 64K buffer for use in an emergency. See the +F file in the Perl distribution for information on how to +add custom C compilation flags when compiling perl. To discourage casual +use of this advanced feature, there is no L long name for +this variable. + +This variable was added in Perl 5.004. + +=item $OSNAME + +=item $^O +X<$^O> X<$OSNAME> + +The name of the operating system under which this copy of Perl was +built, as determined during the configuration process. For examples +see L. + +The value is identical to C<$Config{'osname'}>. See also L +and the B<-V> command-line switch documented in L. + +In Windows platforms, C<$^O> is not very helpful: since it is always +C, it doesn't tell the difference between +95/98/ME/NT/2000/XP/CE/.NET. Use C or +Win32::GetOSVersion() (see L and L) to distinguish +between the variants. + +This variable was added in Perl 5.003. + +=item %SIG +X<%SIG> + +The hash C<%SIG> contains signal handlers for signals. For example: + + sub handler { # 1st argument is signal name + my($sig) = @_; + print "Caught a SIG$sig--shutting down\n"; + close(LOG); + exit(0); + } + + $SIG{'INT'} = \&handler; + $SIG{'QUIT'} = \&handler; + ... + $SIG{'INT'} = 'DEFAULT'; # restore default action + $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT + +Using a value of C<'IGNORE'> usually has the effect of ignoring the +signal, except for the C signal. See L for more about +this special case. + +Here are some other examples: + + $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not + # recommended) + $SIG{"PIPE"} = \&Plumber; # just fine; assume current + # Plumber + $SIG{"PIPE"} = *Plumber; # somewhat esoteric + $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() + # return?? + +Be sure not to use a bareword as the name of a signal handler, +lest you inadvertently call it. + +If your system has the C function then signal handlers +are installed using it. This means you get reliable signal handling. + +The default delivery policy of signals changed in Perl v5.8.0 from +immediate (also known as "unsafe") to deferred, also known as "safe +signals". See L for more information. + +Certain internal hooks can be also set using the C<%SIG> hash. The +routine indicated by C<$SIG{__WARN__}> is called when a warning +message is about to be printed. The warning message is passed as the +first argument. The presence of a C<__WARN__> hook causes the +ordinary printing of warnings to C to be suppressed. You can +use this to save warnings in a variable, or turn warnings into fatal +errors, like this: + + local $SIG{__WARN__} = sub { die $_[0] }; + eval $proggie; + +As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can +disable warnings using the empty subroutine: + + local $SIG{__WARN__} = sub {}; + +The routine indicated by C<$SIG{__DIE__}> is called when a fatal +exception is about to be thrown. The error message is passed as the +first argument. When a C<__DIE__> hook routine returns, the exception +processing continues as it would have in the absence of the hook, +unless the hook routine itself exits via a C, a loop exit, +or a C. The C<__DIE__> handler is explicitly disabled during +the call, so that you can die from a C<__DIE__> handler. Similarly +for C<__WARN__>. + +Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called +even inside an C. Do not use this to rewrite a pending +exception in C<$@>, or as a bizarre substitute for overriding +C. This strange action at a distance may be fixed +in a future release so that C<$SIG{__DIE__}> is only called if your +program is about to exit, as was the original intent. Any other use is +deprecated. + +C<__DIE__>/C<__WARN__> handlers are very special in one respect: they +may be called to report (probable) errors found by the parser. In such +a case the parser may be in inconsistent state, so any attempt to +evaluate Perl code from such a handler will probably result in a +segfault. This means that warnings or errors that result from parsing +Perl should be used with extreme caution, like this: + + require Carp if defined $^S; + Carp::confess("Something wrong") if defined &Carp::confess; + die "Something wrong, but could not load Carp to give " + . "backtrace...\n\t" + . "To see backtrace try starting Perl with -MCarp switch"; + +Here the first line will load C I it is the parser who +called the handler. The second line will print backtrace and die if +C was available. The third line will be executed only if C was +not available. + +Having to even think about the C<$^S> variable in your exception +handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented +invites grievous and difficult to track down errors. Avoid it +and use an C or CORE::GLOBAL::die override instead. + +See L, L, L, and +L for additional information. + +=item $BASETIME + +=item $^T +X<$^T> X<$BASETIME> + +The time at which the program began running, in seconds since the +epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, +and B<-C> filetests are based on this value. + +=item $PERL_VERSION + +=item $^V +X<$^V> X<$PERL_VERSION> + +The revision, version, and subversion of the Perl interpreter, +represented as a C object. + +This variable first appeared in perl v5.6.0; earlier versions of perl +will see an undefined value. Before perl v5.10.0 C<$^V> was represented +as a v-string. + +C<$^V> can be used to determine whether the Perl interpreter executing +a script is in the right range of versions. For example: + + warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 + +To convert C<$^V> into its string representation use C's +C<"%vd"> conversion: + + printf "version is v%vd\n", $^V; # Perl's version + +See the documentation of C and C +for a convenient way to fail if the running Perl interpreter is too old. + +See also C<$]> for an older representation of the Perl version. + +This variable was added in Perl v5.6.0. + +Mnemonic: use ^V for Version Control. + +=item ${^WIN32_SLOPPY_STAT} +X<${^WIN32_SLOPPY_STAT}> X X + +If this variable is set to a true value, then C on Windows will +not try to open the file. This means that the link count cannot be +determined and file attributes may be out of date if additional +hardlinks to the file exist. On the other hand, not opening the file +is considerably faster, especially for files on network drives. + +This variable could be set in the F file to +configure the local Perl installation to use "sloppy" C by +default. See the documentation for B<-f> in +L for more information about site +customization. + +This variable was added in Perl v5.10.0. + +=item $EXECUTABLE_NAME + +=item $^X +X<$^X> X<$EXECUTABLE_NAME> + +The name used to execute the current copy of Perl, from C's +C or (where supported) F. + +Depending on the host operating system, the value of C<$^X> may be +a relative or absolute pathname of the perl program file, or may +be the string used to invoke perl but not the pathname of the +perl program file. Also, most operating systems permit invoking +programs that are not in the PATH environment variable, so there +is no guarantee that the value of C<$^X> is in PATH. For VMS, the +value may or may not include a version number. + +You usually can use the value of C<$^X> to re-invoke an independent +copy of the same perl that is currently running, e.g., + + @first_run = `$^X -le "print int rand 100 for 1..100"`; + +But recall that not all operating systems support forking or +capturing of the output of commands, so this complex statement +may not be portable. + +It is not safe to use the value of C<$^X> as a path name of a file, +as some operating systems that have a mandatory suffix on +executable files do not require use of the suffix when invoking +a command. To convert the value of C<$^X> to a path name, use the +following statements: + + # Build up a set of file names (not command names). + use Config; + my $this_perl = $^X; + if ($^O ne 'VMS') { + $this_perl .= $Config{_exe} + unless $this_perl =~ m/$Config{_exe}$/i; + } + +Because many operating systems permit anyone with read access to +the Perl program file to make a copy of it, patch the copy, and +then execute the copy, the security-conscious Perl programmer +should take care to invoke the installed copy of perl, not the +copy referenced by C<$^X>. The following statements accomplish +this goal, and produce a pathname that can be invoked as a +command or referenced as a file. + + use Config; + my $secure_perl_path = $Config{perlpath}; + if ($^O ne 'VMS') { + $secure_perl_path .= $Config{_exe} + unless $secure_perl_path =~ m/$Config{_exe}$/i; + } + +=back + +=head2 Variables related to regular expressions + +Most of the special variables related to regular expressions are side +effects. Perl sets these variables when it has a successful match, so +you should check the match result before using them. For instance: + + if( /P(A)TT(ER)N/ ) { + print "I found $1 and $2\n"; + } + +These variables are read-only and dynamically-scoped, unless we note +otherwise. + +The dynamic nature of the regular expression variables means that +their value is limited to the block that they are in, as demonstrated +by this bit of code: + + my $outer = 'Wallace and Grommit'; + my $inner = 'Mutt and Jeff'; + + my $pattern = qr/(\S+) and (\S+)/; + + sub show_n { print "\$1 is $1; \$2 is $2\n" } + + { + OUTER: + show_n() if $outer =~ m/$pattern/; + + INNER: { + show_n() if $inner =~ m/$pattern/; + } + + show_n(); + } + +The output shows that while in the C block, the values of C<$1> +and C<$2> are from the match against C<$outer>. Inside the C +block, the values of C<$1> and C<$2> are from the match against +C<$inner>, but only until the end of the block (i.e. the dynamic +scope). After the C block completes, the values of C<$1> and +C<$2> return to the values for the match against C<$outer> even though +we have not made another match: + + $1 is Wallace; $2 is Grommit + $1 is Mutt; $2 is Jeff + $1 is Wallace; $2 is Grommit + +If you are using Perl v5.18 or earlier, note that C imposes a considerable performance penalty on all regular +expression matches in a program because it uses the C<$`>, C<$&>, and +C<$'>, regardless of whether they occur in the scope of C. For that reason, saying C in libraries is +strongly discouraged unless you import it without the match variables: + + use English '-no_match_vars' + +The C and C +modules can help you find uses of these +problematic match variables in your code. + +Since Perl v5.10.0, you can use the C

match operator flag and the +C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead +so you only suffer the performance penalties. + +If you are using Perl v5.20.0 or higher, you do not need to worry about +this, as the three naughty variables are no longer naughty. + +=over 8 + +=item $> ($1, $2, ...) +X<$1> X<$2> X<$3> + +Contains the subpattern from the corresponding set of capturing +parentheses from the last successful pattern match, not counting patterns +matched in nested blocks that have been exited already. + +These variables are read-only and dynamically-scoped. + +Mnemonic: like \digits. + +=item $MATCH + +=item $& +X<$&> X<$MATCH> -C<$.> is reset when the filehandle is closed, but B when an open -filehandle is reopened without an intervening close(). For more -details, see LO Operators">. Because C<< <> >> never does -an explicit close, line numbers increase across ARGV files (but see -examples in L). +The string matched by the last successful pattern match (not counting +any matches hidden within a BLOCK or C enclosed by the current +BLOCK). -You can also use C<< HANDLE->input_line_number(EXPR) >> to access the -line counter for a given filehandle without having to worry about -which handle you last accessed. +In Perl v5.18 and earlier, the use of this variable +anywhere in a program imposes a considerable +performance penalty on all regular expression matches. To avoid this +penalty, you can extract the same substring by using L. Starting +with Perl v5.10.0, you can use the C

match flag and the C<${^MATCH}> +variable to do the same thing for particular match operations. -(Mnemonic: many programs use "." to mean the current line number.) +This variable is read-only and dynamically-scoped. -=item IO::Handle->input_record_separator(EXPR) +Mnemonic: like C<&> in some editors. -=item $INPUT_RECORD_SEPARATOR +=item ${^MATCH} +X<${^MATCH}> -=item $RS +This is similar to C<$&> (C<$MATCH>) except that it does not incur the +performance penalty associated with that variable. +In Perl v5.18 and earlier, it is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C

modifier. In Perl v5.20, the C

modifier does nothing, so +C<${^MATCH}> does the same thing as C<$MATCH>. -=item $/ -X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> +This variable was added in Perl v5.10.0. -The input record separator, newline by default. This -influences Perl's idea of what a "line" is. Works like B's RS -variable, including treating empty lines as a terminator if set to -the null string. (An empty line cannot contain any spaces -or tabs.) You may set it to a multi-character string to match a -multi-character terminator, or to C to read through the end -of file. Setting it to C<"\n\n"> means something slightly -different than setting to C<"">, if the file contains consecutive -empty lines. Setting to C<""> will treat two or more consecutive -empty lines as a single empty line. Setting to C<"\n\n"> will -blindly assume that the next input character belongs to the next -paragraph, even if it's a newline. (Mnemonic: / delimits -line boundaries when quoting poetry.) +This variable is read-only and dynamically-scoped. - local $/; # enable "slurp" mode - local $_ = ; # whole file now here - s/\n[ \t]+/ /g; +=item $PREMATCH -Remember: the value of C<$/> is a string, not a regex. B has to be -better for something. :-) +=item $` +X<$`> X<$PREMATCH> X<${^PREMATCH}> -Setting C<$/> to a reference to an integer, scalar containing an integer, or -scalar that's convertible to an integer will attempt to read records -instead of lines, with the maximum record size being the referenced -integer. So this: +The string preceding whatever was matched by the last successful +pattern match, not counting any matches hidden within a BLOCK or C +enclosed by the current BLOCK. - local $/ = \32768; # or \"32768", or \$var_containing_32768 - open my $fh, "<", $myfile or die $!; - local $_ = <$fh>; +In Perl v5.18 and earlier, the use of this variable +anywhere in a program imposes a considerable +performance penalty on all regular expression matches. To avoid this +penalty, you can extract the same substring by using L. Starting +with Perl v5.10.0, you can use the C

match flag and the +C<${^PREMATCH}> variable to do the same thing for particular match +operations. -will read a record of no more than 32768 bytes from FILE. If you're -not reading from a record-oriented file (or your OS doesn't have -record-oriented files), then you'll likely get a full chunk of data -with every read. If a record is larger than the record size you've -set, you'll get the record back in pieces. Trying to set the record -size to zero or less will cause reading in the (rest of the) whole file. +This variable is read-only and dynamically-scoped. -On VMS, record reads are done with the equivalent of C, -so it's best not to mix record and non-record reads on the same -file. (This is unlikely to be a problem, because any file you'd -want to read in record mode is probably unusable in line mode.) -Non-VMS systems do normal I/O, so it's safe to mix record and -non-record reads of a file. +Mnemonic: C<`> often precedes a quoted string. -See also L. Also see C<$.>. +=item ${^PREMATCH} +X<$`> X<${^PREMATCH}> -=item HANDLE->autoflush(EXPR) +This is similar to C<$`> ($PREMATCH) except that it does not incur the +performance penalty associated with that variable. +In Perl v5.18 and earlier, it is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C

modifier. In Perl v5.20, the C

modifier does nothing, so +C<${^PREMATCH}> does the same thing as C<$PREMATCH>. -=item $OUTPUT_AUTOFLUSH +This variable was added in Perl v5.10.0 -=item $| -X<$|> X X X<$OUTPUT_AUTOFLUSH> +This variable is read-only and dynamically-scoped. -If set to nonzero, forces a flush right away and after every write -or print on the currently selected output channel. Default is 0 -(regardless of whether the channel is really buffered by the -system or not; C<$|> tells you only whether you've asked Perl -explicitly to flush after each write). STDOUT will -typically be line buffered if output is to the terminal and block -buffered otherwise. Setting this variable is useful primarily when -you are outputting to a pipe or socket, such as when you are running -a Perl program under B and want to see the output as it's -happening. This has no effect on input buffering. See L -for that. See L on how to select the output channel. -See also L. (Mnemonic: when you want your pipes to be piping hot.) - -=item IO::Handle->output_field_separator EXPR +=item $POSTMATCH -=item $OUTPUT_FIELD_SEPARATOR +=item $' +X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@-> -=item $OFS +The string following whatever was matched by the last successful +pattern match (not counting any matches hidden within a BLOCK or C +enclosed by the current BLOCK). Example: -=item $, -X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> + local $_ = 'abcdefghi'; + /def/; + print "$`:$&:$'\n"; # prints abc:def:ghi -The output field separator for the print operator. If defined, this -value is printed between each of print's arguments. Default is C. -(Mnemonic: what is printed when there is a "," in your print statement.) +In Perl v5.18 and earlier, the use of this variable +anywhere in a program imposes a considerable +performance penalty on all regular expression matches. +To avoid this penalty, you can extract the same substring by +using L. Starting with Perl v5.10.0, you can use the C

match flag +and the C<${^POSTMATCH}> variable to do the same thing for particular +match operations. -=item IO::Handle->output_record_separator EXPR +This variable is read-only and dynamically-scoped. -=item $OUTPUT_RECORD_SEPARATOR +Mnemonic: C<'> often follows a quoted string. -=item $ORS +=item ${^POSTMATCH} +X<${^POSTMATCH}> X<$'> X<$POSTMATCH> -=item $\ -X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> +This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the +performance penalty associated with that variable. +In Perl v5.18 and earlier, it is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C

modifier. In Perl v5.20, the C

modifier does nothing, so +C<${^POSTMATCH}> does the same thing as C<$POSTMATCH>. -The output record separator for the print operator. If defined, this -value is printed after the last of print's arguments. Default is C. -(Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. -Also, it's just like C<$/>, but it's what you get "back" from Perl.) +This variable was added in Perl v5.10.0. -=item $LIST_SEPARATOR +This variable is read-only and dynamically-scoped. -=item $" -X<$"> X<$LIST_SEPARATOR> +=item $LAST_PAREN_MATCH -This is like C<$,> except that it applies to array and slice values -interpolated into a double-quoted string (or similar interpreted -string). Default is a space. (Mnemonic: obvious, I think.) +=item $+ +X<$+> X<$LAST_PAREN_MATCH> -=item $SUBSCRIPT_SEPARATOR +The text matched by the last bracket of the last successful search pattern. +This is useful if you don't know which one of a set of alternative patterns +matched. For example: -=item $SUBSEP + /Version: (.*)|Revision: (.*)/ && ($rev = $+); -=item $; -X<$;> X<$SUBSEP> X +This variable is read-only and dynamically-scoped. -The subscript separator for multidimensional array emulation. If you -refer to a hash element as +Mnemonic: be positive and forward looking. - $foo{$a,$b,$c} +=item $LAST_SUBMATCH_RESULT -it really means +=item $^N +X<$^N> X<$LAST_SUBMATCH_RESULT> - $foo{join($;, $a, $b, $c)} +The text matched by the used group most-recently closed (i.e. the group +with the rightmost closing parenthesis) of the last successful search +pattern. -But don't put +This is primarily used inside C<(?{...})> blocks for examining text +recently matched. For example, to effectively capture text to a variable +(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with - @foo{$a,$b,$c} # a slice--note the @ + (?:(...)(?{ $var = $^N })) -which means +By setting and then using C<$var> in this way relieves you from having to +worry about exactly which numbered set of parentheses they are. - ($foo{$a},$foo{$b},$foo{$c}) +This variable was added in Perl v5.8.0. -Default is "\034", the same as SUBSEP in B. If your -keys contain binary data there might not be any safe value for C<$;>. -(Mnemonic: comma (the syntactic subscript separator) is a -semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already -taken for something more important.) +Mnemonic: the (possibly) Nested parenthesis that most recently closed. -Consider using "real" multidimensional arrays as described -in L. +=item @LAST_MATCH_END -=item HANDLE->format_page_number(EXPR) +=item @+ +X<@+> X<@LAST_MATCH_END> -=item $FORMAT_PAGE_NUMBER +This array holds the offsets of the ends of the last successful +submatches in the currently active dynamic scope. C<$+[0]> is +the offset into the string of the end of the entire match. This +is the same value as what the C function returns when called +on the variable that was matched against. The Ith element +of this array holds the offset of the Ith submatch, so +C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset +past where C<$2> ends, and so on. You can use C<$#+> to determine +how many subgroups were in the last successful match. See the +examples given for the C<@-> variable. -=item $% -X<$%> X<$FORMAT_PAGE_NUMBER> +This variable was added in Perl v5.6.0. -The current page number of the currently selected output channel. -Used with formats. -(Mnemonic: % is page number in B.) +=item %LAST_PAREN_MATCH -=item HANDLE->format_lines_per_page(EXPR) +=item %+ +X<%+> X<%LAST_PAREN_MATCH> -=item $FORMAT_LINES_PER_PAGE +Similar to C<@+>, the C<%+> hash allows access to the named capture +buffers, should they exist, in the last successful match in the +currently active dynamic scope. -=item $= -X<$=> X<$FORMAT_LINES_PER_PAGE> +For example, C<$+{foo}> is equivalent to C<$1> after the following match: -The current page length (printable lines) of the currently selected -output channel. Default is 60. -Used with formats. -(Mnemonic: = has horizontal lines.) + 'foo' =~ /(?foo)/; -=item HANDLE->format_lines_left(EXPR) +The keys of the C<%+> hash list only the names of buffers that have +captured (and that are thus associated to defined values). -=item $FORMAT_LINES_LEFT +The underlying behaviour of C<%+> is provided by the +L module. -=item $- -X<$-> X<$FORMAT_LINES_LEFT> +B C<%-> and C<%+> are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via C may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. -The number of lines left on the page of the currently selected output -channel. -Used with formats. -(Mnemonic: lines_on_page - lines_printed.) +This variable was added in Perl v5.10.0. + +This variable is read-only and dynamically-scoped. =item @LAST_MATCH_START =item @- X<@-> X<@LAST_MATCH_START> -$-[0] is the offset of the start of the last successful match. +C<$-[0]> is the offset of the start of the last successful match. C<$-[>IC<]> is the offset of the start of the substring matched by I-th subpattern, or undef if the subpattern did not match. -Thus after a match against $_, $& coincides with C, C<$&> coincides with C. Similarly, $I coincides with C if C<$-[n]> is defined, and $+ coincides with -C. One can use C<$#-> to find the last -matched subgroup in the last successful match. Contrast with +C. One can use C<$#-> to find the +last matched subgroup in the last successful match. Contrast with C<$#+>, the number of subgroups in the regular expression. Compare with C<@+>. @@ -609,1179 +1029,1194 @@ This array holds the offsets of the beginnings of the last successful submatches in the currently active dynamic scope. C<$-[0]> is the offset into the string of the beginning of the entire match. The Ith element of this array holds the offset -of the Ith submatch, so C<$-[1]> is the offset where $1 -begins, C<$-[2]> the offset where $2 begins, and so on. +of the Ith submatch, so C<$-[1]> is the offset where C<$1> +begins, C<$-[2]> the offset where C<$2> begins, and so on. -After a match against some variable $var: +After a match against some variable C<$var>: =over 5 =item C<$`> is the same as C -=item C<$&> is the same as C +=item C<$&> is the same as C + +=item C<$'> is the same as C + +=item C<$1> is the same as C + +=item C<$2> is the same as C + +=item C<$3> is the same as C + +=back + +This variable was added in Perl v5.6.0. + +=item %LAST_MATCH_START + +=item %- +X<%-> X<%LAST_MATCH_START> + +Similar to C<%+>, this variable allows access to the named capture groups +in the last successful match in the currently active dynamic scope. To +each capture group name found in the regular expression, it associates a +reference to an array containing the list of values captured by all +buffers with that name (should there be several of them), in the order +where they appear. + +Here's an example: + + if ('1234' =~ /(?1)(?2)(?3)(?4)/) { + foreach my $bufname (sort keys %-) { + my $ary = $-{$bufname}; + foreach my $idx (0..$#$ary) { + print "\$-{$bufname}[$idx] : ", + (defined($ary->[$idx]) + ? "'$ary->[$idx]'" + : "undef"), + "\n"; + } + } + } + +would print out: + + $-{A}[0] : '1' + $-{A}[1] : '3' + $-{B}[0] : '2' + $-{B}[1] : '4' + +The keys of the C<%-> hash correspond to all buffer names found in +the regular expression. + +The behaviour of C<%-> is implemented via the +L module. + +B C<%-> and C<%+> are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via C may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. + +This variable was added in Perl v5.10.0. + +This variable is read-only and dynamically-scoped. + +=item $LAST_REGEXP_CODE_RESULT + +=item $^R +X<$^R> X<$LAST_REGEXP_CODE_RESULT> + +The result of evaluation of the last successful C<(?{ code })> +regular expression assertion (see L). May be written to. + +This variable was added in Perl 5.005. + +=item ${^RE_DEBUG_FLAGS} +X<${^RE_DEBUG_FLAGS}> + +The current value of the regex debugging flags. Set to 0 for no debug output +even when the C module is loaded. See L for details. + +This variable was added in Perl v5.10.0. + +=item ${^RE_TRIE_MAXBUF} +X<${^RE_TRIE_MAXBUF}> + +Controls how certain regex optimisations are applied and how much memory they +utilize. This value by default is 65536 which corresponds to a 512kB +temporary cache. Set this to a higher value to trade +memory for speed when matching large alternations. Set +it to a lower value if you want the optimisations to +be as conservative of memory as possible but still occur, and set it to a +negative value to prevent the optimisation and conserve the most memory. +Under normal situations this variable should be of no interest to you. + +This variable was added in Perl v5.10.0. + +=back + +=head2 Variables related to filehandles + +Variables that depend on the currently selected filehandle may be set +by calling an appropriate object method on the C object, +although this is less efficient than using the regular built-in +variables. (Summary lines below for this contain the word HANDLE.) +First you must say + + use IO::Handle; + +after which you may use either + + method HANDLE EXPR + +or more safely, + + HANDLE->method(EXPR) + +Each method returns the old value of the C attribute. The +methods each take an optional EXPR, which, if supplied, specifies the +new value for the C attribute in question. If not +supplied, most methods do nothing to the current value--except for +C, which will assume a 1 for you, just to be different. + +Because loading in the C class is an expensive operation, +you should learn how to use the regular built-in variables. + +A few of these variables are considered "read-only". This means that +if you try to assign to this variable, either directly or indirectly +through a reference, you'll raise a run-time exception. + +You should be very careful when modifying the default values of most +special variables described in this document. In most cases you want +to localize these variables before changing them, since if you don't, +the change may affect other modules which rely on the default values +of the special variables that you have changed. This is one of the +correct ways to read the whole file at once: + + open my $fh, "<", "foo" or die $!; + local $/; # enable localized slurp mode + my $content = <$fh>; + close $fh; + +But the following code is quite bad: + + open my $fh, "<", "foo" or die $!; + undef $/; # enable slurp mode + my $content = <$fh>; + close $fh; + +since some other module, may want to read data from some file in the +default "line mode", so if the code we have just presented has been +executed, the global value of C<$/> is now changed for any other code +running inside the same Perl interpreter. + +Usually when a variable is localized you want to make sure that this +change affects the shortest scope possible. So unless you are already +inside some short C<{}> block, you should create one yourself. For +example: + + my $content = ''; + open my $fh, "<", "foo" or die $!; + { + local $/; + $content = <$fh>; + } + close $fh; + +Here is an example of how your own code can go broken: + + for ( 1..3 ){ + $\ = "\r\n"; + nasty_break(); + print "$_"; + } + + sub nasty_break { + $\ = "\f"; + # do something with $_ + } + +You probably expect this code to print the equivalent of -=item C<$'> is the same as C + "1\r\n2\r\n3\r\n" -=item C<$1> is the same as C +but instead you get: -=item C<$2> is the same as C + "1\f2\f3\f" -=item C<$3> is the same as C +Why? Because C modifies C<$\> without localizing it +first. The value you set in C is still there when you +return. The fix is to add C so the value doesn't leak out of +C: -=back + local $\ = "\f"; -=item %- -X<%-> +It's easy to notice the problem in such a short example, but in more +complicated code you are looking for trouble if you don't localize +changes to the special variables. -Similar to C<%+>, this variable allows access to the named capture buffers -in the last successful match in the currently active dynamic scope. To -each capture buffer name found in the regular expression, it associates a -reference to an array containing the list of values captured by all -buffers with that name (should there be several of them), in the order -where they appear. +=over 8 -Here's an example: +=item $ARGV +X<$ARGV> - if ('1234' =~ /(?1)(?2)(?3)(?4)/) { - foreach my $bufname (sort keys %-) { - my $ary = $-{$bufname}; - foreach my $idx (0..$#$ary) { - print "\$-{$bufname}[$idx] : ", - (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), - "\n"; - } - } - } +Contains the name of the current file when reading from C<< <> >>. -would print out: +=item @ARGV +X<@ARGV> - $-{A}[0] : '1' - $-{A}[1] : '3' - $-{B}[0] : '2' - $-{B}[1] : '4' +The array C<@ARGV> contains the command-line arguments intended for +the script. C<$#ARGV> is generally the number of arguments minus +one, because C<$ARGV[0]> is the first argument, I the program's +command name itself. See L for the command name. -The keys of the C<%-> hash correspond to all buffer names found in -the regular expression. +=item ARGV +X -The behaviour of C<%-> is implemented via the -L module. +The special filehandle that iterates over command-line filenames in +C<@ARGV>. Usually written as the null filehandle in the angle operator +C<< <> >>. Note that currently C only has its magical effect +within the C<< <> >> operator; elsewhere it is just a plain filehandle +corresponding to the last file opened by C<< <> >>. In particular, +passing C<\*ARGV> as a parameter to a function that expects a filehandle +may not cause your function to automatically read the contents of all the +files in C<@ARGV>. -B C<%-> and C<%+> are tied views into a common internal hash -associated with the last successful regular expression. Therefore mixing -iterative access to them via C may have unpredictable results. -Likewise, if the last successful match changes, then the results may be -surprising. +=item ARGVOUT +X -=item HANDLE->format_name(EXPR) +The special filehandle that points to the currently open output file +when doing edit-in-place processing with B<-i>. Useful when you have +to do a lot of inserting and don't want to keep modifying C<$_>. See +L for the B<-i> switch. -=item $FORMAT_NAME +=item IO::Handle->output_field_separator( EXPR ) -=item $~ -X<$~> X<$FORMAT_NAME> +=item $OUTPUT_FIELD_SEPARATOR -The name of the current report format for the currently selected output -channel. Default is the name of the filehandle. (Mnemonic: brother to -C<$^>.) +=item $OFS -=item HANDLE->format_top_name(EXPR) +=item $, +X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> -=item $FORMAT_TOP_NAME +The output field separator for the print operator. If defined, this +value is printed between each of print's arguments. Default is C. -=item $^ -X<$^> X<$FORMAT_TOP_NAME> +You cannot call C on a handle, only as a +static method. See L. -The name of the current top-of-page format for the currently selected -output channel. Default is the name of the filehandle with _TOP -appended. (Mnemonic: points to top of page.) +Mnemonic: what is printed when there is a "," in your print statement. -=item IO::Handle->format_line_break_characters EXPR +=item HANDLE->input_line_number( EXPR ) -=item $FORMAT_LINE_BREAK_CHARACTERS +=item $INPUT_LINE_NUMBER -=item $: -X<$:> X +=item $NR -The current set of characters after which a string may be broken to -fill continuation fields (starting with ^) in a format. Default is -S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in -poetry is a part of a line.) +=item $. +X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X -=item IO::Handle->format_formfeed EXPR +Current line number for the last filehandle accessed. -=item $FORMAT_FORMFEED +Each filehandle in Perl counts the number of lines that have been read +from it. (Depending on the value of C<$/>, Perl's idea of what +constitutes a line may not match yours.) When a line is read from a +filehandle (via C or C<< <> >>), or when C or +C is called on it, C<$.> becomes an alias to the line counter +for that filehandle. -=item $^L -X<$^L> X<$FORMAT_FORMFEED> +You can adjust the counter by assigning to C<$.>, but this will not +actually move the seek pointer. I will not localize +the filehandle's line count>. Instead, it will localize perl's notion +of which filehandle C<$.> is currently aliased to. -What formats output as a form feed. Default is \f. +C<$.> is reset when the filehandle is closed, but B when an open +filehandle is reopened without an intervening C. For more +details, see LO Operators">. Because C<< <> >> never does +an explicit close, line numbers increase across C files (but see +examples in L). -=item $ACCUMULATOR +You can also use C<< HANDLE->input_line_number(EXPR) >> to access the +line counter for a given filehandle without having to worry about +which handle you last accessed. -=item $^A -X<$^A> X<$ACCUMULATOR> +Mnemonic: many programs use "." to mean the current line number. -The current value of the write() accumulator for format() lines. A format -contains formline() calls that put their result into C<$^A>. After -calling its format, write() prints out the contents of C<$^A> and empties. -So you never really see the contents of C<$^A> unless you call -formline() yourself and then look at it. See L and -L. +=item IO::Handle->input_record_separator( EXPR ) -=item $CHILD_ERROR +=item $INPUT_RECORD_SEPARATOR -=item $? -X<$?> X<$CHILD_ERROR> +=item $RS -The status returned by the last pipe close, backtick (C<``>) command, -successful call to wait() or waitpid(), or from the system() -operator. This is just the 16-bit status word returned by the -traditional Unix wait() system call (or else is made up to look like it). Thus, the -exit value of the subprocess is really (C<<< $? >> 8 >>>), and -C<$? & 127> gives which signal, if any, the process died from, and -C<$? & 128> reports whether there was a core dump. (Mnemonic: -similar to B and B.) +=item $/ +X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> -Additionally, if the C variable is supported in C, its value -is returned via $? if any C function fails. +The input record separator, newline by default. This influences Perl's +idea of what a "line" is. Works like B's RS variable, including +treating empty lines as a terminator if set to the null string (an +empty line cannot contain any spaces or tabs). You may set it to a +multi-character string to match a multi-character terminator, or to +C to read through the end of file. Setting it to C<"\n\n"> +means something slightly different than setting to C<"">, if the file +contains consecutive empty lines. Setting to C<""> will treat two or +more consecutive empty lines as a single empty line. Setting to +C<"\n\n"> will blindly assume that the next input character belongs to +the next paragraph, even if it's a newline. -If you have installed a signal handler for C, the -value of C<$?> will usually be wrong outside that handler. + local $/; # enable "slurp" mode + local $_ = ; # whole file now here + s/\n[ \t]+/ /g; -Inside an C subroutine C<$?> contains the value that is going to be -given to C. You can modify C<$?> in an C subroutine to -change the exit status of your program. For example: +Remember: the value of C<$/> is a string, not a regex. B has to +be better for something. :-) - END { - $? = 1 if $? == 255; # die would make it 255 - } +Setting C<$/> to a reference to an integer, scalar containing an +integer, or scalar that's convertible to an integer will attempt to +read records instead of lines, with the maximum record size being the +referenced integer number of characters. So this: -Under VMS, the pragma C makes C<$?> reflect the -actual VMS exit status, instead of the default emulation of POSIX -status; see L for details. + local $/ = \32768; # or \"32768", or \$var_containing_32768 + open my $fh, "<", $myfile or die $!; + local $_ = <$fh>; -Also see L. +will read a record of no more than 32768 characters from $fh. If you're +not reading from a record-oriented file (or your OS doesn't have +record-oriented files), then you'll likely get a full chunk of data +with every read. If a record is larger than the record size you've +set, you'll get the record back in pieces. Trying to set the record +size to zero or less will cause reading in the (rest of the) whole file. -=item ${^CHILD_ERROR_NATIVE} -X<$^CHILD_ERROR_NATIVE> +On VMS only, record reads bypass PerlIO layers and any associated +buffering, so you must not mix record and non-record reads on the +same filehandle. Record mode mixes with line mode only when the +same buffering layer is in use for both modes. -The native status returned by the last pipe close, backtick (C<``>) -command, successful call to wait() or waitpid(), or from the system() -operator. On POSIX-like systems this value can be decoded with the -WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG -and WIFCONTINUED functions provided by the L module. +You cannot call C on a handle, only as a +static method. See L. -Under VMS this reflects the actual VMS exit status; i.e. it is the same -as $? when the pragma C is in effect. +See also L. Also see L. -=item ${^ENCODING} -X<$^ENCODING> +Mnemonic: / delimits line boundaries when quoting poetry. -The I to the Encode object that is used to convert -the source code to Unicode. Thanks to this variable your perl script -does not have to be written in UTF-8. Default is I. The direct -manipulation of this variable is highly discouraged. +=item IO::Handle->output_record_separator( EXPR ) -=item $OS_ERROR +=item $OUTPUT_RECORD_SEPARATOR -=item $ERRNO +=item $ORS -=item $! -X<$!> X<$ERRNO> X<$OS_ERROR> +=item $\ +X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> -If used numerically, yields the current value of the C C -variable, or in other words, if a system or library call fails, it -sets this variable. This means that the value of C<$!> is meaningful -only I after a B: +The output record separator for the print operator. If defined, this +value is printed after the last of print's arguments. Default is C. - if (open my $fh, "<", $filename) { - # Here $! is meaningless. - ... - } else { - # ONLY here is $! meaningful. - ... - # Already here $! might be meaningless. - } - # Since here we might have either success or failure, - # here $! is meaningless. +You cannot call C on a handle, only as a +static method. See L. -In the above I stands for anything: zero, non-zero, -C. A successful system or library call does B set -the variable to zero. +Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. +Also, it's just like C<$/>, but it's what you get "back" from Perl. -If used as a string, yields the corresponding system error string. -You can assign a number to C<$!> to set I if, for instance, -you want C<"$!"> to return the string for error I, or you want -to set the exit value for the die() operator. (Mnemonic: What just -went bang?) +=item HANDLE->autoflush( EXPR ) -Also see L. +=item $OUTPUT_AUTOFLUSH -=item %OS_ERROR +=item $| +X<$|> X X X<$OUTPUT_AUTOFLUSH> -=item %ERRNO +If set to nonzero, forces a flush right away and after every write or +print on the currently selected output channel. Default is 0 +(regardless of whether the channel is really buffered by the system or +not; C<$|> tells you only whether you've asked Perl explicitly to +flush after each write). STDOUT will typically be line buffered if +output is to the terminal and block buffered otherwise. Setting this +variable is useful primarily when you are outputting to a pipe or +socket, such as when you are running a Perl program under B and +want to see the output as it's happening. This has no effect on input +buffering. See L for that. See L on +how to select the output channel. See also L. -=item %! -X<%!> +Mnemonic: when you want your pipes to be piping hot. -Each element of C<%!> has a true value only if C<$!> is set to that -value. For example, C<$!{ENOENT}> is true if and only if the current -value of C<$!> is C; that is, if the most recent error was -"No such file or directory" (or its moral equivalent: not all operating -systems give that exact error, and certainly not all languages). -To check if a particular key is meaningful on your system, use -C; for a list of legal keys, use C. -See L for more information, and also see above for the -validity of C<$!>. +=item ${^LAST_FH} +X<${^LAST_FH}> -=item $EXTENDED_OS_ERROR +This read-only variable contains a reference to the last-read filehandle. +This is set by C<< >>, C, C, C and C. +This is the same handle that C<$.> and C and C without arguments +use. It is also the handle used when Perl appends ", line 1" to +an error or warning message. -=item $^E -X<$^E> X<$EXTENDED_OS_ERROR> +This variable was added in Perl v5.18.0. -Error information specific to the current operating system. At -the moment, this differs from C<$!> under only VMS, OS/2, and Win32 -(and for MacPerl). On all other platforms, C<$^E> is always just -the same as C<$!>. +=back -Under VMS, C<$^E> provides the VMS status value from the last -system error. This is more specific information about the last -system error than that provided by C<$!>. This is particularly -important when C<$!> is set to B. +=head3 Variables related to formats -Under OS/2, C<$^E> is set to the error code of the last call to -OS/2 API either via CRT, or directly from perl. +The special variables for formats are a subset of those for +filehandles. See L for more information about Perl's +formats. -Under Win32, C<$^E> always returns the last error information -reported by the Win32 call C which describes -the last error from within the Win32 API. Most Win32-specific -code will report errors via C<$^E>. ANSI C and Unix-like calls -set C and so most portable Perl code will report errors -via C<$!>. +=over 8 -Caveats mentioned in the description of C<$!> generally apply to -C<$^E>, also. (Mnemonic: Extra error explanation.) +=item $ACCUMULATOR -Also see L. +=item $^A +X<$^A> X<$ACCUMULATOR> -=item $EVAL_ERROR +The current value of the C accumulator for C lines. +A format contains C calls that put their result into +C<$^A>. After calling its format, C prints out the contents +of C<$^A> and empties. So you never really see the contents of C<$^A> +unless you call C yourself and then look at it. See +L and L. -=item $@ -X<$@> X<$EVAL_ERROR> +=item IO::Handle->format_formfeed(EXPR) -The Perl syntax error message from the last eval() operator. -If $@ is the null string, the last eval() parsed and executed -correctly (although the operations you invoked may have failed in the -normal fashion). (Mnemonic: Where was the syntax error "at"?) +=item $FORMAT_FORMFEED -Warning messages are not collected in this variable. You can, -however, set up a routine to process warnings by setting C<$SIG{__WARN__}> -as described below. +=item $^L +X<$^L> X<$FORMAT_FORMFEED> -Also see L. +What formats output as a form feed. The default is C<\f>. -=item $PROCESS_ID +You cannot call C on a handle, only as a static +method. See L. -=item $PID +=item HANDLE->format_page_number(EXPR) -=item $$ -X<$$> X<$PID> X<$PROCESS_ID> +=item $FORMAT_PAGE_NUMBER -The process number of the Perl running this script. You should -consider this variable read-only, although it will be altered -across fork() calls. (Mnemonic: same as shells.) +=item $% +X<$%> X<$FORMAT_PAGE_NUMBER> -Note for Linux users: on Linux, the C functions C and -C return different values from different threads. In order to -be portable, this behavior is not reflected by C<$$>, whose value remains -consistent across threads. If you want to call the underlying C, -you may use the CPAN module C. +The current page number of the currently selected output channel. -=item $REAL_USER_ID +Mnemonic: C<%> is page number in B. -=item $UID +=item HANDLE->format_lines_left(EXPR) -=item $< -X<< $< >> X<$UID> X<$REAL_USER_ID> +=item $FORMAT_LINES_LEFT -The real uid of this process. (Mnemonic: it's the uid you came I, -if you're running setuid.) You can change both the real uid and -the effective uid at the same time by using POSIX::setuid(). Since -changes to $< require a system call, check $! after a change attempt to -detect any possible errors. +=item $- +X<$-> X<$FORMAT_LINES_LEFT> -=item $EFFECTIVE_USER_ID +The number of lines left on the page of the currently selected output +channel. -=item $EUID +Mnemonic: lines_on_page - lines_printed. -=item $> -X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> +=item IO::Handle->format_line_break_characters EXPR -The effective uid of this process. Example: +=item $FORMAT_LINE_BREAK_CHARACTERS - $< = $>; # set real to effective uid - ($<,$>) = ($>,$<); # swap real and effective uid +=item $: +X<$:> X -You can change both the effective uid and the real uid at the same -time by using POSIX::setuid(). Changes to $> require a check to $! -to detect any possible errors after an attempted change. +The current set of characters after which a string may be broken to +fill continuation fields (starting with C<^>) in a format. The default is +S<" \n-">, to break on a space, newline, or a hyphen. -(Mnemonic: it's the uid you went I, if you're running setuid.) -C<< $< >> and C<< $> >> can be swapped only on machines -supporting setreuid(). +You cannot call C on a handle, only as +a static method. See L. -=item $REAL_GROUP_ID +Mnemonic: a "colon" in poetry is a part of a line. -=item $GID +=item HANDLE->format_lines_per_page(EXPR) -=item $( -X<$(> X<$GID> X<$REAL_GROUP_ID> +=item $FORMAT_LINES_PER_PAGE -The real gid of this process. If you are on a machine that supports -membership in multiple groups simultaneously, gives a space separated -list of groups you are in. The first number is the one returned by -getgid(), and the subsequent ones by getgroups(), one of which may be -the same as the first number. +=item $= +X<$=> X<$FORMAT_LINES_PER_PAGE> -However, a value assigned to C<$(> must be a single number used to -set the real gid. So the value given by C<$(> should I be assigned -back to C<$(> without being forced numeric, such as by adding zero. Note -that this is different to the effective gid (C<$)>) which does take a -list. +The current page length (printable lines) of the currently selected +output channel. The default is 60. -You can change both the real gid and the effective gid at the same -time by using POSIX::setgid(). Changes to $( require a check to $! -to detect any possible errors after an attempted change. +Mnemonic: = has horizontal lines. -(Mnemonic: parentheses are used to I things. The real gid is the -group you I, if you're running setgid.) +=item HANDLE->format_top_name(EXPR) -=item $EFFECTIVE_GROUP_ID +=item $FORMAT_TOP_NAME -=item $EGID +=item $^ +X<$^> X<$FORMAT_TOP_NAME> -=item $) -X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> +The name of the current top-of-page format for the currently selected +output channel. The default is the name of the filehandle with C<_TOP> +appended. For example, the default format top name for the C +filehandle is C. -The effective gid of this process. If you are on a machine that -supports membership in multiple groups simultaneously, gives a space -separated list of groups you are in. The first number is the one -returned by getegid(), and the subsequent ones by getgroups(), one of -which may be the same as the first number. +Mnemonic: points to top of page. -Similarly, a value assigned to C<$)> must also be a space-separated -list of numbers. The first number sets the effective gid, and -the rest (if any) are passed to setgroups(). To get the effect of an -empty list for setgroups(), just repeat the new effective gid; that is, -to force an effective gid of 5 and an effectively empty setgroups() -list, say C< $) = "5 5" >. +=item HANDLE->format_name(EXPR) -You can change both the effective gid and the real gid at the same -time by using POSIX::setgid() (use only a single numeric argument). -Changes to $) require a check to $! to detect any possible errors -after an attempted change. +=item $FORMAT_NAME -(Mnemonic: parentheses are used to I things. The effective gid -is the group that's I for you, if you're running setgid.) +=item $~ +X<$~> X<$FORMAT_NAME> -C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on -machines that support the corresponding I routine. C<$(> -and C<$)> can be swapped only on machines supporting setregid(). +The name of the current report format for the currently selected +output channel. The default format name is the same as the filehandle +name. For example, the default format name for the C +filehandle is just C. -=item $PROGRAM_NAME +Mnemonic: brother to C<$^>. -=item $0 -X<$0> X<$PROGRAM_NAME> +=back -Contains the name of the program being executed. +=head2 Error Variables +X X -On some (read: not all) operating systems assigning to C<$0> modifies -the argument area that the C program sees. On some platforms you -may have to use special C options or a different C to see the -changes. Modifying the $0 is more useful as a way of indicating the -current program state than it is for hiding the program you're -running. (Mnemonic: same as B and B.) +The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information +about different types of error conditions that may appear during +execution of a Perl program. The variables are shown ordered by +the "distance" between the subsystem which reported the error and +the Perl process. They correspond to errors detected by the Perl +interpreter, C library, operating system, or an external program, +respectively. -Note that there are platform specific limitations on the maximum -length of C<$0>. In the most extreme case it may be limited to the -space occupied by the original C<$0>. +To illustrate the differences between these variables, consider the +following Perl expression, which uses a single-quoted string. After +execution of this statement, perl may have set all four special error +variables: -In some platforms there may be arbitrary amount of padding, for -example space characters, after the modified name as shown by C. -In some platforms this padding may extend all the way to the original -length of the argument area, no matter what you do (this is the case -for example with Linux 2.2). + eval q{ + open my $pipe, "/cdrom/install |" or die $!; + my @res = <$pipe>; + close $pipe or die "bad pipe: $?, $!"; + }; -Note for BSD users: setting C<$0> does not completely remove "perl" -from the ps(1) output. For example, setting C<$0> to C<"foobar"> may -result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix -and the " (perl)" suffix are shown depends on your exact BSD variant -and version). This is an operating system feature, Perl cannot help it. +When perl executes the C expression, it translates the +C, C<< >>, and C calls in the C run-time library +and thence to the operating system kernel. perl sets C<$!> to +the C library's C if one of these calls fails. -In multithreaded scripts Perl coordinates the threads so that any -thread may modify its copy of the C<$0> and the change becomes visible -to ps(1) (assuming the operating system plays along). Note that -the view of C<$0> the other threads have will not change since they -have their own copies of it. +C<$@> is set if the string to be C-ed did not compile (this may +happen if C or C were imported with bad prototypes), or +if Perl code executed during evaluation Cd. In these cases the +value of C<$@> is the compile error, or the argument to C (which +will interpolate C<$!> and C<$?>). (See also L, though.) -If the program has been given to perl via the switches C<-e> or C<-E>, -C<$0> will contain the string C<"-e">. +Under a few operating systems, C<$^E> may contain a more verbose error +indicator, such as in this case, "CDROM tray not closed." Systems that +do not support extended error messages leave C<$^E> the same as C<$!>. -On Linux as of perl 5.14 the legacy process name will be set with -L, in addition to altering the POSIX name via C as -perl has done since version 4.000. Now system utilities that read the -legacy process name such as ps, top and killall will recognize the -name you set when assigning to C<$0>. The string you supply will be -cut off at 16 bytes, this is a limitation imposed by Linux. +Finally, C<$?> may be set to non-0 value if the external program +F fails. The upper eight bits reflect specific error +conditions encountered by the program (the program's C value). +The lower eight bits reflect mode of failure, like signal death and +core dump information. See L for details. In contrast to +C<$!> and C<$^E>, which are set only if error condition is detected, +the variable C<$?> is set on each C or pipe C, +overwriting the old value. This is more like C<$@>, which on every +C is always set on failure and cleared on success. + +For more details, see the individual descriptions at C<$@>, C<$!>, +C<$^E>, and C<$?>. -=item $[ -X<$[> +=over 8 -The index of the first element in an array, and of the first character -in a substring. Default is 0, but you could theoretically set it -to 1 to make Perl behave more like B (or Fortran) when -subscripting and when evaluating the index() and substr() functions. -(Mnemonic: [ begins subscripts.) +=item ${^CHILD_ERROR_NATIVE} +X<$^CHILD_ERROR_NATIVE> -As of release 5 of Perl, assignment to C<$[> is treated as a compiler -directive, and cannot influence the behavior of any other file. -(That's why you can only assign compile-time constants to it.) Its -use is deprecated, and by default will trigger a warning. +The native status returned by the last pipe close, backtick (C<``>) +command, successful call to C or C, or from the +C operator. On POSIX-like systems this value can be decoded +with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, +WSTOPSIG and WIFCONTINUED functions provided by the L module. -Note that, unlike other compile-time directives (such as L), -assignment to C<$[> can be seen from outer lexical scopes in the same file. -However, you can use local() on it to strictly bind its value to a -lexical block. +Under VMS this reflects the actual VMS exit status; i.e. it is the +same as C<$?> when the pragma C is in effect. -=item $] -X<$]> +This variable was added in Perl v5.10.0. -The version + patchlevel / 1000 of the Perl interpreter. This variable -can be used to determine whether the Perl interpreter executing a -script is in the right range of versions. (Mnemonic: Is this version -of perl in the right bracket?) Example: +=item $EXTENDED_OS_ERROR - warn "No checksumming!\n" if $] < 3.019; +=item $^E +X<$^E> X<$EXTENDED_OS_ERROR> -See also the documentation of C and C -for a convenient way to fail if the running Perl interpreter is too old. +Error information specific to the current operating system. At the +moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and +for MacPerl). On all other platforms, C<$^E> is always just the same +as C<$!>. -The floating point representation can sometimes lead to inaccurate -numeric comparisons. See C<$^V> for a more modern representation of -the Perl version that allows accurate string comparisons. +Under VMS, C<$^E> provides the VMS status value from the last system +error. This is more specific information about the last system error +than that provided by C<$!>. This is particularly important when C<$!> +is set to B. -=item $COMPILING +Under OS/2, C<$^E> is set to the error code of the last call to OS/2 +API either via CRT, or directly from perl. -=item $^C -X<$^C> X<$COMPILING> +Under Win32, C<$^E> always returns the last error information reported +by the Win32 call C which describes the last error +from within the Win32 API. Most Win32-specific code will report errors +via C<$^E>. ANSI C and Unix-like calls set C and so most +portable Perl code will report errors via C<$!>. -The current value of the flag associated with the B<-c> switch. -Mainly of use with B<-MO=...> to allow code to alter its behavior -when being compiled, such as for example to AUTOLOAD at compile -time rather than normal, deferred loading. Setting -C<$^C = 1> is similar to calling C. +Caveats mentioned in the description of C<$!> generally apply to +C<$^E>, also. -=item $DEBUGGING +This variable was added in Perl 5.003. -=item $^D -X<$^D> X<$DEBUGGING> +Mnemonic: Extra error explanation. -The current value of the debugging flags. (Mnemonic: value of B<-D> -switch.) May be read or set. Like its command-line equivalent, you can use -numeric or symbolic values, eg C<$^D = 10> or C<$^D = "st">. +=item $EXCEPTIONS_BEING_CAUGHT -=item ${^RE_DEBUG_FLAGS} +=item $^S +X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> -The current value of the regex debugging flags. Set to 0 for no debug output -even when the re 'debug' module is loaded. See L for details. +Current state of the interpreter. -=item ${^RE_TRIE_MAXBUF} + $^S State + --------- ------------------------------------- + undef Parsing module, eval, or main program + true (1) Executing an eval + false (0) Otherwise -Controls how certain regex optimisations are applied and how much memory they -utilize. This value by default is 65536 which corresponds to a 512kB temporary -cache. Set this to a higher value to trade memory for speed when matching -large alternations. Set it to a lower value if you want the optimisations to -be as conservative of memory as possible but still occur, and set it to a -negative value to prevent the optimisation and conserve the most memory. -Under normal situations this variable should be of no interest to you. +The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}> +handlers. -=item $SYSTEM_FD_MAX +The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because +the C value does not indicate whether exceptions are being caught, +since compilation of the main program does not catch exceptions. -=item $^F -X<$^F> X<$SYSTEM_FD_MAX> +This variable was added in Perl 5.004. -The maximum system file descriptor, ordinarily 2. System file -descriptors are passed to exec()ed processes, while higher file -descriptors are not. Also, during an open(), system file descriptors are -preserved even if the open() fails. (Ordinary file descriptors are -closed before the open() is attempted.) The close-on-exec -status of a file descriptor will be decided according to the value of -C<$^F> when the corresponding file, pipe, or socket was opened, not the -time of the exec(). +=item $WARNING -=item $^H +=item $^W +X<$^W> X<$WARNING> -WARNING: This variable is strictly for internal use only. Its availability, -behavior, and contents are subject to change without notice. +The current value of the warning switch, initially true if B<-w> was +used, false otherwise, but directly modifiable. -This variable contains compile-time hints for the Perl interpreter. At the -end of compilation of a BLOCK the value of this variable is restored to the -value when the interpreter started to compile the BLOCK. +See also L. -When perl begins to parse any block construct that provides a lexical scope -(e.g., eval body, required file, subroutine body, loop body, or conditional -block), the existing value of $^H is saved, but its value is left unchanged. -When the compilation of the block is completed, it regains the saved value. -Between the points where its value is saved and restored, code that -executes within BEGIN blocks is free to change the value of $^H. +Mnemonic: related to the B<-w> switch. -This behavior provides the semantic of lexical scoping, and is used in, -for instance, the C pragma. +=item ${^WARNING_BITS} +X<${^WARNING_BITS}> -The contents should be an integer; different bits of it are used for -different pragmatic flags. Here's an example: +The current set of warning checks enabled by the C pragma. +It has the same scoping as the C<$^H> and C<%^H> variables. The exact +values are considered internal to the L pragma and may change +between versions of Perl. - sub add_100 { $^H |= 0x100 } +This variable was added in Perl v5.6.0. - sub foo { - BEGIN { add_100() } - bar->baz($boon); - } +=item $OS_ERROR -Consider what happens during execution of the BEGIN block. At this point -the BEGIN block has already been compiled, but the body of foo() is still -being compiled. The new value of $^H will therefore be visible only while -the body of foo() is being compiled. +=item $ERRNO -Substitution of the above BEGIN block with: +=item $! +X<$!> X<$ERRNO> X<$OS_ERROR> - BEGIN { require strict; strict->import('vars') } +When referenced, C<$!> retrieves the current value +of the C C integer variable. +If C<$!> is assigned a numerical value, that value is stored in C. +When referenced as a string, C<$!> yields the system error string +corresponding to C. -demonstrates how C is implemented. Here's a conditional -version of the same lexical pragma: +Many system or library calls set C if they fail, +to indicate the cause of failure. They usually do B +set C to zero if they succeed. This means C, +hence C<$!>, is meaningful only I after a B: - BEGIN { require strict; strict->import('vars') if $condition } + if (open my $fh, "<", $filename) { + # Here $! is meaningless. + ... + } + else { + # ONLY here is $! meaningful. + ... + # Already here $! might be meaningless. + } + # Since here we might have either success or failure, + # $! is meaningless. -=item %^H +Here, I means that C<$!> may be unrelated to the outcome +of the C operator. Assignment to C<$!> is similarly ephemeral. +It can be used immediately before invoking the C operator, +to set the exit value, or to inspect the system error string +corresponding to error I, or to restore C<$!> to a meaningful state. -The %^H hash provides the same scoping semantic as $^H. This makes it -useful for implementation of lexically scoped pragmas. See L. +Mnemonic: What just went bang? -=item $INPLACE_EDIT +=item %OS_ERROR -=item $^I -X<$^I> X<$INPLACE_EDIT> +=item %ERRNO -The current value of the inplace-edit extension. Use C to disable -inplace editing. (Mnemonic: value of B<-i> switch.) +=item %! +X<%!> X<%OS_ERROR> X<%ERRNO> -=item $^M -X<$^M> +Each element of C<%!> has a true value only if C<$!> is set to that +value. For example, C<$!{ENOENT}> is true if and only if the current +value of C<$!> is C; that is, if the most recent error was "No +such file or directory" (or its moral equivalent: not all operating +systems give that exact error, and certainly not all languages). To +check if a particular key is meaningful on your system, use C; for a list of legal keys, use C. See L +for more information, and also see L. -By default, running out of memory is an untrappable, fatal error. -However, if suitably built, Perl can use the contents of C<$^M> -as an emergency memory pool after die()ing. Suppose that your Perl -were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. -Then +This variable was added in Perl 5.005. - $^M = 'a' x (1 << 16); +=item $CHILD_ERROR -would allocate a 64K buffer for use in an emergency. See the -F file in the Perl distribution for information on how to -add custom C compilation flags when compiling perl. To discourage casual -use of this advanced feature, there is no L long name for -this variable. +=item $? +X<$?> X<$CHILD_ERROR> -=item $OSNAME +The status returned by the last pipe close, backtick (C<``>) command, +successful call to C or C, or from the C +operator. This is just the 16-bit status word returned by the +traditional Unix C system call (or else is made up to look +like it). Thus, the exit value of the subprocess is really (C<<< $? >> +8 >>>), and C<$? & 127> gives which signal, if any, the process died +from, and C<$? & 128> reports whether there was a core dump. -=item $^O -X<$^O> X<$OSNAME> +Additionally, if the C variable is supported in C, its value +is returned via C<$?> if any C function fails. -The name of the operating system under which this copy of Perl was -built, as determined during the configuration process. For examples -see L. +If you have installed a signal handler for C, the +value of C<$?> will usually be wrong outside that handler. -The value is identical to C<$Config{'osname'}>. See also L -and the B<-V> command-line switch documented in L. +Inside an C subroutine C<$?> contains the value that is going to be +given to C. You can modify C<$?> in an C subroutine to +change the exit status of your program. For example: -In Windows platforms, $^O is not very helpful: since it is always -C, it doesn't tell the difference between -95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or -Win32::GetOSVersion() (see L and L) to distinguish -between the variants. + END { + $? = 1 if $? == 255; # die would make it 255 + } -=item ${^OPEN} +Under VMS, the pragma C makes C<$?> reflect the +actual VMS exit status, instead of the default emulation of POSIX +status; see L for details. -An internal variable used by PerlIO. A string in two parts, separated -by a C<\0> byte, the first part describes the input layers, the second -part describes the output layers. +Mnemonic: similar to B and B. -=item $PERLDB +=item $EVAL_ERROR -=item $^P -X<$^P> X<$PERLDB> +=item $@ +X<$@> X<$EVAL_ERROR> -The internal variable for debugging support. The meanings of the -various bits are subject to change, but currently indicate: +The Perl syntax error message from the +last C operator. If C<$@> is +the null string, the last C parsed and executed correctly +(although the operations you invoked may have failed in the normal +fashion). -=over 6 +Warning messages are not collected in this variable. You can, however, +set up a routine to process warnings by setting C<$SIG{__WARN__}> as +described in L. -=item 0x01 +Mnemonic: Where was the syntax error "at"? -Debug subroutine enter/exit. +=back -=item 0x02 +=head2 Variables related to the interpreter state -Line-by-line debugging. Causes DB::DB() subroutine to be called for each -statement executed. Also causes saving source code lines (like 0x400). +These variables provide information about the current interpreter state. -=item 0x04 +=over 8 -Switch off optimizations. +=item $COMPILING -=item 0x08 +=item $^C +X<$^C> X<$COMPILING> -Preserve more data for future interactive inspections. +The current value of the flag associated with the B<-c> switch. +Mainly of use with B<-MO=...> to allow code to alter its behavior +when being compiled, such as for example to C at compile +time rather than normal, deferred loading. Setting +C<$^C = 1> is similar to calling C. -=item 0x10 +This variable was added in Perl v5.6.0. -Keep info about source lines on which a subroutine is defined. +=item $DEBUGGING -=item 0x20 +=item $^D +X<$^D> X<$DEBUGGING> -Start with single-step on. +The current value of the debugging flags. May be read or set. Like its +command-line equivalent, you can use numeric or symbolic values, eg +C<$^D = 10> or C<$^D = "st">. -=item 0x40 +Mnemonic: value of B<-D> switch. -Use subroutine address instead of name when reporting. +=item ${^ENCODING} +X<${^ENCODING}> -=item 0x80 +The I to the C object that is used to convert +the source code to Unicode. Thanks to this variable your Perl script +does not have to be written in UTF-8. Default is I. The direct +manipulation of this variable is highly discouraged. -Report C as well. +This variable was added in Perl 5.8.2. -=item 0x100 +=item ${^GLOBAL_PHASE} +X<${^GLOBAL_PHASE}> -Provide informative "file" names for evals based on the place they were compiled. +The current phase of the perl interpreter. -=item 0x200 +Possible values are: -Provide informative names to anonymous subroutines based on the place they -were compiled. +=over 8 -=item 0x400 +=item CONSTRUCT -Save source code lines into C<@{"_<$filename"}>. +The C is being constructed via C. This +value is mostly there for completeness and for use via the +underlying C variable C. It's not really possible for Perl +code to be executed unless construction of the interpreter is +finished. -=back +=item START -Some bits may be relevant at compile-time only, some at -run-time only. This is a new mechanism and the details may change. -See also L. +This is the global compile-time. That includes, basically, every +C block executed directly or indirectly from during the +compile-time of the top-level program. -=item $LAST_REGEXP_CODE_RESULT +This phase is not called "BEGIN" to avoid confusion with +C-blocks, as those are executed during compile-time of any +compilation unit, not just the top-level program. A new, localised +compile-time entered at run-time, for example by constructs as +C are not global interpreter phases, and +therefore aren't reflected by C<${^GLOBAL_PHASE}>. -=item $^R -X<$^R> X<$LAST_REGEXP_CODE_RESULT> +=item CHECK -The result of evaluation of the last successful C<(?{ code })> -regular expression assertion (see L). May be written to. +Execution of any C blocks. -=item $EXCEPTIONS_BEING_CAUGHT +=item INIT -=item $^S -X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> +Similar to "CHECK", but for C-blocks, not C blocks. -Current state of the interpreter. +=item RUN - $^S State - --------- ------------------- - undef Parsing module/eval - true (1) Executing an eval - false (0) Otherwise +The main run-time, i.e. the execution of C. -The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers. +=item END -=item $BASETIME +Execution of any C blocks. -=item $^T -X<$^T> X<$BASETIME> +=item DESTRUCT -The time at which the program began running, in seconds since the -epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, -and B<-C> filetests are based on this value. +Global destruction. -=item ${^TAINT} +=back -Reflects if taint mode is on or off. 1 for on (the program was run with -B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with -B<-t> or B<-TU>). This variable is read-only. +Also note that there's no value for UNITCHECK-blocks. That's because +those are run for each compilation unit individually, and therefore is +not a global interpreter phase. -=item ${^UNICODE} +Not every program has to go through each of the possible phases, but +transition from one phase to another can only happen in the order +described in the above list. -Reflects certain Unicode settings of Perl. See L -documentation for the C<-C> switch for more information about -the possible values. This variable is set during Perl startup -and is thereafter read-only. +An example of all of the phases Perl code can see: -=item ${^UTF8CACHE} + BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" } -This variable controls the state of the internal UTF-8 offset caching code. -1 for on (the default), 0 for off, -1 to debug the caching code by checking -all its results against linear scans, and panicking on any discrepancy. + INIT { print "init-time: ${^GLOBAL_PHASE}\n" } -=item ${^UTF8LOCALE} + CHECK { print "check-time: ${^GLOBAL_PHASE}\n" } -This variable indicates whether a UTF-8 locale was detected by perl at -startup. This information is used by perl when it's in -adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line -switch); see L for more info on this. + { + package Print::Phase; -=item $PERL_VERSION + sub new { + my ($class, $time) = @_; + return bless \$time, $class; + } -=item $^V -X<$^V> X<$PERL_VERSION> + sub DESTROY { + my $self = shift; + print "$$self: ${^GLOBAL_PHASE}\n"; + } + } -The revision, version, and subversion of the Perl interpreter, represented -as a C object. + print "run-time: ${^GLOBAL_PHASE}\n"; -This variable first appeared in perl 5.6.0; earlier versions of perl will -see an undefined value. Before perl 5.10.0 $^V was represented as a v-string. + my $runtime = Print::Phase->new( + "lexical variables are garbage collected before END" + ); -$^V can be used to determine whether the Perl interpreter executing a -script is in the right range of versions. (Mnemonic: use ^V for Version -Control.) Example: + END { print "end-time: ${^GLOBAL_PHASE}\n" } - warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 + our $destruct = Print::Phase->new( + "package variables are garbage collected after END" + ); -To convert C<$^V> into its string representation use sprintf()'s -C<"%vd"> conversion: +This will print out - printf "version is v%vd\n", $^V; # Perl's version + compile-time: START + check-time: CHECK + init-time: INIT + run-time: RUN + lexical variables are garbage collected before END: RUN + end-time: END + package variables are garbage collected after END: DESTRUCT -See the documentation of C and C -for a convenient way to fail if the running Perl interpreter is too old. +This variable was added in Perl 5.14.0. -See also C<$]> for an older representation of the Perl version. +=item $^H +X<$^H> -=item $WARNING +WARNING: This variable is strictly for +internal use only. Its availability, +behavior, and contents are subject to change without notice. -=item $^W -X<$^W> X<$WARNING> +This variable contains compile-time hints for the Perl interpreter. At the +end of compilation of a BLOCK the value of this variable is restored to the +value when the interpreter started to compile the BLOCK. -The current value of the warning switch, initially true if B<-w> -was used, false otherwise, but directly modifiable. (Mnemonic: -related to the B<-w> switch.) See also L. +When perl begins to parse any block construct that provides a lexical scope +(e.g., eval body, required file, subroutine body, loop body, or conditional +block), the existing value of C<$^H> is saved, but its value is left unchanged. +When the compilation of the block is completed, it regains the saved value. +Between the points where its value is saved and restored, code that +executes within BEGIN blocks is free to change the value of C<$^H>. -=item ${^WARNING_BITS} +This behavior provides the semantic of lexical scoping, and is used in, +for instance, the C pragma. -The current set of warning checks enabled by the C pragma. -See the documentation of C for more details. +The contents should be an integer; different bits of it are used for +different pragmatic flags. Here's an example: -=item ${^WIN32_SLOPPY_STAT} -X X + sub add_100 { $^H |= 0x100 } -If this variable is set to a true value, then stat() on Windows will -not try to open the file. This means that the link count cannot be -determined and file attributes may be out of date if additional -hardlinks to the file exist. On the other hand, not opening the file -is considerably faster, especially for files on network drives. + sub foo { + BEGIN { add_100() } + bar->baz($boon); + } -This variable could be set in the F file to -configure the local Perl installation to use "sloppy" stat() by -default. See the documentation for B<-f> in -L for more information about site -customization. +Consider what happens during execution of the BEGIN block. At this point +the BEGIN block has already been compiled, but the body of C is still +being compiled. The new value of C<$^H> +will therefore be visible only while +the body of C is being compiled. -=item $EXECUTABLE_NAME +Substitution of C block with: -=item $^X -X<$^X> X<$EXECUTABLE_NAME> + BEGIN { require strict; strict->import('vars') } -The name used to execute the current copy of Perl, from C's -C or (where supported) F. +demonstrates how C is implemented. Here's a conditional +version of the same lexical pragma: -Depending on the host operating system, the value of $^X may be -a relative or absolute pathname of the perl program file, or may -be the string used to invoke perl but not the pathname of the -perl program file. Also, most operating systems permit invoking -programs that are not in the PATH environment variable, so there -is no guarantee that the value of $^X is in PATH. For VMS, the -value may or may not include a version number. + BEGIN { + require strict; strict->import('vars') if $condition + } -You usually can use the value of $^X to re-invoke an independent -copy of the same perl that is currently running, e.g., +This variable was added in Perl 5.003. - @first_run = `$^X -le "print int rand 100 for 1..100"`; +=item %^H +X<%^H> -But recall that not all operating systems support forking or -capturing of the output of commands, so this complex statement -may not be portable. +The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes +it useful for implementation of lexically scoped pragmas. See +L. -It is not safe to use the value of $^X as a path name of a file, -as some operating systems that have a mandatory suffix on -executable files do not require use of the suffix when invoking -a command. To convert the value of $^X to a path name, use the -following statements: +When putting items into C<%^H>, in order to avoid conflicting with other +users of the hash there is a convention regarding which keys to use. +A module should use only keys that begin with the module's name (the +name of its main package) and a "/" character. For example, a module +C should use keys such as C. - # Build up a set of file names (not command names). - use Config; - $this_perl = $^X; - if ($^O ne 'VMS') - {$this_perl .= $Config{_exe} - unless $this_perl =~ m/$Config{_exe}$/i;} +This variable was added in Perl v5.6.0. -Because many operating systems permit anyone with read access to -the Perl program file to make a copy of it, patch the copy, and -then execute the copy, the security-conscious Perl programmer -should take care to invoke the installed copy of perl, not the -copy referenced by $^X. The following statements accomplish -this goal, and produce a pathname that can be invoked as a -command or referenced as a file. +=item ${^OPEN} +X<${^OPEN}> - use Config; - $secure_perl_path = $Config{perlpath}; - if ($^O ne 'VMS') - {$secure_perl_path .= $Config{_exe} - unless $secure_perl_path =~ m/$Config{_exe}$/i;} +An internal variable used by PerlIO. A string in two parts, separated +by a C<\0> byte, the first part describes the input layers, the second +part describes the output layers. -=item ARGV -X +This variable was added in Perl v5.8.0. -The special filehandle that iterates over command-line filenames in -C<@ARGV>. Usually written as the null filehandle in the angle operator -C<< <> >>. Note that currently C only has its magical effect -within the C<< <> >> operator; elsewhere it is just a plain filehandle -corresponding to the last file opened by C<< <> >>. In particular, -passing C<\*ARGV> as a parameter to a function that expects a filehandle -may not cause your function to automatically read the contents of all the -files in C<@ARGV>. +=item $PERLDB -=item $ARGV -X<$ARGV> +=item $^P +X<$^P> X<$PERLDB> -contains the name of the current file when reading from <>. +The internal variable for debugging support. The meanings of the +various bits are subject to change, but currently indicate: -=item @ARGV -X<@ARGV> +=over 6 -The array @ARGV contains the command-line arguments intended for -the script. C<$#ARGV> is generally the number of arguments minus -one, because C<$ARGV[0]> is the first argument, I the program's -command name itself. See C<$0> for the command name. +=item 0x01 -=item ARGVOUT -X +Debug subroutine enter/exit. -The special filehandle that points to the currently open output file -when doing edit-in-place processing with B<-i>. Useful when you have -to do a lot of inserting and don't want to keep modifying $_. See -L for the B<-i> switch. +=item 0x02 -=item @F -X<@F> +Line-by-line debugging. Causes C subroutine to be called for +each statement executed. Also causes saving source code lines (like +0x400). -The array @F contains the fields of each line read in when autosplit -mode is turned on. See L for the B<-a> switch. This array -is package-specific, and must be declared or given a full package name -if not in package main when running under C. +=item 0x04 -=item @INC -X<@INC> +Switch off optimizations. -The array @INC contains the list of places that the C, -C, or C constructs look for their library files. It -initially consists of the arguments to any B<-I> command-line -switches, followed by the default Perl library, probably -F, followed by ".", to represent the current -directory. ("." will not be appended if taint checks are enabled, either by -C<-T> or by C<-t>.) If you need to modify this at runtime, you should use -the C pragma to get the machine-dependent library properly -loaded also: +=item 0x08 - use lib '/mypath/libdir/'; - use SomeMod; +Preserve more data for future interactive inspections. -You can also insert hooks into the file inclusion system by putting Perl -code directly into @INC. Those hooks may be subroutine references, array -references or blessed objects. See L for details. +=item 0x10 -=item @ARG +Keep info about source lines on which a subroutine is defined. -=item @_ -X<@_> X<@ARG> +=item 0x20 -Within a subroutine the array @_ contains the parameters passed to that -subroutine. See L. +Start with single-step on. -=item %INC -X<%INC> +=item 0x40 -The hash %INC contains entries for each filename included via the -C, C, or C operators. The key is the filename -you specified (with module names converted to pathnames), and the -value is the location of the file found. The C -operator uses this hash to determine whether a particular file has -already been included. +Use subroutine address instead of name when reporting. -If the file was loaded via a hook (e.g. a subroutine reference, see -L for a description of these hooks), this hook is -by default inserted into %INC in place of a filename. Note, however, -that the hook may have set the %INC entry by itself to provide some more -specific info. +=item 0x80 -=item %ENV +Report C as well. -=item $ENV{expr} -X<%ENV> +=item 0x100 -The hash %ENV contains your current environment. Setting a -value in C changes the environment for any child processes -you subsequently fork() off. +Provide informative "file" names for evals based on the place they were compiled. -=item %SIG +=item 0x200 -=item $SIG{expr} -X<%SIG> +Provide informative names to anonymous subroutines based on the place they +were compiled. -The hash C<%SIG> contains signal handlers for signals. For example: +=item 0x400 - sub handler { # 1st argument is signal name - my($sig) = @_; - print "Caught a SIG$sig--shutting down\n"; - close(LOG); - exit(0); - } +Save source code lines into C<@{"_<$filename"}>. - $SIG{'INT'} = \&handler; - $SIG{'QUIT'} = \&handler; - ... - $SIG{'INT'} = 'DEFAULT'; # restore default action - $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT +=back -Using a value of C<'IGNORE'> usually has the effect of ignoring the -signal, except for the C signal. See L for more about -this special case. +Some bits may be relevant at compile-time only, some at +run-time only. This is a new mechanism and the details may change. +See also L. -Here are some other examples: +=item ${^TAINT} +X<${^TAINT}> - $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) - $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber - $SIG{"PIPE"} = *Plumber; # somewhat esoteric - $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? +Reflects if taint mode is on or off. 1 for on (the program was run with +B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with +B<-t> or B<-TU>). -Be sure not to use a bareword as the name of a signal handler, -lest you inadvertently call it. +This variable is read-only. -If your system has the sigaction() function then signal handlers are -installed using it. This means you get reliable signal handling. +This variable was added in Perl v5.8.0. -The default delivery policy of signals changed in Perl 5.8.0 from -immediate (also known as "unsafe") to deferred, also known as -"safe signals". See L for more information. +=item ${^UNICODE} +X<${^UNICODE}> -Certain internal hooks can be also set using the %SIG hash. The -routine indicated by C<$SIG{__WARN__}> is called when a warning message is -about to be printed. The warning message is passed as the first -argument. The presence of a C<__WARN__> hook causes the ordinary printing -of warnings to C to be suppressed. You can use this to save warnings -in a variable, or turn warnings into fatal errors, like this: +Reflects certain Unicode settings of Perl. See L +documentation for the C<-C> switch for more information about +the possible values. - local $SIG{__WARN__} = sub { die $_[0] }; - eval $proggie; +This variable is set during Perl startup and is thereafter read-only. -As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can -disable warnings using the empty subroutine: +This variable was added in Perl v5.8.2. - local $SIG{__WARN__} = sub {}; +=item ${^UTF8CACHE} +X<${^UTF8CACHE}> -The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception -is about to be thrown. The error message is passed as the first -argument. When a C<__DIE__> hook routine returns, the exception -processing continues as it would have in the absence of the hook, -unless the hook routine itself exits via a C, a loop exit, or a C. -The C<__DIE__> handler is explicitly disabled during the call, so that you -can die from a C<__DIE__> handler. Similarly for C<__WARN__>. +This variable controls the state of the internal UTF-8 offset caching code. +1 for on (the default), 0 for off, -1 to debug the caching code by checking +all its results against linear scans, and panicking on any discrepancy. -Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called -even inside an eval(). Do not use this to rewrite a pending exception -in C<$@>, or as a bizarre substitute for overriding C. -This strange action at a distance may be fixed in a future release -so that C<$SIG{__DIE__}> is only called if your program is about -to exit, as was the original intent. Any other use is deprecated. - -C<__DIE__>/C<__WARN__> handlers are very special in one respect: -they may be called to report (probable) errors found by the parser. -In such a case the parser may be in inconsistent state, so any -attempt to evaluate Perl code from such a handler will probably -result in a segfault. This means that warnings or errors that -result from parsing Perl should be used with extreme caution, like -this: +This variable was added in Perl v5.8.9. It is subject to change or +removal without notice, but is currently used to avoid recalculating the +boundaries of multi-byte UTF-8-encoded characters. - require Carp if defined $^S; - Carp::confess("Something wrong") if defined &Carp::confess; - die "Something wrong, but could not load Carp to give backtrace... - To see backtrace try starting Perl with -MCarp switch"; +=item ${^UTF8LOCALE} +X<${^UTF8LOCALE}> -Here the first line will load Carp I it is the parser who -called the handler. The second line will print backtrace and die if -Carp was available. The third line will be executed only if Carp was -not available. +This variable indicates whether a UTF-8 locale was detected by perl at +startup. This information is used by perl when it's in +adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line +switch); see L for more info on this. -See L, L, L, and -L for additional information. +This variable was added in Perl v5.8.8. =back -=head2 Names that are no longer special +=head2 Deprecated and removed variables -These variables had special meaning in prior versions of Perl but now -have no effect and will cause warnings if used. They are included -here for historical reference. +Deprecating a variable announces the intent of the perl maintainers to +eventually remove the variable from the language. It may still be +available despite its status. Using a deprecated variable triggers +a warning. + +Once a variable is removed, its use triggers an error telling you +the variable is unsupported. + +See L for details about error messages. =over 8 -=item $# -X<$#> +=item $OFMT -C<$#> used to be a variable that could be used to format printed numbers. -After a deprecation cycle, its magic was removed in Perl 5.10 and using it -now triggers a warning: C<$# is no longer supported>. +=item $# +X<$#> X<$OFMT> -C<$#> is also used as sigil, which, when prepended on the name of an -array, gives the index of the last element in that array. +C<$#> was a variable that could be used to format printed numbers. +After a deprecation cycle, its magic was removed in Perl v5.10.0 and +using it now triggers a warning: C<$# is no longer supported>. - my @array = ("a", "b", "c"); - my $last_index = $#array; # $last_index is 2 +This is not the sigil you use in front of an array name to get the +last index, like C<$#array>. That's still how you get the last index +of an array in Perl. The two have nothing to do with each other. - for my $i (0 .. $#array) { - print "The value of index $i is $array[$i]\n"; - } +Deprecated in Perl 5. -Also see L. +Removed in Perl v5.10.0. =item $* X<$*> -C<$*> used to be a variable that enabled multiline matching. -After a deprecation cycle, its magic was removed in Perl 5.10. +C<$*> was a variable that you could use to enable multiline matching. +After a deprecation cycle, its magic was removed in Perl v5.10.0. Using it now triggers a warning: C<$* is no longer supported>. -Use the C and C regexp modifiers instead. - -Also see L. +You should use the C and C regexp modifiers instead. -=back +Deprecated in Perl 5. -=head2 Error Indicators -X X +Removed in Perl v5.10.0. -The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information -about different types of error conditions that may appear during -execution of a Perl program. The variables are shown ordered by -the "distance" between the subsystem which reported the error and -the Perl process. They correspond to errors detected by the Perl -interpreter, C library, operating system, or an external program, -respectively. +=item $ARRAY_BASE -To illustrate the differences between these variables, consider the -following Perl expression, which uses a single-quoted string: +=item $[ +X<$[> X<$ARRAY_BASE> - eval q{ - open my $pipe, "/cdrom/install |" or die $!; - my @res = <$pipe>; - close $pipe or die "bad pipe: $?, $!"; - }; +This variable stores the index of the first element in an array, and +of the first character in a substring. The default is 0, but you could +theoretically set it to 1 to make Perl behave more like B (or Fortran) +when subscripting and when evaluating the index() and substr() functions. -After execution of this statement all 4 variables may have been set. +As of release 5 of Perl, assignment to C<$[> is treated as a compiler +directive, and cannot influence the behavior of any other file. +(That's why you can only assign compile-time constants to it.) +Its use is highly discouraged. -C<$@> is set if the string to be C-ed did not compile (this -may happen if C or C were imported with bad prototypes), -or if Perl code executed during evaluation die()d . In these cases -the value of $@ is the compile error, or the argument to C -(which will interpolate C<$!> and C<$?>). (See also L, -though.) +Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical +scopes in the same file, unlike other compile-time directives (such as +L). Using local() on it would bind its value strictly to a lexical +block. Now it is always lexically scoped. -When the eval() expression above is executed, open(), C<< >>, -and C are translated to calls in the C run-time library and -thence to the operating system kernel. C<$!> is set to the C library's -C if one of these calls fails. +As of Perl v5.16.0, it is implemented by the L module. See +L for more details on its behaviour. -Under a few operating systems, C<$^E> may contain a more verbose -error indicator, such as in this case, "CDROM tray not closed." -Systems that do not support extended error messages leave C<$^E> -the same as C<$!>. +Under C, or C, C<$[> no longer has any +effect, and always contains 0. Assigning 0 to it is permitted, but any +other value will produce an error. -Finally, C<$?> may be set to non-0 value if the external program -F fails. The upper eight bits reflect specific -error conditions encountered by the program (the program's exit() -value). The lower eight bits reflect mode of failure, like signal -death and core dump information See wait(2) for details. In -contrast to C<$!> and C<$^E>, which are set only if error condition -is detected, the variable C<$?> is set on each C or pipe -C, overwriting the old value. This is more like C<$@>, which -on every eval() is always set on failure and cleared on success. +Mnemonic: [ begins subscripts. -For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, -and C<$?>. +Deprecated in Perl v5.12.0. -=head2 Technical Note on the Syntax of Variable Names +=item $OLD_PERL_VERSION -Variable names in Perl can have several formats. Usually, they -must begin with a letter or underscore, in which case they can be -arbitrarily long (up to an internal limit of 251 characters) and -may contain letters, digits, underscores, or the special sequence -C<::> or C<'>. In this case, the part before the last C<::> or -C<'> is taken to be a I; see L. +=item $] +X<$]> X<$OLD_PERL_VERSION> -Perl variable names may also be a sequence of digits or a single -punctuation or control character. These names are all reserved for -special uses by Perl; for example, the all-digits names are used -to hold data captured by backreferences after a regular expression -match. Perl has a special syntax for the single-control-character -names: It understands C<^X> (caret C) to mean the control-C -character. For example, the notation C<$^W> (dollar-sign caret -C) is the scalar variable whose name is the single character -control-C. This is better than typing a literal control-C -into your program. +See L for a more modern representation of the Perl version that allows +accurate string comparisons. -Finally, new in Perl 5.6, Perl variable names may be alphanumeric -strings that begin with control characters (or better yet, a caret). -These variables must be written in the form C<${^Foo}>; the braces -are not optional. C<${^Foo}> denotes the scalar variable whose -name is a control-C followed by two C's. These variables are -reserved for future special uses by Perl, except for the ones that -begin with C<^_> (control-underscore or caret-underscore). No -control-character name that begins with C<^_> will acquire a special -meaning in any future version of Perl; such names may therefore be -used safely in programs. C<$^_> itself, however, I reserved. +The version + patchlevel / 1000 of the Perl interpreter. This variable +can be used to determine whether the Perl interpreter executing a +script is in the right range of versions: -Perl identifiers that begin with digits, control characters, or -punctuation characters are exempt from the effects of the C -declaration and are always forced to be in package C
; they are -also exempt from C errors. A few other names are also -exempt in these ways: + warn "No checksumming!\n" if $] < 3.019; - ENV STDIN - INC STDOUT - ARGV STDERR - ARGVOUT _ - SIG +The floating point representation can sometimes lead to inaccurate +numeric comparisons. -In particular, the new special C<${^_XYZ}> variables are always taken -to be in package C
, regardless of any C declarations -presently in scope. +See also the documentation of C and C +for a convenient way to fail if the running Perl interpreter is too old. -=head1 BUGS +Mnemonic: Is this version of perl in the right bracket? -Due to an unfortunate accident of Perl's implementation, C imposes a considerable performance penalty on all regular -expression matches in a program, regardless of whether they occur -in the scope of C. For that reason, saying C in libraries is strongly discouraged. See the -Devel::SawAmpersand module documentation from CPAN -( http://www.cpan.org/modules/by-module/Devel/ ) -for more information. Writing C -avoids the performance penalty. +=back -Having to even think about the C<$^S> variable in your exception -handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented -invites grievous and difficult to track down errors. Avoid it -and use an C or CORE::GLOBAL::die override instead. +=cut