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
57namespace absl {
58
59// InitializeSymbolizer()
60//
61// Initializes the program counter symbolizer, given the path of the program
62// (typically obtained through `main()`s `argv[0]`). The Abseil symbolizer
63// allows you to read program counters (instruction pointer values) using their
64// human-readable names within output such as stack traces.
65//
66// Example:
67//
68// int main(int argc, char *argv[]) {
69// absl::InitializeSymbolizer(argv[0]);
70// // Now you can use the symbolizer
71// }
72void InitializeSymbolizer(const char* argv0);
73
74// Symbolize()
75//
76// Symbolizes a program counter (instruction pointer value) `pc` and, on
77// success, writes the name to `out`. The symbol name is demangled, if possible.
78// Note that the symbolized name may be truncated and will be NUL-terminated.
79// Demangling is supported for symbols generated by GCC 3.x or newer). Returns
80// `false` on failure.
81//
82// Example:
83//
84// // Print a program counter and its symbol name.
85// static void DumpPCAndSymbol(void *pc) {
86// char tmp[1024];
87// const char *symbol = "(unknown)";
88// if (absl::Symbolize(pc, tmp, sizeof(tmp))) {
89// symbol = tmp;
90// }
91// absl::PrintF("%*p %s\n", pc, symbol);
92// }
93bool Symbolize(const void *pc, char *out, int out_size);
94
95} // namespace absl
96
97#endif // ABSL_DEBUGGING_SYMBOLIZE_H_
98