X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=0248fe07192a52de4d495923623b644611b0a4aa;hb=84287afe68eecc4342d7e27aac5d9df9d2412490;hp=e5d0091c85c2e49e2250ab85ba369ba4c94653fd;hpb=4633a7c4bad06b471d9310620b7fe8ddd158cccd;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index e5d0091..0248fe0 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -63,8 +63,49 @@ 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.)
 
+=back
+
+=over 8
+
 =item $<I<digit>>
 
 Contains the subpattern from the corresponding set of parentheses in
@@ -139,8 +180,9 @@ Use of "C<$*>" is deprecated in Perl 5.
 
 =item $.
 
-The current input line number of the last filehandle that was read.  An
-explicit close on the filehandle resets the line number.  Since
+The current input line number for the last file handle from
+which you read (or performed a C<seek> or <tell> on).  An
+explicit close on a 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()).  Localizing C<$.> has
 the effect of also localizing Perl's notion of "the last read
@@ -177,12 +219,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<$|> only tells
+you whether you've asked Perl to explicitly 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
 
@@ -262,9 +307,10 @@ 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.
 
@@ -371,6 +417,18 @@ to "C<$!>" in order to set I<errno> if, for instance, you want "C<$!>" to return
 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.)
+At the moment, this differs from C<$!> only under VMS, where it
+provides the VMS status value from the last system error.  The
+caveats mentioned in the description of C<$!> apply here, too.
+(Mnemonic: Extra error explanation.)
+
+
 =item $EVAL_ERROR
 
 =item $@
@@ -444,7 +502,8 @@ 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().
+can only be swapped on machines supporting setregid().   Because Perl doesn't
+currently use initgroups(), you can't set your group vector to multiple groups.
 
 =item $PROGRAM_NAME
 
@@ -472,7 +531,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:
@@ -508,6 +569,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
@@ -515,12 +581,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
@@ -561,9 +635,14 @@ 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 in order
+to also get the machine-dependent library properly loaded:
+
+    use lib '/mypath/libdir/';
+    use SomeMod;
+  
 =item %INC
 
 The hash %INC contains entries for each filename that has
@@ -622,7 +701,8 @@ The routine indicated by $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 goto, a loop exit, or a die.
+unless the hook routine itself exits via a C<goto>, a loop exit, or a die().
+The __DIE__ handler is explicitly disabled during the call, so that you
+can die from a __DIE__ handler.  Similarly for __WARN__.
 
 =back
-