DyninstAPI defensive mode manual update.
[dyninst.git] / instructionAPI / doc / latex / classDyninst_1_1InstructionAPI_1_1Dereference.tex
1 \subsection{Dereference Class}
2 \label{classDyninst_1_1InstructionAPI_1_1Dereference}\index{Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}}
3 \subsubsection*{Public Member Functions}
4 \begin{DoxyCompactItemize}
5 \item 
6 {\textbf Dereference} ({\textbf Expression::Ptr} addr, Result\_\-Type result\_\-type)
7 \item 
8 virtual void {\textbf getChildren} (vector$<$ InstructionAST::Ptr $>$ \&children) const 
9 \item 
10 virtual void {\textbf getUses} (set$<$ InstructionAST::Ptr $>$ \&uses)
11 \item 
12 virtual bool {\textbf isUsed} (InstructionAST::Ptr findMe) const 
13 \end{DoxyCompactItemize}
14
15
16
17 A Dereference object is a Expression that dereferences another ValueComputation.
18
19 A Dereference contains an Expression representing an effective address computation. Its use set is the same as the use set of the Expression being dereferenced.
20
21 It is not possible, given the information in a single instruction, to evaluate the result of a dereference. {\ttfamily eval} may still be called on a Expression that includes dereferences, but the expected use case is as follows:
22 \begin{DoxyItemize}
23 \item Determine the address being used in a dereference via the {\ttfamily eval} mechanism
24 \item Perform analysis to determine the contents of that address
25 \item If necessary, fill in the Dereference node with the contents of that addresss, using {\ttfamily setValue} 
26 \end{DoxyItemize}
27
28 The type associated with a Dereference node will be the type of the value {\itshape read\/} {\itshape from\/} {\itshape memory\/}, not the type used for the address computation. Two Dereferences that access the same address but interpret the contents of that memory as different types will produce different values. The children of a Dereference at a given address are identical, regardless of the type of dereference being performed at that address. For example, the Expression shown in Figure 6 could have its root Dereference, which interprets the memory being dereferenced as a unsigned 16-\/bit integer, replaced with a Dereference that interprets the memory being dereferenced as any other type. The remainder of the Expression tree would, however, remain unchanged. 
29
30 \subsubsection{Constructors \& Destructors}
31 \index{Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}!Dereference@{Dereference}}
32 \index{Dereference@{Dereference}!Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}}
33 \paragraph[{Dereference}]{\setlength{\rightskip}{0pt plus 5cm}{\textbf Dereference} (
34 \begin{DoxyParamCaption}
35 \item[{{\textbf Expression::Ptr}}]{ addr, }
36 \item[{Result\_\-Type}]{ result\_\-type}
37 \end{DoxyParamCaption}
38 )}\hfill\label{classDyninst_1_1InstructionAPI_1_1Dereference_a39fee3d3fdcb936e63f9e64f250cd889}
39 A Dereference is constructed from a Expression pointer (raw or shared) representing the address to be dereferenced and a type indicating how the memory at the address in question is to be interpreted. 
40
41 \subsubsection{Member Functions}
42 \index{Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}!getChildren@{getChildren}}
43 \index{getChildren@{getChildren}!Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}}
44 \paragraph[{getChildren}]{\setlength{\rightskip}{0pt plus 5cm}virtual void getChildren (
45 \begin{DoxyParamCaption}
46 \item[{vector$<$ InstructionAST::Ptr $>$ \&}]{ children}
47 \end{DoxyParamCaption}
48 ) const\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1Dereference_adabe6006766a7aaa6fa099f5f0ca5c0c}
49 A Dereference has one child, which represents the address being dereferenced. 
50 \begin{DoxyParams}{Parameters}
51 \item[{\em children}]Appends the child of this Dereference to {\ttfamily children}. \end{DoxyParams}
52
53
54
55 \index{Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}!getUses@{getUses}}
56 \index{getUses@{getUses}!Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}}
57 \paragraph[{getUses}]{\setlength{\rightskip}{0pt plus 5cm}virtual void getUses (
58 \begin{DoxyParamCaption}
59 \item[{set$<$ InstructionAST::Ptr $>$ \&}]{ uses}
60 \end{DoxyParamCaption}
61 )\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1Dereference_a3793407f71d4fba12ae0af46e78da4b4}
62 The use set of a Dereference is the same as the use set of its children. 
63 \begin{DoxyParams}{Parameters}
64 \item[{\em uses}]The use set of this Dereference is inserted into {\ttfamily uses}. \end{DoxyParams}
65
66
67
68 \index{Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}!isUsed@{isUsed}}
69 \index{isUsed@{isUsed}!Dyninst::InstructionAPI::Dereference@{Dyninst::InstructionAPI::Dereference}}
70 \paragraph[{isUsed}]{\setlength{\rightskip}{0pt plus 5cm}virtual bool isUsed (
71 \begin{DoxyParamCaption}
72 \item[{InstructionAST::Ptr}]{ findMe}
73 \end{DoxyParamCaption}
74 ) const\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1Dereference_af5b1db3ca39797ac0f619e04dd8bf9fc}
75 An InstructionAST is used by a Dereference if it is equivalent to the Dereference or it is used by the lone child of the Dereference 
76
77