Component balst_stacktraceprintutil [Package balst]

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

Namespaces
namespace	balst

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • 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:

Component 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.

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.