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. 80 extern 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. 87 extern 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. 106 extern 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. 113 extern PERFTOOLS_DLL_DECL int GetStackTraceWithContext(void** result, int max_depth, 114 int skip_count, const void *uc); 115 116 #endif /* GOOGLE_STACKTRACE_H_ */ 117
