Documentation updates for v11.0.0 release (#1016)
[dyninst.git] / dyninstAPI / h / BPatch_module.h
1 /*
2  * See the dyninst/COPYRIGHT file for copyright information.
3  * 
4  * We provide the Paradyn Tools (below described as "Paradyn")
5  * on an AS IS basis, and do not warrant its validity or performance.
6  * We reserve the right to update, modify, or discontinue this
7  * software at any time.  We shall have no obligation to supply such
8  * updates or modifications or any other form of support to you.
9  * 
10  * By your use of Paradyn, you understand and agree that we (or any
11  * other person or entity with proprietary rights in Paradyn) are
12  * under no obligation to provide either maintenance services,
13  * update services, notices of latent defects, or correction of
14  * defects for Paradyn.
15  * 
16  * This library is free software; you can redistribute it and/or
17  * modify it under the terms of the GNU Lesser General Public
18  * License as published by the Free Software Foundation; either
19  * version 2.1 of the License, or (at your option) any later version.
20  * 
21  * This library is distributed in the hope that it will be useful,
22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
24  * Lesser General Public License for more details.
25  * 
26  * You should have received a copy of the GNU Lesser General Public
27  * License along with this library; if not, write to the Free Software
28  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
29  */
30
31 #ifndef _BPatch_module_h_
32 #define _BPatch_module_h_
33 #include "BPatch_dll.h"
34 #include "BPatch_Vector.h"
35 #include "BPatch_sourceObj.h"
36 #include "BPatch_enums.h"
37 #include "dyntypes.h"
38 #include <vector>
39 #include <map>
40
41 class mapped_module;
42
43 class BPatch_image;
44 class BPatch_function;
45 class BPatch_typeCollection;
46 class BPatch_builtInTypeCollection;
47 class BPatch_addressSpace;
48 class BPatch_process;
49 class BPatch_statement;
50 class func_instance;
51 class int_variable;
52 class instPoint;
53 class AddressSpace;
54 class BPatch_snippet;
55 class BPatchSnippetHandle;
56 class BPatch_module;
57 class BPatch_object;
58
59 namespace Dyninst { 
60    namespace SymtabAPI {
61       class Module;
62        struct AddressRange;
63       BPATCH_DLL_EXPORT Module *convert(const BPatch_module *);
64    }
65    namespace PatchAPI {
66            class PatchFunction;
67            class Point;
68    }
69 }
70
71 extern BPatch_builtInTypeCollection * builtInTypes;
72
73
74 class BPATCH_DLL_EXPORT BPatch_module: public BPatch_sourceObj{
75
76     friend class BPatch_function;
77     friend class BPatch_flowGraph;
78     friend class BPatch_image;
79     friend class BPatch_thread;
80     friend class BPatch_process;
81     friend class BPatch_binaryEdit;
82     friend class BPatch_addressSpace;
83     friend class BPatch_statement;
84     friend Dyninst::SymtabAPI::Module *Dyninst::SymtabAPI::convert(const BPatch_module *);
85
86
87     typedef std::map<Dyninst::PatchAPI::PatchFunction*, 
88        BPatch_function*> BPatch_funcMap;
89     typedef std::map<int_variable*, BPatch_variableExpr*> BPatch_varMap;
90     typedef std::map<Dyninst::PatchAPI::Point *, 
91        BPatch_point*> BPatch_instpMap;
92
93
94     
95     BPatch_addressSpace *addSpace;
96     AddressSpace *lladdSpace;
97     mapped_module        *mod;
98     BPatch_image         *img;
99     AddressSpace *getAS();
100
101 public:
102
103     //  This function should go away when paradyn is on top of dyninst
104     mapped_module* lowlevel_mod() { return mod; }
105
106     // The following functions are for internal use by  the library only:
107     BPatch_module(BPatch_addressSpace *_addSpace,
108                   AddressSpace *as,
109                   mapped_module *_mod, 
110                   BPatch_image *img);
111     virtual ~BPatch_module();
112     bool getSourceObj(BPatch_Vector<BPatch_sourceObj *>&);
113     BPatch_sourceObj *getObjParent();
114     void parseTypes();
115     char *parseStabStringSymbol(int line, char *stabstr, void *stabptr);
116     void setDefaultNamespacePrefix(char *name);    
117     void handleUnload();
118     bool isExploratoryModeOn();// true if exploratory or defensive mode is on
119     bool setAnalyzedCodeWriteable(bool writeable);//sets write perm's analyzed code pages
120     bool isSystemLib();
121     bool remove(BPatch_function*);
122     bool remove(instPoint*);
123     // End functions for internal use only
124   
125     // BPatch_module::getName
126     // Returns file name associated with module
127
128     char * getName(char *buffer, int length);
129
130     // BPatch_module::getFullName
131     // Returns full path name of module, when available
132
133     char * getFullName(char *buffer, int length);
134
135     // BPatch_module::libraryName
136     // Returns name if library, if this module is a shared object
137
138     const char * libraryName();
139
140     // BPatch_module::getObject
141     // Returns BPatch_object containing this file
142     BPatch_object *  getObject();
143
144     // BPatch_module::getAddressWidth
145     // Returns the width (in bytes) of an address in this module
146
147     size_t getAddressWidth();
148
149     // BPatch_module::getVariables
150     // Fills a vector with the global variables that are specified in this module
151
152     bool getVariables(BPatch_Vector<BPatch_variableExpr *> &vars);
153
154     // BPatch_module::findVariable
155     // Find and return a global variable (NULL if not found)
156
157     BPatch_variableExpr* findVariable(const char* name);
158
159         // BPatch_module::getProcedures
160     // Returns a vector of all functions in this module
161     BPatch_Vector<BPatch_function *> * getProcedures(bool incUninstrumentable = false);
162
163                bool  getProcedures(BPatch_Vector<BPatch_function*> &procs, bool incUninstrumentable = false);
164
165     // BPatch_module::findFunction
166     // Returns a vector of BPatch_function *  matching specified <name>
167
168     BPatch_Vector<BPatch_function *> * findFunction(const char *name,
169                           BPatch_Vector<BPatch_function *> &funcs,
170                           bool notify_on_failure =true,
171                           bool regex_case_sensitive =true,
172                           bool incUninstrumentable =false,
173                           bool dont_use_regex = false);
174
175
176     //  BPatch_addressSpace::findFunctionByEntry
177     //  Returns the function starting at the given address
178     BPatch_function * findFunctionByEntry(Dyninst::Address entry);
179
180
181     // FIXME: This method is (undocumented) 
182
183     BPatch_Vector<BPatch_function *> * 
184     findFunctionByAddress(void *addr,
185                            BPatch_Vector<BPatch_function *> &funcs,
186                            bool notify_on_failure = true,
187                            bool incUninstrumentable = false);
188
189     // get the module types member (instead of directly accessing)
190     BPatch_typeCollection *getModuleTypes();
191     
192  
193     // BPatch_module::findFunctionByMangled
194     // Returns a function, if it exits, that matches the provided mangled name
195
196     BPatch_function * findFunctionByMangled(const char * mangled_name,
197                                              bool incUninstrumentable=false);
198
199
200     //  BPatch_module::findPoints
201     //
202     //  Returns a vector of BPatch_points that correspond with the provided address, one
203     //  per function that includes an instruction at that address. Will have one element
204     //  if there is not overlapping code. 
205     bool  findPoints(Dyninst::Address addr, std::vector<BPatch_point *> &points);
206
207
208     // BPatch_module::dumpMangled
209     // Prints all <mangled> function names in this module
210
211     bool dumpMangled(char *prefix);
212
213     // BPatch_module::isSharedLib
214     // Returns true if this module represents a shared library
215
216     bool isSharedLib();
217
218
219     // BPatch_module::getAddressRanges
220     // 
221     // function to get addresses for a line of the module
222     // if fileName is NULL, uses the name of the module
223
224     bool getAddressRanges(const char *fileName, unsigned int lineNo,
225                           std::vector<Dyninst::SymtabAPI::AddressRange > &ranges);
226     
227     // BPatch_module::getSourceLines
228     //
229     // function to get source file names and lines
230     // for an address in the module
231     
232     bool getSourceLines( unsigned long addr, BPatch_Vector<BPatch_statement> &lines);
233
234
235     // BPatch_mode::getStatements
236     //
237     // Fill supplied vector with all BPatch_statements from this module
238   
239     bool getStatements(BPatch_Vector<BPatch_statement> &statements);
240
241     // BPatch_module::wgetBaseAddr
242     // Returns a base address of the module; defined as the start
243     // of the first function.
244     void * getBaseAddr(void);
245
246     Dyninst::Address getLoadAddr(void);
247
248     // BPatch_module::getSize
249     // Returns the size of the module; defined as the end of the last
250     // function minus the start of the first function.
251     unsigned long getSize(void);
252
253     bool isValid();
254
255     // BPastch_module::getHybridMode
256     // returns the hybrid Analysis mode: normal, exploratory, defensive
257     BPatch_hybridMode getHybridMode();
258
259     void enableDefensiveMode(bool on);
260     
261 private:
262     // Parse wrapper
263     bool parseTypesIfNecessary();
264     BPatch_typeCollection *moduleTypes;
265
266     // In particular, we understand the type information
267     // in both DWARF and STABS format.
268     void parseStabTypes();
269     void parseDwarfTypes();
270
271    BPatch_funcMap func_map;
272    BPatch_instpMap instp_map;
273    BPatch_varMap var_map;
274    
275    bool full_func_parse;
276    bool full_var_parse;
277 };
278
279 #endif /* _BPatch_module_h_ */