X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=2ed3e97f77b4753406bef17d2f6907b522248f8d;hb=9c4d0f167fb7643c3ff9ccfd4b79b6aeb9763e43;hp=75f4e6d5c2b591732d030152c5c33100f4c53dd2;hpb=fb73857aa0bfa8ed43d4d2f972c564c70a57e0c4;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 75f4e6d..2ed3e97 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -6,15 +6,15 @@ perlvar - Perl predefined variables =head2 Predefined Names -The following names have special meaning to Perl. Most of the +The following names have special meaning to Perl. Most punctuation names have reasonable mnemonics, or analogues in one of -the shells. Nevertheless, if you wish to use the long variable names, +the shells. Nevertheless, if you wish to use long variable names, you just need to say use English; at the top of your program. This will alias all the short names to the -long names in the current package. Some of them even have medium names, +long names in the current package. Some even have medium names, generally borrowed from B. To go a step further, those variables that depend on the currently @@ -28,7 +28,7 @@ after which you may use either method HANDLE EXPR -or +or more safely, HANDLE->method(EXPR) @@ -112,11 +112,11 @@ test. Note that outside of a C test, this will not happen. =over 8 -=item $EIE +=item $EIE Contains the subpattern from the corresponding set of parentheses in the last pattern matched, not counting patterns matched in nested -blocks that have been exited already. (Mnemonic: like \digit.) +blocks that have been exited already. (Mnemonic: like \digits.) These variables are all read-only. =item $MATCH @@ -176,7 +176,8 @@ is 0. (Mnemonic: * matches multiple things.) Note that this variable influences the interpretation of only "C<^>" and "C<$>". A literal newline can be searched for even when C<$* == 0>. -Use of "C<$*>" is deprecated in modern perls. +Use of "C<$*>" is deprecated in modern Perls, supplanted by +the C and C modifiers on pattern matching. =item input_line_number HANDLE EXPR @@ -222,6 +223,27 @@ character belongs to the next paragraph, even if it's a newline. Remember: the value of $/ is a string, not a regexp. AWK has to be better for something :-) +Setting $/ to a reference to an integer, scalar containing an integer, or +scalar that's convertable to an integer will attempt to read records +instead of lines, with the maximum record size being the referenced +integer. So this: + + $/ = \32768; # or \"32768", or \$var_containing_32768 + open(FILE, $myfile); + $_ = ; + +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. + +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 +likely not a problem, as any file you'd want to read in record mode is +proably usable in line mode) Non-VMS systems perform normal I/O, so +it's safe to mix record and non-record reads of a file. + =item autoflush HANDLE EXPR =item $OUTPUT_AUTOFLUSH @@ -406,12 +428,14 @@ L. =item $? The status returned by the last pipe close, backtick (C<``>) command, -or system() operator. Note that this is the status word returned by -the wait() system call (or else is made up to look like it). Thus, -the exit value of the subprocess is actually (C<$? EE 8>), and -C<$? & 255> gives which signal, if any, the process died from, and -whether there was a core dump. (Mnemonic: similar to B and -B.) +or system() operator. Note that this is the status word returned by the +wait() system call (or else is made up to look like it). Thus, the exit +value of the subprocess is actually (C<$? EE 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.) + +Additionally, if the C variable is supported in C, its value +is returned via $? if any of the C functions fail. Note that if you have installed a signal handler for C, the value of C<$?> will usually be wrong outside that handler. @@ -424,6 +448,8 @@ Under VMS, the pragma C makes C<$?> reflect the actual VMS exit status, instead of the default emulation of POSIX status. +Also see L. + =item $OS_ERROR =item $ERRNO @@ -432,24 +458,43 @@ status. If used in a numeric context, yields the current value of errno, with all the usual caveats. (This means that you shouldn't depend on the -value of "C<$!>" to be anything in particular unless you've gotten a +value of C<$!> to be anything in particular unless you've gotten a specific error return indicating a system error.) If used in a string context, yields the corresponding system error string. You can assign -to "C<$!>" to set I if, for instance, you want "C<$!>" to return the +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?) +Also see L. + =item $EXTENDED_OS_ERROR =item $^E -More specific information about the last system error than that provided by -C<$!>, if available. (If not, it's just C<$!> again.) -At the moment, this differs from C<$!> under only VMS and OS/2, where it -provides the VMS status value from the last system error, and OS/2 error -code of the last call to OS/2 API either via CRT, or directly from perl. The -caveats mentioned in the description of C<$!> apply here, too. -(Mnemonic: Extra error explanation.) +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<$!>. + +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. + +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. + +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<$!>. + +Caveats mentioned in the description of C<$!> generally apply to +C<$^E>, also. (Mnemonic: Extra error explanation.) + +Also see L. =item $EVAL_ERROR @@ -464,6 +509,8 @@ Note that 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. +Also see L. + =item $PROCESS_ID =item $PID @@ -670,11 +717,17 @@ Start with single-step on. Note that some bits may be relevent at compile-time only, some at run-time only. This is a new mechanism and the details may change. +=item $^R + +The result of evaluation of the last successful L> +regular expression assertion. (Excluding those used as switches.) May +be written to. + =item $^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, othewise false. +$SIG{__WARN__} handlers). True if inside an eval, otherwise false. =item $BASETIME @@ -806,7 +859,7 @@ The C<__DIE__> handler is explicitly disabled during the call, so that you can die from a C<__DIE__> handler. Similarly for C<__WARN__>. Note that the C<$SIG{__DIE__}> hook is called even inside eval()ed -blocks/strings. See L, L for how to +blocks/strings. See L and L for how to circumvent this. Note that C<__DIE__>/C<__WARN__> handlers are very special in one @@ -830,3 +883,54 @@ See L, L and L for additional info. =back + +=head2 Error Indicators + +The variables L<$@>, L<$!>, L<$^E>, and L<$?> contain information about +different types of error conditions that may appear during execution of +Perl script. The variables are shown ordered by the "distance" between +the subsystem which reported the error and the Perl process, and +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: + + eval ' + open PIPE, "/cdrom/install |"; + @res = ; + 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 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 (either implicitly, say, +if C was imported from module L, or the C after +C was triggered). In these cases the value of $@ is the compile +error, or C error (which will interpolate C<$!>!), or the argument +to C (which will interpolate C<$!> and C<$?>!). + +When the above expression is executed, open(), C<>, and C +are translated to C run-time library calls. $! is set if one of these +calls fails. The value is a symbolic indicator chosen by the C run-time +library, say C. + +On some systems the above C library calls are further translated +to calls to the kernel. The kernel may have set more verbose error +indicator that one of the handful of standard C errors. In such cases $^E +contains this verbose error indicator, which may be, say, C. On systems where C library calls are identical to system calls +$^E is a duplicate of $!. + +Finally, $? may be set to non-C<0> value if the external program +C fails. Upper bits of the particular value may reflect +specific error conditions encountered by this program (this is +program-dependent), lower-bits reflect mode of failure (segfault, completion, +etc.). Note that in contrast to $@, $!, and $^E, which are set only +if error condition is detected, the variable $? is set on each C or +pipe C, overwriting the old value. + +For more details, see the individual descriptions at L<$@>, L<$!>, L<$^E>, +and L<$?>.