debugging/internal/examine_stack.h

0001 //
0002 // Copyright 2018 The Abseil Authors.
0003 //
0004 // Licensed under the Apache License, Version 2.0 (the "License");
0005 // you may not use this file except in compliance with the License.
0006 // You may obtain a copy of the License at
0007 //
0008 //      https://www.apache.org/licenses/LICENSE-2.0
0009 //
0010 // Unless required by applicable law or agreed to in writing, software
0011 // distributed under the License is distributed on an "AS IS" BASIS,
0012 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013 // See the License for the specific language governing permissions and
0014 // limitations under the License.
0015 //
0016
0017 #ifndef ABSL_DEBUGGING_INTERNAL_EXAMINE_STACK_H_
0018 #define ABSL_DEBUGGING_INTERNAL_EXAMINE_STACK_H_
0019
0020 #include "absl/base/config.h"
0021
0022 namespace absl {
0023 ABSL_NAMESPACE_BEGIN
0024 namespace debugging_internal {
0025
0026 // Type of function used for printing in stack trace dumping, etc.
0027 // We avoid closures to keep things simple.
0028 typedef void OutputWriter(const char*, void*);
0029
0030 // RegisterDebugStackTraceHook() allows to register a single routine
0031 // `hook` that is called each time DumpStackTrace() is called.
0032 // `hook` may be called from a signal handler.
0033 typedef void (*SymbolizeUrlEmitter)(void* const stack[], int depth,
0034                                     OutputWriter* writer, void* writer_arg);
0035
0036 // Registration of SymbolizeUrlEmitter for use inside of a signal handler.
0037 // This is inherently unsafe and must be signal safe code.
0038 void RegisterDebugStackTraceHook(SymbolizeUrlEmitter hook);
0039 SymbolizeUrlEmitter GetDebugStackTraceHook();
0040
0041 // Returns the program counter from signal context, or nullptr if
0042 // unknown. `vuc` is a ucontext_t*. We use void* to avoid the use of
0043 // ucontext_t on non-POSIX systems.
0044 void* GetProgramCounter(void* const vuc);
0045
0046 // Uses `writer` to dump the program counter, stack trace, and stack
0047 // frame sizes.
0048 void DumpPCAndFrameSizesAndStackTrace(void* const pc, void* const stack[],
0049                                       int frame_sizes[], int depth,
0050                                       int min_dropped_frames,
0051                                       bool symbolize_stacktrace,
0052                                       OutputWriter* writer, void* writer_arg);
0053
0054 // Dump current stack trace omitting the topmost `min_dropped_frames` stack
0055 // frames.
0056 void DumpStackTrace(int min_dropped_frames, int max_num_frames,
0057                     bool symbolize_stacktrace, OutputWriter* writer,
0058                     void* writer_arg);
0059
0060 }  // namespace debugging_internal
0061 ABSL_NAMESPACE_END
0062 }  // namespace absl
0063
0064 #endif  // ABSL_DEBUGGING_INTERNAL_EXAMINE_STACK_H_