summaryrefslogtreecommitdiff
path: root/absl/debugging/symbolize.h
diff options
context:
space:
mode:
Diffstat (limited to 'absl/debugging/symbolize.h')
-rw-r--r--absl/debugging/symbolize.h78
1 files changed, 70 insertions, 8 deletions
diff --git a/absl/debugging/symbolize.h b/absl/debugging/symbolize.h
index 073a4479..24e6e647 100644
--- a/absl/debugging/symbolize.h
+++ b/absl/debugging/symbolize.h
@@ -11,7 +11,44 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
-
+//
+// -----------------------------------------------------------------------------
+// File: symbolize.h
+// -----------------------------------------------------------------------------
+//
+// This file configures the Abseil symbolizer for use in converting instruction
+// pointer addresses (program counters) into human-readable names (function
+// calls, etc.) within Abseil code.
+//
+// The symbolizer may be invoked from several sources:
+//
+// * Implicitly, through the installation of an Abseil failure signal handler.
+// (See failure_signal_handler.h for more information.)
+// * By calling `Symbolize()` directly on a program counter you obtain through
+// `absl::GetStackTrace()` or `absl::GetStackFrames()`. (See stacktrace.h
+// for more information.
+// * By calling `Symbolize()` directly on a program counter you obtain through
+// other means (which would be platform-dependent).
+//
+// In all of the above cases, the symbolizer must first be initialized before
+// any program counter values can be symbolized. If you are installing a failure
+// signal handler, initialize the symbolizer before you do so.
+//
+// Example:
+//
+// int main(int argc, char** argv) {
+// // Initialize the Symbolizer before installing the failure signal handler
+// absl::InitializeSymbolizer(argv[0]);
+//
+// // Now you may install the failure signal handler
+// absl::FailureSignalHandlerOptions options;
+// absl::InstallFailureSignalHandler(options);
+//
+// // Start running your main program
+// ...
+// return 0;
+// }
+//
#ifndef ABSL_DEBUGGING_SYMBOLIZE_H_
#define ABSL_DEBUGGING_SYMBOLIZE_H_
@@ -19,15 +56,40 @@
namespace absl {
-// Initializes this module. Symbolize() may fail prior calling this function.
-// `argv0` is the path to this program, which is usually obtained in main()
-// though argv[0].
+// InitializeSymbolizer()
+//
+// Initializes the program counter symbolizer, given the path of the program
+// (typically obtained through `main()`s `argv[0]`). The Abseil symbolizer
+// allows you to read program counters (instruction pointer values) using their
+// human-readable names within output such as stack traces.
+//
+// Example:
+//
+// int main(int argc, char *argv[]) {
+// absl::InitializeSymbolizer(argv[0]);
+// // Now you can use the symbolizer
+// }
void InitializeSymbolizer(const char* argv0);
-// Symbolizes a program counter. On success, returns true and write the
-// symbol name to "out". The symbol name is demangled if possible
-// (supports symbols generated by GCC 3.x or newer), may be truncated, and
-// will be '\0' terminated. Otherwise, returns false.
+// Symbolize()
+//
+// Symbolizes a program counter (instruction pointer value) `pc` and, on
+// success, writes the name to `out`. The symbol name is demangled, if possible.
+// Note that the symbolized name may be truncated and will be NUL-terminated.
+// Demangling is supported for symbols generated by GCC 3.x or newer). Returns
+// `false` on failure.
+//
+// Example:
+//
+// // Print a program counter and its symbol name.
+// static void DumpPCAndSymbol(void *pc) {
+// char tmp[1024];
+// const char *symbol = "(unknown)";
+// if (absl::Symbolize(pc, tmp, sizeof(tmp))) {
+// symbol = tmp;
+// }
+// absl::PrintF("%*p %s\n", pc, symbol);
+// }
bool Symbolize(const void *pc, char *out, int out_size);
} // namespace absl