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-2013 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#include "pub_tool_basics.h" // Addr 35 36// The basic stack trace type: just an array of code addresses. 37typedef 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 61extern 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 invokation of 'action' (a poor man's 70// closure). Doesn't go below main() unless --show-below-main=yes is 71// set. 72extern 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. 79extern 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)(). 83extern void VG_(get_and_pp_StackTrace) ( ThreadId tid, UInt n_ips ); 84 85#endif // __PUB_TOOL_STACKTRACE_H 86 87/*--------------------------------------------------------------------*/ 88/*--- end ---*/ 89/*--------------------------------------------------------------------*/ 90