Added stackwalk/doc LaTeX files.
[dyninst.git] / stackwalk / doc / API / Frame.tex
1 \subsubsection{Class Frame}
2 \label{subsec:frame}
3 \definedin{frame.h}
4         
5 The \code{Walker} class returns a call stack as a vector of \code{Frame} objects. As described
6 in Section~\ref{subsec:definitions}, each Frame object represents a stack frame, and contains a
7 return address (RA), stack pointer (SP) and frame pointer (FP). For each of
8 these values, optionally, it stores the location where the values were found.
9 Each Frame object may also be augmented with symbol information giving a
10 function name (or a symbolic name, in the case of non-functions) for the object
11 that created the stack frame.
12
13 The Frame class provides a set of functions (getRALocation, getSPLocation and
14 getFPLocation) that return the location in the target process' memory or
15 registers where the RA, SP, or FP were found. These functions may be used to
16 modify the stack. For example, the DyninstAPI uses these functions to change
17 return addresses on the stack when it relocates code. The RA, SP, and FP may be
18 found in a register or in a memory address on a call stack. 
19
20 \begin{apient}
21 static Frame *newFrame(Dyninst::MachRegisterVal ra,
22                        Dyninst::MachRegisterVal sp, 
23                        Dyninst::MachRegisterVal fp, 
24                        Walker *walker)
25 \end{apient}
26 \apidesc{
27     This method creates a new \code{Frame} object and sets the mandatory data
28     members: RA, SP and FP. The new \code{Frame} object is associated with
29     \code{walker}.
30         
31     The optional location fields can be set by the methods below.
32         
33     The new \code{Frame} object is created with the \code{new} operator, and the
34     user should be deallocate it with the \code{delete} operator when it is no longer needed.
35 }
36
37 \begin{apient}
38 Dyninst::MachRegisterVal getRA() const
39 \end{apient}
40 \apidesc{
41         This method returns this \code{Frame} object's return address.
42 }
43
44 \begin{apient}
45 void setRA(Dyninst::MachRegisterVal val)
46 \end{apient}
47 \apidesc{
48     This method sets this \code{Frame} object's return address to \code{val}.
49 }
50
51 \begin{apient}
52 Dyninst::MachRegisterVal getSP() const
53 \end{apient}
54 \apidesc{
55         This method returns this \code{Frame} object's stack pointer.
56 }
57
58 \begin{apient}
59 void setSP(Dyninst::MachRegisterVal val)
60 \end{apient}
61 \apidesc{
62     This method sets this \code{Frame} object's stack pointer to \code{val}.
63 }
64
65 \begin{apient}
66 Dyninst::MachRegisterVal getFP() const
67 \end{apient}
68 \apidesc{
69         This method returns this \code{Frame} object's frame pointer.
70 }
71
72 \begin{apient}
73 void setFP(Dyninst::MachRegisterVal val)
74 \end{apient}
75 \apidesc{
76     This method sets this \code{Frame} object's frame pointer to \code{val}.
77 }
78
79 \begin{apient}
80 typedef enum { 
81     loc_address, 
82     loc_register, 
83     loc_unknown 
84 } storage_t;
85 \end{apient}
86
87 \begin{apient}
88 typedef struct {
89     union {
90         address addr;
91         Dyninst::MachRegister reg;
92     } val;
93     storage_t location;
94 } location_t; 
95 \end{apient}
96 \apidesc{
97     The \code{location\_t} structure is used by the \code{getRALocation},
98     \code{getSPLocation}, and \code{getFPLocation} methods to describe where in
99     the process a \code{Frame} object's RA, SP, or FP were found. When walking a
100     call stack these values may be found in registers or memory. If they were
101     found in memory, the \code{location} field of \code{location\_t} will contain
102     \code{loc\_address} and the \code{addr} field will contain the address where it was found.
103     If they were found in a register the \code{location} field of \code{location\_t}
104     will contain \code{loc\_register} and the \code{reg} field will refer to the register where
105     it was found. If this \code{Frame} object was not created by a stackwalk
106     (using the \code{newframe} factory method, for example), and has not had a set
107     location method called, then location will contain \code{loc\_unknown}.
108 }
109
110 \begin{apient}
111 location_t getRALocation() const
112 \end{apient}
113 \apidesc{
114         This method returns a \code{location\_t} describing where the RA was found.
115 }
116
117 \begin{apient}
118 void setRALocation(location_t newval)
119 \end{apient}
120 \apidesc{
121         This method sets the location of where the RA was found to newval.
122 }
123
124 \begin{apient}
125 location_t getSPLocation() const
126 \end{apient}
127 \apidesc{
128         This method returns a \code{location\_t} describing where the SP was found.
129 }
130
131 \begin{apient}
132 void setSPLocation(location_t newval)
133 \end{apient}
134 \apidesc{
135     This method sets the location of where the SP was found to \code{newval}.
136 }
137
138 \begin{apient}
139 location_t getFPLocation() const
140 \end{apient}
141 \apidesc{
142         This method returns a \code{location\_t} describing where the FP was found.
143 }
144
145 \begin{apient}
146 void setFPLocation(location_t newval)
147 \end{apient}
148 \apidesc{
149     This method sets the location of where the FP was found to \code{newval}.
150 }
151
152 \begin{apient}
153 bool getName(std::string &str)
154 \end{apient}
155 \apidesc{
156 This method returns a stack frame's symbolic name. Most stack frames are created
157 by functions, or function-like objects such as signal handlers or system calls.
158 This method returns the name of the object that created this stack frame. For
159 stack frames created by functions, this symbolic name will be the function name.
160 A symbolic name may not always be available for all \code{Frame} objects, such
161 as in cases of stripped binaries or special stack frames types.
162         
163 The function name is obtained by using this \code{Frame} object's RA to call the
164 \code{SymbolLookup} callback. By default StackwalkerAPI will attempt to use the
165 \code{SymtabAPI} package to look up symbol names in binaries. If
166 \code{SymtabAPI} is not found, and no alternative \code{SymbolLookup} object is
167 present, then this method will return an error.
168         
169 This method returns \code{true} on success and \code{false} on error.  
170 }
171
172 \begin{apient}
173 bool getObject(void* &obj)
174 \end{apient}
175 \apidesc{
176     In addition to returning a symbolic name (see \code{getName}) the \code{SymbolLookup}
177     interface allows for an opaque object, a \code{void*}, to be associated with a
178     \code{Frame} object. The contents of this \code{void*} is determined by the
179 \code{SymbolLookup} implementation. Under the default implementation that uses
180 SymtabAPI, the \code{void*} points to a Symbol object or NULL if no symbol is found.
181
182 This method returns \code{true} on success and \code{false} on error.  
183 }
184
185 \begin{apient}
186 bool getStepper(FrameStepper* &stepper) const
187 \end{apient}
188 \apidesc{
189     This method returns the \code{FrameStepper} object that was used to
190     construct this \code{Frame} object in the \code{stepper} output parameter. 
191
192     This method returns \code{true} on success and \code{false} on error.  
193 }
194
195 \begin{apient}
196 bool getLibOffset(std::string &lib, Dyninst::Offset &offset, void* &symtab)
197 \end{apient}
198 \apidesc{
199 This method returns the DSO (a library or executable) and an offset into that
200 DSO that points to the location within that DSO where this frame was created.
201 \code{lib} is the path to the library that was loaded, and \code{offset} is the offset into
202 that library. The return value of the \code{symtab} parameter is dependent on the
203 SymbolLookup implementation-by default it will contain a pointer to a
204 Dyninst::Symtab object for this DSO. See the SymtabAPI Programmer's Guide for
205 more information on using Dyninst::Symtab objects.
206 }