X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=49cdcb273e6973eee61af3364ab9484b67726ca5;hb=7817ba4dfeb754838a0da8f159127895c2dcf4fc;hp=5e705313d5133a93b0af3fa4d45712337961b023;hpb=146174a91a192983720a158796dc066226ad0e55;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 5e70531..49cdcb2 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -99,7 +99,7 @@ The implicit iterator variable in the grep() and map() functions. =item * -The default place to put an input record when a CFHE> +The default place to put an input record when a C<< >> operation's result is tested by itself as the sole criterion of a C test. Outside a C test, this will not happen. @@ -111,7 +111,7 @@ test. Outside a C test, this will not happen. =over 8 -=item $EIE +=item $> Contains the subpattern from the corresponding set of capturing parentheses from the last pattern match, not counting patterns @@ -174,18 +174,20 @@ example: (Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. -=item @+ +=item @LAST_MATCH_END -$+[0] is the offset of the end of the last successful match. -C<$+[>IC<]> is the offset of the end of the substring matched by -I-th subpattern, or undef if the subpattern did not match. +=item @+ -Thus after a match against $_, $& coincides with C. Similarly, C<$>I coincides with CIC<], -$+[>IC<] - $-[>IC<]> if C<$-[>IC<]> is defined, and $+ coincides with -C. One can use C<$#+> to find the number -of subgroups in the last successful match. Contrast with -C<$#->, the last I subgroup. Compare with C<@->. +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 $MULTILINE_MATCHING @@ -215,7 +217,7 @@ you just read() (or called a C or C on). The value may be different from the actual physical line number in the file, depending on what notion of "line" is in effect--see C<$/> on how to change that. An explicit close on a filehandle resets the line -number. Because CE> never does an explicit close, line +number. Because C<< <> >> never does an explicit close, line numbers increase across ARGV files (but see examples in L). Consider this variable read-only: setting it does not reposition the seek pointer; you'll have to do that on your own. Localizing C<$.> @@ -412,6 +414,8 @@ channel. Used with formats. (Mnemonic: lines_on_page - lines_printed.) +=item @LAST_MATCH_START + =item @- $-[0] is the offset of the start of the last successful match. @@ -426,6 +430,33 @@ matched subgroup in the last successful match. Contrast with C<$#+>, the number of subgroups in the regular expression. Compare with C<@+>. +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. +You can use C<$#-> to determine how many subgroups were in the +last successful match. Compare with the C<@+> variable. + +After a match against some variable $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<$1> is the same as C + +=item C<$2> is the same as C + +=item C<$3> is the same as C + +=back + =item format_name HANDLE EXPR =item $FORMAT_NAME @@ -484,7 +515,7 @@ 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 wait() system call (or else is made up to look like it). Thus, the -exit value of the subprocess is really (C<$? EE 8>), and +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.) @@ -588,7 +619,8 @@ across fork() calls. (Mnemonic: same as shells.) =item $< The real uid of this process. (Mnemonic: it's the uid you came I, -if you're running setuid.) +if you're running setuid.) You can change both the real uid and +the effective uid at the same time by using POSIX::setuid(). =item $EFFECTIVE_USER_ID @@ -601,8 +633,11 @@ The effective uid of this process. Example: $< = $>; # set real to effective uid ($<,$>) = ($>,$<); # swap real and effective uid +You can change both the effective uid and the real uid at the same +time by using POSIX::setuid(). + (Mnemonic: it's the uid you went I, if you're running setuid.) -C<$E> and C<$E> can be swapped only on machines +C<< $< >> and C<< $> >> can be swapped only on machines supporting setreuid(). =item $REAL_GROUP_ID @@ -621,6 +656,9 @@ 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. +You can change both the real gid and the effective gid at the same +time by using POSIX::setgid(). + (Mnemonic: parentheses are used to I things. The real gid is the group you I, if you're running setgid.) @@ -643,10 +681,13 @@ 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" >. +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). + (Mnemonic: parentheses are used to I things. The effective gid is the group that's I for you, if you're running setgid.) -C<$E>, C<$E>, C<$(> and C<$)> can be set only on +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(). @@ -660,6 +701,11 @@ program sees. This 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.) +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"> will +result in C<"perl: foobar (perl)">. This is an operating system +feature. + =item $[ The index of the first element in an array, and of the first character @@ -672,8 +718,6 @@ As of release 5 of Perl, assignment to C<$[> is treated as a compiler directive, and cannot influence the behavior of any other file. Its use is highly discouraged. -=item $PERL_VERSION - =item $] The version + patchlevel / 1000 of the Perl interpreter. This variable @@ -686,6 +730,11 @@ of perl in the right bracket?) Example: See also the documentation of C and C for a convenient way to fail if the running Perl interpreter is too old. +The use of this variable is deprecated. 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. + =item $COMPILING =item $^C @@ -713,12 +762,59 @@ 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 open() or pipe() was called, not the time of the exec(). +C<$^F> when the corresponding file, pipe, or socket was opened, not the +time of the exec(). =item $^H -The current set of syntax checks enabled by C and other block -scoped compiler hints. See the documentation of C for more details. +WARNING: This variable is strictly for internal use only. Its availability, +behavior, and contents are subject to change without notice. + +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. + +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. + +This behavior provides the semantic of lexical scoping, and is used in, +for instance, the C pragma. + +The contents should be an integer; different bits of it are used for +different pragmatic flags. Here's an example: + + sub add_100 { $^H |= 0x100 } + + sub foo { + BEGIN { add_100() } + bar->baz($boon); + } + +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. + +Substitution of the above BEGIN block with: + + BEGIN { require strict; strict->import('vars') } + +demonstrates how C is implemented. Here's a conditional +version of the same lexical pragma: + + BEGIN { require strict; strict->import('vars') if $condition } + +=item %^H + +WARNING: This variable is strictly for internal use only. Its availability, +behavior, and contents are subject to change without notice. + +The %^H hash provides the same scoping semantic as $^H. This makes it +useful for implementation of lexically scoped pragmas. =item $INPLACE_EDIT @@ -737,10 +833,10 @@ Then $^M = 'a' x (1 << 16); -would allocate a 64K buffer for use when in emergency. See the +would allocate a 64K buffer for use in an emergency. See the F file in the Perl distribution for information on how to enable this option. To discourage casual use of this advanced -feature, there is no L long name for this variable. +feature, there is no L long name for this variable. =item $OSNAME @@ -784,16 +880,37 @@ Keep info about source lines on which a subroutine is defined. Start with single-step on. +=item 0x40 + +Use subroutine address instead of name when reporting. + +=item 0x80 + +Report C as well. + +=item 0x100 + +Provide informative "file" names for evals based on the place they were compiled. + +=item 0x200 + +Provide informative names to anonymous subroutines based on the place they +were compiled. + =back Some bits may be relevant at compile-time only, some at run-time only. This is a new mechanism and the details may change. +=item $LAST_REGEXP_CODE_RESULT + =item $^R The result of evaluation of the last successful C<(?{ code })> regular expression assertion (see L). May be written to. +=item $EXCEPTIONS_BEING_CAUGHT + =item $^S Current state of the interpreter. Undefined if parsing of the current @@ -808,6 +925,27 @@ 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 + +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 C and will return true for +C<$^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 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. + =item $WARNING =item $^W @@ -816,11 +954,26 @@ 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. -=item ${^Warnings} +=item ${^WARNING_BITS} The current set of warning checks enabled by the C pragma. See the documentation of C for more details. +=item ${^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<-C> switch. + +The initial value is typically C<0> for compatibility with Perl versions +earlier than 5.6, but may be automatically set to C<1> by Perl if the system +provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>). + +The C pragma always overrides the effect of this flag in the current +lexical scope. See L. + =item $EXECUTABLE_NAME =item $^X @@ -830,7 +983,7 @@ This may not be a full pathname, nor even necessarily in your path. =item $ARGV -contains the name of the current file when reading from EE. +contains the name of the current file when reading from <>. =item @ARGV @@ -1000,7 +1153,7 @@ the value of $@ is the compile error, or the argument to C (which will interpolate C<$!> and C<$?>!). (See also L, though.) -When the eval() expression above is executed, open(), C<>, +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. @@ -1077,7 +1230,7 @@ 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.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme) +(http://www.perl.com/CPAN/modules/by-module/Devel/) for more information. Having to even think about the C<$^S> variable in your exception