make EMBEDMYMALLOC the default and provide PERL_POLLUTE_MALLOC to let

them ask for insanity (untested)

p4raw-id: //depot/perl@2832

1 files changed, 22 insertions, 0 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 86781389b5..b2e197f47b 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -23,6 +23,28 @@ macros for extension source compatibility.  As of release 5.006, these
 preprocessor definitions are not available by default.  You need to explicitly
 compile perl with C<-DPERL_POLLUTE> in order to get these definitions.
 
+=item C<PERL_POLLUTE_MALLOC>
+
+Enabling the use of Perl's malloc in release 5.005 and earlier caused
+the namespace of system versions of the malloc family of functions to
+be usurped by the Perl versions of these functions, since they used the
+same names by default.
+
+Besides causing problems on platforms that do not allow these functions to
+be cleanly replaced, this also meant that the system versions could not
+be called in programs that used Perl's malloc.  Previous versions of Perl
+have allowed this behavior to be suppressed with the HIDEMYMALLOC and
+EMBEDMYMALLOC preprocessor definitions.
+
+As of release 5.006, Perl's malloc family of functions have default names
+distinct from the system versions.  You need to explicitly compile perl with
+C<-DPERL_POLLUTE_MALLOC> in order to get the older behavior.  HIDEMYMALLOC
+and EMBEDMYMALLOC have no effect, since the behavior they enabled is now
+the default.
+
+Note that these functions do B<not> constitute Perl's memory allocation API.
+See L<perlguts/"Memory Allocation"> for further information about that.
+
 =item C<PL_na> and C<dTHR> Issues
 
 The C<PL_na> global is now thread local, so a C<dTHR> declaration is needed