X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=f0447cd58fe04cf4bc4e2c44d714c1fc658b1d67;hb=f86702ccfcc3646d7aa30b09ce4f4413be9f99d1;hp=bdf24f6c896fcf026deeab37afa7a7f99ed01e46;hpb=a0d0e21ea6ea90a22318550944fe6cb09ae10cda;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index bdf24f6..f0447cd 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -7,7 +7,7 @@ perlvar - Perl predefined variables
 =head2 Predefined Names
 
 The following names have special meaning to Perl.  Most of the
-punctuational names have reasonable mnemonics, or analogues in one of
+punctuation names have reasonable mnemonics, or analogues in one of
 the shells.  Nevertheless, if you wish to use the long variable names,
 you just need to say
 
@@ -38,9 +38,9 @@ new value for the FileHandle attribute in question.  If not supplied,
 most of the methods do nothing to the current value, except for
 autoflush(), which will assume a 1 for you, just to be different.
 
-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.  If you attempt to do so, you'll raise a run-time exception.
+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.
 
 =over 8
 
@@ -51,7 +51,7 @@ a reference.  If you attempt to do so, you'll raise a run-time exception.
 The default input and pattern-searching space.  The following pairs are
 equivalent:
 
-    while (<>) {...}	# only equivalent in while!
+    while (<>) {...}	# equivalent in only while!
     while ($_ = <>) {...}
 
     /^Subject:/
@@ -63,11 +63,52 @@ equivalent:
     chop
     chop($_)
 
+Here are the places where Perl will assume $_ even if you 
+don't use it:
+
+=over 3
+
+=item *
+
+Various unary functions, including functions like ord() and int(), as well
+as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to
+STDIN.
+
+=item *
+
+Various list functions like print() and unlink().
+
+=item *
+
+The pattern matching operations C<m//>, C<s///>, and C<tr///> when used
+without an C<=~> operator.
+
+=item * 
+
+The default iterator variable in a C<foreach> loop if no other
+variable is supplied.
+
+=item * 
+
+The implicit iterator variable in the grep() and map() functions.
+
+=item * 
+
+The default place to put an input record when a C<E<lt>FHE<gt>>
+operation's result is tested by itself as the sole criterion of a C<while>
+test.  Note that outside of a C<while> test, this will not happen.
+
+=back
+
 (Mnemonic: underline is understood in certain operations.)
 
-=item $<I<digit>>
+=back
+
+=over 8
+
+=item $E<lt>I<digit>E<gt>
 
-Contains the subpattern from the corresponding set of parentheses in
+Contains the sub-pattern 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.)
 These variables are all read-only.
@@ -86,7 +127,7 @@ BLOCK).  (Mnemonic: like & in some editors.)  This variable is read-only.
 
 The string preceding whatever was matched by the last successful
 pattern match (not counting any matches hidden within a BLOCK or eval
-enclosed by the current BLOCK).  (Mnemonic: ` often precedes a quoted
+enclosed by the current BLOCK).  (Mnemonic: C<`> often precedes a quoted
 string.)  This variable is read-only.
 
 =item $POSTMATCH
@@ -95,7 +136,7 @@ string.)  This variable is read-only.
 
 The string following whatever was matched by the last successful
 pattern match (not counting any matches hidden within a BLOCK or eval()
-enclosed by the current BLOCK).  (Mnemonic: ' often follows a quoted
+enclosed by the current BLOCK).  (Mnemonic: C<'> often follows a quoted
 string.)  Example:
 
     $_ = 'abcdefghi';
@@ -121,15 +162,15 @@ This variable is read-only.
 
 =item $*
 
-Set to 1 to do multiline matching within a string, 0 to tell Perl
+Set to 1 to do multi-line matching within a string, 0 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.  Default
 is 0.  (Mnemonic: * matches multiple things.)  Note that this variable
-only influences the interpretation of "C<^>" and "C<$>".  A literal newline can
+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 Perl 5.
+Use of "C<$*>" is deprecated in modern perls.
 
 =item input_line_number HANDLE EXPR
 
@@ -139,12 +180,14 @@ Use of "C<$*>" is deprecated in Perl 5.
 
 =item $.
 
-The current input line number of the last filehandle that was read.
-This variable should be considered read-only.  
-Remember that only an explicit close on the filehandle
-resets the line number.  Since "C<E<lt>E<gt>>" never does an explicit close, line
-numbers increase across ARGV files (but see examples under eof()).
-(Mnemonic: many programs use "." to mean the current line number.)
+The current input line number for the last file handle from
+which you read (or performed a C<seek> or C<tell> on).  An
+explicit close on a filehandle resets the line number.  Because
+"C<E<lt>E<gt>>" never does an explicit close, line numbers increase
+across ARGV files (but see examples under eof()).  Localizing C<$.> has
+the effect of also localizing Perl's notion of "the last read
+filehandle".  (Mnemonic: many programs use "." to mean the current line
+number.)
 
 =item input_record_separator HANDLE EXPR
 
@@ -155,14 +198,15 @@ numbers increase across ARGV files (but see examples under eof()).
 =item $/
 
 The input record separator, newline by default.  Works like B<awk>'s RS
-variable, including treating blank lines as delimiters if set to the
-null string.  You may set it to a multicharacter string to match a
+variable, including treating empty lines as delimiters if set to the
+null string.  (Note:  An empty line cannot contain any spaces or
+tabs.) You may set it to a multicharacter string to match a
 multi-character delimiter.  Note that setting it to C<"\n\n"> means
 something slightly different than setting it to C<"">, if the file
-contains consecutive blank lines.  Setting it to C<""> will treat two or
-more consecutive blank lines as a single blank line.  Setting it to
-C<"\n\n"> will blindly assume that the next input character belongs to the
-next paragraph, even if it's a newline.  (Mnemonic: / is used to
+contains consecutive empty lines.  Setting it to C<""> will treat two
+or more consecutive empty lines as a single empty line.  Setting it to
+C<"\n\n"> will blindly assume that the next input character belongs to
+the next paragraph, even if it's a newline.  (Mnemonic: / is used to
 delimit line boundaries when quoting poetry.)
 
     undef $/;
@@ -176,12 +220,15 @@ delimit line boundaries when quoting poetry.)
 =item $|
 
 If set to nonzero, forces a flush after every write or print on the
-currently selected output channel.  Default is 0.  Note that STDOUT
-will typically be line buffered if output is to the terminal and block
-buffered otherwise.  Setting this variable is useful primarily when you
-are outputting to a pipe, such as when you are running a Perl script
-under rsh and want to see the output as it's happening.  (Mnemonic:
-when you want your pipes to be piping hot.)
+currently selected output channel.  Default is 0 (regardless of whether
+the channel is actually buffered by the system or not; C<$|> tells you
+only whether you've asked Perl explicitly to flush after each write). 
+Note that STDOUT will typically be line buffered if output is to the
+terminal and block buffered otherwise.  Setting this variable is useful
+primarily when you are outputting to a pipe, such as when you are running
+a Perl script under rsh and want to see the output as it's happening.  This
+has no effect on input buffering.
+(Mnemonic: when you want your pipes to be piping hot.)
 
 =item output_field_separator HANDLE EXPR
 
@@ -192,8 +239,8 @@ when you want your pipes to be piping hot.)
 =item $,
 
 The output field separator for the print operator.  Ordinarily the
-print operator simply prints out the comma separated fields you
-specify.  In order to get behavior more like B<awk>, set this variable
+print operator simply prints out the comma-separated fields you
+specify.  To get behavior more like B<awk>, set this variable
 as you would set B<awk>'s OFS variable to specify what is printed
 between fields.  (Mnemonic: what is printed when there is a , in your
 print statement.)
@@ -207,12 +254,12 @@ print statement.)
 =item $\
 
 The output record separator for the print operator.  Ordinarily the
-print operator simply prints out the comma separated fields you
-specify, with no trailing newline or record separator assumed.  In
-order to get behavior more like B<awk>, set this variable as you would
+print operator simply prints out the comma-separated fields you
+specify, with no trailing newline or record separator assumed.
+To get behavior more like B<awk>, set this variable as you would
 set B<awk>'s ORS variable to specify what is printed at the end of the
 print.  (Mnemonic: you set "C<$\>" instead of adding \n at the end of the
-print.  Also, it's just like /, but it's what you get "back" from
+print.  Also, it's just like C<$/>, but it's what you get "back" from
 Perl.)
 
 =item $LIST_SEPARATOR
@@ -252,7 +299,7 @@ keys contain binary data there might not be any safe value for "C<$;>".
 semi-semicolon.  Yeah, I know, it's pretty lame, but "C<$,>" is already
 taken for something more important.)
 
-Consider using "real" multi-dimensional arrays in Perl 5.
+Consider using "real" multi-dimensional arrays.
 
 =item $OFMT
 
@@ -261,11 +308,12 @@ Consider using "real" multi-dimensional arrays in Perl 5.
 The output format for printed numbers.  This variable is a half-hearted
 attempt to emulate B<awk>'s OFMT variable.  There are times, however,
 when B<awk> and Perl have differing notions of what is in fact
-numeric.  Also, the initial value is %.20g rather than %.6g, so you
-need to set "C<$#>" explicitly to get B<awk>'s value.  (Mnemonic: # is the
-number sign.)
+numeric.  The initial value is %.I<n>g, where I<n> is the value
+of the macro DBL_DIG from your system's F<float.h>.  This is different from
+B<awk>'s default OFMT setting of %.6g, so you need to set "C<$#>"
+explicitly to get B<awk>'s value.  (Mnemonic: # is the number sign.)
 
-Use of "C<$#>" is deprecated in Perl 5.
+Use of "C<$#>" is deprecated.
 
 =item format_page_number HANDLE EXPR
 
@@ -331,7 +379,7 @@ poetry is a part of a line.)
 
 =item $^L
 
-What formats output to perform a formfeed.  Default is \f.
+What formats output to perform a form feed.  Default is \f.
 
 =item $ACCUMULATOR
 
@@ -348,12 +396,26 @@ L<perlfunc/formline()>.
 
 =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, so the exit value of the subprocess is actually
-(C<$? E<gt>E<gt> 8>).  Thus on many systems, C<$? & 255> gives which signal,
-if any, the process died from, and whether there was a core dump.
-(Mnemonic: similar to B<sh> and B<ksh>.)
+The status returned by the last pipe close, back-tick (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 -- see L<$^S>).
+Thus, the exit value of the subprocess is actually (C<$? E<gt>E<gt> 8>),
+and C<$? & 255> gives which signal, if any, the process died from, and
+whether there was a core dump.  (Mnemonic: similar to B<sh> and B<ksh>.)
+
+Inside an C<END> subroutine C<$?> contains the value that is going to be
+given to C<exit()>.  You can modify C<$?> in an C<END> subroutine to
+change the exit status of the script.
+
+=item $SYSTEM_CHILD_STATUS
+
+=item $^S
+
+The status returned by the last pipe close, back-tick (C<``>) command, or
+system() operator, in the native system format.  On UNIX and UNIX-like
+systems, C<$^S> is a synonym for C<$?>.  Elsewhere, C<$^S> can be used to
+determine aspects of child status that are system-specific.  Check C<$^O>
+before using this variable.  (Mnemonic: System-Specific Subprocess Status.)
 
 =item $OS_ERROR
 
@@ -366,10 +428,25 @@ 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
 specific error return indicating a system error.)  If used in a string
 context, yields the corresponding system error string.  You can assign
-to "C<$!>" in order to set I<errno> if, for instance, you want "C<$!>" to return the
+to "C<$!>" to set I<errno> if, for instance, you want "C<$!>" to return the
 string for error I<n>, or you want to set the exit value for the die()
 operator.  (Mnemonic: What just went bang?)
 
+=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, 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.)
+
+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.
+
 =item $EVAL_ERROR
 
 =item $@
@@ -379,6 +456,10 @@ last eval() parsed and executed correctly (although the operations you
 invoked may have failed in the normal fashion).  (Mnemonic: Where was
 the syntax error "at"?)
 
+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__}>
+below.
+
 =item $PROCESS_ID
 
 =item $PID
@@ -409,7 +490,7 @@ The effective uid of this process.  Example:
     ($<,$>) = ($>,$<);	# swap real and effective uid
 
 (Mnemonic: it's the uid you went I<TO>, if you're running setuid.)  Note:
-"C<$E<lt>>" and "C<$E<gt>>" can only be swapped on machines supporting setreuid().
+"C<$E<lt>>" and "C<$E<gt>>" can be swapped on only machines supporting setreuid().
 
 =item $REAL_GROUP_ID
 
@@ -438,9 +519,11 @@ which may be the same as the first number.  (Mnemonic: parentheses are
 used to I<GROUP> things.  The effective gid is the group that's I<RIGHT> for
 you, if you're running setgid.)
 
-Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can only be set on machines
-that support the corresponding I<set[re][ug]id()> routine.  "C<$(>" and "C<$)>" 
-can only be swapped on machines supporting setregid().
+Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can be set only on
+machines that support the corresponding I<set[re][ug]id()> 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.
 
 =item $PROGRAM_NAME
 
@@ -468,7 +551,9 @@ discouraged.
 
 =item $]
 
-The string printed out when you say C<perl -v>.  It can be used to
+The string printed out when you say C<perl -v>.
+(This is currently I<BROKEN>).
+It can be used to
 determine at the beginning of a script whether the perl interpreter
 executing the script is in the right range of versions.  If used in a
 numeric context, returns the version + patchlevel / 1000.  Example:
@@ -504,6 +589,11 @@ closed before the open() is attempted.)  Note that the close-on-exec
 status of a file descriptor will be decided according to the value of
 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<use strict>.  See the
+documentation of C<strict> for more details.
+
 =item $INPLACE_EDIT
 
 =item $^I
@@ -511,12 +601,20 @@ C<$^F> at the time of the open, not the time of the exec.
 The current value of the inplace-edit extension.  Use C<undef> to disable
 inplace editing.  (Mnemonic: value of B<-i> switch.)
 
+=item $OSNAME
+
+=item $^O
+
+The name of the operating system under which this copy of Perl was
+built, as determined during the configuration process.  The value
+is identical to C<$Config{'osname'}>.
+
 =item $PERLDB
 
 =item $^P
 
 The internal flag that the debugger clears so that it doesn't debug
-itself.  You could conceivable disable debugging yourself by clearing
+itself.  You could conceivably disable debugging yourself by clearing
 it.
 
 =item $BASETIME
@@ -524,7 +622,7 @@ it.
 =item $^T
 
 The time at which the script began running, in seconds since the
-epoch (beginning of 1970).  The values returned by the B<-M>, B<-A> 
+epoch (beginning of 1970).  The values returned by the B<-M>, B<-A>,
 and B<-C> filetests are
 based on this value.
 
@@ -532,8 +630,8 @@ based on this value.
 
 =item $^W
 
-The current value of the warning switch, either TRUE or FALSE.  (Mnemonic: related to the
-B<-w> switch.)
+The current value of the warning switch, either TRUE or FALSE.
+(Mnemonic: related to the B<-w> switch.)
 
 =item $EXECUTABLE_NAME
 
@@ -543,13 +641,13 @@ The name that the Perl binary itself was executed as, from C's C<argv[0]>.
 
 =item $ARGV
 
-contains the name of the current file when reading from <>.
+contains the name of the current file when reading from E<lt>E<gt>.
 
 =item @ARGV
 
 The array @ARGV contains the command line arguments intended for the
 script.  Note that C<$#ARGV> is the generally number of arguments minus
-one, since C<$ARGV[0]> is the first argument, I<NOT> the command name.  See
+one, because C<$ARGV[0]> is the first argument, I<NOT> the command name.  See
 "C<$0>" for the command name.
 
 =item @INC
@@ -557,8 +655,13 @@ one, since C<$ARGV[0]> is the first argument, I<NOT> the command name.  See
 The array @INC contains the list of places to look for Perl scripts to
 be evaluated by the C<do EXPR>, C<require>, or C<use> constructs.  It
 initially consists of the arguments to any B<-I> command line switches,
-followed by the default Perl library, probably "/usr/local/lib/perl",
-followed by ".", to represent the current directory.
+followed by the default Perl library, probably F</usr/local/lib/perl>,
+followed by ".", to represent the current directory.  If you need to
+modify this at runtime, you should use the C<use lib> pragma
+to get the machine-dependent library properly loaded also:
+
+    use lib '/mypath/libdir/';
+    use SomeMod;
 
 =item %INC
 
@@ -591,7 +694,7 @@ signals.  Example:
     $SIG{'INT'} = 'DEFAULT';	# restore default action
     $SIG{'QUIT'} = 'IGNORE';	# ignore SIGQUIT
 
-The %SIG array only contains values for the signals actually set within
+The %SIG array contains values for only the signals actually set within
 the Perl script.  Here are some other examples:
 
     $SIG{PIPE} = Plumber;       # SCARY!!
@@ -602,7 +705,41 @@ the Perl script.  Here are some other examples:
 The one marked scary is problematic because it's a bareword, which means
 sometimes it's a string representing the function, and sometimes it's 
 going to call the subroutine call right then and there!  Best to be sure
-and quote it or take a reference to it.  *Plumber works too.  See <perlsubs>.
+and quote it or take a reference to it.  *Plumber works too.  See L<perlsub>.
+
+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 it 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";
+
+See L<POSIX>.
+
+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
+about to be printed.  The warning message is passed as the first
+argument.  The presence of a __WARN__ hook causes the ordinary printing
+of warnings to STDERR to be suppressed.  You can use this to save warnings
+in a variable, or turn warnings into fatal errors, like this:
+
+    local $SIG{__WARN__} = sub { die $_[0] };
+    eval $proggie;
+
+The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception
+is about to be thrown.  The error message is passed as the first
+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<goto>, 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<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval>.
 
 =back
-