perlvaro.txt

source of perl for linux application,

$^P
The internal variable for debugging support. The meanings of the various bits are subject to change, but currently indicate:
0x01
Debug subroutine enter/exit.
0x02
Line-by-line debugging.
0x04
Switch off optimizations.
0x08
Preserve more data for future interactive inspections.
0x10
Keep info about source lines on which a subroutine is defined.
0x20
Start with single-step on.
0x40
Use subroutine address instead of name when reporting.
0x80
Report goto &subroutine as well.
0x100
Provide informative "file" names for evals based on the place they were compiled.
0x200
Provide informative names to anonymous subroutines based on the place they were compiled.
Some bits may be relevant at compile-time only, some at run-time only. This is a new mechanism and the details may change.
$LAST_REGEXP_CODE_RESULT
$^R
The result of evaluation of the last successful (?{ code }) regular expression assertion (see perlre). May be written to.
$EXCEPTIONS_BEING_CAUGHT
$^S
Current state of the interpreter. Undefined if parsing of the current module/eval is not finished (may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers). True if inside an eval(), otherwise false.
$BASETIME
$^T
The time at which the program began running, in seconds since the epoch (beginning of 1970). The values returned by the -M, -A, and -C filetests are based on this value.
$PERL_VERSION
$^V
The revision, version, and subversion of the Perl interpreter, represented as a string composed of characters with those ordinals. Thus in Perl v5.6.0 it equals chr(5) . chr(6) . chr(0) and will return true for $^V eq v5.6.0. Note that the characters in this string value can potentially be in Unicode range.
This 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:
    warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
See the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old.
See also $] for an older representation of the Perl version.
$WARNING
$^W
The current value of the warning switch, initially true if -w was used, false otherwise, but directly modifiable. (Mnemonic: related to the -w switch.) See also warnings.
${^WARNING_BITS}
The current set of warning checks enabled by the use warnings pragma. See the documentation of warnings for more details.
${^WIDE_SYSTEM_CALLS}
Global flag that enables system calls made by Perl to use wide character APIs native to the system, if available. This is currently only implemented on the Windows platform.
This can also be enabled from the command line using the -C switch.
The initial value is typically 0 for compatibility with Perl versions earlier than 5.6, but may be automatically set to 1 by Perl if the system provides a user-settable default (e.g., $ENV{LC_CTYPE}).
The bytes pragma always overrides the effect of this flag in the current lexical scope. See bytes.
$EXECUTABLE_NAME
$^X
The name that the Perl binary itself was executed as, from C's argv[0]. This may not be a full pathname, nor even necessarily in your path.
$ARGV
contains the name of the current file when reading from <>.
@ARGV
The array @ARGV contains the command-line arguments intended for the script. $#ARGV is generally the number of arguments minus one, because $ARGV[0] is the first argument, not the program's command name itself. See $0 for the command name.
@INC
The array @INC contains the list of places that the do EXPR, require, or use constructs look for their library files. It initially consists of the arguments to any -I command-line switches, followed by the default Perl library, probably /usr/local/lib/perl, followed by ".", to represent the current directory. If you need to modify this at runtime, you should use the use lib pragma to get the machine-dependent library properly loaded also:
    use lib '/mypath/libdir/';
    use SomeMod;
@_
Within a subroutine the array @_ contains the parameters passed to that subroutine. See perlsub.
%INC
The hash %INC contains entries for each filename included via the do, require, or use 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 require operator uses this hash to determine whether a particular file has already been included.
%ENV
$ENV{expr}
The hash %ENV contains your current environment. Setting a value in ENV changes the environment for any child processes you subsequently fork() off.
%SIG
$SIG{expr}
The hash %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 'IGNORE' usually has the effect of ignoring the signal, except for the CHLD signal. See perlipc 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 sigaction() function then signal handlers are installed using it. This means you get reliable signal handling. If your system has the SA_RESTART flag it is used when signals handlers are installed. This means that system calls for which restarting is supported continue rather than returning when a signal arrives. If you want your system calls to be interrupted by signal delivery then do something like this:
    use POSIX ':signal_h';
    my $alarm = 0;
    sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 }
        or die "Error setting SIGALRM handler: $!\n";
See POSIX.
Certain internal hooks can be also set using the %SIG hash. The routine indicated by $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 __WARN__ hook causes the ordinary printing of warnings to STDERR 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;
The routine indicated by $SIG{__DIE__} is called when a fatal exception is about to be thrown. The error message is passed as the first argument. When a __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 goto, a loop exit, or a die(). The __DIE__ handler is explicitly disabled during the call, so that you can die from a __DIE__ handler. Similarly for __WARN__.
Due to an implementation glitch, the $SIG{__DIE__} hook is called even inside an eval(). Do not use this to rewrite a pending exception in $@, or as a bizarre substitute for overriding CORE::GLOBAL::die(). This strange action at a distance may be fixed in a future release so that $SIG{__DIE__} is only called if your program is about to exit, as was the original intent. Any other use is deprecated.
__DIE__/__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...
         To see backtrace try starting Perl with -MCarp switch";
Here the first line will load Carp unless 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.
See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and warnings for additional information.
Error Indicators
The variables $@, $!, $^E, and $? 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.
To illustrate the differences between these variables, consider the following Perl expression, which uses a single-quoted string:
    eval q{
        open PIPE, "/cdrom/install |";
        @res = <PIPE>;
        close PIPE or die "bad pipe: $?, $!";
    };
After execution of this statement all 4 variables may have been set. 
$@ is set if the string to be eval-ed did not compile (this may happen if open or close 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 die (which will interpolate $! and $?!). (See also Fatal, though.)
When the eval() expression above is executed, open(), <PIPE>, and close are translated to calls in the C run-time library and thence to the operating system kernel. $! is set to the C library's errno if one of these calls fails. 
Under a few operating systems, $^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 $^E the same as $!.
Finally, $? may be set to non-0 value if the external program /cdrom/install 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 $! and $^E, which are set only if error condition is detected, the variable $? is set on each wait or pipe close, overwriting the old value. This is more like $@, which on every eval() is always set on failure and cleared on success.
For more details, see the individual descriptions at $@, $!, $^E, and $?.
Technical Note on the Syntax of Variable Names
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 :: or '. In this case, the part before the last :: or ' is taken to be a package qualifier; see perlmod.
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 ^X (caret X) to mean the control-X character. For example, the notation $^W (dollar-sign caret W) is the scalar variable whose name is the single character control-W. This is better than typing a literal control-W into your program.
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 ${^Foo}; the braces are not optional. ${^Foo} denotes the scalar variable whose name is a control-F followed by two o's. These variables are reserved for future special uses by Perl, except for the ones that begin with ^_ (control-underscore or caret-underscore). No control-character name that begins with ^_ will acquire a special meaning in any future version of Perl; such names may therefore be used safely in programs. $^_ itself, however, is reserved.
Perl identifiers that begin with digits, control characters, or punctuation characters are exempt from the effects of the package declaration and are always forced to be in package main. A few other names are also exempt:
        ENV             STDIN
        INC             STDOUT
        ARGV            STDERR
        ARGVOUT
        SIG
In particular, the new special ${^_XYZ} variables are always taken to be in package main, regardless of any package declarations presently in scope.
BUGS
Due to an unfortunate accident of Perl's implementation, use English imposes a considerable performance penalty on all regular expression matches in a program, regardless of whether they occur in the scope of use English. For that reason, saying use English in libraries is strongly discouraged. See the Devel::SawAmpersand module documentation from CPAN (http://www.perl.com/CPAN/modules/by-module/Devel/) for more information.
Having to even think about the $^S variable in your exception handlers is simply wrong. $SIG{__DIE__} as currently implemented invites grievous and difficult to track down errors. Avoid it and use an END{} or CORE::GLOBAL::die override instead.