scripts/interface/SBModule.i

   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     lldb::SBFileSpec
 153     GetRemoteInstallFileSpec ();
 154
 155     bool
 156     SetRemoteInstallFileSpec (lldb::SBFileSpec &file);
 157
 158     %feature("docstring", "Returns the UUID of the module as a Python string."
 159     ) GetUUIDString;
 160     const char *
 161     GetUUIDString () const;
 162
 163     lldb::SBSection
 164     FindSection (const char *sect_name);
 165
 166     lldb::SBAddress
 167     ResolveFileAddress (lldb::addr_t vm_addr);
 168
 169     lldb::SBSymbolContext
 170     ResolveSymbolContextForAddress (const lldb::SBAddress& addr,
 171                                     uint32_t resolve_scope);
 172
 173     bool
 174     GetDescription (lldb::SBStream &description);
 175
 176     uint32_t
 177     GetNumCompileUnits();
 178
 179     lldb::SBCompileUnit
 180     GetCompileUnitAtIndex (uint32_t);
 181
 182     size_t
 183     GetNumSymbols ();
 184
 185     lldb::SBSymbol
 186     GetSymbolAtIndex (size_t idx);
 187
 188     lldb::SBSymbol
 189     FindSymbol (const char *name,
 190                 lldb::SymbolType type = eSymbolTypeAny);
 191
 192     lldb::SBSymbolContextList
 193     FindSymbols (const char *name,
 194                  lldb::SymbolType type = eSymbolTypeAny);
 195
 196
 197     size_t
 198     GetNumSections ();
 199
 200     lldb::SBSection
 201     GetSectionAtIndex (size_t idx);
 202
 203
 204     %feature("docstring", "
 205     //------------------------------------------------------------------
 206     /// Find functions by name.
 207     ///
 208     /// @param[in] name
 209     ///     The name of the function we are looking for.
 210     ///
 211     /// @param[in] name_type_mask
 212     ///     A logical OR of one or more FunctionNameType enum bits that
 213     ///     indicate what kind of names should be used when doing the
 214     ///     lookup. Bits include fully qualified names, base names,
 215     ///     C++ methods, or ObjC selectors.
 216     ///     See FunctionNameType for more details.
 217     ///
 218     /// @return
 219     ///     A symbol context list that gets filled in with all of the
 220     ///     matches.
 221     //------------------------------------------------------------------
 222     ") FindFunctions;
 223     lldb::SBSymbolContextList
 224     FindFunctions (const char *name,
 225                    uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
 226
 227     lldb::SBType
 228     FindFirstType (const char* name);
 229
 230     lldb::SBTypeList
 231     FindTypes (const char* type);
 232
 233     lldb::SBType
 234     GetTypeByID (lldb::user_id_t uid);
 235
 236     lldb::SBType
 237     GetBasicType(lldb::BasicType type);
 238
 239     %feature("docstring", "
 240     //------------------------------------------------------------------
 241     /// Get all types matching \a type_mask from debug info in this
 242     /// module.
 243     ///
 244     /// @param[in] type_mask
 245     ///     A bitfield that consists of one or more bits logically OR'ed
 246     ///     together from the lldb::TypeClass enumeration. This allows
 247     ///     you to request only structure types, or only class, struct
 248     ///     and union types. Passing in lldb::eTypeClassAny will return
 249     ///     all types found in the debug information for this module.
 250     ///
 251     /// @return
 252     ///     A list of types in this module that match \a type_mask
 253     //------------------------------------------------------------------
 254     ") GetTypes;
 255     lldb::SBTypeList
 256     GetTypes (uint32_t type_mask = lldb::eTypeClassAny);
 257
 258     %feature("docstring", "
 259     //------------------------------------------------------------------
 260     /// Find global and static variables by name.
 261     ///
 262     /// @param[in] target
 263     ///     A valid SBTarget instance representing the debuggee.
 264     ///
 265     /// @param[in] name
 266     ///     The name of the global or static variable we are looking
 267     ///     for.
 268     ///
 269     /// @param[in] max_matches
 270     ///     Allow the number of matches to be limited to \a max_matches.
 271     ///
 272     /// @return
 273     ///     A list of matched variables in an SBValueList.
 274     //------------------------------------------------------------------
 275     ") FindGlobalVariables;
 276     lldb::SBValueList
 277     FindGlobalVariables (lldb::SBTarget &target,
 278                          const char *name,
 279                          uint32_t max_matches);
 280
 281     %feature("docstring", "
 282     //------------------------------------------------------------------
 283     /// Find the first global (or static) variable by name.
 284     ///
 285     /// @param[in] target
 286     ///     A valid SBTarget instance representing the debuggee.
 287     ///
 288     /// @param[in] name
 289     ///     The name of the global or static variable we are looking
 290     ///     for.
 291     ///
 292     /// @return
 293     ///     An SBValue that gets filled in with the found variable (if any).
 294     //------------------------------------------------------------------
 295     ") FindFirstGlobalVariable;
 296     lldb::SBValue
 297     FindFirstGlobalVariable (lldb::SBTarget &target, const char *name);
 298
 299     lldb::ByteOrder
 300     GetByteOrder ();
 301
 302     uint32_t
 303     GetAddressByteSize();
 304
 305     const char *
 306     GetTriple ();
 307
 308     uint32_t
 309     GetVersion (uint32_t *versions,
 310                 uint32_t num_versions);
 311
 312     lldb::SBFileSpec
 313     GetSymbolFileSpec() const;
 314
 315     lldb::SBAddress
 316     GetObjectFileHeaderAddress() const;
 317
 318     bool
 319     operator == (const lldb::SBModule &rhs) const;
 320
 321     bool
 322     operator != (const lldb::SBModule &rhs) const;
 323
 324     %pythoncode %{
 325         class symbols_access(object):
 326             re_compile_type = type(re.compile('.'))
 327             '''A helper object that will lazily hand out lldb.SBSymbol objects for a module when supplied an index, name, or regular expression.'''
 328             def __init__(self, sbmodule):
 329                 self.sbmodule = sbmodule
 330
 331             def __len__(self):
 332                 if self.sbmodule:
 333                     return int(self.sbmodule.GetNumSymbols())
 334                 return 0
 335
 336             def __getitem__(self, key):
 337                 count = len(self)
 338                 if type(key) is int:
 339                     if key < count:
 340                         return self.sbmodule.GetSymbolAtIndex(key)
 341                 elif type(key) is str:
 342                     matches = []
 343                     sc_list = self.sbmodule.FindSymbols(key)
 344                     for sc in sc_list:
 345                         symbol = sc.symbol
 346                         if symbol:
 347                             matches.append(symbol)
 348                     return matches
 349                 elif isinstance(key, self.re_compile_type):
 350                     matches = []
 351                     for idx in range(count):
 352                         symbol = self.sbmodule.GetSymbolAtIndex(idx)
 353                         added = False
 354                         name = symbol.name
 355                         if name:
 356                             re_match = key.search(name)
 357                             if re_match:
 358                                 matches.append(symbol)
 359                                 added = True
 360                         if not added:
 361                             mangled = symbol.mangled
 362                             if mangled:
 363                                 re_match = key.search(mangled)
 364                                 if re_match:
 365                                     matches.append(symbol)
 366                     return matches
 367                 else:
 368                     print("error: unsupported item type: %s" % type(key))
 369                 return None
 370
 371         def get_symbols_access_object(self):
 372             '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.'''
 373             return self.symbols_access (self)
 374
 375         def get_compile_units_access_object (self):
 376             '''An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.'''
 377             return self.compile_units_access (self)
 378
 379         def get_symbols_array(self):
 380             '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
 381             symbols = []
 382             for idx in range(self.num_symbols):
 383                 symbols.append(self.GetSymbolAtIndex(idx))
 384             return symbols
 385
 386         class sections_access(object):
 387             re_compile_type = type(re.compile('.'))
 388             '''A helper object that will lazily hand out lldb.SBSection objects for a module when supplied an index, name, or regular expression.'''
 389             def __init__(self, sbmodule):
 390                 self.sbmodule = sbmodule
 391
 392             def __len__(self):
 393                 if self.sbmodule:
 394                     return int(self.sbmodule.GetNumSections())
 395                 return 0
 396
 397             def __getitem__(self, key):
 398                 count = len(self)
 399                 if type(key) is int:
 400                     if key < count:
 401                         return self.sbmodule.GetSectionAtIndex(key)
 402                 elif type(key) is str:
 403                     for idx in range(count):
 404                         section = self.sbmodule.GetSectionAtIndex(idx)
 405                         if section.name == key:
 406                             return section
 407                 elif isinstance(key, self.re_compile_type):
 408                     matches = []
 409                     for idx in range(count):
 410                         section = self.sbmodule.GetSectionAtIndex(idx)
 411                         name = section.name
 412                         if name:
 413                             re_match = key.search(name)
 414                             if re_match:
 415                                 matches.append(section)
 416                     return matches
 417                 else:
 418                     print("error: unsupported item type: %s" % type(key))
 419                 return None
 420
 421         class compile_units_access(object):
 422             re_compile_type = type(re.compile('.'))
 423             '''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.'''
 424             def __init__(self, sbmodule):
 425                 self.sbmodule = sbmodule
 426
 427             def __len__(self):
 428                 if self.sbmodule:
 429                     return int(self.sbmodule.GetNumCompileUnits())
 430                 return 0
 431
 432             def __getitem__(self, key):
 433                 count = len(self)
 434                 if type(key) is int:
 435                     if key < count:
 436                         return self.sbmodule.GetCompileUnitAtIndex(key)
 437                 elif type(key) is str:
 438                     is_full_path = key[0] == '/'
 439                     for idx in range(count):
 440                         comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx)
 441                         if is_full_path:
 442                             if comp_unit.file.fullpath == key:
 443                                 return comp_unit
 444                         else:
 445                             if comp_unit.file.basename == key:
 446                                 return comp_unit
 447                 elif isinstance(key, self.re_compile_type):
 448                     matches = []
 449                     for idx in range(count):
 450                         comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx)
 451                         fullpath = comp_unit.file.fullpath
 452                         if fullpath:
 453                             re_match = key.search(fullpath)
 454                             if re_match:
 455                                 matches.append(comp_unit)
 456                     return matches
 457                 else:
 458                     print("error: unsupported item type: %s" % type(key))
 459                 return None
 460
 461         def get_sections_access_object(self):
 462             '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
 463             return self.sections_access (self)
 464
 465         def get_sections_array(self):
 466             '''An accessor function that returns an array object that contains all sections in this module object.'''
 467             if not hasattr(self, 'sections_array'):
 468                 self.sections_array = []
 469                 for idx in range(self.num_sections):
 470                     self.sections_array.append(self.GetSectionAtIndex(idx))
 471             return self.sections_array
 472
 473         def get_compile_units_array(self):
 474             '''An accessor function that returns an array object that contains all compile_units in this module object.'''
 475             if not hasattr(self, 'compile_units_array'):
 476                 self.compile_units_array = []
 477                 for idx in range(self.GetNumCompileUnits()):
 478                     self.compile_units_array.append(self.GetCompileUnitAtIndex(idx))
 479             return self.compile_units_array
 480
 481         __swig_getmethods__["symbols"] = get_symbols_array
 482         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.''')
 483
 484         __swig_getmethods__["symbol"] = get_symbols_access_object
 485         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''')
 486
 487         __swig_getmethods__["sections"] = get_sections_array
 488         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.''')
 489
 490         __swig_getmethods__["compile_units"] = get_compile_units_array
 491         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.''')
 492
 493         __swig_getmethods__["section"] = get_sections_access_object
 494         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''')
 495
 496         __swig_getmethods__["compile_unit"] = get_compile_units_access_object
 497         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.''')
 498
 499         def get_uuid(self):
 500             return uuid.UUID (self.GetUUIDString())
 501
 502         __swig_getmethods__["uuid"] = get_uuid
 503         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.''')
 504
 505         __swig_getmethods__["file"] = GetFileSpec
 506         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.''')
 507
 508         __swig_getmethods__["platform_file"] = GetPlatformFileSpec
 509         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.''')
 510
 511         __swig_getmethods__["byte_order"] = GetByteOrder
 512         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.''')
 513
 514         __swig_getmethods__["addr_size"] = GetAddressByteSize
 515         if _newclass: addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''')
 516
 517         __swig_getmethods__["triple"] = GetTriple
 518         if _newclass: triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''')
 519
 520         __swig_getmethods__["num_symbols"] = GetNumSymbols
 521         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.''')
 522
 523         __swig_getmethods__["num_sections"] = GetNumSections
 524         if _newclass: num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''')
 525
 526     %}
 527
 528 };
 529
 530 } // namespace lldb