Applied patches from Alin Mindroc and Marc Bruenink.
[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 bool nonReturningSyscall(int /*number*/)
21 \end{apient}
22 \apidesc{Looks up whether a system call returns (by system call number). This information may be statically known for some code sources, and can lead to better parsing accuracy.}
23
24
25 \begin{apient}
26 virtual Address baseAddress()
27 virtual Address loadAddress()
28 \end{apient}
29 \apidesc{If the binary file type supplies non-zero base or load addresses (e.g. Windows PE), implementations should override these functions.}
30
31 \begin{apient}
32 std::map< Address, std::string > & linkage()
33 \end{apient}
34 \apidesc{Returns a reference to the external linkage map, which may or may not be filled in for a particular CodeSource implementation.}
35
36 \begin{apient}
37 struct Hint {
38     Address _addr;
39     CodeRegion *_region;
40     std::string _name;
41     Hint(Addr, CodeRegion *, std::string);
42 }
43 std::vector< Hint > const& hints()
44 \end{apient}
45 \apidesc{Returns a vector of the currently defined function entry hints.}
46
47 \begin{apient}
48 std::vector<CodeRegion *> const& regions()
49 \end{apient}
50 \apidesc{Returns a read-only vector of code regions within the binary represented by this code source.}
51
52 \begin{apient}
53 int findRegions(Address addr,
54                 set<CodeRegion *> & ret)
55 \end{apient}
56 \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.}
57
58 \begin{apient}
59 bool regionsOverlap() 
60 \end{apient}
61 \apidesc{Indicates whether the CodeSource contains overlapping regions.}