blob: 6142c39dfb965e5717fde504eb46304ee084f2e1 [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
Greg Clayton0b93a752012-12-05 21:24:42 +0000225 lldb::SBType
226 GetBasicType(lldb::BasicType type);
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000227
228 %feature("docstring", "
229 //------------------------------------------------------------------
230 /// Find global and static variables by name.
231 ///
232 /// @param[in] target
233 /// A valid SBTarget instance representing the debuggee.
234 ///
235 /// @param[in] name
236 /// The name of the global or static variable we are looking
237 /// for.
238 ///
239 /// @param[in] max_matches
240 /// Allow the number of matches to be limited to \a max_matches.
241 ///
242 /// @return
243 /// A list of matched variables in an SBValueList.
244 //------------------------------------------------------------------
245 ") FindGlobalVariables;
246 lldb::SBValueList
247 FindGlobalVariables (lldb::SBTarget &target,
248 const char *name,
249 uint32_t max_matches);
Greg Clayton1b925202012-01-29 06:07:39 +0000250
Enrico Granata392bd8d2013-01-16 18:53:52 +0000251 %feature("docstring", "
252 //------------------------------------------------------------------
253 /// Find the first global (or static) variable by name.
254 ///
255 /// @param[in] target
256 /// A valid SBTarget instance representing the debuggee.
257 ///
258 /// @param[in] name
259 /// The name of the global or static variable we are looking
260 /// for.
261 ///
262 /// @return
263 /// An SBValue that gets filled in with the found variable (if any).
264 //------------------------------------------------------------------
265 ") FindFirstGlobalVariable;
266 lldb::SBValue
267 FindFirstGlobalVariable (lldb::SBTarget &target, const char *name);
268
Greg Clayton1b925202012-01-29 06:07:39 +0000269 lldb::ByteOrder
270 GetByteOrder ();
271
272 uint32_t
273 GetAddressByteSize();
274
275 const char *
276 GetTriple ();
Greg Clayton49f4bf22012-02-22 19:41:02 +0000277
278 uint32_t
279 GetVersion (uint32_t *versions,
280 uint32_t num_versions);
Greg Clayton1b925202012-01-29 06:07:39 +0000281
282 %pythoncode %{
Greg Claytonb302dff2012-02-01 08:09:32 +0000283 class symbols_access(object):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000284 re_compile_type = type(re.compile('.'))
Greg Claytonb302dff2012-02-01 08:09:32 +0000285 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
286 def __init__(self, sbmodule):
287 self.sbmodule = sbmodule
288
289 def __len__(self):
290 if self.sbmodule:
Filipe Cabecinhas3cae38b2012-05-11 20:39:42 +0000291 return int(self.sbmodule.GetNumSymbols())
Greg Claytonb302dff2012-02-01 08:09:32 +0000292 return 0
293
294 def __getitem__(self, key):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000295 count = len(self)
Greg Claytonb302dff2012-02-01 08:09:32 +0000296 if type(key) is int:
297 if key < count:
298 return self.sbmodule.GetSymbolAtIndex(key)
299 elif type(key) is str:
300 matches = []
Greg Claytonb3dafc62012-12-04 02:22:16 +0000301 sc_list = self.sbmodule.FindSymbols(key)
302 for sc in sc_list:
303 symbol = sc.symbol
304 if symbol:
Greg Claytonb302dff2012-02-01 08:09:32 +0000305 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000306 return matches
307 elif isinstance(key, self.re_compile_type):
Greg Claytonb302dff2012-02-01 08:09:32 +0000308 matches = []
309 for idx in range(count):
310 symbol = self.sbmodule.GetSymbolAtIndex(idx)
311 added = False
312 name = symbol.name
313 if name:
314 re_match = key.search(name)
315 if re_match:
316 matches.append(symbol)
317 added = True
318 if not added:
319 mangled = symbol.mangled
320 if mangled:
321 re_match = key.search(mangled)
322 if re_match:
323 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000324 return matches
Greg Claytonb302dff2012-02-01 08:09:32 +0000325 else:
326 print "error: unsupported item type: %s" % type(key)
327 return None
328
329 def get_symbols_access_object(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000330 '''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 +0000331 return self.symbols_access (self)
332
333 def get_symbols_array(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000334 '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
Greg Claytonb302dff2012-02-01 08:09:32 +0000335 symbols = []
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000336 for idx in range(self.num_symbols):
Greg Claytonb302dff2012-02-01 08:09:32 +0000337 symbols.append(self.GetSymbolAtIndex(idx))
338 return symbols
339
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000340 class sections_access(object):
341 re_compile_type = type(re.compile('.'))
342 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
343 def __init__(self, sbmodule):
344 self.sbmodule = sbmodule
345
346 def __len__(self):
347 if self.sbmodule:
Filipe Cabecinhas3cae38b2012-05-11 20:39:42 +0000348 return int(self.sbmodule.GetNumSections())
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000349 return 0
350
351 def __getitem__(self, key):
352 count = len(self)
353 if type(key) is int:
354 if key < count:
355 return self.sbmodule.GetSectionAtIndex(key)
356 elif type(key) is str:
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000357 for idx in range(count):
358 section = self.sbmodule.GetSectionAtIndex(idx)
359 if section.name == key:
Greg Clayton39f54ea2012-02-04 02:58:17 +0000360 return section
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000361 elif isinstance(key, self.re_compile_type):
362 matches = []
363 for idx in range(count):
364 section = self.sbmodule.GetSectionAtIndex(idx)
365 name = section.name
366 if name:
367 re_match = key.search(name)
368 if re_match:
369 matches.append(section)
370 return matches
371 else:
372 print "error: unsupported item type: %s" % type(key)
373 return None
374
375 def get_sections_access_object(self):
376 '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
377 return self.sections_access (self)
378
379 def get_sections_array(self):
380 '''An accessor function that returns an array object that contains all sections in this module object.'''
381 if not hasattr(self, 'sections'):
382 self.sections = []
383 for idx in range(self.num_sections):
384 self.sections.append(self.GetSectionAtIndex(idx))
385 return self.sections
386
Greg Claytonb302dff2012-02-01 08:09:32 +0000387 __swig_getmethods__["symbols"] = get_symbols_array
Greg Clayton2a94be12012-06-29 22:00:42 +0000388 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 +0000389
390 __swig_getmethods__["symbol"] = get_symbols_access_object
Greg Clayton2a94be12012-06-29 22:00:42 +0000391 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 +0000392
393 __swig_getmethods__["sections"] = get_sections_array
Greg Clayton2a94be12012-06-29 22:00:42 +0000394 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 +0000395
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000396 __swig_getmethods__["section"] = get_sections_access_object
Greg Clayton2a94be12012-06-29 22:00:42 +0000397 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 +0000398
Greg Claytonb302dff2012-02-01 08:09:32 +0000399 def get_uuid(self):
400 return uuid.UUID (self.GetUUIDString())
401
402 __swig_getmethods__["uuid"] = get_uuid
Greg Clayton2a94be12012-06-29 22:00:42 +0000403 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 +0000404
Greg Clayton1b925202012-01-29 06:07:39 +0000405 __swig_getmethods__["file"] = GetFileSpec
Greg Clayton2a94be12012-06-29 22:00:42 +0000406 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 +0000407
408 __swig_getmethods__["platform_file"] = GetPlatformFileSpec
Greg Clayton2a94be12012-06-29 22:00:42 +0000409 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 +0000410
Greg Clayton1b925202012-01-29 06:07:39 +0000411 __swig_getmethods__["byte_order"] = GetByteOrder
Greg Clayton2a94be12012-06-29 22:00:42 +0000412 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 +0000413
414 __swig_getmethods__["addr_size"] = GetAddressByteSize
Greg Clayton2a94be12012-06-29 22:00:42 +0000415 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 +0000416
417 __swig_getmethods__["triple"] = GetTriple
Greg Clayton2a94be12012-06-29 22:00:42 +0000418 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 +0000419
420 __swig_getmethods__["num_symbols"] = GetNumSymbols
Greg Clayton2a94be12012-06-29 22:00:42 +0000421 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 +0000422
423 __swig_getmethods__["num_sections"] = GetNumSections
Greg Clayton2a94be12012-06-29 22:00:42 +0000424 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 +0000425
426 %}
427
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000428};
429
430} // namespace lldb