home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / perlvar < prev   
Text File  |  1999-04-17  |  39KB  |  983 lines

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