From: Jim Cromie <jim.cromie@gmail.com>
Date: Sat, 20 Jun 2009 15:43:43 +0000 (-0600)
Subject: update PERL_MEM_LOG in perlhack.pod
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=10a879f5b15504fdd9aa98740d738732eeee2f22;p=p5sagit%2Fp5-mst-13.2.git

update PERL_MEM_LOG in perlhack.pod
---

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index a0e9e02..75fa1b7 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -2942,27 +2942,29 @@ by C<-DPERL_MEM_LOG> instead.
 
 =head2 PERL_MEM_LOG
 
-If compiled with C<-DPERL_MEM_LOG>, all Newx() and Renew() allocations
-and Safefree() in the Perl core go through logging functions, which is
-handy for breakpoint setting.  If also compiled with C<-DPERL_MEM_LOG_STDERR>,
-the allocations and frees are logged to STDERR (or more precisely, to the
-file descriptor 2) in these logging functions, with the calling source code
-file and line number (and C function name, if supported by the C compiler).
-
-This logging is somewhat similar to C<-Dm> but independent of C<-DDEBUGGING>,
-and at a higher level (the C<-Dm> is directly at the point of C<malloc()>,
-while the C<PERL_MEM_LOG> is at the level of C<New()>).
-
-In addition to memory allocations, SV allocations will be logged, just as
-with C<-Dm>. However, since the logging doesn't use PerlIO, all SV allocations
-are logged and no extra SV allocations are introduced by enabling the logging.
-If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for each SV
-allocation is also logged.
-
-You can control the logging from your environment if you compile with
-C<-DPERL_MEM_LOG_ENV>. Then you need to explicitly set C<PERL_MEM_LOG> and/or
-C<PERL_SV_LOG> to a non-zero value to enable logging of memory and/or SV
-allocations.
+If compiled with C<-DPERL_MEM_LOG>, both memory and SV allocations go
+through logging functions, which is handy for breakpoint setting.
+
+Unless C<-DPERL_MEM_LOG_NOIMPL> is also compiled, the logging
+functions read ENV{PERL_MEM_LOG} to determine whether to log the
+event, and if so how:
+
+    ENV{PERL_MEM_LOG} =~ /m/		Log all memory ops
+    ENV{PERL_MEM_LOG} =~ /s/		Log all SV ops
+    ENV{PERL_MEM_LOG} =~ /t/		include timestamp in Log
+    ENV{PERL_MEM_LOG} =~ /^(\d+)/	write to FD given (default is 2)
+
+Memory logging is somewhat similar to C<-Dm> but is independent of
+C<-DDEBUGGING>, and at a higher level; all uses of Newx(), Renew(),
+and Safefree() are logged with the callers source code file and line
+number (and C function name, if supported by the C compiler).  In
+contrast, C<-Dm> is directly at the point of C<malloc()>.  SV logging
+is similar.
+
+Since the logging doesn't use PerlIO, all SV allocations are logged
+and no extra SV allocations are introduced by enabling the logging.
+If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for
+each SV allocation is also logged.
 
 =head2 Profiling