blob: b98afdecde9092a70f5a6a0e3758f8a630dc70b3 [file] [log] [blame]
Johnny Chenfb35e2a2011-07-18 23:11:07 +00001//===-- SWIG Interface for SBModule -----------------------------*- C++ -*-===//
2//
3// The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10namespace lldb {
11
12%feature("docstring",
13"Represents an executable image and its associated object and symbol files.
14
15The module is designed to be able to select a single slice of an
16executable image as it would appear on disk and during program
17execution.
18
19You can retrieve SBModule from SBSymbolContext, which in turn is available
20from SBFrame.
21
22SBModule supports symbol iteration, for example,
23
24 for symbol in module:
25 name = symbol.GetName()
26 saddr = symbol.GetStartAddress()
27 eaddr = symbol.GetEndAddress()
28
29and rich comparion methods which allow the API program to use,
30
31 if thisModule == thatModule:
32 print 'This module is the same as that module'
33
Johnny Chendc0cbd12011-09-24 04:51:43 +000034to test module equality. A module also contains object file sections, namely
Johnny Chenbf338e62011-09-30 00:42:49 +000035SBSection. SBModule supports section iteration through section_iter(), for
36example,
37
38 print 'Number of sections: %d' % module.GetNumSections()
39 for sec in module.section_iter():
40 print sec
41
42And to iterate the symbols within a SBSection, use symbol_in_section_iter(),
43
44 # Iterates the text section and prints each symbols within each sub-section.
45 for subsec in text_sec:
46 print INDENT + repr(subsec)
47 for sym in exe_module.symbol_in_section_iter(subsec):
48 print INDENT2 + repr(sym)
49 print INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType())
50
Johnny Chen5cac6a52011-10-01 01:19:45 +000051produces this following output:
Johnny Chenbf338e62011-09-30 00:42:49 +000052
53 [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text
54 id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870)
55 symbol type: code
56 id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0)
57 symbol type: code
58 id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c)
59 symbol type: code
60 id = {0x00000023}, name = 'start', address = 0x0000000100001780
61 symbol type: code
62 [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs
63 id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62)
64 symbol type: trampoline
65 id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68)
66 symbol type: trampoline
67 id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e)
68 symbol type: trampoline
69 id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74)
70 symbol type: trampoline
71 id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a)
72 symbol type: trampoline
73 id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80)
74 symbol type: trampoline
75 id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86)
76 symbol type: trampoline
77 id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c)
78 symbol type: trampoline
79 id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92)
80 symbol type: trampoline
81 id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98)
82 symbol type: trampoline
83 id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e)
84 symbol type: trampoline
85 id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4)
86 symbol type: trampoline
87 [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper
88 [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring
89 [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info
90 [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame
91"
Johnny Chenfb35e2a2011-07-18 23:11:07 +000092) SBModule;
93class SBModule
94{
95public:
96
97 SBModule ();
98
99 SBModule (const SBModule &rhs);
100
Greg Claytonb5a8f142012-02-05 02:38:54 +0000101 SBModule (lldb::SBProcess &process,
102 lldb::addr_t header_addr);
103
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000104 ~SBModule ();
105
106 bool
107 IsValid () const;
108
Jim Inghame0bd5712011-12-19 20:39:44 +0000109 void
110 Clear();
111
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000112 %feature("docstring", "
113 //------------------------------------------------------------------
114 /// Get const accessor for the module file specification.
115 ///
116 /// This function returns the file for the module on the host system
117 /// that is running LLDB. This can differ from the path on the
118 /// platform since we might be doing remote debugging.
119 ///
120 /// @return
121 /// A const reference to the file specification object.
122 //------------------------------------------------------------------
123 ") GetFileSpec;
124 lldb::SBFileSpec
125 GetFileSpec () const;
126
127 %feature("docstring", "
128 //------------------------------------------------------------------
129 /// Get accessor for the module platform file specification.
130 ///
131 /// Platform file refers to the path of the module as it is known on
132 /// the remote system on which it is being debugged. For local
133 /// debugging this is always the same as Module::GetFileSpec(). But
134 /// remote debugging might mention a file '/usr/lib/liba.dylib'
135 /// which might be locally downloaded and cached. In this case the
136 /// platform file could be something like:
137 /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
138 /// The file could also be cached in a local developer kit directory.
139 ///
140 /// @return
141 /// A const reference to the file specification object.
142 //------------------------------------------------------------------
143 ") GetPlatformFileSpec;
144 lldb::SBFileSpec
145 GetPlatformFileSpec () const;
146
147 bool
148 SetPlatformFileSpec (const lldb::SBFileSpec &platform_file);
149
150 %feature("docstring", "Returns the UUID of the module as a Python string."
151 ) GetUUIDString;
152 const char *
153 GetUUIDString () const;
154
Greg Clayton3e8c25f2011-09-24 00:52:29 +0000155 lldb::SBSection
156 FindSection (const char *sect_name);
157
158 lldb::SBAddress
159 ResolveFileAddress (lldb::addr_t vm_addr);
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000160
161 lldb::SBSymbolContext
162 ResolveSymbolContextForAddress (const lldb::SBAddress& addr,
163 uint32_t resolve_scope);
164
165 bool
166 GetDescription (lldb::SBStream &description);
167
Johnny Chen1dbf2a82012-03-16 21:55:42 +0000168 uint32_t
169 GetNumCompileUnits();
170
171 lldb::SBCompileUnit
172 GetCompileUnitAtIndex (uint32_t);
173
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000174 size_t
175 GetNumSymbols ();
176
177 lldb::SBSymbol
178 GetSymbolAtIndex (size_t idx);
179
Greg Claytonb3dafc62012-12-04 02:22:16 +0000180 lldb::SBSymbol
181 FindSymbol (const char *name,
182 lldb::SymbolType type = eSymbolTypeAny);
183
184 lldb::SBSymbolContextList
185 FindSymbols (const char *name,
186 lldb::SymbolType type = eSymbolTypeAny);
187
188
Greg Clayton3e8c25f2011-09-24 00:52:29 +0000189 size_t
190 GetNumSections ();
191
192 lldb::SBSection
193 GetSectionAtIndex (size_t idx);
194
195
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000196 %feature("docstring", "
197 //------------------------------------------------------------------
198 /// Find functions by name.
199 ///
200 /// @param[in] name
201 /// The name of the function we are looking for.
202 ///
203 /// @param[in] name_type_mask
204 /// A logical OR of one or more FunctionNameType enum bits that
205 /// indicate what kind of names should be used when doing the
206 /// lookup. Bits include fully qualified names, base names,
207 /// C++ methods, or ObjC selectors.
208 /// See FunctionNameType for more details.
209 ///
Greg Clayton7dd5c512012-02-06 01:44:54 +0000210 /// @return
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000211 /// A symbol context list that gets filled in with all of the
212 /// matches.
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000213 //------------------------------------------------------------------
214 ") FindFunctions;
Greg Clayton7dd5c512012-02-06 01:44:54 +0000215 lldb::SBSymbolContextList
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000216 FindFunctions (const char *name,
Greg Clayton7dd5c512012-02-06 01:44:54 +0000217 uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
Enrico Granata979e20d2011-07-29 19:53:35 +0000218
219 lldb::SBType
220 FindFirstType (const char* name);
221
222 lldb::SBTypeList
223 FindTypes (const char* type);
224
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000225
226 %feature("docstring", "
227 //------------------------------------------------------------------
228 /// Find global and static variables by name.
229 ///
230 /// @param[in] target
231 /// A valid SBTarget instance representing the debuggee.
232 ///
233 /// @param[in] name
234 /// The name of the global or static variable we are looking
235 /// for.
236 ///
237 /// @param[in] max_matches
238 /// Allow the number of matches to be limited to \a max_matches.
239 ///
240 /// @return
241 /// A list of matched variables in an SBValueList.
242 //------------------------------------------------------------------
243 ") FindGlobalVariables;
244 lldb::SBValueList
245 FindGlobalVariables (lldb::SBTarget &target,
246 const char *name,
247 uint32_t max_matches);
Greg Clayton1b925202012-01-29 06:07:39 +0000248
249 lldb::ByteOrder
250 GetByteOrder ();
251
252 uint32_t
253 GetAddressByteSize();
254
255 const char *
256 GetTriple ();
Greg Clayton49f4bf22012-02-22 19:41:02 +0000257
258 uint32_t
259 GetVersion (uint32_t *versions,
260 uint32_t num_versions);
Greg Clayton1b925202012-01-29 06:07:39 +0000261
262 %pythoncode %{
Greg Claytonb302dff2012-02-01 08:09:32 +0000263 class symbols_access(object):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000264 re_compile_type = type(re.compile('.'))
Greg Claytonb302dff2012-02-01 08:09:32 +0000265 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
266 def __init__(self, sbmodule):
267 self.sbmodule = sbmodule
268
269 def __len__(self):
270 if self.sbmodule:
Filipe Cabecinhas3cae38b2012-05-11 20:39:42 +0000271 return int(self.sbmodule.GetNumSymbols())
Greg Claytonb302dff2012-02-01 08:09:32 +0000272 return 0
273
274 def __getitem__(self, key):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000275 count = len(self)
Greg Claytonb302dff2012-02-01 08:09:32 +0000276 if type(key) is int:
277 if key < count:
278 return self.sbmodule.GetSymbolAtIndex(key)
279 elif type(key) is str:
280 matches = []
Greg Claytonb3dafc62012-12-04 02:22:16 +0000281 sc_list = self.sbmodule.FindSymbols(key)
282 for sc in sc_list:
283 symbol = sc.symbol
284 if symbol:
Greg Claytonb302dff2012-02-01 08:09:32 +0000285 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000286 return matches
287 elif isinstance(key, self.re_compile_type):
Greg Claytonb302dff2012-02-01 08:09:32 +0000288 matches = []
289 for idx in range(count):
290 symbol = self.sbmodule.GetSymbolAtIndex(idx)
291 added = False
292 name = symbol.name
293 if name:
294 re_match = key.search(name)
295 if re_match:
296 matches.append(symbol)
297 added = True
298 if not added:
299 mangled = symbol.mangled
300 if mangled:
301 re_match = key.search(mangled)
302 if re_match:
303 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000304 return matches
Greg Claytonb302dff2012-02-01 08:09:32 +0000305 else:
306 print "error: unsupported item type: %s" % type(key)
307 return None
308
309 def get_symbols_access_object(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000310 '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.'''
Greg Claytonb302dff2012-02-01 08:09:32 +0000311 return self.symbols_access (self)
312
313 def get_symbols_array(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000314 '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
Greg Claytonb302dff2012-02-01 08:09:32 +0000315 symbols = []
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000316 for idx in range(self.num_symbols):
Greg Claytonb302dff2012-02-01 08:09:32 +0000317 symbols.append(self.GetSymbolAtIndex(idx))
318 return symbols
319
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000320 class sections_access(object):
321 re_compile_type = type(re.compile('.'))
322 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
323 def __init__(self, sbmodule):
324 self.sbmodule = sbmodule
325
326 def __len__(self):
327 if self.sbmodule:
Filipe Cabecinhas3cae38b2012-05-11 20:39:42 +0000328 return int(self.sbmodule.GetNumSections())
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000329 return 0
330
331 def __getitem__(self, key):
332 count = len(self)
333 if type(key) is int:
334 if key < count:
335 return self.sbmodule.GetSectionAtIndex(key)
336 elif type(key) is str:
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000337 for idx in range(count):
338 section = self.sbmodule.GetSectionAtIndex(idx)
339 if section.name == key:
Greg Clayton39f54ea2012-02-04 02:58:17 +0000340 return section
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000341 elif isinstance(key, self.re_compile_type):
342 matches = []
343 for idx in range(count):
344 section = self.sbmodule.GetSectionAtIndex(idx)
345 name = section.name
346 if name:
347 re_match = key.search(name)
348 if re_match:
349 matches.append(section)
350 return matches
351 else:
352 print "error: unsupported item type: %s" % type(key)
353 return None
354
355 def get_sections_access_object(self):
356 '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
357 return self.sections_access (self)
358
359 def get_sections_array(self):
360 '''An accessor function that returns an array object that contains all sections in this module object.'''
361 if not hasattr(self, 'sections'):
362 self.sections = []
363 for idx in range(self.num_sections):
364 self.sections.append(self.GetSectionAtIndex(idx))
365 return self.sections
366
Greg Claytonb302dff2012-02-01 08:09:32 +0000367 __swig_getmethods__["symbols"] = get_symbols_array
Greg Clayton2a94be12012-06-29 22:00:42 +0000368 if _newclass: symbols = property(get_symbols_array, None, doc='''A read only property that returns a list() of lldb.SBSymbol objects contained in this module.''')
Greg Claytonb302dff2012-02-01 08:09:32 +0000369
370 __swig_getmethods__["symbol"] = get_symbols_access_object
Greg Clayton2a94be12012-06-29 22:00:42 +0000371 if _newclass: symbol = property(get_symbols_access_object, None, doc='''A read only property that can be used to access symbols by index ("symbol = module.symbol[0]"), name ("symbols = module.symbol['main']"), or using a regular expression ("symbols = module.symbol[re.compile(...)]"). The return value is a single lldb.SBSymbol object for array access, and a list() of lldb.SBSymbol objects for name and regular expression access''')
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000372
373 __swig_getmethods__["sections"] = get_sections_array
Greg Clayton2a94be12012-06-29 22:00:42 +0000374 if _newclass: sections = property(get_sections_array, None, doc='''A read only property that returns a list() of lldb.SBSection objects contained in this module.''')
Greg Claytonb302dff2012-02-01 08:09:32 +0000375
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000376 __swig_getmethods__["section"] = get_sections_access_object
Greg Clayton2a94be12012-06-29 22:00:42 +0000377 if _newclass: section = property(get_sections_access_object, None, doc='''A read only property that can be used to access symbols by index ("section = module.section[0]"), name ("sections = module.section[\'main\']"), or using a regular expression ("sections = module.section[re.compile(...)]"). The return value is a single lldb.SBSection object for array access, and a list() of lldb.SBSection objects for name and regular expression access''')
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000378
Greg Claytonb302dff2012-02-01 08:09:32 +0000379 def get_uuid(self):
380 return uuid.UUID (self.GetUUIDString())
381
382 __swig_getmethods__["uuid"] = get_uuid
Greg Clayton2a94be12012-06-29 22:00:42 +0000383 if _newclass: uuid = property(get_uuid, None, doc='''A read only property that returns a standard python uuid.UUID object that represents the UUID of this module.''')
Greg Claytonb302dff2012-02-01 08:09:32 +0000384
Greg Clayton1b925202012-01-29 06:07:39 +0000385 __swig_getmethods__["file"] = GetFileSpec
Greg Clayton2a94be12012-06-29 22:00:42 +0000386 if _newclass: file = property(GetFileSpec, None, doc='''A read only property that returns an lldb object that represents the file (lldb.SBFileSpec) for this object file for this module as it is represented where it is being debugged.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000387
388 __swig_getmethods__["platform_file"] = GetPlatformFileSpec
Greg Clayton2a94be12012-06-29 22:00:42 +0000389 if _newclass: platform_file = property(GetPlatformFileSpec, None, doc='''A read only property that returns an lldb object that represents the file (lldb.SBFileSpec) for this object file for this module as it is represented on the current host system.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000390
Greg Clayton1b925202012-01-29 06:07:39 +0000391 __swig_getmethods__["byte_order"] = GetByteOrder
Greg Clayton2a94be12012-06-29 22:00:42 +0000392 if _newclass: byte_order = property(GetByteOrder, None, doc='''A read only property that returns an lldb enumeration value (lldb.eByteOrderLittle, lldb.eByteOrderBig, lldb.eByteOrderInvalid) that represents the byte order for this module.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000393
394 __swig_getmethods__["addr_size"] = GetAddressByteSize
Greg Clayton2a94be12012-06-29 22:00:42 +0000395 if _newclass: addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000396
397 __swig_getmethods__["triple"] = GetTriple
Greg Clayton2a94be12012-06-29 22:00:42 +0000398 if _newclass: triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000399
400 __swig_getmethods__["num_symbols"] = GetNumSymbols
Greg Clayton2a94be12012-06-29 22:00:42 +0000401 if _newclass: num_symbols = property(GetNumSymbols, None, doc='''A read only property that returns number of symbols in the module symbol table as an integer.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000402
403 __swig_getmethods__["num_sections"] = GetNumSections
Greg Clayton2a94be12012-06-29 22:00:42 +0000404 if _newclass: num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''')
Greg Clayton1b925202012-01-29 06:07:39 +0000405
406 %}
407
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000408};
409
410} // namespace lldb