include/valgrind/pub_tool_stacktrace.h

0001 /*--------------------------------------------------------------------*/
0002 /*--- Stack traces: getting, traversing, printing.                 ---*/
0003 /*---                                            tool_stacktrace.h ---*/
0004 /*--------------------------------------------------------------------*/
0005
0006 /*
0007    This file is part of Valgrind, a dynamic binary instrumentation
0008    framework.
0009
0010    Copyright (C) 2000-2017 Julian Seward
0011       jseward@acm.org
0012
0013    This program is free software; you can redistribute it and/or
0014    modify it under the terms of the GNU General Public License as
0015    published by the Free Software Foundation; either version 2 of the
0016    License, or (at your option) any later version.
0017
0018    This program is distributed in the hope that it will be useful, but
0019    WITHOUT ANY WARRANTY; without even the implied warranty of
0020    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0021    General Public License for more details.
0022
0023    You should have received a copy of the GNU General Public License
0024    along with this program; if not, see <http://www.gnu.org/licenses/>.
0025
0026    The GNU General Public License is contained in the file COPYING.
0027 */
0028
0029 #ifndef __PUB_TOOL_STACKTRACE_H
0030 #define __PUB_TOOL_STACKTRACE_H
0031
0032 #include "pub_tool_basics.h"   // Addr, DiEpoch
0033
0034 // The basic stack trace type:  just an array of code addresses.
0035 typedef Addr* StackTrace;
0036
0037 // Walks the stack to get instruction pointers from the top stack frames
0038 // for thread 'tid'.  Maximum of 'n_ips' addresses put into 'ips';
0039 // 0 is the top of the stack, 1 is its caller, etc.  Everything from
0040 // ips[return_value] onwards is undefined and should not be read.
0041 // The initial IP value to use is adjusted by first_ip_delta before
0042 // the stack is unwound. A safe value to pass is zero.
0043 //
0044 // The specific meaning of the returned addresses is:
0045 //
0046 // [0] is the IP of thread 'tid'
0047 // [1] points to the last byte of the call instruction that called [0].
0048 // [2] points to the last byte of the call instruction that called [1].
0049 // etc etc
0050 //
0051 // Hence ips[0 .. return_value-1] should all point to currently
0052 // 'active' (in the sense of a stack of unfinished function calls)
0053 // instructions.  [0] points to the start of an arbitrary instruction.#
0054 // [1 ..] point to the last byte of a chain of call instructions.
0055 //
0056 // If sps and fps are non-NULL, the corresponding frame-pointer and
0057 // stack-pointer values for each frame are stored there.
0058
0059 extern UInt VG_(get_StackTrace) ( ThreadId tid,
0060                                   /*OUT*/StackTrace ips, UInt n_ips,
0061                                   /*OUT*/StackTrace sps,
0062                                   /*OUT*/StackTrace fps,
0063                                   Word first_ip_delta );
0064
0065 // Same as VG_(get_StackTrace), but applies a delta to the first SP used for
0066 //  unwinding the first frame.
0067 extern UInt VG_(get_StackTrace_with_deltas)(
0068                 ThreadId tid,
0069                 /*OUT*/StackTrace ips, UInt n_ips,
0070                 /*OUT*/StackTrace sps,
0071                 /*OUT*/StackTrace fps,
0072                 Word first_ip_delta,
0073                 Word first_sp_delta
0074              );
0075
0076 // Apply a function to every element in the StackTrace.  The parameter 'n'
0077 // gives the index of the passed ip.  'opaque' is an arbitrary pointer
0078 // provided to each invocation of 'action' (a poor man's closure).  'ep' is
0079 // the debuginfo epoch assumed to apply to all code addresses in the stack
0080 // trace.  Doesn't go below main() unless --show-below-main=yes is set.
0081 extern void VG_(apply_StackTrace)(
0082                void(*action)(UInt n, DiEpoch ep, Addr ip, void* opaque),
0083                void* opaque,
0084                DiEpoch ep, StackTrace ips, UInt n_ips
0085             );
0086
0087 // Print a StackTrace.
0088 extern void VG_(pp_StackTrace) ( DiEpoch ep, StackTrace ips, UInt n_ips );
0089
0090 // Gets and immediately prints a StackTrace.  Just a bit simpler than
0091 // calling VG_(get_StackTrace)() then VG_(pp_StackTrace)().
0092 extern void VG_(get_and_pp_StackTrace) ( ThreadId tid, UInt n_ips );
0093
0094 #endif   // __PUB_TOOL_STACKTRACE_H
0095
0096 /*--------------------------------------------------------------------*/
0097 /*--- end                                                          ---*/
0098 /*--------------------------------------------------------------------*/