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 stacktrace can be helpful in debugging. For example, you can include a
31// stacktrace member in a object (probably around #ifndef NDEBUG) so that you
32// can later see where the given object was created from.
33class BASE_EXPORT StackTrace {
34 public:
35  // Creates a stacktrace from the current location.
36  StackTrace();
37
38  // Creates a stacktrace from an existing array of instruction
39  // pointers (such as returned by Addresses()).  |count| will be
40  // trimmed to |kMaxTraces|.
41  StackTrace(const void* const* trace, size_t count);
42
43#if defined(OS_WIN)
44  // Creates a stacktrace for an exception.
45  // Note: this function will throw an import not found (StackWalk64) exception
46  // on system without dbghelp 5.1.
47  StackTrace(_EXCEPTION_POINTERS* exception_pointers);
48#endif
49
50  // Copying and assignment are allowed with the default functions.
51
52  ~StackTrace();
53
54  // Gets an array of instruction pointer values. |*count| will be set to the
55  // number of elements in the returned array.
56  const void* const* Addresses(size_t* count) const;
57
58  // Prints a backtrace to stderr
59  void PrintBacktrace() const;
60
61  // Resolves backtrace to symbols and write to stream.
62  void OutputToStream(std::ostream* os) const;
63
64  // Resolves backtrace to symbols and returns as string.
65  std::string ToString() const;
66
67 private:
68  // From http://msdn.microsoft.com/en-us/library/bb204633.aspx,
69  // the sum of FramesToSkip and FramesToCapture must be less than 63,
70  // so set it to 62. Even if on POSIX it could be a larger value, it usually
71  // doesn't give much more information.
72  static const int kMaxTraces = 62;
73
74  void* trace_[kMaxTraces];
75
76  // The number of valid frames in |trace_|.
77  size_t count_;
78};
79
80namespace internal {
81
82#if defined(OS_POSIX) && !defined(OS_ANDROID)
83// POSIX doesn't define any async-signal safe function for converting
84// an integer to ASCII. We'll have to define our own version.
85// itoa_r() converts a (signed) integer to ASCII. It returns "buf", if the
86// conversion was successful or NULL otherwise. It never writes more than "sz"
87// bytes. Output will be truncated as needed, and a NUL character is always
88// appended.
89BASE_EXPORT char *itoa_r(intptr_t i,
90                         char *buf,
91                         size_t sz,
92                         int base,
93                         size_t padding);
94#endif  // defined(OS_POSIX) && !defined(OS_ANDROID)
95
96}  // namespace internal
97
98}  // namespace debug
99}  // namespace base
100
101#endif  // BASE_DEBUG_STACK_TRACE_H_
102