1 // Copyright 2018 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // -----------------------------------------------------------------------------
16 // File: symbolize.h
17 // -----------------------------------------------------------------------------
18 //
19 // This file configures the Abseil symbolizer for use in converting instruction
20 // pointer addresses (program counters) into human-readable names (function
21 // calls, etc.) within Abseil code.
22 //
23 // The symbolizer may be invoked from several sources:
24 //
25 // * Implicitly, through the installation of an Abseil failure signal handler.
26 // (See failure_signal_handler.h for more information.)
27 // * By calling `Symbolize()` directly on a program counter you obtain through
28 // `absl::GetStackTrace()` or `absl::GetStackFrames()`. (See stacktrace.h
29 // for more information.
30 // * By calling `Symbolize()` directly on a program counter you obtain through
31 // other means (which would be platform-dependent).
32 //
33 // In all of the above cases, the symbolizer must first be initialized before
34 // any program counter values can be symbolized. If you are installing a failure
35 // signal handler, initialize the symbolizer before you do so.
36 //
37 // Example:
38 //
39 // int main(int argc, char** argv) {
40 // // Initialize the Symbolizer before installing the failure signal handler
41 // absl::InitializeSymbolizer(argv[0]);
42 //
43 // // Now you may install the failure signal handler
44 // absl::FailureSignalHandlerOptions options;
45 // absl::InstallFailureSignalHandler(options);
46 //
47 // // Start running your main program
48 // ...
49 // return 0;
50 // }
51 //
52 #ifndef ABSL_DEBUGGING_SYMBOLIZE_H_
53 #define ABSL_DEBUGGING_SYMBOLIZE_H_
54
55 #include "absl/debugging/internal/symbolize.h"
56
57 namespace absl {
58 ABSL_NAMESPACE_BEGIN
59
60 // InitializeSymbolizer()
61 //
62 // Initializes the program counter symbolizer, given the path of the program
63 // (typically obtained through `main()`s `argv[0]`). The Abseil symbolizer
64 // allows you to read program counters (instruction pointer values) using their
65 // human-readable names within output such as stack traces.
66 //
67 // Example:
68 //
69 // int main(int argc, char *argv[]) {
70 // absl::InitializeSymbolizer(argv[0]);
71 // // Now you can use the symbolizer
72 // }
73 void InitializeSymbolizer(const char* argv0);
74 //
75 // Symbolize()
76 //
77 // Symbolizes a program counter (instruction pointer value) `pc` and, on
78 // success, writes the name to `out`. The symbol name is demangled, if possible.
79 // Note that the symbolized name may be truncated and will be NUL-terminated.
80 // Demangling is supported for symbols generated by GCC 3.x or newer). Returns
81 // `false` on failure.
82 //
83 // Example:
84 //
85 // // Print a program counter and its symbol name.
86 // static void DumpPCAndSymbol(void *pc) {
87 // char tmp[1024];
88 // const char *symbol = "(unknown)";
89 // if (absl::Symbolize(pc, tmp, sizeof(tmp))) {
90 // symbol = tmp;
91 // }
92 // absl::PrintF("%p %s\n", pc, symbol);
main(String args[])93 // }
94 bool Symbolize(const void *pc, char *out, int out_size);
95
96 ABSL_NAMESPACE_END
97 } // namespace absl
98
99 #endif // ABSL_DEBUGGING_SYMBOLIZE_H_
100