balst_stacktraceprintutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • logExceptionStackTrace
  • Usage
    • Example 1: Printing a Stack Trace

Purpose

Provide a single function to perform and print a stack trace.

Classes

• balst::StackTracePrintUtil: namespace for functions to print a stack trace

See also

balst_stacktraceutil

Description

This component defines a namespace struct, balst::StackTracePrintUtil, containing static platform-independent functions that will perform a stack trace and print it to a supplied stream. Not all properties of a stack trace are printed on all platforms because the set of properties describing a stack trace that are obtainable varies according to both the platform and build parameters. For example, on Solaris, source file names and line numbers are not provided. Function names and addresses are provided on all platforms. The printStackTrace function always prints a description of the stack of the calling thread.

logExceptionStackTrace

The function StackTracePrintUtil::logExceptionStackTrace is meant to be passed as a function pointer to the bslstl::StdExceptUtil::set*Hook functions and will result in a stack trace being logged with fatal severity prior to the respective exception being thrown. It is a substitute for the function bslstl::StdExceptUtil::logCheapStackTrace that takes longer to run but provides far superior output.

Usage

This section illustrates intended use of this component.

Example 1: Printing a Stack Trace

This example shows how to obtain a stack trace and print it to a stream, all by calling just the static function balst::StackTracePrintUtil::printStackTrace.

First, we define a recursive function recurseAndPrintStack that recurses to the specified depth, then calls balst::StackTracePrintUtil::printStackTrace to obtain a stack trace and print it to cout. When we call printStackTrace, neither of the optional arguments corresponding to maxFrames or demanglingPreferredFlag are supplied; maxFrames defaults to at least 1024 (which is more than we need), and demanglingPreferredFlag defaults to true.

static
void recurseAndPrintStack(int *depth)
    // Recurse to the specified 'depth', then print out the stack trace to
    // 'cout'.
{
    if (--*depth > 0) {
        recurseAndPrintStack(depth);
    }
    else {
        balst::StackTracePrintUtil::printStackTrace(cout);
    }
 
    ++*depth;   // Prevent compiler from optimizing tail recursion as a
                // loop.
}

Then, we call recurseAndPrintStack from the main program.

int main()
{
    int depth = 5;
    recurseAndPrintStack(&depth);
    assert(5 == depth);
}

Now, invoking the main program on AIX produces the following output:

(0): BloombergLP::balst::StackTracePrintUtil::.printStackTrace(
     std::basic_ostream<char,std::char_traits<char> >&,int,bool)+0x170 at
     0x1000a2c8 source:balst_stacktraceprintutil.cpp:52 in
     balst_stacktraceprintutil.t.dbg_
(1): .recurseAndPrintStack(int*)+0x58 at 0x1000a118
     source:balst_stacktraceprintutil.t.cpp:652 in
     balst_stacktraceprintutil.t.dbg_
(2): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
     source:balst_stacktraceprintutil.t.cpp:650
     in balst_stacktraceprintutil.t.dbg_
(3): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
     source:balst_stacktraceprintutil.t.cpp:650 in
     balst_stacktraceprintutil.t.dbg_
(4): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
     source:balst_stacktraceprintutil.t.cpp:650 in
     balst_stacktraceprintutil.t.dbg_
(5): .recurseAndPrintStack(int*)+0x40 at 0x1000a100
     source:balst_stacktraceprintutil.t.cpp:650 in
     balst_stacktraceprintutil.t.dbg_
(6): .main+0x2f4 at 0x10000a4c source:balst_stacktraceprintutil.t.cpp:724
     in balst_stacktraceprintutil.t.dbg_
(7): .__start+0x6c at 0x1000020c source:crt0main.s in
     balst_stacktraceprintutil.t.dbg_

Finally, we observe the following about the above output to cout. Notice that since the actual output would write each stack trace frame all on a single line, and all the lines here were longer than 80 characters, it has been manually edited to wrap and have every line be less than 80 columns. Also note the program name is truncated to 32 characters in length.