Fix typo for ParseAPI manual
[dyninst.git] / parseAPI / doc / API / CodeObject.tex
1 \subsection{Class CodeObject}
2
3 \definedin{CodeObject.h}
4
5 The CodeObject class describes an individual binary code object, such as an
6 executable or library. It is the top-level container for parsing the object as
7 well as accessing that parse data. The following API routines and data types
8 are provided to support parsing and retrieving parsing products.
9
10 \begin{apient}
11
12 typedef std::set<Function *, Function::less> funclist
13 \end{apient}
14 \apidesc{Container for access to functions. Refer to Section \ref{sec:containers} for details. Library users \emph{must not} rely on the underlying container type of std::set, as it is subject to change.}
15
16 \begin{apient}
17 CodeObject(CodeSource * cs,
18            CFGFactory * fact = NULL,
19            ParseCallback * cb = NULL,
20            bool defensiveMode = false)
21 \end{apient}
22 \apidesc{Constructs a new CodeObject from the provided CodeSource and
23 optional object factory and callback handlers. Any parsing hints provided
24 by the CodeSource are processed, but the binary is not parsed when this
25 constructor returns.
26
27 \medskip\noindent The \code{defensiveMode}
28 parameter optionally trades off coverage for safety; this mode is not
29 recommended for most applications as it makes very conservative assumptions
30 about control flow transfer instructions (see Section \ref{sec:defmode}).}
31
32 \begin{apient}
33 void parse()
34 \end{apient}
35 \apidesc{Recursively parses the binary represented by this CodeObject from all
36 known function entry points (i.e., the hints provided by the CodeSource). This
37 method and the following parsing methods may safely be invoked repeatedly if
38 new information about function locations is provided through the CodeSource.}
39
40 \begin{apient}
41 void parse(Address target,
42            bool recursive)
43 \end{apient}
44 \apidesc{Parses the binary starting with the instruction at the provided target address. If \code{recursive} is {\scshape true}, recursive traversal parsing is used as in the default \code{parse()} method; otherwise only instructions reachable through intraprocedural control flow are visited.}
45
46 \begin{apient}
47 void parse(CodeRegion * cr,
48            Address target,
49            bool recursive)
50 \end{apient}
51 \apidesc{Parses the specified core region of the binary starting with the 
52 instruction at the provided target address. If \code{recursive} is 
53 {\scshape true}, recursive traversal parsing is used as in the default 
54 \code{parse()} method; otherwise only instructions reachable through 
55 intraprocedural control flow are visited.
56 }
57
58 \begin{apient}
59 struct NewEdgeToParse {
60     Block *source;
61     Address target;
62     EdgeTypeEnum type;
63 }
64 bool parseNewEdges( vector<NewEdgeToParse> & worklist )
65 \end{apient}
66 \apidesc{Parses a set of newly created edges specified in the worklist supplied 
67 that were not included when the function was originally parsed. 
68 }
69
70 \begin{apient}
71 void parseGaps(CodeRegion *cr)
72 \end{apient}
73 \apidesc{Speculatively parse the indicated region of the binary using pattern matching to find likely function entry points. Only enabled on the x86 32-bit platform.}
74
75 \begin{apient}
76 Function * findFuncByEntry(CodeRegion * cr,
77                            Address entry)
78 \end{apient}
79 \apidesc{Find the function starting at address \code{entry} in the indicated CodeRegion. Returns {\scshape null} if no such function exists.}
80
81 \begin{apient}
82 int findFuncs(CodeRegion * cr,
83               Address addr,
84               std::set<Function*> & funcs)
85 \end{apient}
86 \apidesc{Finds all functions spanning \code{addr} in the code region, adding each to \code{funcs}. The number of results of this stabbing query are returned.}
87
88 \begin{apient}
89 int findFuncs(CodeRegion * cr,
90               Address start,
91               Address end,
92               std::set<Function*> & funcs)
93 \end{apient}
94 \apidesc{Finds all functions overlapping the range \code{[start,end)} in the code region, adding each to \code{funcs}. The number of results of this stabbing query are returned.}
95
96 \begin{apient}
97 funclist & funcs()
98 \end{apient}
99 \apidesc{Returns a reference to a container of all functions in the binary. Refer to Section \ref{sec:containers} for container access details.}
100
101 \begin{apient}
102 Block * findBlockByEntry(CodeRegion * cr,
103                          Address entry)
104 \end{apient}
105 \apidesc{Find the basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
106
107 \begin{apient}
108 int findBlocks(CodeRegion * cr,
109                Address addr,
110                std::set<Block*> & blocks)
111 \end{apient}
112 \apidesc{Finds all blocks spanning \code{addr} in the code region, adding each to \code{blocks}. Multiple blocks can be returned only on platforms with variable-length instruction sets (such as IA32) for which overlapping instructions are possible; at most one block will be returned on all other platforms.}
113
114 \begin{apient}
115 Block * findNextBlock(CodeRegion * cr,
116                       Address addr)
117 \end{apient}
118 \apidesc{Find the next reachable basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
119
120 \begin{apient}
121 CodeSource * cs()
122 \end{apient}
123 \apidesc{Return a reference to the underlying CodeSource.}
124
125 \begin{apient}
126 CFGFactory * fact()
127 \end{apient}
128 \apidesc{Return a reference to the CFG object factory.}
129
130 \begin{apient}
131 bool defensiveMode()
132 \end{apient}
133 \apidesc{Return a boolean specifying whether or not defensive mode is enabled.}
134
135 \begin{apient}
136 bool isIATcall(Address insn,
137                std::string &calleeName)
138 \end{apient}
139 \apidesc{Returns a boolean specifying if the address at \code{addr} is located at the call named in \code{calleeName}. }
140
141 \begin{apient}
142 void startCallbackBatch()
143 \end{apient}
144 \apidesc{Starts a batch of callbacks that have been registered.}
145
146 \begin{apient}
147 void finishCallbackBatch()
148 \end{apient}
149 \apidesc{Completes all callbacks in the current batch.}
150
151 \begin{apient}
152 void finalize()
153 \end{apient}
154 \apidesc{Force complete parsing of the CodeObject; parsing operations are otherwise completed only as needed to answer queries.}
155
156 \begin{apient}
157 void destroy(Edge *)
158 \end{apient}
159 \apidesc{Destroy the edge listed.}
160
161 \begin{apient}
162 void destroy(Block *)
163 \end{apient}
164 \apidesc{Destroy the code block listed.}
165
166 \begin{apient}
167 void destroy(Function *)
168 \end{apient}
169 \apidesc{Destroy the function listed.}
170