Applied patches from Alin Mindroc and Marc Bruenink.
[dyninst.git] / parseAPI / doc / 3-Example.tex
1 \section{Examples}
2 \label{sec:example}
3
4 \subsection{Function Disassembly}
5
6 The following example uses ParseAPI and InstructionAPI to disassemble
7 the basic blocks in a function. As an example, it can be built with
8 G++ as follows: \code{g++ -std=c++0x -o code\_sample code\_sample.cc -L<library
9   install path> -I<headers install path> -lparseAPI -linstructionAPI
10   -lsymtabAPI -lsymLite -ldynDwarf -ldynElf -lcommon -L<libelf path>
11   -lelf -L<libdwarf path> -ldwarf}. Note: this example must be
12 compiled with C++11x support; for G++ this is enabled with
13 \code{-std=c++0x}, and it is on by default for Visual Studio.
14
15 \lstset{language=[GNU]C++,basicstyle=\fontfamily{fvm}\selectfont\small}
16 \lstset{numbers=left, numberstyle=\tiny, stepnumber=5, numbersep=5pt}
17 \lstset{showstringspaces=false}
18 \lstinputlisting{code_sample.cc}
19
20 \subsection{Control flow graph traversal}
21
22 The following complete example uses the ParseAPI to parse a binary and
23 dump its control flow graph in the Graphviz file format. As an
24 example, it can be built with G++ as follows: \code{g++ -std=c++0x -o example
25   example.cc -L<library install path> -I<headers install path>
26   -lparseAPI -linstructionAPI -lsymtabAPI -lsymLite -ldynDwarf
27   -ldynElf -lcommon -L<libelf path> -lelf -L<libdwarf path>
28   -ldwarf}. Note: this example must be compiled with C++11x support;
29 for G++ this is enabled with \code{-std=c++0x}, and it is on by
30 default for Visual Studio.
31
32 \lstset{language=[GNU]C++,basicstyle=\fontfamily{fvm}\selectfont\small}
33 \lstset{numbers=left, numberstyle=\tiny, stepnumber=5, numbersep=5pt}
34 \lstset{showstringspaces=false}
35 \lstinputlisting{example.cc}
36
37 \subsection{Loop analysis}
38
39 The following code example shows how to get loop information using ParseAPI once we have an parsed Function object.
40
41 \lstset{language=[GNU]C++,basicstyle=\fontfamily{fvm}\selectfont\small}
42 \lstset{numbers=left, numberstyle=\tiny, stepnumber=5, numbersep=5pt}
43 \lstset{showstringspaces=false}
44 \begin{lstlisting}
45 void GetLoopInFunc(Function *f) {
46     // Get all loops in the function
47     vector<Loop*> loops;
48     f->getLoops(loops);
49
50     // Iterate over all loops
51     for (auto lit = loops.begin(); lit != loops.end(); ++lit) {
52         Loop *loop = *lit;
53
54         // Get all the entry blocks of the loop
55         vector<Block*> entries;
56         loop->getLoopEntries(entries);
57
58         // Get all the blocks in the loop
59         vector<Block*> blocks;
60         loop->getLoopBasicBlocks(blocks);
61
62         // Get all the back edges in the loop
63         vector<Edge*> backEdges;
64         loop->getBackEdges(backEdges);
65     }
66 }
67 \end{lstlisting}
68