Document Third Degree some more, and also PERL_DESTRUCT_LEVEL.

p4raw-id: //depot/perl@9218

3 files changed, 45 insertions, 8 deletions

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 1f398a4fce..490049b394 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1683,14 +1683,50 @@ DEC OSF/1).
 
 When building Perl, you must first run Configure with -Doptimize=-g
 and -Uusemymalloc flags, after that you can use the make targets
+"perl.third" and "test.third".
 
-"perl.third" and "test.third".  The short story is that with "atom"
-you can instrument the Perl executable to create a new executable
-called "perl.third."  When the instrumented executable is run, it
-creates a log of dubious memory traffic in file called "perl.3log".
-See man atom and man third for more information.  The most extensive
-Third Degree documentation is available in the Compaq "Tru64 UNIX
-Programmer's Guide", chapter "Debugging Programs with Third Degree".
+The short story is that with "atom" you can instrument the Perl
+executable to create a new executable called "perl.third".
+When the instrumented executable is run, it creates a log of dubious
+memory traffic in file called "perl.3log".  See man atom and man third
+for more information.  The most extensive Third Degree documentation
+is available in the Compaq "Tru64 UNIX Programmer's Guide", chapter
+"Debugging Programs with Third Degree".
+
+The "test.third" leaves a lot of files named perl.3log.* in the t/
+subdirectory.  There is a problem with these files: Third Degree is so
+effective that it finds problems also in the system libraries.
+Therefore there are certain types of errors that you should ignore
+in your debugging.  Errors with stack traces matching
+
+    __actual_atof|__catgets|_doprnt|__exc_|__exec|_findio|__localtime|setlocale|__sia_|__strxfrm
+
+(all in libc.so) are known to be non-serious.  You can also
+ignore the combinations
+
+    Perl_gv_fetchfile() calling strcpy()
+    S_doopen_pmc() calling strcmp()
+
+causing "rih" (reading invalid heap) errors.
+
+There are also leaks that for given certain definition of a leak,
+aren't.  See L</PERL_DESTRUCT_LEVEL> for more information.
+
+=head2 PERL_DESTRUCT_LEVEL
+
+If you want to run any of the tests yourself manually using the
+pureperl or perl.third executables, please note that by default
+perl B<does not> explicitly cleanup all the memory it has allocated
+(such as global memory arenas) but instead lets the exit() of
+the whole program "take care" of such allocations, also known
+as "global destruction of objects".
+
+There is a way to tell perl to do complete cleanup: set the
+environment variable PERL_DESTRUCT_LEVEL to a non-zero value.
+The t/TEST wrapper does set this to 2, and this is what you
+need to do too, if you don't want to see the "global leaks":
+
+	PERL_DESTRUCT_LEVEL=2 ./perl.third t/foo/bar.t
 
 =head2 CONCLUSION
 
diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 285ed9975e..53009c5eb2 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -548,6 +548,7 @@ destructed.  Plain refs are only garbage-collected if the destruct level
 is greater than 0.  You can test the higher levels of global destruction
 by setting the PERL_DESTRUCT_LEVEL environment variable, presuming
 C<-DDEBUGGING> was enabled during perl build time.
+See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
 
 A more complete garbage collection strategy will be implemented
 at a future date.
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 3170df4ccc..0bfcaff3b8 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -830,7 +830,7 @@ after compilation.
 
 Relevant only if your perl executable was built with B<-DDEBUGGING>,
 this controls the behavior of global destruction of objects and other
-references.
+references.  See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
 
 =item PERL_ROOT (specific to the VMS port)