[inseparable changes from match from perl-5.003_90 to perl-5.003_91]

 BUILD PROCESS

Subject: Sanity check linking with $libs
Date: Tue, 25 Feb 1997 14:13:45 -0500 (EST)
From: Andy Dougherty <doughera@fractal.phys.lafayette.edu>
Files: Configure
Msg-ID: <Pine.SOL.3.95q.970225221634.2486A-100000@fractal.lafayette.edu>

    (applied based on p5p patch as commit 5c37e92e59bb92e49d5a21017cd6dc066a28ddea)

Subject: Flush stdout when printing $randbits guess
From: Chip Salzenberg <chip@perl.com>
Files: Configure

Subject: Configure changes for Irix nm
From: Helmut Jarausch <helmutjarausch@unknown>
Files: Configure

 CORE LANGUAGE CHANGES

Subject: Fix perl_call_*() when !G_EVAL
Date: Tue, 25 Feb 1997 02:25:56 -0500
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: MANIFEST gv.c interp.sym perl.c perl.h pp_ctl.c pp_sys.c t/op/runlevel.t
Msg-ID: <199702250725.CAA09192@aatma.engin.umich.edu>, <199702251925.OAA15498@aatma.engin.umich.edu>, <199702252200.RAA16853@aatma.engin.umich.edu>

    (applied based on p5p patch as commits 40f788c454d994616342c409de5b5d181ad9b8af, and 907a881cde89c56bc61d3f314c0efb8754ca472a, 20efc0829f6564c44574762adb07e8865bc14026)

Subject: Fix taint tests for writeable dirs in $ENV{PATH}
From: Chip Salzenberg <chip@perl.com>
Files: mg.c mg.h pod/perlsec.pod taint.c

Subject: Forbid tainted parameters for truncate()
From: Chip Salzenberg <chip@perl.com>
Files: pp_sys.c

Subject: Don't taint magic hash keys unnecessarily
Date: Fri, 28 Feb 1997 02:11:26 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: hv.c

    private-msgid: <01IFXL9TY74Y00661G@hmivax.humgen.upenn.edu>

 CORE PORTABILITY

Subject: VMS patches post _90
Date: Fri, 28 Feb 1997 15:26:33 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: doio.c mg.c perl.h pp_hot.c t/op/rand.t t/op/taint.t taint.c vms/descrip.mms vms/vms.c

    private-msgid: <01IFYDE5ZT7O005A53@hmivax.humgen.upenn.edu>

Subject: Fix taint check in system() and exec() under VMS and OS/2
From: Chip Salzenberg <chip@perl.com>
Files: pp_sys.c

Subject: If _XOPEN_VERSION >= 4, socket length parameters are size_t
From: Michael H. Moran <mhm@austin.ibm.com>
Files: perl.h pp_sys.c

Subject: Make dooneliner() compile again
From: Chip Salzenberg <chip@perl.com>
Files: pp_sys.c

 DOCUMENTATION

Subject: Move ENVIRONMENT from perl.pod to perlrun.pod
From: Chip Salzenberg <chip@perl.com>
Files: pod/perl.pod pod/perlrun.pod

Subject: Describe PERL_DEBUG_MSTATS in perlrun.pod
From: Nat <gnat@frii.com>
Files: pod/perlrun.pod

Subject: Fix references to perlbug
From: Chip Salzenberg <chip@perl.com>
Files: pod/perl.pod pod/perldelta.pod pod/perllocale.pod pod/perltoc.pod

 OTHER CORE CHANGES

Subject: Short-circuit duplicate study() calls
From: Chip Salzenberg <chip@perl.com>
Files: pp.c

Subject: Call sv_set[iu]v() with [IU]V parameter, not [IU]32
From: Chip Salzenberg <chip@perl.com>
Files: perl.c pp.c pp_sys.c toke.c util.c

Subject: Clean up and document API for hashes
Date: Tue, 25 Feb 1997 13:24:02 -0500
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: hv.c hv.h pod/perldelta.pod pod/perlguts.pod
Msg-ID: <199702251824.NAA14859@aatma.engin.umich.edu>

    (applied based on p5p patch as commit a61fe43df197fcc70e6f310c06ee17d52b606c45)

Subject: pp_undef was not always freeing memory
Date: Thu, 27 Feb 1997 01:53:51 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: pp.c
Msg-ID: <199702270653.BAA13949@monk.mps.ohio-state.edu>

    (applied based on p5p patch as commit 1da885048b65b5be1bd3077c6fc45f92c567e1b5)

Subject: Don't examine rx->exec_tainted if pregexec() fails
From: Chip Salzenberg <chip@perl.com>
Files: pp_hot.c

 TESTS

Subject: New test op/taint.t
Date: Tue, 25 Feb 1997 11:36:53 -0800 (PST)
From: Tom Phoenix <rootbeer@teleport.com>
Files: MANIFEST t/op/taint.t

    private-msgid: <Pine.GSO.3.95q.970225101328.18288M-100000@kelly.teleport.com

Subject: Patch to t/op/rand.t
Date: Tue, 25 Feb 1997 18:19:34 -0800 (PST)
From: Tom Phoenix <rootbeer@teleport.com>
Files: t/op/rand.t

    private-msgid: <Pine.GSO.3.95q.970225181321.13796Q-100000@kelly.teleport.com

 UTILITIES

Subject: Add --lax option to pod2man; use it in perldoc
From: Nat <gnat@frii.com>
Files: pod/pod2man.PL utils/perldoc.PL

Subject: Eliminate dead code in pod2man
From: Chip Salzenberg <chip@perl.com>
Files: pod/pod2man.PL

1 files changed, 161 insertions, 1 deletions

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 77acc98aae..95bd4eccbd 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -322,6 +322,48 @@ The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
     while (i--)
 	hash = hash * 33 + *s++;
 
+=head2 Hash API Extensions
+
+Beginning with version 5.004, the following functions are also supported:
+
+    HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
+    HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);
+    
+    bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
+    SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
+    
+    SV*     hv_iterkeysv  (HE* entry);
+
+Note that these functions take C<SV*> keys, which simplifies writing
+of extension code that deals with hash structures.  These functions
+also allow passing of C<SV*> keys to C<tie> functions without forcing
+you to stringify the keys (unlike the previous set of functions).
+
+They also return and accept whole hash entries (C<HE*>), making their
+use more efficient (since the hash number for a particular string
+doesn't have to be recomputed every time).  See L<API LISTING> later in
+this document for detailed descriptions.
+
+The following macros must always be used to access the contents of hash
+entries.  Note that the arguments to these macros must be simple
+variables, since they may get evaluated more than once.  See
+L<API LISTING> later in this document for detailed descriptions of these
+macros.
+
+    HePV(HE* he, STRLEN len)
+    HeVAL(HE* he)
+    HeHASH(HE* he)
+    HeSVKEY(HE* he)
+    HeSVKEY_force(HE* he)
+    HeSVKEY_set(HE* he, SV* sv)
+
+These two lower level macros are defined, but must only be used when
+dealing with keys that are not C<SV*>s:
+
+    HeKEY(HE* he)
+    HeKLEN(HE* he)
+
+
 =head2 References
 
 References are a special type of scalar that point to other data types
@@ -1392,6 +1434,12 @@ statement (or thereabouts) with C<sv_2mortal>.  See C<hv_iternext>.
 
 	void    he_delayfree _((HV* hv, HE* hent));
 
+=item HEf_SVKEY
+
+This flag, used in the length slot of hash entries and magic
+structures, specifies the structure contains a C<SV*> pointer where a
+C<char*> pointer is to be expected. (For information only--not to be used).
+
 =item he_free
 
 Releases a hash entry, such as while iterating though the hash.  See
@@ -1399,6 +1447,71 @@ C<hv_iternext>.
 
 	void    he_free _((HV* hv, HE* hent));
 
+=item HeHASH
+
+Returns the computed hash (type C<U32>) stored in the hash entry.
+
+	HeHASH(HE* he)
+
+=item HeKEY
+
+Returns the actual pointer stored in the key slot of the hash entry.
+The pointer may be either C<char*> or C<SV*>, depending on the value of
+C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros
+are usually preferable for finding the value of a key.
+
+	HeKEY(HE* he)
+
+=item HeKLEN
+
+If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
+holds an C<SV*> key.  Otherwise, holds the actual length of the key.
+Can be assigned to. The C<HePV()> macro is usually preferable for finding
+key lengths.
+
+	HeKLEN(HE* he)
+
+=item HePV
+
+Returns the key slot of the hash entry as a C<char*> value, doing any
+necessary dereferencing of possibly C<SV*> keys.  The length of
+the string is placed in C<len> (this is a macro, so do I<not> use
+C<&len>).  If you do not care about what the length of the key is,
+you may use the global variable C<na>.  Remember though, that hash
+keys in perl are free to contain embedded nulls, so using C<strlen()>
+or similar is not a good way to find the length of hash keys.
+This is very similar to the C<SvPV()> macro described elsewhere in
+this document.
+
+	HePV(HE* he, STRLEN len)
+
+=item HeSVKEY
+
+Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
+does not contain an C<SV*> key.
+
+	HeSVKEY(HE* he)
+
+=item HeSVKEY_force
+
+Returns the key as an C<SV*>.  Will create and return a temporary
+mortal C<SV*> if the hash entry contains only a C<char*> key.
+
+	HeSVKEY_force(HE* he)
+
+=item HeSVKEY_set
+
+Sets the key to a given C<SV*>, taking care to set the appropriate flags
+to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
+
+	HeSVKEY_set(HE* he, SV* sv)
+
+=item HeVAL
+
+Returns the value slot (type C<SV*>) stored in the hash entry.
+
+	HeVAL(HE* he)
+
 =item hv_clear
 
 Clears a hash, making it empty.
@@ -1414,6 +1527,15 @@ returned.
 
 	SV*	hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
 
+=item hv_delete_ent
+
+Deletes a key/value pair in the hash.  The value SV is removed from the hash
+and returned to the caller.  The C<flags> value will normally be zero; if set
+to G_DISCARD then null will be returned.  C<hash> can be a valid pre-computed
+hash value, or 0 to ask for it to be computed.
+
+	SV*     hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash));
+
 =item hv_exists
 
 Returns a boolean indicating whether the specified hash key exists.  The
@@ -1421,6 +1543,13 @@ C<klen> is the length of the key.
 
 	bool	hv_exists _((HV* tb, char* key, U32 klen));
 
+=item hv_exists_ent
+
+Returns a boolean indicating whether the specified hash key exists. C<hash>
+can be a valid pre-computed hash value, or 0 to ask for it to be computed.
+
+	bool    hv_exists_ent _((HV* tb, SV* key, U32 hash));
+
 =item hv_fetch
 
 Returns the SV which corresponds to the specified key in the hash.  The
@@ -1430,6 +1559,18 @@ dereferencing it to a C<SV*>.
 
 	SV**	hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
 
+=item hv_fetch_ent
+
+Returns the hash entry which corresponds to the specified key in the hash.
+C<hash> must be a valid pre-computed hash number for the given C<key>, or
+0 if you want the function to compute it.  IF C<lval> is set then the
+fetch will be part of a store.  Make sure the return value is non-null
+before accessing it.  The return value when C<tb> is a tied hash
+is a pointer to a static location, so be sure to make a copy of the
+structure if you need to store it somewhere.
+
+	HE*     hv_fetch_ent  _((HV* tb, SV* key, I32 lval, U32 hash));
+
 =item hv_iterinit
 
 Prepares a starting point to traverse a hash table.
@@ -1443,6 +1584,14 @@ C<hv_iterinit>.
 
 	char*	hv_iterkey _((HE* entry, I32* retlen));
 
+=item hv_iterkeysv
+	
+Returns the key as an C<SV*> from the current position of the hash
+iterator.  The return value will always be a mortal copy of the
+key.  Also see C<hv_iterinit>.
+
+	SV*     hv_iterkeysv  _((HE* entry));
+
 =item hv_iternext
 
 Returns entries from a hash iterator.  See C<hv_iterinit>.
@@ -1485,6 +1634,17 @@ original C<SV*>.
 
 	SV**	hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
 
+=item hv_store_ent
+
+Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
+parameter is the pre-computed hash value; if it is zero then Perl will
+compute it.  The return value is the new hash entry so created.  It will be
+null if the operation failed or if the entry was stored in a tied hash.
+Otherwise the contents of the return value can be accessed using the
+C<He???> macros described here.
+
+	HE*     hv_store_ent  _((HV* tb, SV* key, SV* val, U32 hash));
+
 =item hv_undef
 
 Undefines the hash.
@@ -2748,4 +2908,4 @@ API Listing by Dean Roehrich <roehrich@cray.com>.
 
 =head1 DATE
 
-Version 31: 1997/1/27
+Version 31.1: 1997/2/25