text: // 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.)
  
  #ifndef ABSL_DEBUGGING_STACKTRACE_H_
  #define ABSL_DEBUGGING_STACKTRACE_H_
  
  namespace absl {
  
  // 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
  }  // namespace absl
  
  #endif  // ABSL_DEBUGGING_STACKTRACE_H_
  