X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=52ed78bbc1f5eb4f193d5c49a39b9a0cae39d6a7;hb=cf2649810f00335bd657355d81bcc9384a620135;hp=69cd592d9c564780c5b28f5436fe6b1a899854ed;hpb=4c5cef9b8e6593e27c89ee587dbf91631cce9552;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 69cd592..52ed78b 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -177,6 +177,11 @@ test. Outside a C test, this will not happen. =back +As C<$_> is a global variable, this may lead in some cases to unwanted +side-effects. As of perl 5.9.1, you can now use a lexical version of +C<$_> by declaring it in a file or in a block with C. Moreover, +declaring C restores the global C<$_> in the current scope. + (Mnemonic: underline is understood in certain operations.) =back @@ -189,10 +194,9 @@ test. Outside a C test, this will not happen. Special package variables when using sort(), see L. Because of this specialness $a and $b don't need to be declared -(using local(), use vars, or our()) even when using the strict -vars pragma. Don't lexicalize them with C or C -if you want to be able to use them in the sort() comparison block -or function. +(using use vars, or our()) even when using the C pragma. +Don't lexicalize them with C or C if you want to be +able to use them in the sort() comparison block or function. =back @@ -294,26 +298,6 @@ 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 - -=item $* - -Set to a non-zero integer value to do multi-line matching within a -string, 0 (or undefined) to tell Perl that it can assume that strings -contain a single line, for the purpose of optimizing pattern matches. -Pattern matches on strings containing multiple newlines can produce -confusing results when C<$*> is 0 or undefined. Default is undefined. -(Mnemonic: * matches multiple things.) 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 Perl, supplanted by -the C and C modifiers on pattern matching. - -Assigning a non-numerical value to C<$*> triggers a warning (and makes -C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*> -makes that an implicit C is applied on the value. - =item HANDLE->input_line_number(EXPR) =item $INPUT_LINE_NUMBER @@ -491,8 +475,6 @@ taken for something more important.) Consider using "real" multidimensional arrays as described in L. -=item $OFMT - =item $# The output format for printed numbers. This variable is a half-hearted @@ -546,9 +528,9 @@ C<$-[>IC<]> is the offset of the start of the substring matched by I-th subpattern, or undef if the subpattern did not match. 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 last +$+[0] - $-[0]>. Similarly, $I coincides with C if C<$-[n]> is defined, and $+ coincides with +C. One can use C<$#-> to find the last matched subgroup in the last successful match. Contrast with C<$#+>, the number of subgroups in the regular expression. Compare with C<@+>. @@ -635,7 +617,7 @@ L. 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 +traditional Unix wait() system call (or else is made up to look like it). Thus, the 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: @@ -661,10 +643,24 @@ status; see L for details. Also see L. +=item ${^CHILD_ERROR_NATIVE} + +The native status returned by the last pipe close, backtick (C<``>) +command, successful call to wait() or waitpid(), or from the system() +operator. On POSIX-like systems this value can be decoded with the +WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG +and WIFCONTINUED functions provided by the L module. + +Under VMS this reflects the actual VMS exit status; i.e. it is the same +as $? when the pragma C is in effect. + =item ${^ENCODING} -The encoding used to interpret native eight-bit encodings to Unicode, -see L. An opaque C object. +The I to the Encode object that is used to convert +the source code to Unicode. Thanks to this variable your perl script +does not have to be written in UTF-8. Default is I. The direct +manipulation of this variable is highly discouraged. See L +for more details. =item $OS_ERROR @@ -692,7 +688,7 @@ In the above I stands for anything: zero, non-zero, C. A successful system or library call does B set the variable to zero. -If used an a string, yields the corresponding system error string. +If used as a string, yields the corresponding system error string. You can assign a number 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 @@ -704,10 +700,13 @@ Also see L. Each element of C<%!> has a true value only if C<$!> is set to that value. For example, C<$!{ENOENT}> is true if and only if the current -value of C<$!> is C; that is, if the mot recent error was "No -such file or directory". To check if a particular key is meaningful -on your system, use C; for a list of legal keys, -use C. See L for more information. +value of C<$!> is C; that is, if the most recent error was +"No such file or directory" (or its moral equivalent: not all operating +systems give that exact error, and certainly not all languages). +To check if a particular key is meaningful on your system, use +C; for a list of legal keys, use C. +See L for more information, and also see above for the +validity of C<$!>. =item $EXTENDED_OS_ERROR @@ -763,6 +762,12 @@ The process number of the Perl running this script. You should consider this variable read-only, although it will be altered across fork() calls. (Mnemonic: same as shells.) +Note for Linux users: on Linux, the C functions C and +C return different values from different threads. In order to +be portable, this behavior is not reflected by C<$$>, whose value remains +consistent across threads. If you want to call the underlying C, +you may use the CPAN module C. + =item $REAL_USER_ID =item $UID @@ -771,7 +776,9 @@ across fork() calls. (Mnemonic: same as shells.) The real uid of this process. (Mnemonic: it's the uid you came I, if you're running setuid.) You can change both the real uid and -the effective uid at the same time by using POSIX::setuid(). +the effective uid at the same time by using POSIX::setuid(). Since +changes to $< require a system call, check $! after a change attempt to +detect any possible errors. =item $EFFECTIVE_USER_ID @@ -785,7 +792,8 @@ The effective uid of this process. Example: ($<,$>) = ($>,$<); # swap real and effective uid You can change both the effective uid and the real uid at the same -time by using POSIX::setuid(). +time by using POSIX::setuid(). Changes to $> require a check to $! +to detect any possible errors after an attempted change. (Mnemonic: it's the uid you went I, if you're running setuid.) C<< $< >> and C<< $> >> can be swapped only on machines @@ -808,7 +816,8 @@ 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(). +time by using POSIX::setgid(). Changes to $( require a check to $! +to detect any possible errors after an attempted change. (Mnemonic: parentheses are used to I things. The real gid is the group you I, if you're running setgid.) @@ -834,6 +843,8 @@ 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). +Changes to $) require a check to $! to detect any possible errors +after an attempted change. (Mnemonic: parentheses are used to I things. The effective gid is the group that's I for you, if you're running setgid.) @@ -846,16 +857,36 @@ and C<$)> can be swapped only on machines supporting setregid(). =item $0 -Contains the name of the program being executed. On some operating -systems assigning to C<$0> modifies the argument area that the B -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.) +Contains the name of the program being executed. + +On some (read: not all) operating systems assigning to C<$0> modifies +the argument area that the C program sees. On some platforms you +may have to use special C options or a different C to see the +changes. Modifying the $0 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 that there are platform specific limitations on the the maximum +length of C<$0>. In the most extreme case it may be limited to the +space occupied by the original C<$0>. + +In some platforms there may be arbitrary amount of padding, for +example space characters, after the modified name as shown by C. +In some platforms this padding may extend all the way to the original +length of the argument area, no matter what you do (this is the case +for example with Linux 2.2). 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. +from the ps(1) output. For example, setting C<$0> to C<"foobar"> may +result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix +and the " (perl)" suffix are shown depends on your exact BSD variant +and version). This is an operating system feature, Perl cannot help it. + +In multithreaded scripts Perl coordinates the threads so that any +thread may modify its copy of the C<$0> and the change becomes visible +to ps(1) (assuming the operating system plays along). Note that the +the view of C<$0> the other threads have will not change since they +have their own copies of it. =item $[ @@ -867,8 +898,14 @@ subscripting and when evaluating the index() and substr() functions. As of release 5 of Perl, assignment to C<$[> is treated as a compiler directive, and cannot influence the behavior of any other file. +(That's why you can only assign compile-time constants to it.) Its use is highly discouraged. +Note that, unlike other compile-time directives (such as L), +assignment to $[ can be seen from outer lexical scopes in the same file. +However, you can use local() on it to strictly bound its value to a +lexical block. + =item $] The version + patchlevel / 1000 of the Perl interpreter. This variable @@ -900,7 +937,23 @@ C<$^C = 1> is similar to calling C. =item $^D The current value of the debugging flags. (Mnemonic: value of B<-D> -switch.) +switch.) May be read or set. Like its command-line equivalent, you can use +numeric or symbolic values, eg C<$^D = 10> or C<$^D = "st">. + +=item ${^RE_DEBUG_FLAGS} + +The current value of the regex debugging flags. Set to 0 for no debug output +even when the re 'debug' module is loaded. See L for details. + +=item ${^RE_TRIE_MAXBUF} + +Controls how certain regex optimisations are applied and how much memory they +utilize. This value by default is 65536 which corresponds to a 512kB temporary +cache. Set this to a higher value to trade memory for speed when matching +large alternations. Set it to a lower value if you want the optimisations to +be as conservative of memory as possible but still occur, and set it to a +negative value to prevent the optimisation and conserve the most memory. +Under normal situations this variable should be of no interest to you. =item $SYSTEM_FD_MAX @@ -997,11 +1050,17 @@ built, as determined during the configuration process. The value is identical to C<$Config{'osname'}>. See also L and the B<-V> command-line switch documented in L. +In Windows platforms, $^O is not very helpful: since it is always +C, it doesn't tell the difference between +95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or +Win32::GetOSVersion() (see L and L) to distinguish +between the variants. + =item ${^OPEN} An internal variable used by PerlIO. A string in two parts, separated -by a C<\0> byte, the first part is the input disciplines, the second -part is the output disciplines. +by a C<\0> byte, the first part describes the input layers, the second +part describes the output layers. =item $PERLDB @@ -1053,6 +1112,10 @@ Provide informative "file" names for evals based on the place they were compiled Provide informative names to anonymous subroutines based on the place they were compiled. +=item 0x400 + +Debug assertion subroutines enter/exit. + =back Some bits may be relevant at compile-time only, some at @@ -1069,9 +1132,15 @@ regular expression assertion (see L). 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(), otherwise false. +Current state of the interpreter. + + $^S State + --------- ------------------- + undef Parsing module/eval + true (1) Executing an eval + false (0) Otherwise + +The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers. =item $BASETIME @@ -1083,8 +1152,23 @@ and B<-C> filetests are based on this value. =item ${^TAINT} -Reflects if taint mode is on or off (i.e. if the program was run with -B<-T> or not). True for on, false for off. +Reflects if taint mode is on or off. 1 for on (the program was run with +B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with +B<-t> or B<-TU>). This variable is read-only. + +=item ${^UNICODE} + +Reflects certain Unicode settings of Perl. See L +documentation for the C<-C> switch for more information about +the possible values. This variable is set during Perl startup +and is thereafter read-only. + +=item ${^UTF8LOCALE} + +This variable indicates whether an UTF-8 locale was detected by perl at +startup. This information is used by perl when it's in +adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line +switch); see L for more info on this. =item $PERL_VERSION @@ -1125,27 +1209,56 @@ related to the B<-w> switch.) See also L. 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 -The name that the Perl binary itself was executed as, from C's C. -This may not be a full pathname, nor even necessarily in your path. +The name used to execute the current copy of Perl, from C's +C. + +Depending on the host operating system, the value of $^X may be +a relative or absolute pathname of the perl program file, or may +be the string used to invoke perl but not the pathname of the +perl program file. Also, most operating systems permit invoking +programs that are not in the PATH environment variable, so there +is no guarantee that the value of $^X is in PATH. For VMS, the +value may or may not include a version number. + +You usually can use the value of $^X to re-invoke an independent +copy of the same perl that is currently running, e.g., + + @first_run = `$^X -le "print int rand 100 for 1..100"`; + +But recall that not all operating systems support forking or +capturing of the output of commands, so this complex statement +may not be portable. + +It is not safe to use the value of $^X as a path name of a file, +as some operating systems that have a mandatory suffix on +executable files do not require use of the suffix when invoking +a command. To convert the value of $^X to a path name, use the +following statements: + + # Build up a set of file names (not command names). + use Config; + $this_perl = $^X; + if ($^O ne 'VMS') + {$this_perl .= $Config{_exe} + unless $this_perl =~ m/$Config{_exe}$/i;} + +Because many operating systems permit anyone with read access to +the Perl program file to make a copy of it, patch the copy, and +then execute the copy, the security-conscious Perl programmer +should take care to invoke the installed copy of perl, not the +copy referenced by $^X. The following statements accomplish +this goal, and produce a pathname that can be invoked as a +command or referenced as a file. + + use Config; + $secure_perl_path = $Config{perlpath}; + if ($^O ne 'VMS') + {$secure_perl_path .= $Config{_exe} + unless $secure_perl_path =~ m/$Config{_exe}$/i;} =item ARGV @@ -1169,6 +1282,13 @@ the script. C<$#ARGV> is generally the number of arguments minus one, because C<$ARGV[0]> is the first argument, I the program's command name itself. See C<$0> for the command name. +=item ARGVOUT + +The special filehandle that points to the currently open output file +when doing edit-in-place processing with B<-i>. Useful when you have +to do a lot of inserting and don't want to keep modifying $_. See +L for the B<-i> switch. + =item @F The array @F contains the fields of each line read in when autosplit @@ -1257,20 +1377,11 @@ 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"; +installed using it. This means you get reliable signal handling. -See L. +The default delivery policy of signals changed in Perl 5.8.0 from +immediate (also known as "unsafe") to deferred, also known as +"safe signals". See L for more information. Certain internal hooks can be also set using the %SIG hash. The routine indicated by C<$SIG{__WARN__}> is called when a warning message is @@ -1345,7 +1456,7 @@ C<$@> 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 . In these cases the value of $@ is the compile error, or the argument to C -(which will interpolate C<$!> and C<$?>!). (See also L, +(which will interpolate C<$!> and C<$?>). (See also L, though.) When the eval() expression above is executed, open(), C<< >>, @@ -1404,18 +1515,19 @@ used safely in programs. C<$^_> itself, however, I reserved. Perl identifiers that begin with digits, control characters, or punctuation characters are exempt from the effects of the C -declaration and are always forced to be in package C
. A few -other names are also exempt: +declaration and are always forced to be in package C
; they are +also exempt from C errors. A few other names are also +exempt in these ways: ENV STDIN INC STDOUT ARGV STDERR - ARGVOUT + ARGVOUT _ SIG In particular, the new special C<${^_XYZ}> variables are always taken to be in package C
, regardless of any C declarations -presently in scope. +presently in scope. =head1 BUGS @@ -1425,7 +1537,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.cpan.org/modules/by-module/Devel/) +( http://www.cpan.org/modules/by-module/Devel/ ) for more information. Having to even think about the C<$^S> variable in your exception