1// Copyright (c) 2012 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#ifndef BASE_DEBUG_STACK_TRACE_H_
6#define BASE_DEBUG_STACK_TRACE_H_
7
8#include <iosfwd>
9#include <string>
10
11#include "base/base_export.h"
12#include "build/build_config.h"
13
14#if defined(OS_POSIX)
15#include <unistd.h>
16#endif
17
18#if defined(OS_WIN)
19struct _EXCEPTION_POINTERS;
20#endif
21
22namespace base {
23namespace debug {
24
25// Enables stack dump to console output on exception and signals.
26// When enabled, the process will quit immediately. This is meant to be used in
27// unit_tests only! This is not thread-safe: only call from main thread.
28BASE_EXPORT bool EnableInProcessStackDumping();
29
30// A different version of EnableInProcessStackDumping that also works for
31// sandboxed processes.  For more details take a look at the description
32// of EnableInProcessStackDumping.
33// Calling this function on Linux opens /proc/self/maps and caches its
34// contents. In DEBUG builds, this function also opens the object files that
35// are loaded in memory and caches their file descriptors (this cannot be
36// done in official builds because it has security implications).
37BASE_EXPORT bool EnableInProcessStackDumpingForSandbox();
38
39// A stacktrace can be helpful in debugging. For example, you can include a
40// stacktrace member in a object (probably around #ifndef NDEBUG) so that you
41// can later see where the given object was created from.
42class BASE_EXPORT StackTrace {
43 public:
44  // Creates a stacktrace from the current location.
45  StackTrace();
46
47  // Creates a stacktrace from an existing array of instruction
48  // pointers (such as returned by Addresses()).  |count| will be
49  // trimmed to |kMaxTraces|.
50  StackTrace(const void* const* trace, size_t count);
51
52#if defined(OS_WIN)
53  // Creates a stacktrace for an exception.
54  // Note: this function will throw an import not found (StackWalk64) exception
55  // on system without dbghelp 5.1.
56  StackTrace(const _EXCEPTION_POINTERS* exception_pointers);
57#endif
58
59  // Copying and assignment are allowed with the default functions.
60
61  ~StackTrace();
62
63  // Gets an array of instruction pointer values. |*count| will be set to the
64  // number of elements in the returned array.
65  const void* const* Addresses(size_t* count) const;
66
67  // Prints the stack trace to stderr.
68  void Print() const;
69
70#if !defined(__UCLIBC__)
71  // Resolves backtrace to symbols and write to stream.
72  void OutputToStream(std::ostream* os) const;
73#endif
74
75  // Resolves backtrace to symbols and returns as string.
76  std::string ToString() const;
77
78 private:
79  // From http://msdn.microsoft.com/en-us/library/bb204633.aspx,
80  // the sum of FramesToSkip and FramesToCapture must be less than 63,
81  // so set it to 62. Even if on POSIX it could be a larger value, it usually
82  // doesn't give much more information.
83  static const int kMaxTraces = 62;
84
85  void* trace_[kMaxTraces];
86
87  // The number of valid frames in |trace_|.
88  size_t count_;
89};
90
91namespace internal {
92
93#if defined(OS_POSIX) && !defined(OS_ANDROID)
94// POSIX doesn't define any async-signal safe function for converting
95// an integer to ASCII. We'll have to define our own version.
96// itoa_r() converts a (signed) integer to ASCII. It returns "buf", if the
97// conversion was successful or NULL otherwise. It never writes more than "sz"
98// bytes. Output will be truncated as needed, and a NUL character is always
99// appended.
100BASE_EXPORT char *itoa_r(intptr_t i,
101                         char *buf,
102                         size_t sz,
103                         int base,
104                         size_t padding);
105#endif  // defined(OS_POSIX) && !defined(OS_ANDROID)
106
107}  // namespace internal
108
109}  // namespace debug
110}  // namespace base
111
112#endif  // BASE_DEBUG_STACK_TRACE_H_
113