[inseparable changes from patch from perl5.003_23 to perl5.003_24]perl-5.003_24

 CORE LANGUAGE CHANGES

Subject: glob defaults to $_
Date: Mon, 27 Jan 1997 03:09:13 -0500
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: op.c opcode.pl pod/perlfunc.pod t/op/glob.t

    private-msgid: <199701270809.DAA00934@aatma.engin.umich.edu>

Subject: Re: an overloading bug 
Date: Sun, 26 Jan 1997 19:07:45 -0500
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: pod/perldiag.pod pod/perlfunc.pod pp_ctl.c

    private-msgid: <199701270007.TAA26525@aatma.engin.umich.edu>

 CORE PORTABILITY

Subject: Win32 port
From: Gary Ng <71564.1743@compuserve.com>
Files: MANIFEST win32/*

Subject: Amiga files
Date: Sun, 26 Jan 1997 17:42:15 +0100
From: Norbert Pueschel <pueschel@imsdd.meb.uni-bonn.de>
Files: MANIFEST README.amiga hints/amigaos.sh

    private-msgid: <77724712@Armageddon.meb.uni-bonn.de>

 DOCUMENTATION

Subject: perldelta Fcntl enhancement
Date: Sat, 25 Jan 1997 17:05:34 +0200 (EET)
From: Jarkko Hietaniemi <jhi@cc.hut.fi>
Files: pod/perldelta.pod

    private-msgid: <199701251505.RAA22159@alpha.hut.fi>

Subject: Updates to perldelta re: Fcntl, DB_File, Net::Ping
From: Paul Marquess <pmarquess@bfsec.bt.co.uk>
Files: pod/perldelta.pod

Subject: Document restrictions on gv_fetchmethod() and perl_call_sv()
From: Chip Salzenberg <chip@atlantic.net>
Files: pod/perldelta.pod pod/perlguts.pod

Subject: perldiag.pod: No comma allowed after %s
Date: Sat, 25 Jan 1997 17:41:53 +0200 (EET)
From: Jarkko Hietaniemi <Jarkko.Hietaniemi@cc.hut.fi>
Files: pod/perldiag.pod

    private-msgid: <199701251541.RAA04120@alpha.hut.fi>

Subject: perlfunc.pod: localtime
Date: Sat, 25 Jan 1997 18:29:37 +0200 (EET)
From: Jarkko Hietaniemi <jhi@cc.hut.fi>
Files: pod/perlfunc.pod

    private-msgid: <199701251629.SAA08114@alpha.hut.fi>

Subject: perlfunc diff: gmtime
Date: Tue, 28 Jan 1997 14:52:08 +0000
From: Peter Haworth <pmh@edison.ioppublishing.com>
Files: pod/perlfunc.pod

    private-msgid: <32EE1298.7B90@edison.ioppublishing.com>

Subject: Updates to guts
Date: Sun, 26 Jan 1997 19:34:18 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: pod/perlguts.pod

    private-msgid: <199701270034.TAA13177@monk.mps.ohio-state.edu>

 TESTS

Subject: New test op/closure.t
From: Tom Phoenix <rootbeer@teleport.com>
Files: MANIFEST t/op/closure.t

5 files changed, 382 insertions, 93 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index b33f1ff81f..04e9a45ab8 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -34,21 +34,6 @@ application of opcode masks.  The revised Safe module has a new API
 and is implemented using the new Opcode module.  Please read the new
 Opcode and Safe documentation.
 
-=head2 Extended Fcntl Module
-
-The Fcntl module now supports these new constants
-
-	F_GETOWN F_SETOWN
-	O_ASYNC O_DEFER O_DSYNC O_RSYNC O_SYNC
-	O_EXLOCK O_SHLOCK
-
-provided that your operating system supports these constants. The
-constants are for use with the Perl sysopen() and fcntl(). These
-constants are also visible for the basic database modules like the
-SDBM_File. For the exact meaning of these contants and other Fcntl
-constants please refer to the fcntl() documentation of your operating
-system. Unsupported constants will cause run-time errors.
-
 =head2 Internal Change: FileHandle Deprecated
 
 Filehandles are now stored internally as type IO::Handle.
@@ -243,7 +228,7 @@ before, and is fine now:
 The C<UNIVERSAL> package automatically contains the following methods that
 are inherited by all other classes:
 
-=over 4
+=over
 
 =item isa(CLASS)
 
@@ -429,6 +414,21 @@ provided that your operating system happens to support them:
     O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC 
     O_EXLOCK O_SHLOCK
 
+These constants are intended for use with the Perl operators sysopen()
+and fcntl() and the basic database modules like SDBM_File.  For the
+exact meaning of these and other Fcntl constants please refer to your
+operating system's documentation for fcntl() and open().
+
+In addition, the Fcntl module now provides these constants for use
+with the Perl operator flock():
+
+	LOCK_SH LOCK_EX LOCK_NB LOCK_UN
+
+These constants are defined in all environments (because where there is
+no flock() system call, Perl emulates it).  However, for historical
+reasons, these constants are not exported unless they are explicitly
+requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
+
 =head2 Module Information Summary
 
 Brand new modules, arranged by topic rather than strictly
@@ -499,6 +499,52 @@ And these functions are now exported:
     sinh cosh tanh cotanh asinh acosh atanh acotanh
     cplx cplxe
 
+=head2 DB_File
+
+There have been quite a few changes made to DB_File. Here are a few of
+the highlights:
+
+=over
+
+=item *
+
+Fixed a handful of bugs.
+
+=item *
+
+By public demand, added support for the standard hash function exists().
+
+=item *
+
+Made it compatible with Berkeley DB 1.86.
+
+=item *
+
+Made negative subscripts work with RECNO interface.
+
+=item *
+
+Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
+mode from 0640 to 0666.
+
+=item *
+
+Made DB_File automatically import the open() constants (O_RDWR,
+O_CREAT etc.) from Fcntl, if available.
+
+=item *
+
+Updated documentation.
+
+=back
+
+Refer to the HISTORY section in DB_File.pm for a complete list of
+changes. Everything after DB_File 1.01 has been added since 5.003.
+
+=head2 Net::Ping
+
+Major rewrite - support added for both udp echo and real icmp pings.
+
 =head2 Overridden Built-ins
 
 Many of the Perl built-ins returning lists now have
@@ -524,6 +570,8 @@ For example, you can now say
 
 =head2 xsubpp
 
+=over
+
 =item C<void> XSUBs now default to returning nothing
 
 Due to a documentation/implementation bug in previous versions of
@@ -543,12 +591,34 @@ It does so by examining the text of the XSUB: if I<xsubpp> finds
 what looks like an assignment to C<ST(0)>, it assumes that the
 XSUB's return type is really C<SV *>.
 
+=back
+
+=head1 C Language API Changes
+
+=over
+
+=item C<gv_fetchmethod> and C<perl_call_sv>
+
+The C<gv_fetchmethod> function finds a method for an object, just like
+in Perl 5.003.  The GV it returns may be a method cache entry.
+However, in Perl 5.004, method cache entries are not visible to users;
+therefore, they can no longer be passed directly to C<perl_call_sv>.
+Instead, you should use the C<GvCV> macro on the GV to extract its CV,
+and pass the CV to C<perl_call_sv>.
+
+The most likely symptom of passing the result of C<gv_fetchmethod> to
+C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
+error on the I<second> call to a given method (since there is no cache
+on the first call).
+
+=back
+
 =head1 Documentation Changes
 
 Many of the base and library pods were updated.  These
 new pods are included in section 1:
 
-=over 4
+=over
 
 =item L<perldelta>
 
@@ -592,7 +662,7 @@ increasing order of desperation):
    (X) A very fatal error (non-trappable).
    (A) An alien error message (not generated by Perl).
 
-=over 4
+=over
 
 =item "my" variable %s masks earlier declaration in same scope
 
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 0f204a868a..018ebb757a 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -342,30 +342,37 @@ the return value of your socket() call?  See L<perlfunc/bind>.
 (F) A subroutine invoked from an external package via perl_call_sv()
 exited by calling exit.
 
+=item Can't "goto" outside a block
+
+(F) A "goto" statement was executed to jump out of what might look
+like a block, except that it isn't a proper block.  This usually
+occurs if you tried to jump out of a sort() block or subroutine, which
+is a no-no.  See L<perlfunc/goto>.
+
 =item Can't "last" outside a block
 
 (F) A "last" statement was executed to break out of the current block,
 except that there's this itty bitty problem called there isn't a
 current block.  Note that an "if" or "else" block doesn't count as a
-"loopish" block.  You can usually double the curlies to get the same
-effect though, because the inner curlies will be considered a block
-that loops once.  See L<perlfunc/last>.
+"loopish" block, as doesn't a block given to sort().  You can usually double
+the curlies to get the same effect though, because the inner curlies
+will be considered a block that loops once.  See L<perlfunc/last>.
 
 =item Can't "next" outside a block
 
 (F) A "next" statement was executed to reiterate the current block, but
 there isn't a current block.  Note that an "if" or "else" block doesn't
-count as a "loopish" block.  You can usually double the curlies to get
-the same effect though, because the inner curlies will be considered a block
-that loops once.  See L<perlfunc/last>.
+count as a "loopish" block, as doesn't a block given to sort().  You can
+usually double the curlies to get the same effect though, because the inner
+curlies will be considered a block that loops once.  See L<perlfunc/last>.
 
 =item Can't "redo" outside a block
 
 (F) A "redo" statement was executed to restart the current block, but
 there isn't a current block.  Note that an "if" or "else" block doesn't
-count as a "loopish" block.  You can usually double the curlies to get
-the same effect though, because the inner curlies will be considered a block
-that loops once.  See L<perlfunc/last>.
+count as a "loopish" block, as doesn't a block given to sort().  You can
+usually double the curlies to get the same effect though, because the inner
+curlies will be considered a block that loops once.  See L<perlfunc/last>.
 
 =item Can't bless non-reference value
 
@@ -922,6 +929,12 @@ case the conversion routines don't handle.  Drat.
 (W) You are exiting an eval by unconventional means, such as
 a goto, or a loop control statement.
 
+=item Exiting pseudo-block via %s
+
+(W) You are exiting a rather special block construct (like a sort block or
+subroutine) by unconventional means, such as a goto, or a loop control
+statement.  See L<perlfunc/sort>.
+
 =item Exiting subroutine via %s
 
 (W) You are exiting a subroutine by unconventional means, such as
@@ -1304,6 +1317,18 @@ See L<perlsec>.
 allowed to have a comma between that and the following arguments.
 Otherwise it'd be just another one of the arguments.
 
+One possible cause for this is that you expected to have imported a
+constant to your name space with B<use> or B<import> while no such
+importing took place, it may for example be that your operating system
+does not support that particular constant. Hopefully you did use an
+explicit import list for the constants you expect to see, please see
+L<perlfunc/use> and L<perlfunc/import>. While an explicit import list
+would probably have caught this error earlier it naturally does not
+remedy the fact that your operating system still does not support that
+constant. Maybe you have a typo in the constants of the symbol import
+list of B<use> or B<import> or in the constant name at the line where
+this error was triggered?
+
 =item No command into which to pipe on command line
 
 (F) An error peculiar to VMS.  Perl handles its own command line redirection,
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 99231b9ffd..e532ed2aa3 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1408,9 +1408,12 @@ Returns the socket option requested, or undefined if there is an error.
 
 =item glob EXPR
 
+=item glob
+
 Returns the value of EXPR with filename expansions such as a shell
 would do.  This is the internal function implementing the E<lt>*.*E<gt>
 operator, except it's easier to use.
+If EXPR is omitted, $_ is used.
 
 =item gmtime EXPR
 
@@ -1426,6 +1429,13 @@ All array elements are numeric, and come straight out of a struct tm.
 In particular this means that $mon has the range 0..11 and $wday has
 the range 0..6.  If EXPR is omitted, does C<gmtime(time())>.
 
+In a scalar context, prints out the ctime(3) value:
+
+    $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"
+
+Also see the F<timegm.pl> library, and the strftime(3) function available
+via the POSIX module.
+
 =item goto LABEL
 
 =item goto EXPR
@@ -1435,8 +1445,9 @@ the range 0..6.  If EXPR is omitted, does C<gmtime(time())>.
 The goto-LABEL form finds the statement labeled with LABEL and resumes
 execution there.  It may not be used to go into any construct that
 requires initialization, such as a subroutine or a foreach loop.  It
-also can't be used to go into a construct that is optimized away.  It
-can be used to go almost anywhere else within the dynamic scope,
+also can't be used to go into a construct that is optimized away,
+or to get out of a block or subroutine given to sort().
+It can be used to go almost anywhere else within the dynamic scope,
 including out of subroutines, but it's usually better to use some other
 construct such as last or die.  The author of Perl has never felt the
 need to use this form of goto (in Perl, that is--C is another matter).
@@ -1692,13 +1703,14 @@ follows:
 
 All array elements are numeric, and come straight out of a struct tm.
 In particular this means that $mon has the range 0..11 and $wday has
-the range 0..6.  If EXPR is omitted, does localtime(time).
+the range 0..6 and $year is year-1900, that is, $year is 123 in year
+2023.  If EXPR is omitted, uses the current time ("localtime(time)").
 
-In a scalar context, prints out the ctime(3) value:
+In a scalar context, returns the ctime(3) value:
 
     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
-Also see the F<timelocal.pl> library, and the strftime(3) function available
+Also see the Time::Local module, and the strftime(3) function available
 via the POSIX module.
 
 =item log EXPR
@@ -2787,6 +2799,9 @@ the subroutine not via @_ but as the package global variables $a and
 $b (see example below).  They are passed by reference, so don't
 modify $a and $b.  And don't try to declare them as lexicals either.
 
+You also cannot exit out of the sort block or subroutine using any of the
+loop control operators described in L<perlsyn> or with goto().
+
 When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
 current collation locale.  See L<perllocale>.
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index a7b11c6e87..3d16f94f25 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -8,6 +8,8 @@ This document attempts to describe some of the internal functions of the
 Perl executable.  It is far from complete and probably contains many errors.
 Please refer any questions or comments to the author below.
 
+=head1 Variables
+
 =head2 Datatypes
 
 Perl has three typedefs that handle Perl's three main data types:
@@ -557,7 +559,47 @@ as any other SV.
 
 For more information on references and blessings, consult L<perlref>.
 
-=head2 Magic
+=head2 Double-Typed SV's
+
+Scalar variables normally contain only one type of value, an integer,
+double, pointer, or reference.  Perl will automatically convert the
+actual scalar data from the stored type into the requested type.
+
+Some scalar variables contain more than one type of scalar data.  For
+example, the variable C<$!> contains either the numeric value of C<errno>
+or its string equivalent from either C<strerror> or C<sys_errlist[]>.
+
+To force multiple data values into an SV, you must do two things: use the
+C<sv_set*v> routines to add the additional scalar type, then set a flag
+so that Perl will believe it contains more than one type of data.  The
+four macros to set the flags are:
+
+	SvIOK_on
+	SvNOK_on
+	SvPOK_on
+	SvROK_on
+
+The particular macro you must use depends on which C<sv_set*v> routine
+you called first.  This is because every C<sv_set*v> routine turns on
+only the bit for the particular type of data being set, and turns off
+all the rest.
+
+For example, to create a new Perl variable called "dberror" that contains
+both the numeric and descriptive string error values, you could use the
+following code:
+
+    extern int  dberror;
+    extern char *dberror_list;
+
+    SV* sv = perl_get_sv("dberror", TRUE);
+    sv_setiv(sv, (IV) dberror);
+    sv_setpv(sv, dberror_list[dberror]);
+    SvIOK_on(sv);
+
+If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
+macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
+
+=head2 Magic Variables
 
 [This section still under construction.  Ignore everything here.  Post no
 bills.  Everything not permitted is forbidden.]
@@ -724,45 +766,7 @@ This routine checks to see what types of magic C<sv> has.  If the mg_type
 field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
 the mg_type field is changed to be the lower-case letter.
 
-=head2 Double-Typed SV's
-
-Scalar variables normally contain only one type of value, an integer,
-double, pointer, or reference.  Perl will automatically convert the
-actual scalar data from the stored type into the requested type.
-
-Some scalar variables contain more than one type of scalar data.  For
-example, the variable C<$!> contains either the numeric value of C<errno>
-or its string equivalent from either C<strerror> or C<sys_errlist[]>.
-
-To force multiple data values into an SV, you must do two things: use the
-C<sv_set*v> routines to add the additional scalar type, then set a flag
-so that Perl will believe it contains more than one type of data.  The
-four macros to set the flags are:
-
-	SvIOK_on
-	SvNOK_on
-	SvPOK_on
-	SvROK_on
-
-The particular macro you must use depends on which C<sv_set*v> routine
-you called first.  This is because every C<sv_set*v> routine turns on
-only the bit for the particular type of data being set, and turns off
-all the rest.
-
-For example, to create a new Perl variable called "dberror" that contains
-both the numeric and descriptive string error values, you could use the
-following code:
-
-    extern int  dberror;
-    extern char *dberror_list;
-
-    SV* sv = perl_get_sv("dberror", TRUE);
-    sv_setiv(sv, (IV) dberror);
-    sv_setpv(sv, dberror_list[dberror]);
-    SvIOK_on(sv);
-
-If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
-macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
+=head1 Subroutines
 
 =head2 XSUB's and the Argument Stack
 
@@ -914,8 +918,6 @@ is being used.
 
 For a complete description of the PerlIO abstraction, consult L<perlapio>.
 
-=head2 Scratchpads
-
 =head2 Putting a C value on Perl stack
 
 A lot of opcodes (this is an elementary operation in the internal perl
@@ -924,7 +926,7 @@ the corresponding SV is (usually) not recreated each time. The opcodes
 reuse specially assigned SVs (I<target>s) which are (as a corollary)
 not constantly freed/created.
 
-Each of the targets is created only once (but see 
+Each of the targets is created only once (but see
 L<Scratchpads and recursion> below), and when an opcode needs to put
 an integer, a double, or a string on stack, it just sets the
 corresponding parts of its I<target> and puts the I<target> on stack.
@@ -973,7 +975,144 @@ if it is, new scratchpad is created and pushed into the array.
 The I<target>s on this scratchpad are C<undef>s, but they are already
 marked with correct flags.
 
-=head2 API LISTING
+=head1 Compiled code
+
+=head2 Code tree
+
+Here we describe the internal form your code is converted to by
+Perl. Start with a simple example:
+
+  $a = $b + $c;
+
+This is converted to a tree similar to this one:
+
+             assign-to
+           /           \
+          +             $a
+        /   \
+      $b     $c
+
+(but slightly more complicated).  This tree reflect the way Perl
+parsed your code, but has nothing to do with the execution order.
+There is an additional "thread" going through the nodes of the tree
+which shows the order of execution of the nodes.  In our simplified
+example above it looks like:
+
+     $b ---> $c ---> + ---> $a ---> assign-to
+
+But with the actual compile tree for C<$a = $b + $c> it is different:
+some nodes I<optimized away>.  As a corollary, though the actual tree
+contains more nodes than our simplified example, the execution order
+is the same as in our example.
+
+=head2 Examining the tree
+
+If you have your perl compiled for debugging (usually done with C<-D
+optimize=-g> on C<Configure> command line), you may examine the
+compiled tree by specifying C<-Dx> on the Perl command line.  The
+output takes several lines per node, and for C<$b+$c> it looks like
+this:
+
+    5           TYPE = add  ===> 6
+                TARG = 1
+                FLAGS = (SCALAR,KIDS)
+                {
+                    TYPE = null  ===> (4)
+                      (was rv2sv)
+                    FLAGS = (SCALAR,KIDS)
+                    {
+    3                   TYPE = gvsv  ===> 4
+                        FLAGS = (SCALAR)
+                        GV = main::b
+                    }
+                }
+                {
+                    TYPE = null  ===> (5)
+                      (was rv2sv)
+                    FLAGS = (SCALAR,KIDS)
+                    {
+    4                   TYPE = gvsv  ===> 5
+                        FLAGS = (SCALAR)
+                        GV = main::c
+                    }
+                }
+
+This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
+not optimized away (one per number in the left column).  The immediate
+children of the given node correspond to C<{}> pairs on the same level
+of indentation, thus this listing corresponds to the tree:
+
+                   add
+                 /     \
+               null    null
+                |       |
+               gvsv    gvsv
+
+The execution order is indicated by C<===E<gt>> marks, thus it is C<3
+4 5 6> (node C<6> is not included into above listing), i.e.,
+C<gvsv gvsv add whatever>.
+
+=head2 Compile pass 1: check routines
+
+The tree is created by the I<pseudo-compiler> while yacc code feeds it
+the constructions it recognizes. Since yacc works bottom-up, so does
+the first pass of perl compilation.
+
+What makes this pass interesting for perl developers is that some
+optimization may be performed on this pass.  This is optimization by
+so-called I<check routines>.  The correspondence between node names
+and corresponding check routines is described in F<opcode.pl> (do not
+forget to run C<make regen_headers> if you modify this file).
+
+A check routine is called when the node is fully constructed except
+for the execution-order thread.  Since at this time there is no
+back-links to the currently constructed node, one can do most any
+operation to the top-level node, including freeing it and/or creating
+new nodes above/below it.
+
+The check routine returns the node which should be inserted into the
+tree (if the top-level node was not modified, check routine returns
+its argument).
+
+By convention, check routines have names C<ck_*>. They are usually
+called from C<new*OP> subroutines (or C<convert>) (which in turn are
+called from F<perly.y>).
+
+=head2 Compile pass 1a: constant folding
+
+Immediately after the check routine is called the returned node is
+checked for being compile-time executable.  If it is (the value is
+judged to be constant) it is immediately executed, and a I<constant>
+node with the "return value" of the corresponding subtree is
+substituted instead.  The subtree is deleted.
+
+If constant folding was not performed, the execution-order thread is
+created.
+
+=head2 Compile pass 2: context propagation
+
+When a context for a part of compile tree is known, it is propagated
+down through the tree.  Aat this time the context can have 5 values
+(instead of 2 for runtime context): void, boolean, scalar, list, and
+lvalue.  In contrast with the pass 1 this pass is processed from top
+to bottom: a node's context determines the context for its children.
+
+Additional context-dependent optimizations are performed at this time.
+Since at this moment the compile tree contains back-references (via
+"thread" pointers), nodes cannot be free()d now.  To allow
+optimized-away nodes at this stage, such nodes are null()ified instead
+of free()ing (i.e. their type is changed to OP_NULL).
+
+=head2 Compile pass 3: peephole optimization
+
+After the compile tree for a subroutine (or for an C<eval> or a file)
+is created, an additional pass over the code is performed. This pass
+is neither top-down or bottom-up, but in the execution order (with
+additional compilications for conditionals).  These optimizations are
+done in the subroutine peep().  Optimizations performed at this stage
+are subject to the same restrictions as in the pass 2.
+
+=head1 API LISTING
 
 This is a listing of functions, macros, flags, and variables that may be
 useful to extension writers or that may be found while reading other
@@ -1192,10 +1331,16 @@ Returns the glob with the given C<name> and a defined subroutine or
 C<NULL>. The glob lives in the given C<stash>, or in the stashes accessable
 via @ISA and @<UNIVERSAL>.
 
-As a side-effect creates a glob with the given C<name> in the given C<stash>
-which in the case of success contains an alias for the subroutine, and
-sets up caching info for this glob.  Similarly for all the searched
-stashes.
+The argument C<level> should be either 0 or -1. If C<level==0>, as a
+side-effect creates a glob with the given C<name> in the given
+C<stash> which in the case of success contains an alias for the
+subroutine, and sets up caching info for this glob.  Similarly for all
+the searched stashes.
+
+The GV returned from C<gv_fetchmeth> may be a method cache entry,
+which is not visible to Perl code.  So when calling C<perl_call_sv>,
+you should not use the GV directly; instead, you should use the
+method's CV, which can be obtained from the GV with the C<GvCV> macro.
 
         GV*     gv_fetchmeth _((HV* stash, char* name, STRLEN len, I32 level));
 
@@ -1214,8 +1359,10 @@ Use the glob created via a side effect to do this.
 This function grants C<"SUPER"> token as prefix of name or postfix of
 the stash name.
 
-Has the same side-effects and as C<gv_fetchmeth()>.  C<name> should be
-writable if contains C<':'> or C<'\''>.
+Has the same side-effects and as C<gv_fetchmeth> with C<level==0>.
+C<name> should be writable if contains C<':'> or C<'\''>.
+The warning against passing the GV returned by C<gv_fetchmeth> to
+C<perl_call_sv> apply equally to C<gv_fetchmethod>.
 
         GV*     gv_fetchmethod _((HV* stash, char* name));
 
@@ -2601,4 +2748,4 @@ API Listing by Dean Roehrich <roehrich@cray.com>.
 
 =head1 DATE
 
-Version 30: 1997/1/17
+Version 31: 1997/1/27
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index f451606df5..8c97163e05 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -54,8 +54,6 @@ HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERL_DESTRUCT_LEVEL, PERLLIB
 
 =item New Opcode Module and Revised Safe Module
 
-=item Extended Fcntl Module
-
 =item Internal Change: FileHandle Deprecated
 
 =item Internal Change: PerlIO internal IO abstraction interface
@@ -99,6 +97,10 @@ use blib, use blib 'dir', use locale, use ops
 
 =item Math::Complex
 
+=item DB_File
+
+=item Net::Ping
+
 =item Overridden Built-ins
 
 =back
@@ -113,6 +115,10 @@ C<void> XSUBs now default to returning nothing
 
 =back
 
+=item C Language API Changes
+
+C<gv_fetchmethod> and C<perl_call_sv>
+
 =item Documentation Changes
 
 L<perldelta>, L<perllocale>, L<perltoot>, L<perlapio>, L<perldebug>,
@@ -353,8 +359,8 @@ getgrent, gethostent, getnetent, getprotoent, getservent, setpwent,
 setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN,
 setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent,
 endprotoent, endservent, getsockname SOCKET, getsockopt
-SOCKET,LEVEL,OPTNAME, glob EXPR, gmtime EXPR, goto LABEL, goto EXPR, goto
-&NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, import, index
+SOCKET,LEVEL,OPTNAME, glob EXPR, glob, gmtime EXPR, goto LABEL, goto EXPR,
+goto &NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, import, index
 STR,SUBSTR,POSITION, index STR,SUBSTR, int EXPR, int, ioctl
 FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys ASSOC_ARRAY, kill LIST,
 last LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length,
@@ -1395,6 +1401,8 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)>
 
 =item DESCRIPTION
 
+=item Variables
+
 =over
 
 =item Datatypes
@@ -1419,7 +1427,9 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)>
 
 =item Stashes and Globs
 
-=item Magic
+=item Double-Typed SV's
+
+=item Magic Variables
 
 =item Assigning Magic
 
@@ -1427,7 +1437,11 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)>
 
 =item Finding Magic
 
-=item Double-Typed SV's
+=back
+
+=item Subroutines
+
+=over
 
 =item XSUB's and the Argument Stack
 
@@ -1437,14 +1451,32 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)>
 
 =item PerlIO
 
-=item Scratchpads
-
 =item Putting a C value on Perl stack
 
 =item Scratchpads
 
 =item Scratchpads and recursions
 
+=back
+
+=item Compiled code
+
+=over
+
+=item Code tree
+
+=item Examining the tree
+
+=item Compile pass 1: check routines
+
+=item Compile pass 1a: constant folding
+
+=item Compile pass 2: context propagation
+
+=item Compile pass 3: peephole optimization
+
+=back
+
 =item API LISTING
 
 AvFILL, av_clear, av_extend, av_fetch, av_len, av_make, av_pop, av_push,
@@ -1482,8 +1514,6 @@ XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, XSRETURN_NV,
 XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNV, XST_mNO,
 XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, Zero
 
-=back
-
 =item EDITOR
 
 =item DATE
@@ -3410,6 +3440,8 @@ unexpand(1)
 
 =item EXAMPLE
 
+=item BUGS
+
 =item AUTHOR
 
 =head2 Tie::Hash, Tie::StdHash - base class definitions for tied hashes