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-2017 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 #include "pub_tool_basics.h" // Addr 35 36 // The basic stack trace type: just an array of code addresses. 37 typedef Addr* StackTrace; 38 39 // Walks the stack to get instruction pointers from the top stack frames 40 // for thread 'tid'. Maximum of 'n_ips' addresses put into 'ips'; 41 // 0 is the top of the stack, 1 is its caller, etc. Everything from 42 // ips[return_value] onwards is undefined and should not be read. 43 // The initial IP value to use is adjusted by first_ip_delta before 44 // the stack is unwound. A safe value to pass is zero. 45 // 46 // The specific meaning of the returned addresses is: 47 // 48 // [0] is the IP of thread 'tid' 49 // [1] points to the last byte of the call instruction that called [0]. 50 // [2] points to the last byte of the call instruction that called [1]. 51 // etc etc 52 // 53 // Hence ips[0 .. return_value-1] should all point to currently 54 // 'active' (in the sense of a stack of unfinished function calls) 55 // instructions. [0] points to the start of an arbitrary instruction.# 56 // [1 ..] point to the last byte of a chain of call instructions. 57 // 58 // If sps and fps are non-NULL, the corresponding frame-pointer and 59 // stack-pointer values for each frame are stored there. 60 61 extern UInt VG_(get_StackTrace) ( ThreadId tid, 62 /*OUT*/StackTrace ips, UInt n_ips, 63 /*OUT*/StackTrace sps, 64 /*OUT*/StackTrace fps, 65 Word first_ip_delta ); 66 67 // Apply a function to every element in the StackTrace. The parameter 68 // 'n' gives the index of the passed ip. 'opaque' is an arbitrary 69 // pointer provided to each invocation of 'action' (a poor man's 70 // closure). Doesn't go below main() unless --show-below-main=yes is 71 // set. 72 extern void VG_(apply_StackTrace)( 73 void(*action)(UInt n, Addr ip, void* opaque), 74 void* opaque, 75 StackTrace ips, UInt n_ips 76 ); 77 78 // Print a StackTrace. 79 extern void VG_(pp_StackTrace) ( StackTrace ips, UInt n_ips ); 80 81 // Gets and immediately prints a StackTrace. Just a bit simpler than 82 // calling VG_(get_StackTrace)() then VG_(pp_StackTrace)(). 83 extern void VG_(get_and_pp_StackTrace) ( ThreadId tid, UInt n_ips ); 84 85 #endif // __PUB_TOOL_STACKTRACE_H 86 87 /*--------------------------------------------------------------------*/ 88 /*--- end ---*/ 89 /*--------------------------------------------------------------------*/ 90
