symbolize.h
Go to the documentation of this file.
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 
56 
57 namespace 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 // }
72 void 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 // }
93 bool Symbolize(const void *pc, char *out, int out_size);
94 
95 } // namespace absl
96 
97 #endif // ABSL_DEBUGGING_SYMBOLIZE_H_
void InitializeSymbolizer(const char *argv0)
Definition: algorithm.h:29
char int out_size
Definition: mutex.h:1013
bool Symbolize(const void *pc, char *out, int out_size)
char * out
Definition: mutex.h:1013


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:20