Added stackwalk/doc LaTeX files.
[dyninst.git] / stackwalk / doc / API / SymbolLookup.tex
1 \subsubsection{Class SymbolLookup}
2 \definedin{symlookup.h}
3
4 The \code{SymbolLookup} virtual class is an interface for associating a symbolic
5 name with a stack frame. Each \code{Frame} object contains an address (the RA)
6 pointing into the function (or function-like object) that created its stack
7 frame. However, users do not always want to deal with addresses when symbolic
8 names are more convenient. This class is an interface for mapping a \code{Frame} object's RA into a name.
9
10 In addition to getting a name, this class can also associate an opaque object
11 (via a \code{void*}) with a Frame object. It is up to the \code{SymbolLookup}
12 implementation what to return in this opaque object.
13
14 The default implementation of \code{SymbolLookup} provided by StackwalkerAPI
15 uses the \code{DynSymtab} tool to lookup symbol names. It returns a Symbol
16 object in the anonymous \code{void*}.
17
18 \begin{apient}
19 virtual bool lookupAtAddr(Address addr, 
20                           string &out_name, 
21                           void* &out_value) = 0
22 \end{apient}
23 \apidesc{
24     This method takes an address, \code{addr}, as input and returns the function name,
25     \code{out\_name}, and an opaque value, \code{out\_value}, at that address. Output parameter
26     \code{out\_name} should be the name of the function that contains
27     \code{addr}. Output
28     parameter \code{out\_value} can be any opaque value determined by the
29     \code{SymbolLookup}
30     implementation. The values returned are used by the \code{Frame::getName} and
31     \code{Frame::getObject} functions.
32
33     This method returns \code{true} on success and \code{false} on error.
34 }
35
36 \begin{apient}
37 virtual Walker *getWalker()
38 \end{apient}
39 \apidesc{
40     This method returns the \code{Walker} object associated with this
41     \code{SymbolLookup}.
42 }
43
44 \begin{apient}
45 virtual ProcessState *getProcessSate()
46 \end{apient}
47 \apidesc{
48     This method returns the \code{ProcessState} object associated with this
49     \code{SymbolLookup}.
50 }
51