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-2011 Julian Seward 11 jseward@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. 35typedef 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 59extern 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. 70extern 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. 77extern 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)(). 81extern void VG_(get_and_pp_StackTrace) ( ThreadId tid, UInt n_ips ); 82 83#endif // __PUB_TOOL_STACKTRACE_H 84 85/*--------------------------------------------------------------------*/ 86/*--- end ---*/ 87/*--------------------------------------------------------------------*/ 88