]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/stackwalk.h
another AIX compilation fix: getservbyname_r() returns int, not servent* there
[wxWidgets.git] / interface / wx / stackwalk.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: stackwalk.h
e54c96f1 3// Purpose: interface of wxStackWalker
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
52499582
FM
9/**
10 This is the default value of the wxStackWalker::Walk function.
11*/
12#define wxSTACKWALKER_MAX_DEPTH (200)
13
23324ae1
FM
14/**
15 @class wxStackWalker
7c913512 16
23324ae1
FM
17 wxStackWalker allows an application to enumerate, or walk, the stack frames
18 (the function callstack).
7c913512 19
4701dc09
FM
20 It is mostly useful in only two situations: inside wxApp::OnFatalException
21 function to programmatically get the location of the crash and, in debug builds,
22 in wxApp::OnAssertFailure to report the caller of the failed assert.
23
24 wxStackWalker works by repeatedly calling the wxStackWalker::OnStackFrame
25 method for each frame in the stack, so to use it you must derive your own
26 class from it and override this method.
7c913512 27
23324ae1
FM
28 This class will not return anything except raw stack frame addresses if the
29 debug information is not available. Under Win32 this means that the PDB file
4701dc09
FM
30 matching the program being executed should be present.
31 Note that if you use Microsoft Visual C++ compiler, you can create PDB files
32 even for the programs built in release mode and it doesn't affect the program
33 size (at least if you don't forget to add @c /opt:ref option which is suppressed
34 by using @c /debug linker option by default but should be always enabled for
35 release builds).
36 Under Unix, you need to compile your program with debugging information
37 (usually using @c -g compiler and linker options) to get the file and line
38 numbers information, however function names should be available even without it.
39 Of course, all this is only @true if you build using a recent enough version
40 of GNU libc which provides the @c backtrace() function needed to walk the stack.
41
42 See @ref overview_debugging for how to make it available.
7c913512 43
23324ae1 44 @library{wxbase}
4701dc09 45 @category{debugging}
7c913512 46
e54c96f1 47 @see wxStackFrame
23324ae1 48*/
7c913512 49class wxStackWalker
23324ae1
FM
50{
51public:
52 /**
4701dc09 53 Constructor does nothing, use Walk() to walk the stack.
23324ae1 54 */
11e3af6e 55 wxStackWalker(const char* argv0 = NULL);
23324ae1
FM
56
57 /**
58 Destructor does nothing neither but should be virtual as this class is used as
59 a base one.
60 */
adaaa686 61 virtual ~wxStackWalker();
23324ae1 62
23324ae1
FM
63 /**
64 Enumerate stack frames from the current location, skipping the initial
65 number of them (this can be useful when Walk() is called from some known
66 location and you don't want to see the first few frames anyhow; also
67 notice that Walk() frame itself is not included if skip = 1).
4701dc09 68
4cc4bfaf 69 Up to @a maxDepth frames are walked from the innermost to the outermost one.
52499582 70 It defaults to ::wxSTACKWALKER_MAX_DEPTH.
23324ae1 71 */
52499582 72 virtual void Walk(size_t skip = 1, size_t maxDepth = wxSTACKWALKER_MAX_DEPTH);
23324ae1
FM
73
74 /**
75 Enumerate stack frames from the location of uncaught exception.
4701dc09
FM
76 This method can only be called from wxApp::OnFatalException().
77
4cc4bfaf 78 Up to @a maxDepth frames are walked from the innermost to the outermost one.
52499582 79 It defaults to ::wxSTACKWALKER_MAX_DEPTH.
23324ae1 80 */
52499582 81 virtual void WalkFromException(size_t maxDepth = wxSTACKWALKER_MAX_DEPTH);
551266a9
FM
82
83protected:
84 /**
85 This function must be overrided to process the given frame.
86 */
da1ed74c 87 virtual void OnStackFrame(const wxStackFrame& frame) = 0;
23324ae1
FM
88};
89
90
e54c96f1 91
23324ae1
FM
92/**
93 @class wxStackFrame
7c913512 94
23324ae1 95 wxStackFrame represents a single stack frame, or a single function in the call
4701dc09
FM
96 stack, and is used exclusively together with wxStackWalker, see there for a more
97 detailed discussion.
7c913512 98
23324ae1 99 @library{wxbase}
4701dc09 100 @category{debugging}
7c913512 101
e54c96f1 102 @see wxStackWalker
23324ae1 103*/
7c913512 104class wxStackFrame
23324ae1
FM
105{
106public:
107 /**
108 Return the address of this frame.
109 */
328f5751 110 void* GetAddress() const;
23324ae1
FM
111
112 /**
4701dc09
FM
113 Return the name of the file containing this frame, empty if unavailable
114 (typically because debug info is missing).
115
116 Use HasSourceLocation() to check whether the file name is available.
23324ae1 117 */
328f5751 118 wxString GetFileName() const;
23324ae1
FM
119
120 /**
121 Get the level of this frame (deepest/innermost one is 0).
122 */
328f5751 123 size_t GetLevel() const;
23324ae1
FM
124
125 /**
126 Return the line number of this frame, 0 if unavailable.
3c4f71cc 127
4cc4bfaf 128 @see GetFileName()
23324ae1 129 */
328f5751 130 size_t GetLine() const;
23324ae1
FM
131
132 /**
133 Get the module this function belongs to (empty if not available).
134 */
328f5751 135 wxString GetModule() const;
23324ae1
FM
136
137 /**
4701dc09 138 Return the unmangled (if possible) name of the function containing this frame.
23324ae1 139 */
328f5751 140 wxString GetName() const;
23324ae1
FM
141
142 /**
143 Return the return address of this frame.
144 */
328f5751 145 size_t GetOffset() const;
23324ae1
FM
146
147 /**
148 Get the name, type and value (in text form) of the given parameter.
4701dc09
FM
149 Any pointer may be @NULL if you're not interested in the corresponding value.
150
23324ae1 151 Return @true if at least some values could be retrieved.
4701dc09 152 This function currently is only implemented under Win32 and requires a PDB file.
23324ae1 153 */
fadc2df6
FM
154 virtual bool GetParam(size_t n, wxString* type, wxString* name,
155 wxString* value) const;
23324ae1
FM
156
157 /**
158 Return the number of parameters of this function (may return 0 if we
159 can't retrieve the parameters info even although the function does have
160 parameters).
161 */
adaaa686 162 virtual size_t GetParamCount() const;
23324ae1
FM
163
164 /**
165 Return @true if we have the file name and line number for this frame.
166 */
328f5751 167 bool HasSourceLocation() const;
23324ae1 168};
e54c96f1 169