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