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 <stddef.h>
9
10#include <iosfwd>
11#include <string>
12
13#include "base/base_export.h"
14#include "build/build_config.h"
15
16#if defined(OS_POSIX)
17#include <unistd.h>
18#endif
19
20#if defined(OS_WIN)
21struct _EXCEPTION_POINTERS;
22struct _CONTEXT;
23#endif
24
25namespace base {
26namespace debug {
27
28// Enables stack dump to console output on exception and signals.
29// When enabled, the process will quit immediately. This is meant to be used in
30// unit_tests only! This is not thread-safe: only call from main thread.
31// In sandboxed processes, this has to be called before the sandbox is turned
32// on.
33// Calling this function on Linux opens /proc/self/maps and caches its
34// contents. In non-official builds, this function also opens the object files
35// that 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 EnableInProcessStackDumping();
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(_EXCEPTION_POINTERS* exception_pointers);
57  StackTrace(const _CONTEXT* context);
58#endif
59
60  // Copying and assignment are allowed with the default functions.
61
62  ~StackTrace();
63
64  // Gets an array of instruction pointer values. |*count| will be set to the
65  // number of elements in the returned array.
66  const void* const* Addresses(size_t* count) const;
67
68  // Prints the stack trace to stderr.
69  void Print() const;
70
71#if !defined(__UCLIBC__)
72  // Resolves backtrace to symbols and write to stream.
73  void OutputToStream(std::ostream* os) const;
74#endif
75
76  // Resolves backtrace to symbols and returns as string.
77  std::string ToString() const;
78
79 private:
80#if defined(OS_WIN)
81  void InitTrace(const _CONTEXT* context_record);
82#endif
83
84  // From http://msdn.microsoft.com/en-us/library/bb204633.aspx,
85  // the sum of FramesToSkip and FramesToCapture must be less than 63,
86  // so set it to 62. Even if on POSIX it could be a larger value, it usually
87  // doesn't give much more information.
88  static const int kMaxTraces = 62;
89
90  void* trace_[kMaxTraces];
91
92  // The number of valid frames in |trace_|.
93  size_t count_;
94};
95
96namespace internal {
97
98#if defined(OS_POSIX) && !defined(OS_ANDROID)
99// POSIX doesn't define any async-signal safe function for converting
100// an integer to ASCII. We'll have to define our own version.
101// itoa_r() converts a (signed) integer to ASCII. It returns "buf", if the
102// conversion was successful or NULL otherwise. It never writes more than "sz"
103// bytes. Output will be truncated as needed, and a NUL character is always
104// appended.
105BASE_EXPORT char *itoa_r(intptr_t i,
106                         char *buf,
107                         size_t sz,
108                         int base,
109                         size_t padding);
110#endif  // defined(OS_POSIX) && !defined(OS_ANDROID)
111
112}  // namespace internal
113
114}  // namespace debug
115}  // namespace base
116
117#endif  // BASE_DEBUG_STACK_TRACE_H_
118