base/debug_util.h

   1 // Copyright (c) 2006-2009 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This is a cross platform interface for helper functions related to debuggers.
   6 // You should use this to test if you're running under a debugger, and if you
   7 // would like to yield (breakpoint) into the debugger.
   8
   9 #ifndef BASE_DEBUG_UTIL_H_
  10 #define BASE_DEBUG_UTIL_H_
  11
  12 #include <iosfwd>
  13 #include <vector>
  14
  15 #include "base/basictypes.h"
  16
  17 #if defined(OS_WIN)
  18 struct _EXCEPTION_POINTERS;
  19 #endif
  20
  21 // A stacktrace can be helpful in debugging. For example, you can include a
  22 // stacktrace member in a object (probably around #ifndef NDEBUG) so that you
  23 // can later see where the given object was created from.
  24 class StackTrace {
  25  public:
  26   // Creates a stacktrace from the current location
  27   StackTrace();
  28
  29   // Note that the default copy constructor and assignment constructors
  30   // are OK.
  31
  32 #if defined(OS_WIN)
  33   // Creates a stacktrace for an exception.
  34   // Note: this function will throw an import not found (StackWalk64) exception
  35   // on system without dbghelp 5.1.
  36   StackTrace(_EXCEPTION_POINTERS* exception_pointers);
  37 #endif
  38   // Gets an array of instruction pointer values.
  39   //   count: (output) the number of elements in the returned array
  40   const void *const *Addresses(size_t* count);
  41   // Prints a backtrace to stderr
  42   void PrintBacktrace();
  43
  44   // Resolves backtrace to symbols and write to stream.
  45   void OutputToStream(std::ostream* os);
  46
  47  private:
  48   // From http://msdn.microsoft.com/en-us/library/bb204633.aspx,
  49   // the sum of FramesToSkip and FramesToCapture must be less than 63,
  50   // so set it to 62. Even if on POSIX it could be a larger value, it usually
  51   // doesn't give much more information.
  52   static const int MAX_TRACES = 62;
  53   void* trace_[MAX_TRACES];
  54   int count_;
  55 };
  56
  57 class DebugUtil {
  58  public:
  59   // Starts the registered system-wide JIT debugger to attach it to specified
  60   // process.
  61   static bool SpawnDebuggerOnProcess(unsigned process_id);
  62
  63   // Waits wait_seconds seconds for a debugger to attach to the current process.
  64   // When silent is false, an exception is thrown when a debugger is detected.
  65   static bool WaitForDebugger(int wait_seconds, bool silent);
  66
  67   // Are we running under a debugger?
  68   // On OS X, the underlying mechanism doesn't work when the sandbox is enabled.
  69   // To get around this, this function caches its value.
  70   // WARNING: Because of this, on OS X, a call MUST be made to this function
  71   // BEFORE the sandbox is enabled.
  72   static bool BeingDebugged();
  73
  74   // Break into the debugger, assumes a debugger is present.
  75   static void BreakDebugger();
  76
  77 #if defined(OS_MACOSX)
  78   // On Mac OS X, it can take a really long time for the OS crash handler to
  79   // process a Chrome crash when debugging symbols are available.  This
  80   // translates into a long wait until the process actually dies.  This call
  81   // disables Apple Crash Reporter entirely.
  82   static void DisableOSCrashDumps();
  83 #endif  // defined(OS_MACOSX)
  84
  85   // This should be used only in test code.
  86   static void SuppressDialogs() {
  87     suppress_dialogs_ = true;
  88   }
  89
  90  private:
  91   // If true, avoid displaying any dialogs that could cause problems
  92   // in non-interactive environments.
  93   static bool suppress_dialogs_;
  94 };
  95
  96 #endif  // BASE_DEBUG_UTIL_H_