| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167 | //// Copyright 2017 The Abseil Authors.//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at////      http://www.apache.org/licenses/LICENSE-2.0//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// 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.//// Routines to extract the current stack trace. These functions are// thread-safe and async-signal-safe.// Note that stack trace functionality is platform dependent and requires// additional support from the compiler/build system in many cases. (That is,// this generally only works on platforms/builds that have been specifically// configured to support it.)#ifndef ABSL_DEBUGGING_STACKTRACE_H_#define ABSL_DEBUGGING_STACKTRACE_H_namespace absl {// Skips the most recent "skip_count" stack frames (also skips the// frame generated for the "absl::GetStackFrames" routine itself), and then// records the pc values for up to the next "max_depth" frames in// "result", and the corresponding stack frame sizes in "sizes".// Returns the number of values recorded in "result"/"sizes".//// Example://      main() { foo(); }//      foo() { bar(); }//      bar() {//        void* result[10];//        int sizes[10];//        int depth = absl::GetStackFrames(result, sizes, 10, 1);//      }//// The absl::GetStackFrames call will skip the frame for "bar".  It will// return 2 and will produce pc values that map to the following// procedures://      result[0]       foo//      result[1]       main// (Actually, there may be a few more entries after "main" to account for// startup procedures.)// And corresponding stack frame sizes will also be recorded://    sizes[0]       16//    sizes[1]       16// (Stack frame sizes of 16 above are just for illustration purposes.)// Stack frame sizes of 0 or less indicate that those frame sizes couldn't// be identified.//// This routine may return fewer stack frame entries than are// available. Also note that "result" and "sizes" must both be non-null.extern int GetStackFrames(void** result, int* sizes, int max_depth,                          int skip_count);// Same as above, but to be used from a signal handler. The "uc" parameter// should be the pointer to ucontext_t which was passed as the 3rd parameter// to sa_sigaction signal handler. It may help the unwinder to get a// better stack trace under certain conditions. The "uc" may safely be null.//// If min_dropped_frames is not null, stores in *min_dropped_frames a// lower bound on the number of dropped stack frames. The stored value is// guaranteed to be >= 0. The number of real stack frames is guaranteed to// be >= skip_count + max_depth + *min_dropped_frames.extern int GetStackFramesWithContext(void** result, int* sizes, int max_depth,                                     int skip_count, const void* uc,                                     int* min_dropped_frames);// This is similar to the absl::GetStackFrames routine, except that it returns// the stack trace only, and not the stack frame sizes as well.// Example://      main() { foo(); }//      foo() { bar(); }//      bar() {//        void* result[10];//        int depth = absl::GetStackTrace(result, 10, 1);//      }//// This produces://      result[0]       foo//      result[1]       main//           ....       ...//// "result" must not be null.extern int GetStackTrace(void** result, int max_depth, int skip_count);// Same as above, but to be used from a signal handler. The "uc" parameter// should be the pointer to ucontext_t which was passed as the 3rd parameter// to sa_sigaction signal handler. It may help the unwinder to get a// better stack trace under certain conditions. The "uc" may safely be null.//// If min_dropped_frames is not null, stores in *min_dropped_frames a// lower bound on the number of dropped stack frames. The stored value is// guaranteed to be >= 0. The number of real stack frames is guaranteed to// be >= skip_count + max_depth + *min_dropped_frames.extern int GetStackTraceWithContext(void** result, int max_depth,                                    int skip_count, const void* uc,                                    int* min_dropped_frames);// Call this to provide a custom function for unwinding stack frames// that will be used every time someone invokes one of the static// GetStack{Frames,Trace}{,WithContext}() functions above.//// The arguments passed to the unwinder function will match the// arguments passed to absl::GetStackFramesWithContext() except that sizes// will be non-null iff the caller is interested in frame sizes.//// If unwinder is null, we revert to the default stack-tracing behavior.//// ****************************************************************// WARNINGS//// absl::SetStackUnwinder is not suitable for general purpose use.  It is// provided for custom runtimes.// Some things to watch out for when calling absl::SetStackUnwinder://// (a) The unwinder may be called from within signal handlers and// therefore must be async-signal-safe.//// (b) Even after a custom stack unwinder has been unregistered, other// threads may still be in the process of using that unwinder.// Therefore do not clean up any state that may be needed by an old// unwinder.// ****************************************************************extern void SetStackUnwinder(int (*unwinder)(void** pcs, int* sizes,                                             int max_depth, int skip_count,                                             const void* uc,                                             int* min_dropped_frames));// Function that exposes built-in stack-unwinding behavior, ignoring// any calls to absl::SetStackUnwinder().//// pcs must NOT be null.//// sizes may be null.// uc may be null.// min_dropped_frames may be null.//// The semantics are the same as the corresponding GetStack*() function in the// case where absl::SetStackUnwinder() was never called.  Equivalents are:////                       null sizes         |        non-nullptr sizes//             |==========================================================|//     null uc | GetStackTrace()            | GetStackFrames()            |// non-null uc | GetStackTraceWithContext() | GetStackFramesWithContext() |//             |==========================================================|extern int DefaultStackUnwinder(void** pcs, int* sizes, int max_depth,                                int skip_count, const void* uc,                                int* min_dropped_frames);namespace debugging_internal {// Returns true for platforms which are expected to have functioning stack trace// implementations. Intended to be used for tests which want to exclude// verification of logic known to be broken because stack traces are not// working.extern bool StackTraceWorksForTest();}  // namespace debugging_internal}  // namespace absl#endif  // ABSL_DEBUGGING_STACKTRACE_H_
 |