ParseAPI documentation updates
[dyninst.git] / parseAPI / doc / API / CodeSource.tex
1 \subsection{Class CodeSource}
2 \label{sec:codesource}
3
4 \definedin{CodeSource.h}
5
6 The CodeSource interface is used by the ParseAPI to retrieve binary code from
7 an executable, library, or other binary code object; it also can provide hints
8 of function entry points (such as those derived from debugging symbols) to seed
9 the parser. The ParseAPI provides a default implementation based on the
10 SymtabAPI that supports many common binary formats. For details on implementing
11 a custom CodeSource, see Appendix \ref{sec:extend}.
12
13 \begin{apient}
14 virtual bool nonReturning(Address func_entry)
15 virtual bool nonReturning(std::string func_name)
16 \end{apient}
17 \apidesc{Looks up whether a function returns (by name or location). This information may be statically known for some code sources, and can lead to better parsing accuracy.}
18
19 \begin{apient}
20 virtual Address baseAddress()
21 virtual Address loadAddress()
22 \end{apient}
23 \apidesc{If the binary file type supplies non-zero base or load addresses (e.g. Windows PE), implementations should override these functions.}
24
25 \begin{apient}
26 std::map< Address, std::string > & linkage()
27 \end{apient}
28 \apidesc{Returns a reference to the external linkage map, which may or may not be filled in for a particular CodeSource implementation.}
29
30 \begin{apient}
31 struct Hint {
32     Address addr;
33     CodeRegion *region;
34     std::string name;
35     Hint(Addr, CodeRegion *, std::string);
36 }
37 std::vector< Hint > const& hints()
38 \end{apient}
39 \apidesc{Returns a vector of the currently defined function entry hints.}
40
41 \begin{apient}
42 std::vector<CodeRegion *> const& regions()
43 \end{apient}
44 \apidesc{Returns a read-only vector of code regions within the binary represented by this code source.}
45
46 \begin{apient}
47 int findRegions(Address addr, set<CodeRegion *> & ret)
48 \end{apient}
49 \apidesc{Finds all CodeRegion objects that overlap the provided address. Some code sources (e.g. archive files) may have several regions with overlapping address ranges; others (e.g. ELF binaries) do not.}
50
51 \begin{apient}
52 bool regionsOverlap() 
53 \end{apient}
54 \apidesc{Indicates whether the CodeSource contains overlapping regions.}