1// Copyright (c) 2005, Google Inc. 2// All rights reserved. 3// 4// Redistribution and use in source and binary forms, with or without 5// modification, are permitted provided that the following conditions are 6// met: 7// 8// * Redistributions of source code must retain the above copyright 9// notice, this list of conditions and the following disclaimer. 10// * Redistributions in binary form must reproduce the above 11// copyright notice, this list of conditions and the following disclaimer 12// in the documentation and/or other materials provided with the 13// distribution. 14// * Neither the name of Google Inc. nor the names of its 15// contributors may be used to endorse or promote products derived from 16// this software without specific prior written permission. 17// 18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30// --- 31// Author: Sanjay Ghemawat 32// 33// Routines to extract the current stack trace. These functions are 34// thread-safe. 35 36#ifndef GOOGLE_STACKTRACE_H_ 37#define GOOGLE_STACKTRACE_H_ 38 39// Annoying stuff for windows -- makes sure clients can import these functions 40#ifndef PERFTOOLS_DLL_DECL 41# ifdef _WIN32 42# define PERFTOOLS_DLL_DECL __declspec(dllimport) 43# else 44# define PERFTOOLS_DLL_DECL 45# endif 46#endif 47 48 49// Skips the most recent "skip_count" stack frames (also skips the 50// frame generated for the "GetStackFrames" routine itself), and then 51// records the pc values for up to the next "max_depth" frames in 52// "result", and the corresponding stack frame sizes in "sizes". 53// Returns the number of values recorded in "result"/"sizes". 54// 55// Example: 56// main() { foo(); } 57// foo() { bar(); } 58// bar() { 59// void* result[10]; 60// int sizes[10]; 61// int depth = GetStackFrames(result, sizes, 10, 1); 62// } 63// 64// The GetStackFrames call will skip the frame for "bar". It will 65// return 2 and will produce pc values that map to the following 66// procedures: 67// result[0] foo 68// result[1] main 69// (Actually, there may be a few more entries after "main" to account for 70// startup procedures.) 71// And corresponding stack frame sizes will also be recorded: 72// sizes[0] 16 73// sizes[1] 16 74// (Stack frame sizes of 16 above are just for illustration purposes.) 75// Stack frame sizes of 0 or less indicate that those frame sizes couldn't 76// be identified. 77// 78// This routine may return fewer stack frame entries than are 79// available. Also note that "result" and "sizes" must both be non-NULL. 80extern PERFTOOLS_DLL_DECL int GetStackFrames(void** result, int* sizes, int max_depth, 81 int skip_count); 82 83// Same as above, but to be used from a signal handler. The "uc" parameter 84// should be the pointer to ucontext_t which was passed as the 3rd parameter 85// to sa_sigaction signal handler. It may help the unwinder to get a 86// better stack trace under certain conditions. The "uc" may safely be NULL. 87extern PERFTOOLS_DLL_DECL int GetStackFramesWithContext(void** result, int* sizes, int max_depth, 88 int skip_count, const void *uc); 89 90// This is similar to the GetStackFrames routine, except that it returns 91// the stack trace only, and not the stack frame sizes as well. 92// Example: 93// main() { foo(); } 94// foo() { bar(); } 95// bar() { 96// void* result[10]; 97// int depth = GetStackTrace(result, 10, 1); 98// } 99// 100// This produces: 101// result[0] foo 102// result[1] main 103// .... ... 104// 105// "result" must not be NULL. 106extern PERFTOOLS_DLL_DECL int GetStackTrace(void** result, int max_depth, 107 int skip_count); 108 109// Same as above, but to be used from a signal handler. The "uc" parameter 110// should be the pointer to ucontext_t which was passed as the 3rd parameter 111// to sa_sigaction signal handler. It may help the unwinder to get a 112// better stack trace under certain conditions. The "uc" may safely be NULL. 113extern PERFTOOLS_DLL_DECL int GetStackTraceWithContext(void** result, int max_depth, 114 int skip_count, const void *uc); 115 116#endif /* GOOGLE_STACKTRACE_H_ */ 117