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); 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