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