X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/4a6725af9146bd7faaa10aa5429ff009d393fd6d..5a964f204835a8014f4ba86fc91884cff958ac67:/pod/perlvar.pod diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 00b97ba..1a12011 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -6,21 +6,21 @@ 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 -selected filehandle may instead be set by calling an object method on -the FileHandle object. (Summary lines below for this contain the word -HANDLE.) First you must say +selected filehandle may instead (and preferably) be set by calling an +object method on the FileHandle object. (Summary lines below for this +contain the word HANDLE.) First you must say use FileHandle; @@ -28,7 +28,7 @@ after which you may use either method HANDLE EXPR -or +or more safely, HANDLE->method(EXPR) @@ -42,6 +42,12 @@ 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. +The following list is ordered by scalar variables first, then the +arrays, then the hashes (except $^M was added in the wrong place). +This is somewhat obscured by the fact that %ENV and %SIG are listed as +$ENV{expr} and $SIG{expr}. + + =over 8 =item $ARG @@ -106,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 @@ -170,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 @@ -216,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 @@ -400,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. @@ -426,10 +456,10 @@ 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?) @@ -437,16 +467,28 @@ operator. (Mnemonic: What just went bang?) =item $^E -More specific information about the last system error than that provided by -C<$!>, if available. (If not, it's just C<$!> again, except under OS/2.) -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 which was not directed via CRT. 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. -Note that under OS/2 C<$!> and C<$^E> do not track each other, so if an -OS/2-specific call is performed, you may need to check both. +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.) =item $EVAL_ERROR @@ -490,8 +532,9 @@ The effective uid of this process. Example: $< = $>; # set real to effective uid ($<,$>) = ($>,$<); # swap real and effective uid -(Mnemonic: it's the uid you went I, if you're running setuid.) Note: -"C<$E>" and "C<$E>" can be swapped on only machines supporting setreuid(). +(Mnemonic: it's the uid you went I, if you're running setuid.) +Note: "C<$E>" and "C<$E>" can be swapped only on machines +supporting setreuid(). =item $REAL_GROUP_ID @@ -503,8 +546,14 @@ 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. (Mnemonic: parentheses are used to I -things. The real gid is the group you I, if you're running setgid.) +the same as the first number. + +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. + +(Mnemonic: parentheses are used to I things. The real gid is the +group you I, if you're running setgid.) =item $EFFECTIVE_GROUP_ID @@ -516,15 +565,21 @@ 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: parentheses are -used to I things. The effective gid is the group that's I for -you, if you're running setgid.) +which may be the same as the first number. + +Similarly, a value assigned to "C<$)>" must also be a space-separated +list of numbers. The first number is used to set 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" >. + +(Mnemonic: parentheses are used to I things. The effective gid +is the group that's I for you, if you're running setgid.) Note: "C<$E>", "C<$E>", "C<$(>" and "C<$)>" can be set only on machines that support the corresponding I routine. "C<$(>" -and "C<$)>" can be swapped on only machines supporting setregid(). Because -Perl doesn't currently use initgroups(), you can't set your group vector to -multiple groups. +and "C<$)>" can be swapped only on machines supporting setregid(). =item $PROGRAM_NAME @@ -584,8 +639,8 @@ C<$^F> at the time of the open, not the time of the exec. =item $^H -The current set of syntax checks enabled by C. See the -documentation of C for more details. +The current set of syntax checks enabled by C and other block +scoped compiler hints. See the documentation of C for more details. =item $INPLACE_EDIT @@ -594,6 +649,20 @@ documentation of C for more details. The current value of the inplace-edit extension. Use C to disable inplace editing. (Mnemonic: value of B<-i> switch.) +=item $^M + +By default, running out of memory it is not trappable. However, if +compiled for this, Perl may use the contents of C<$^M> as an emergency +pool after die()ing with this message. Suppose that your Perl were +compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then + + $^M = 'a' x (1<<16); + +would allocate a 64K buffer for use when in emergency. See the F +file for information on how to enable this option. As a disincentive to +casual use of this advanced feature, there is no L long name for +this variable. + =item $OSNAME =item $^O @@ -606,9 +675,45 @@ is identical to C<$Config{'osname'}>. =item $^P -The internal flag that the debugger clears so that it doesn't debug -itself. You could conceivably disable debugging yourself by clearing -it. +The internal variable for debugging support. Different bits mean the +following (subject to change): + +=over 6 + +=item 0x01 + +Debug subroutine enter/exit. + +=item 0x02 + +Line-by-line debugging. + +=item 0x04 + +Switch off optimizations. + +=item 0x08 + +Preserve more data for future interactive inspections. + +=item 0x10 + +Keep info about source lines on which a subroutine is defined. + +=item 0x20 + +Start with single-step on. + +=back + +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 $^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. =item $BASETIME @@ -656,6 +761,11 @@ to get the machine-dependent library properly loaded also: use lib '/mypath/libdir/'; use SomeMod; +=item @_ + +Within a subroutine the array @_ contains the parameters passed to that +subroutine. See L. + =item %INC The hash %INC contains entries for each filename that has @@ -664,25 +774,25 @@ specified, and the value is the location of the file actually found. The C command uses this array to determine whether a given file has already been included. -=item $ENV{expr} +=item %ENV $ENV{expr} The hash %ENV contains your current environment. Setting a value in C changes the environment for child processes. -=item $SIG{expr} +=item %SIG $SIG{expr} The hash %SIG is used to set signal handlers for various signals. Example: sub handler { # 1st argument is signal name - local($sig) = @_; + my($sig) = @_; print "Caught a SIG$sig--shutting down\n"; close(LOG); exit(0); } - $SIG{'INT'} = 'handler'; - $SIG{'QUIT'} = 'handler'; + $SIG{'INT'} = \&handler; + $SIG{'QUIT'} = \&handler; ... $SIG{'INT'} = 'DEFAULT'; # restore default action $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT @@ -690,8 +800,8 @@ signals. Example: The %SIG array contains values for only the signals actually set within the Perl script. Here are some other examples: - $SIG{PIPE} = Plumber; # SCARY!! - $SIG{"PIPE"} = "Plumber"; # just fine, assumes main::Plumber + $SIG{"PIPE"} = Plumber; # SCARY!! + $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? @@ -732,21 +842,30 @@ 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 C, a loop exit, or a die(). The C<__DIE__> handler is explicitly disabled during the call, so that you -can die from a C<__DIE__> handler. Similarly for C<__WARN__>. See -L, L and L. - -=item $^M - -By default, running out of memory it is not trappable. However, if -compiled for this, Perl may use the contents of C<$^M> as an emergency -pool after die()ing with this message. Suppose that your Perl were -compiled with -DEMERGENCY_SBRK and used Perl's malloc. Then - - $^M = 'a' x (1<<16); - -would allocate a 64K buffer for use when in emergency. See the F -file for information on how to enable this option. As a disincentive to -casual use of this advanced feature, there is no L long name for -this variable. +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 and L for how to +circumvent this. + +Note that 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 calls which result/may-result +in parsing Perl should be used with extreme causion, 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 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. + +See L, L and L for +additional info. =back