| // Copyright 2018 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 | |
| // | |
| // https://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. | |
| // | |
| // ----------------------------------------------------------------------------- | |
| // File: stacktrace.h | |
| // ----------------------------------------------------------------------------- | |
| // | |
| // This file contains routines to extract the current stack trace and associated | |
| // stack frames. 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 most cases. (That is, | |
| // this functionality generally only works on platforms/builds that have been | |
| // specifically configured to support it.) | |
| // | |
| // Note: stack traces in Abseil that do not utilize a symbolizer will result in | |
| // frames consisting of function addresses rather than human-readable function | |
| // names. (See symbolize.h for information on symbolizing these values.) | |
| namespace absl { | |
| ABSL_NAMESPACE_BEGIN | |
| // GetStackFrames() | |
| // | |
| // Records program counter values for up to `max_depth` frames, skipping the | |
| // most recent `skip_count` stack frames, stores their corresponding values | |
| // and sizes in `results` and `sizes` buffers, and returns the number of frames | |
| // stored. (Note that the frame generated for the `absl::GetStackFrames()` | |
| // routine itself is also skipped.) | |
| // | |
| // Example: | |
| // | |
| // main() { foo(); } | |
| // foo() { bar(); } | |
| // bar() { | |
| // void* result[10]; | |
| // int sizes[10]; | |
| // int depth = absl::GetStackFrames(result, sizes, 10, 1); | |
| // } | |
| // | |
| // The current stack frame would consist of three function calls: `bar()`, | |
| // `foo()`, and then `main()`; however, since the `GetStackFrames()` call sets | |
| // `skip_count` to `1`, it will skip the frame for `bar()`, the most recently | |
| // invoked function call. It will therefore return 2 and fill `result` with | |
| // program counters within the following functions: | |
| // | |
| // result[0] foo() | |
| // result[1] main() | |
| // | |
| // (Note: in practice, a few more entries after `main()` may be added to account | |
| // for startup processes.) | |
| // | |
| // 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); | |
| // GetStackFramesWithContext() | |
| // | |
| // Records program counter values obtained from a signal handler. Records | |
| // program counter values for up to `max_depth` frames, skipping the most recent | |
| // `skip_count` stack frames, stores their corresponding values and sizes in | |
| // `results` and `sizes` buffers, and returns the number of frames stored. (Note | |
| // that the frame generated for the `absl::GetStackFramesWithContext()` routine | |
| // itself is also skipped.) | |
| // | |
| // The `uc` parameter, if non-null, should be a pointer to a `ucontext_t` value | |
| // passed to a signal handler registered via the `sa_sigaction` field of a | |
| // `sigaction` struct. (See | |
| // http://man7.org/linux/man-pages/man2/sigaction.2.html.) The `uc` value may | |
| // help a stack unwinder to provide a better stack trace under certain | |
| // conditions. `uc` may safely be null. | |
| // | |
| // The `min_dropped_frames` output parameter, if non-null, points to the | |
| // location to note any dropped stack frames, if any, due to buffer limitations | |
| // or other reasons. (This value will be set to `0` if no frames were dropped.) | |
| // The number of total 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); | |
| // GetStackTrace() | |
| // | |
| // Records program counter values for up to `max_depth` frames, skipping the | |
| // most recent `skip_count` stack frames, stores their corresponding values | |
| // in `results`, and returns the number of frames | |
| // stored. Note that this function is similar to `absl::GetStackFrames()` | |
| // except that it returns the stack trace only, and not stack frame sizes. | |
| // | |
| // 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); | |
| // GetStackTraceWithContext() | |
| // | |
| // Records program counter values obtained from a signal handler. Records | |
| // program counter values for up to `max_depth` frames, skipping the most recent | |
| // `skip_count` stack frames, stores their corresponding values in `results`, | |
| // and returns the number of frames stored. (Note that the frame generated for | |
| // the `absl::GetStackFramesWithContext()` routine itself is also skipped.) | |
| // | |
| // The `uc` parameter, if non-null, should be a pointer to a `ucontext_t` value | |
| // passed to a signal handler registered via the `sa_sigaction` field of a | |
| // `sigaction` struct. (See | |
| // http://man7.org/linux/man-pages/man2/sigaction.2.html.) The `uc` value may | |
| // help a stack unwinder to provide a better stack trace under certain | |
| // conditions. `uc` may safely be null. | |
| // | |
| // The `min_dropped_frames` output parameter, if non-null, points to the | |
| // location to note any dropped stack frames, if any, due to buffer limitations | |
| // or other reasons. (This value will be set to `0` if no frames were dropped.) | |
| // The number of total 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); | |
| // SetStackUnwinder() | |
| // | |
| // Provides a custom function for unwinding stack frames that will be used in | |
| // place of the default stack unwinder when invoking 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 set to null, we revert to the default stack-tracing behavior. | |
| // | |
| // ***************************************************************************** | |
| // WARNING | |
| // ***************************************************************************** | |
| // | |
| // 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)); | |
| // DefaultStackUnwinder() | |
| // | |
| // Records program counter values of up to `max_depth` frames, skipping the most | |
| // recent `skip_count` stack frames, and stores their corresponding values in | |
| // `pcs`. (Note that the frame generated for this call itself is also skipped.) | |
| // This function acts as a generic stack-unwinder; prefer usage of the more | |
| // specific `GetStack{Trace,Frames}{,WithContext}()` functions above. | |
| // | |
| // If you have set your own stack unwinder (with the `SetStackUnwinder()` | |
| // function above, you can still get the default stack unwinder by calling | |
| // `DefaultStackUnwinder()`, which will ignore any previously set stack unwinder | |
| // and use the default one instead. | |
| // | |
| // Because this function is generic, only `pcs` is guaranteed to be non-null | |
| // upon return. It is legal for `sizes`, `uc`, and `min_dropped_frames` to all | |
| // be null when called. | |
| // | |
| // 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 | |
| ABSL_NAMESPACE_END | |
| } // namespace absl | |