232 lines
10 KiB
C
232 lines
10 KiB
C
|
// 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_
|
||
|
|
|
||
|
|
#include "absl/base/config.h"
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
#endif // ABSL_DEBUGGING_STACKTRACE_H_
|