• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //===-- 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 
10 namespace lldb {
11 
12 %feature("docstring",
13 "Represents an executable image and its associated object and symbol files.
14 
15 The module is designed to be able to select a single slice of an
16 executable image as it would appear on disk and during program
17 execution.
18 
19 You can retrieve SBModule from SBSymbolContext, which in turn is available
20 from SBFrame.
21 
22 SBModule supports symbol iteration, for example,
23 
24     for symbol in module:
25         name = symbol.GetName()
26         saddr = symbol.GetStartAddress()
27         eaddr = symbol.GetEndAddress()
28 
29 and 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 
34 to test module equality.  A module also contains object file sections, namely
35 SBSection.  SBModule supports section iteration through section_iter(), for
36 example,
37 
38     print 'Number of sections: %d' % module.GetNumSections()
39     for sec in module.section_iter():
40         print sec
41 
42 And 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 
51 produces this following output:
52 
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 "
92 ) SBModule;
93 class SBModule
94 {
95 public:
96 
97     SBModule ();
98 
99     SBModule (const lldb::SBModule &rhs);
100 
101     SBModule (const lldb::SBModuleSpec &module_spec);
102 
103     SBModule (lldb::SBProcess &process,
104               lldb::addr_t header_addr);
105 
106     ~SBModule ();
107 
108     bool
109     IsValid () const;
110 
111     void
112     Clear();
113 
114     %feature("docstring", "
115     //------------------------------------------------------------------
116     /// Get const accessor for the module file specification.
117     ///
118     /// This function returns the file for the module on the host system
119     /// that is running LLDB. This can differ from the path on the
120     /// platform since we might be doing remote debugging.
121     ///
122     /// @return
123     ///     A const reference to the file specification object.
124     //------------------------------------------------------------------
125     ") GetFileSpec;
126     lldb::SBFileSpec
127     GetFileSpec () const;
128 
129     %feature("docstring", "
130     //------------------------------------------------------------------
131     /// Get accessor for the module platform file specification.
132     ///
133     /// Platform file refers to the path of the module as it is known on
134     /// the remote system on which it is being debugged. For local
135     /// debugging this is always the same as Module::GetFileSpec(). But
136     /// remote debugging might mention a file '/usr/lib/liba.dylib'
137     /// which might be locally downloaded and cached. In this case the
138     /// platform file could be something like:
139     /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
140     /// The file could also be cached in a local developer kit directory.
141     ///
142     /// @return
143     ///     A const reference to the file specification object.
144     //------------------------------------------------------------------
145     ") GetPlatformFileSpec;
146     lldb::SBFileSpec
147     GetPlatformFileSpec () const;
148 
149     bool
150     SetPlatformFileSpec (const lldb::SBFileSpec &platform_file);
151 
152     %feature("docstring", "Returns the UUID of the module as a Python string."
153     ) GetUUIDString;
154     const char *
155     GetUUIDString () const;
156 
157     lldb::SBSection
158     FindSection (const char *sect_name);
159 
160     lldb::SBAddress
161     ResolveFileAddress (lldb::addr_t vm_addr);
162 
163     lldb::SBSymbolContext
164     ResolveSymbolContextForAddress (const lldb::SBAddress& addr,
165                                     uint32_t resolve_scope);
166 
167     bool
168     GetDescription (lldb::SBStream &description);
169 
170     uint32_t
171     GetNumCompileUnits();
172 
173     lldb::SBCompileUnit
174     GetCompileUnitAtIndex (uint32_t);
175 
176     size_t
177     GetNumSymbols ();
178 
179     lldb::SBSymbol
180     GetSymbolAtIndex (size_t idx);
181 
182     lldb::SBSymbol
183     FindSymbol (const char *name,
184                 lldb::SymbolType type = eSymbolTypeAny);
185 
186     lldb::SBSymbolContextList
187     FindSymbols (const char *name,
188                  lldb::SymbolType type = eSymbolTypeAny);
189 
190 
191     size_t
192     GetNumSections ();
193 
194     lldb::SBSection
195     GetSectionAtIndex (size_t idx);
196 
197 
198     %feature("docstring", "
199     //------------------------------------------------------------------
200     /// Find functions by name.
201     ///
202     /// @param[in] name
203     ///     The name of the function we are looking for.
204     ///
205     /// @param[in] name_type_mask
206     ///     A logical OR of one or more FunctionNameType enum bits that
207     ///     indicate what kind of names should be used when doing the
208     ///     lookup. Bits include fully qualified names, base names,
209     ///     C++ methods, or ObjC selectors.
210     ///     See FunctionNameType for more details.
211     ///
212     /// @return
213     ///     A symbol context list that gets filled in with all of the
214     ///     matches.
215     //------------------------------------------------------------------
216     ") FindFunctions;
217     lldb::SBSymbolContextList
218     FindFunctions (const char *name,
219                    uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
220 
221     lldb::SBType
222     FindFirstType (const char* name);
223 
224     lldb::SBTypeList
225     FindTypes (const char* type);
226 
227     lldb::SBType
228     GetBasicType(lldb::BasicType type);
229 
230     %feature("docstring", "
231     //------------------------------------------------------------------
232     /// Get all types matching \a type_mask from debug info in this
233     /// module.
234     ///
235     /// @param[in] type_mask
236     ///     A bitfield that consists of one or more bits logically OR'ed
237     ///     together from the lldb::TypeClass enumeration. This allows
238     ///     you to request only structure types, or only class, struct
239     ///     and union types. Passing in lldb::eTypeClassAny will return
240     ///     all types found in the debug information for this module.
241     ///
242     /// @return
243     ///     A list of types in this module that match \a type_mask
244     //------------------------------------------------------------------
245     ") GetTypes;
246     lldb::SBTypeList
247     GetTypes (uint32_t type_mask = lldb::eTypeClassAny);
248 
249     %feature("docstring", "
250     //------------------------------------------------------------------
251     /// Find global and static variables by name.
252     ///
253     /// @param[in] target
254     ///     A valid SBTarget instance representing the debuggee.
255     ///
256     /// @param[in] name
257     ///     The name of the global or static variable we are looking
258     ///     for.
259     ///
260     /// @param[in] max_matches
261     ///     Allow the number of matches to be limited to \a max_matches.
262     ///
263     /// @return
264     ///     A list of matched variables in an SBValueList.
265     //------------------------------------------------------------------
266     ") FindGlobalVariables;
267     lldb::SBValueList
268     FindGlobalVariables (lldb::SBTarget &target,
269                          const char *name,
270                          uint32_t max_matches);
271 
272     %feature("docstring", "
273     //------------------------------------------------------------------
274     /// Find the first global (or static) variable by name.
275     ///
276     /// @param[in] target
277     ///     A valid SBTarget instance representing the debuggee.
278     ///
279     /// @param[in] name
280     ///     The name of the global or static variable we are looking
281     ///     for.
282     ///
283     /// @return
284     ///     An SBValue that gets filled in with the found variable (if any).
285     //------------------------------------------------------------------
286     ") FindFirstGlobalVariable;
287     lldb::SBValue
288     FindFirstGlobalVariable (lldb::SBTarget &target, const char *name);
289 
290     lldb::ByteOrder
291     GetByteOrder ();
292 
293     uint32_t
294     GetAddressByteSize();
295 
296     const char *
297     GetTriple ();
298 
299     uint32_t
300     GetVersion (uint32_t *versions,
301                 uint32_t num_versions);
302 
303     bool
304     operator == (const lldb::SBModule &rhs) const;
305 
306     bool
307     operator != (const lldb::SBModule &rhs) const;
308 
309     %pythoncode %{
310         class symbols_access(object):
311             re_compile_type = type(re.compile('.'))
312             '''A helper object that will lazily hand out lldb.SBSymbol objects for a module when supplied an index, name, or regular expression.'''
313             def __init__(self, sbmodule):
314                 self.sbmodule = sbmodule
315 
316             def __len__(self):
317                 if self.sbmodule:
318                     return int(self.sbmodule.GetNumSymbols())
319                 return 0
320 
321             def __getitem__(self, key):
322                 count = len(self)
323                 if type(key) is int:
324                     if key < count:
325                         return self.sbmodule.GetSymbolAtIndex(key)
326                 elif type(key) is str:
327                     matches = []
328                     sc_list = self.sbmodule.FindSymbols(key)
329                     for sc in sc_list:
330                         symbol = sc.symbol
331                         if symbol:
332                             matches.append(symbol)
333                     return matches
334                 elif isinstance(key, self.re_compile_type):
335                     matches = []
336                     for idx in range(count):
337                         symbol = self.sbmodule.GetSymbolAtIndex(idx)
338                         added = False
339                         name = symbol.name
340                         if name:
341                             re_match = key.search(name)
342                             if re_match:
343                                 matches.append(symbol)
344                                 added = True
345                         if not added:
346                             mangled = symbol.mangled
347                             if mangled:
348                                 re_match = key.search(mangled)
349                                 if re_match:
350                                     matches.append(symbol)
351                     return matches
352                 else:
353                     print "error: unsupported item type: %s" % type(key)
354                 return None
355 
356         def get_symbols_access_object(self):
357             '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.'''
358             return self.symbols_access (self)
359 
360         def get_compile_units_access_object (self):
361             '''An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.'''
362             return self.compile_units_access (self)
363 
364         def get_symbols_array(self):
365             '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
366             symbols = []
367             for idx in range(self.num_symbols):
368                 symbols.append(self.GetSymbolAtIndex(idx))
369             return symbols
370 
371         class sections_access(object):
372             re_compile_type = type(re.compile('.'))
373             '''A helper object that will lazily hand out lldb.SBSection objects for a module when supplied an index, name, or regular expression.'''
374             def __init__(self, sbmodule):
375                 self.sbmodule = sbmodule
376 
377             def __len__(self):
378                 if self.sbmodule:
379                     return int(self.sbmodule.GetNumSections())
380                 return 0
381 
382             def __getitem__(self, key):
383                 count = len(self)
384                 if type(key) is int:
385                     if key < count:
386                         return self.sbmodule.GetSectionAtIndex(key)
387                 elif type(key) is str:
388                     for idx in range(count):
389                         section = self.sbmodule.GetSectionAtIndex(idx)
390                         if section.name == key:
391                             return section
392                 elif isinstance(key, self.re_compile_type):
393                     matches = []
394                     for idx in range(count):
395                         section = self.sbmodule.GetSectionAtIndex(idx)
396                         name = section.name
397                         if name:
398                             re_match = key.search(name)
399                             if re_match:
400                                 matches.append(section)
401                     return matches
402                 else:
403                     print "error: unsupported item type: %s" % type(key)
404                 return None
405 
406         class compile_units_access(object):
407             re_compile_type = type(re.compile('.'))
408             '''A helper object that will lazily hand out lldb.SBCompileUnit objects for a module when supplied an index, full or partial path, or regular expression.'''
409             def __init__(self, sbmodule):
410                 self.sbmodule = sbmodule
411 
412             def __len__(self):
413                 if self.sbmodule:
414                     return int(self.sbmodule.GetNumCompileUnits())
415                 return 0
416 
417             def __getitem__(self, key):
418                 count = len(self)
419                 if type(key) is int:
420                     if key < count:
421                         return self.sbmodule.GetCompileUnitAtIndex(key)
422                 elif type(key) is str:
423                     is_full_path = key[0] == '/'
424                     for idx in range(count):
425                         comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx)
426                         if is_full_path:
427                             if comp_unit.file.fullpath == key:
428                                 return comp_unit
429                         else:
430                             if comp_unit.file.basename == key:
431                                 return comp_unit
432                 elif isinstance(key, self.re_compile_type):
433                     matches = []
434                     for idx in range(count):
435                         comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx)
436                         fullpath = comp_unit.file.fullpath
437                         if fullpath:
438                             re_match = key.search(fullpath)
439                             if re_match:
440                                 matches.append(comp_unit)
441                     return matches
442                 else:
443                     print "error: unsupported item type: %s" % type(key)
444                 return None
445 
446         def get_sections_access_object(self):
447             '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
448             return self.sections_access (self)
449 
450         def get_sections_array(self):
451             '''An accessor function that returns an array object that contains all sections in this module object.'''
452             if not hasattr(self, 'sections_array'):
453                 self.sections_array = []
454                 for idx in range(self.num_sections):
455                     self.sections_array.append(self.GetSectionAtIndex(idx))
456             return self.sections_array
457 
458         def get_compile_units_array(self):
459             '''An accessor function that returns an array object that contains all compile_units in this module object.'''
460             if not hasattr(self, 'compile_units_array'):
461                 self.compile_units_array = []
462                 for idx in range(self.GetNumCompileUnits()):
463                     self.compile_units_array.append(self.GetCompileUnitAtIndex(idx))
464             return self.compile_units_array
465 
466         __swig_getmethods__["symbols"] = get_symbols_array
467         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.''')
468 
469         __swig_getmethods__["symbol"] = get_symbols_access_object
470         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''')
471 
472         __swig_getmethods__["sections"] = get_sections_array
473         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.''')
474 
475         __swig_getmethods__["compile_units"] = get_compile_units_array
476         if _newclass: compile_units = property(get_compile_units_array, None, doc='''A read only property that returns a list() of lldb.SBCompileUnit objects contained in this module.''')
477 
478         __swig_getmethods__["section"] = get_sections_access_object
479         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''')
480 
481         __swig_getmethods__["compile_unit"] = get_compile_units_access_object
482         if _newclass: section = property(get_sections_access_object, None, doc='''A read only property that can be used to access compile units by index ("compile_unit = module.compile_unit[0]"), name ("compile_unit = module.compile_unit[\'main.cpp\']"), or using a regular expression ("compile_unit = module.compile_unit[re.compile(...)]"). The return value is a single lldb.SBCompileUnit object for array access or by full or partial path, and a list() of lldb.SBCompileUnit objects regular expressions.''')
483 
484         def get_uuid(self):
485             return uuid.UUID (self.GetUUIDString())
486 
487         __swig_getmethods__["uuid"] = get_uuid
488         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.''')
489 
490         __swig_getmethods__["file"] = GetFileSpec
491         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.''')
492 
493         __swig_getmethods__["platform_file"] = GetPlatformFileSpec
494         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.''')
495 
496         __swig_getmethods__["byte_order"] = GetByteOrder
497         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.''')
498 
499         __swig_getmethods__["addr_size"] = GetAddressByteSize
500         if _newclass: addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''')
501 
502         __swig_getmethods__["triple"] = GetTriple
503         if _newclass: triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''')
504 
505         __swig_getmethods__["num_symbols"] = GetNumSymbols
506         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.''')
507 
508         __swig_getmethods__["num_sections"] = GetNumSections
509         if _newclass: num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''')
510 
511     %}
512 
513 };
514 
515 } // namespace lldb
516