Readme.backtrace

To help debugging, BoxLib handles various signals in the C standard
library raised in the runs.  This gives us a chance to print out more
information using Linux/Unix backtrace capability.  The signals
include seg fault, interruption by the user (control-c), assertion
errors, and floating point exceptions (NaNs, divided by zero and
overflow).  The handling of seg fault, assertion errors and
interruption by control-C are enabled by default. (Note that in C++
BoxLib, BL_ASSERT() is only on when compiled with DEBUG=TRUE or
USE_ASSERTION=TRUE.)  The trapping of floating point exceptions is not
enabled by default unless the code is compiled with TEST=TRUE or
DEBUG=TRUE in C++ BoxLib, or TEST=t or NDEBUG= in Fortran BoxLib.  For
C++ BoxLib codes, one can also use runtime parameters to control the
handling of floating point exceptions: boxlib.fpe_trap_invalid for
NaNs, boxlib.fpe_trap_zero for division by zero and
boxlib.fpe_trap_overflow for overflow.  To more effectively trap the
use of uninitialized values, BoxLib also initializes MulitFabs and
arrays allocated by bl_allocate to signaling NaNs when it is compiled
with TEST=TRUE or DEBUG=TRUE in C++ BoxLib, or TEST=t or NDEBUG= in
Fortran BoxLib.  In C++ BoxLib, one can also control the setting using
the runtime parameter, fab.init_snan.

If it is compiled with BACKTRACE=TRUE, one can get more information
than the backtrace of the call stack by instrumenting the code.  (This
is in C++ code only.)  Here is an example.  You know the line "Real
rho = state(cell,0);" is causing a segfault.  You could add a print
statement before that.  But it might print out thousands (or even
millions) of line before it hits the segfault.  With BACKTRACE, you
could do

   #include <BLBackTrace.H>
   
   #ifdef BL_BACKTRACING
       std::ostringstream ss;
       ss << "state.box() = " << state.box() << " cell = " << cell;
       BL_BACKTRACE_PUSH(ss.str()); // PUSH takes std::string
   #endif
       Real rho = state(cell,0);  // state is a Fab, and cell is an IntVect.
   #ifdef BL_BACKTRACING
       BL_BACKTRACE_POP(); // One can omit this line.  In that case,
                           // there is an implicit POP when "PUSH" is
                           // out of scope.
   #endif

When it hits the segfault, you will only see the last pint out.