1 /*--------------------------------------------------------------------*/ 2 /*--- Stack traces: getting, traversing, printing. ---*/ 3 /*--- tool_stacktrace.h ---*/ 4 /*--------------------------------------------------------------------*/ 5 6 /* 7 This file is part of Valgrind, a dynamic binary instrumentation 8 framework. 9 10 Copyright (C) 2000-2012 Julian Seward 11 jseward (at) acm.org 12 13 This program is free software; you can redistribute it and/or 14 modify it under the terms of the GNU General Public License as 15 published by the Free Software Foundation; either version 2 of the 16 License, or (at your option) any later version. 17 18 This program is distributed in the hope that it will be useful, but 19 WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 General Public License for more details. 22 23 You should have received a copy of the GNU General Public License 24 along with this program; if not, write to the Free Software 25 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 26 02111-1307, USA. 27 28 The GNU General Public License is contained in the file COPYING. 29 */ 30 31 #ifndef __PUB_TOOL_STACKTRACE_H 32 #define __PUB_TOOL_STACKTRACE_H 33 34 // The basic stack trace type: just an array of code addresses. 35 typedef Addr* StackTrace; 36 37 // Walks the stack to get instruction pointers from the top stack frames 38 // for thread 'tid'. Maximum of 'n_ips' addresses put into 'ips'; 39 // 0 is the top of the stack, 1 is its caller, etc. Everything from 40 // ips[return_value] onwards is undefined and should not be read. 41 // The initial IP value to use is adjusted by first_ip_delta before 42 // the stack is unwound. A safe value to pass is zero. 43 // 44 // The specific meaning of the returned addresses is: 45 // 46 // [0] is the IP of thread 'tid' 47 // [1] points to the last byte of the call instruction that called [0]. 48 // [2] points to the last byte of the call instruction that called [1]. 49 // etc etc 50 // 51 // Hence ips[0 .. return_value-1] should all point to currently 52 // 'active' (in the sense of a stack of unfinished function calls) 53 // instructions. [0] points to the start of an arbitrary instruction.# 54 // [1 ..] point to the last byte of a chain of call instructions. 55 // 56 // If sps and fps are non-NULL, the corresponding frame-pointer and 57 // stack-pointer values for each frame are stored there. 58 59 extern UInt VG_(get_StackTrace) ( ThreadId tid, 60 /*OUT*/StackTrace ips, UInt n_ips, 61 /*OUT*/StackTrace sps, 62 /*OUT*/StackTrace fps, 63 Word first_ip_delta ); 64 65 // Apply a function to every element in the StackTrace. The parameter 66 // 'n' gives the index of the passed ip. 'opaque' is an arbitrary 67 // pointer provided to each invokation of 'action' (a poor man's 68 // closure). Doesn't go below main() unless --show-below-main=yes is 69 // set. 70 extern void VG_(apply_StackTrace)( 71 void(*action)(UInt n, Addr ip, void* opaque), 72 void* opaque, 73 StackTrace ips, UInt n_ips 74 ); 75 76 // Print a StackTrace. 77 extern void VG_(pp_StackTrace) ( StackTrace ips, UInt n_ips ); 78 79 // Gets and immediately prints a StackTrace. Just a bit simpler than 80 // calling VG_(get_StackTrace)() then VG_(pp_StackTrace)(). 81 extern void VG_(get_and_pp_StackTrace) ( ThreadId tid, UInt n_ips ); 82 83 #endif // __PUB_TOOL_STACKTRACE_H 84 85 /*--------------------------------------------------------------------*/ 86 /*--- end ---*/ 87 /*--------------------------------------------------------------------*/ 88