C backtrace tweaks.

Rename the environment variable that triggers the backtrace before
warns and croaks as PERL_USE_C_BACKTRACE_ON_ERROR (and correspondingly,
the define as USE_C_BACKTRACE_ON_ERROR).

Pod cleanups and updates, and move the needed #includes from perl.h
to util.c since that's the only place where they are needed.

1 files changed, 24 insertions, 18 deletions

diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod
index c93a80b413..5cd04e4463 100644
--- a/pod/perlhacktips.pod
+++ b/pod/perlhacktips.pod
@@ -1399,40 +1399,46 @@ Note: you can define up to 20 conversion shortcuts in the gdb section.
 
 =head2 C backtrace
 
-Starting from Perl 5.21.1, on some platforms Perl supports retrieving
-the C level backtrace (similar to what symbolic debuggers like gdb do).
+On some platforms Perl supports retrieving the C level backtrace
+(similar to what symbolic debuggers like gdb do).
 
 The backtrace returns the stack trace of the C call frames,
 with the symbol names (function names), the object names (like "perl"),
 and if it can, also the source code locations (file:line).
 
-The supported platforms are Linux and OS X (some *BSD might work at
-least partly, but they have not yet been tested).
+The supported platforms are Linux, and OS X (some *BSD might
+work at least partly, but they have not yet been tested).
+
+This feature hasn't been tested with multiple threads, but it will
+only show the backtrace of the thread doing the backtracing.
 
 The feature needs to be enabled with C<Configure -Dusecbacktrace>.
 
-The C<-Dusecbacktrace> also enables keeping the debug information
-when compiling.  Many compilers/linkers do support having both
-optimization and keeping the debug information.  The debug information
-is needed for the symbol names and the source locations.
+The C<-Dusecbacktrace> also enables keeping the debug information when
+compiling/linking (often: C<-g>).  Many compilers/linkers do support
+having both optimization and keeping the debug information.  The debug
+information is needed for the symbol names and the source locations.
+
+Static functions might not be visible for the backtrace.
 
 Source code locations, even if available, can often be missing or
-misleading if the compiler has e.g. inlined code.
+misleading if the compiler has e.g. inlined code.  Optimizer can
+make matching the source code and the object code quite challenging.
 
 =over 4
 
 =item Linux
 
 You B<must> have the BFD (-lbfd) library installed, otherwise C<perl> will
-fail to link.  The BFD is usually distributed as part of the binutils.
+fail to link.  The BFD is usually distributed as part of the GNU binutils.
 
 Summary: C<Configure ... -Dusecbacktrace>
 and you need C<-lbfd>.
 
 =item OS X
 
-The source code locations are supported only if you have both C<-g>
-and have the Developer Tools installed.
+The source code locations are supported B<only> if you have
+the Developer Tools installed.  (BFD is B<not> needed.)
 
 Summary: C<Configure ... -Dusecbacktrace>
 and installing the Developer Tools would be good.
@@ -1440,17 +1446,17 @@ and installing the Developer Tools would be good.
 =back
 
 Optionally, for trying out the feature, you may want to enable
-automatic dumping of the backtrace just before a warning message
-is emitted (this includes coincidentally croaking) by adding
-C<-Accflags=-DUSE_C_BACKTRACE_ON_WARN> for Configure.
+automatic dumping of the backtrace just before a warning or croak (die)
+message is emitted, by adding C<-Accflags=-DUSE_C_BACKTRACE_ON_ERROR>
+for Configure.
 
 Unless the above additional feature is enabled, nothing about the
 backtrace functionality is visible, except for the Perl/XS level.
 
 Furthermore, even if you have enabled this feature to be compiled,
 you need to enable it in runtime with an environment variable:
-C<PERL_C_BACKTRACE_ON_WARN=10>.  It must be an integer higher
-than zero, and it tells the desired frame count.
+C<PERL_C_BACKTRACE_ON_ERROR=10>.  It must be an integer higher
+than zero, telling the desired frame count.
 
 Retrieving the backtrace from Perl level (using for example an XS
 extension) would be much less exciting than one would hope: normally
@@ -1458,7 +1464,7 @@ you would see C<runops>, C<entersub>, and not much else.  This API is
 intended to be called B<from within> the Perl implementation, not from
 Perl level execution.
 
-The C API for the backtrace is as follows (see L<perlintern>) for details).
+The C API for the backtrace is as follows:
 
 =over 4