src/stacktrace.h

   1 // Copyright 2000 - 2007 Google Inc.
   2 // All rights reserved.
   3 //
   4 // Routines to extract the current stack trace.  These functions are
   5 // thread-safe.
   6
   7 #ifndef BASE_STACKTRACE_H_
   8 #define BASE_STACKTRACE_H_
   9
  10 #include "config.h"
  11
  12 _START_GOOGLE_NAMESPACE_
  13
  14 // Skips the most recent "skip_count" stack frames (also skips the
  15 // frame generated for the "GetStackFrames" routine itself), and then
  16 // records the pc values for up to the next "max_depth" frames in
  17 // "pcs", and the corresponding stack frame sizes in "sizes".  Returns
  18 // the number of values recorded in "pcs"/"sizes".
  19 //
  20 // Example:
  21 //      main() { foo(); }
  22 //      foo() { bar(); }
  23 //      bar() {
  24 //        void* pcs[10];
  25 //        int sizes[10];
  26 //        int depth = GetStackFrames(pcs, sizes, 10, 1);
  27 //      }
  28 //
  29 // The GetStackFrames call will skip the frame for "bar".  It will
  30 // return 2 and will produce pc values that map to the following
  31 // procedures:
  32 //      pcs[0]       foo
  33 //      pcs[1]       main
  34 // (Actually, there may be a few more entries after "main" to account for
  35 // startup procedures.)
  36 // And corresponding stack frame sizes will also be recorded:
  37 //    sizes[0]       16
  38 //    sizes[1]       16
  39 // (Stack frame sizes of 16 above are just for illustration purposes.)
  40 // Stack frame sizes of 0 or less indicate that those frame sizes couldn't
  41 // be identified.
  42 //
  43 // This routine may return fewer stack frame entries than are
  44 // available. Also note that "pcs" and "sizes" must both be non-NULL.
  45 extern int GetStackFrames(void** pcs, int* sizes, int max_depth,
  46                           int skip_count);
  47
  48 // This is similar to the GetStackFrames routine, except that it returns
  49 // the stack trace only, and not the stack frame sizes as well.
  50 // Example:
  51 //      main() { foo(); }
  52 //      foo() { bar(); }
  53 //      bar() {
  54 //        void* result[10];
  55 //        int depth = GetStackFrames(result, 10, 1);
  56 //      }
  57 //
  58 // This produces:
  59 //      result[0]       foo
  60 //      result[1]       main
  61 //           ....       ...
  62 //
  63 // "result" must not be NULL.
  64 extern int GetStackTrace(void** result, int max_depth, int skip_count);
  65
  66 _END_GOOGLE_NAMESPACE_
  67
  68 #endif  // BASE_STACKTRACE_H_