docs/latex/wx/stackwalker.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        stackwalker.tex
   3 %% Purpose:     wxStackWalker documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Created:     2005-01-19
   6 %% RCS-ID:      $Id$
   7 %% Copyright:   (c) 2005 Vadim Zeitlin
   8 %% License:     wxWindows license
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 \section{\class{wxStackWalker}}\label{wxstackwalker}
  12
  13 wxStackWalker allows an application to enumerate, or walk, the stack frames (the function callstack).
  14 It is mostly useful in only two situations:
  15 inside \helpref{wxApp::OnFatalException}{wxapponfatalexception} function to
  16 programmatically get the location of the crash and, in debug builds, in
  17 \helpref{wxApp::OnAssertFailure}{wxapponassertfailure} to report the caller of the failed
  18 assert.
  19
  20 wxStackWalker works by repeatedly calling
  21 the \helpref{OnStackFrame}{wxstackwalkeronstackframe} method for each frame in the
  22 stack, so to use it you must derive your own class from it and override this
  23 method.
  24
  25 This class will not return anything except raw stack frame addresses if the
  26 debug information is not available. Under Win32 this means that the PDB file
  27 matching the program being executed should be present. Note that if you use
  28 Microsoft Visual C++ compiler, you can create PDB files even for the programs
  29 built in release mode and it doesn't affect the program size (at least if you
  30 don't forget to add \texttt{/opt:ref} option which is suppressed by using
  31 \texttt{/debug} linker option by default but should be always enabled for
  32 release builds). Under Unix, you need to compile your program with debugging
  33 information (usually using \texttt{-g} compiler and linker options) to get the
  34 file and line numbers information, however function names should be available
  35 even without it. Of course, all this is only true if you build using a recent
  36 enough version of GNU libc which provides the \texttt{backtrace()} function
  37 needed to walk the stack.
  38
  39 \helpref{debugging overview}{debuggingoverview} for how to make it available.
  40
  41 \wxheading{Derived from}
  42
  43 No base class
  44
  45 \wxheading{Include files}
  46
  47 <wx/stackwalk.h>
  48
  49 Only available if \texttt{wxUSE\_STACKWALKER} is $1$, currently only
  50 implemented for Win32 and Unix versions using recent version of GNU libc.
  51
  52 \wxheading{See also}
  53
  54 \helpref{wxStackFrame}{wxstackframe}
  55
  56
  57 \latexignore{\rtfignore{\wxheading{Members}}}
  58
  59
  60 \membersection{wxStackWalker::wxStackWalker}\label{wxstackwalkerwxstackwalker}
  61
  62 \func{}{wxStackWalker}{\void}
  63
  64 Constructor does nothing, use \helpref{Walk()}{wxstackwalkerwalk} to walk the
  65 stack.
  66
  67
  68 \membersection{wxStackWalker::\destruct{wxStackWalker}}\label{wxstackwalkerdtor}
  69
  70 \func{}{\destruct{wxStackWalker}}{\void}
  71
  72 Destructor does nothing neither but should be virtual as this class is used as
  73 a base one.
  74
  75
  76 \membersection{wxStackWalker::OnStackFrame}\label{wxstackwalkeronstackframe}
  77
  78 \func{void}{OnStackFrame}{\param{const wxStackFrame\& }{frame}}
  79
  80 This function must be overrided to process the given frame.
  81
  82
  83 \membersection{wxStackWalker::Walk}\label{wxstackwalkerwalk}
  84
  85 \func{void}{Walk}{\param{size\_t }{skip = 1}}
  86
  87 Enumerate stack frames from the current location, skipping the initial
  88 number of them (this can be useful when Walk() is called from some known
  89 location and you don't want to see the first few frames anyhow; also
  90 notice that Walk() frame itself is not included if skip $\ge 1$).
  91
  92
  93 \membersection{wxStackWalker::WalkFromException}\label{wxstackwalkerwalkfromexception}
  94
  95 \func{void}{WalkFromException}{\void}
  96
  97 Enumerate stack frames from the location of uncaught exception.
  98 This method can only be called from
  99 \helpref{wxApp::OnFatalException()}{wxapponfatalexception}.