absl/debugging/symbolize.h

0001 // Copyright 2018 The Abseil Authors.
0002 //
0003 // Licensed under the Apache License, Version 2.0 (the "License");
0004 // you may not use this file except in compliance with the License.
0005 // You may obtain a copy of the License at
0006 //
0007 //      https://www.apache.org/licenses/LICENSE-2.0
0008 //
0009 // Unless required by applicable law or agreed to in writing, software
0010 // distributed under the License is distributed on an "AS IS" BASIS,
0011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0012 // See the License for the specific language governing permissions and
0013 // limitations under the License.
0014 //
0015 // -----------------------------------------------------------------------------
0016 // File: symbolize.h
0017 // -----------------------------------------------------------------------------
0018 //
0019 // This file configures the Abseil symbolizer for use in converting instruction
0020 // pointer addresses (program counters) into human-readable names (function
0021 // calls, etc.) within Abseil code.
0022 //
0023 // The symbolizer may be invoked from several sources:
0024 //
0025 //   * Implicitly, through the installation of an Abseil failure signal handler.
0026 //     (See failure_signal_handler.h for more information.)
0027 //   * By calling `Symbolize()` directly on a program counter you obtain through
0028 //     `absl::GetStackTrace()` or `absl::GetStackFrames()`. (See stacktrace.h
0029 //     for more information.
0030 //   * By calling `Symbolize()` directly on a program counter you obtain through
0031 //     other means (which would be platform-dependent).
0032 //
0033 // In all of the above cases, the symbolizer must first be initialized before
0034 // any program counter values can be symbolized. If you are installing a failure
0035 // signal handler, initialize the symbolizer before you do so.
0036 //
0037 // Example:
0038 //
0039 //   int main(int argc, char** argv) {
0040 //     // Initialize the Symbolizer before installing the failure signal handler
0041 //     absl::InitializeSymbolizer(argv[0]);
0042 //
0043 //     // Now you may install the failure signal handler
0044 //     absl::FailureSignalHandlerOptions options;
0045 //     absl::InstallFailureSignalHandler(options);
0046 //
0047 //     // Start running your main program
0048 //     ...
0049 //     return 0;
0050 //  }
0051 //
0052 #ifndef ABSL_DEBUGGING_SYMBOLIZE_H_
0053 #define ABSL_DEBUGGING_SYMBOLIZE_H_
0054
0055 #include "absl/debugging/internal/symbolize.h"
0056
0057 namespace absl {
0058 ABSL_NAMESPACE_BEGIN
0059
0060 // InitializeSymbolizer()
0061 //
0062 // Initializes the program counter symbolizer, given the path of the program
0063 // (typically obtained through `main()`s `argv[0]`). The Abseil symbolizer
0064 // allows you to read program counters (instruction pointer values) using their
0065 // human-readable names within output such as stack traces.
0066 //
0067 // Example:
0068 //
0069 // int main(int argc, char *argv[]) {
0070 //   absl::InitializeSymbolizer(argv[0]);
0071 //   // Now you can use the symbolizer
0072 // }
0073 void InitializeSymbolizer(const char* argv0);
0074 //
0075 // Symbolize()
0076 //
0077 // Symbolizes a program counter (instruction pointer value) `pc` and, on
0078 // success, writes the name to `out`. The symbol name is demangled, if possible.
0079 // Note that the symbolized name may be truncated and will be NUL-terminated.
0080 // Demangling is supported for symbols generated by GCC 3.x or newer). Returns
0081 // `false` on failure.
0082 //
0083 // Example:
0084 //
0085 //   // Print a program counter and its symbol name.
0086 //   static void DumpPCAndSymbol(void *pc) {
0087 //     char tmp[1024];
0088 //     const char *symbol = "(unknown)";
0089 //     if (absl::Symbolize(pc, tmp, sizeof(tmp))) {
0090 //       symbol = tmp;
0091 //     }
0092 //     absl::PrintF("%p  %s\n", pc, symbol);
0093 //  }
0094 bool Symbolize(const void *pc, char *out, int out_size);
0095
0096 ABSL_NAMESPACE_END
0097 }  // namespace absl
0098
0099 #endif  // ABSL_DEBUGGING_SYMBOLIZE_H_