1//===-- SWIG Interface for SBModule -----------------------------*- C++ -*-===// 2// 3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4// See https://llvm.org/LICENSE.txt for license information. 5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6// 7//===----------------------------------------------------------------------===// 8 9namespace lldb { 10 11#ifdef SWIGPYTHON 12%pythoncode%{ 13# ================================== 14# Helper function for SBModule class 15# ================================== 16def in_range(symbol, section): 17 """Test whether a symbol is within the range of a section.""" 18 symSA = symbol.GetStartAddress().GetFileAddress() 19 symEA = symbol.GetEndAddress().GetFileAddress() 20 secSA = section.GetFileAddress() 21 secEA = secSA + section.GetByteSize() 22 23 if symEA != LLDB_INVALID_ADDRESS: 24 if secSA <= symSA and symEA <= secEA: 25 return True 26 else: 27 return False 28 else: 29 if secSA <= symSA and symSA < secEA: 30 return True 31 else: 32 return False 33%} 34#endif 35 36%feature("docstring", 37"Represents an executable image and its associated object and symbol files. 38 39The module is designed to be able to select a single slice of an 40executable image as it would appear on disk and during program 41execution. 42 43You can retrieve SBModule from SBSymbolContext, which in turn is available 44from SBFrame. 45 46SBModule supports symbol iteration, for example, 47 48 for symbol in module: 49 name = symbol.GetName() 50 saddr = symbol.GetStartAddress() 51 eaddr = symbol.GetEndAddress() 52 53and rich comparison methods which allow the API program to use, 54 55 if thisModule == thatModule: 56 print('This module is the same as that module') 57 58to test module equality. A module also contains object file sections, namely 59SBSection. SBModule supports section iteration through section_iter(), for 60example, 61 62 print('Number of sections: %d' % module.GetNumSections()) 63 for sec in module.section_iter(): 64 print(sec) 65 66And to iterate the symbols within a SBSection, use symbol_in_section_iter(), 67 68 # Iterates the text section and prints each symbols within each sub-section. 69 for subsec in text_sec: 70 print(INDENT + repr(subsec)) 71 for sym in exe_module.symbol_in_section_iter(subsec): 72 print(INDENT2 + repr(sym)) 73 print(INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType())) 74 75produces this following output: 76 77 [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text 78 id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870) 79 symbol type: code 80 id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0) 81 symbol type: code 82 id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c) 83 symbol type: code 84 id = {0x00000023}, name = 'start', address = 0x0000000100001780 85 symbol type: code 86 [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs 87 id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62) 88 symbol type: trampoline 89 id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68) 90 symbol type: trampoline 91 id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e) 92 symbol type: trampoline 93 id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74) 94 symbol type: trampoline 95 id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a) 96 symbol type: trampoline 97 id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80) 98 symbol type: trampoline 99 id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86) 100 symbol type: trampoline 101 id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c) 102 symbol type: trampoline 103 id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92) 104 symbol type: trampoline 105 id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98) 106 symbol type: trampoline 107 id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e) 108 symbol type: trampoline 109 id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4) 110 symbol type: trampoline 111 [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper 112 [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring 113 [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info 114 [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame 115" 116) SBModule; 117class SBModule 118{ 119public: 120 121 SBModule (); 122 123 SBModule (const lldb::SBModule &rhs); 124 125 SBModule (const lldb::SBModuleSpec &module_spec); 126 127 SBModule (lldb::SBProcess &process, 128 lldb::addr_t header_addr); 129 130 ~SBModule (); 131 132 bool 133 IsValid () const; 134 135 explicit operator bool() const; 136 137 void 138 Clear(); 139 140 %feature("docstring", " 141 Get const accessor for the module file specification. 142 143 This function returns the file for the module on the host system 144 that is running LLDB. This can differ from the path on the 145 platform since we might be doing remote debugging. 146 147 @return 148 A const reference to the file specification object.") GetFileSpec; 149 lldb::SBFileSpec 150 GetFileSpec () const; 151 152 %feature("docstring", " 153 Get accessor for the module platform file specification. 154 155 Platform file refers to the path of the module as it is known on 156 the remote system on which it is being debugged. For local 157 debugging this is always the same as Module::GetFileSpec(). But 158 remote debugging might mention a file '/usr/lib/liba.dylib' 159 which might be locally downloaded and cached. In this case the 160 platform file could be something like: 161 '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib' 162 The file could also be cached in a local developer kit directory. 163 164 @return 165 A const reference to the file specification object.") GetPlatformFileSpec; 166 lldb::SBFileSpec 167 GetPlatformFileSpec () const; 168 169 bool 170 SetPlatformFileSpec (const lldb::SBFileSpec &platform_file); 171 172 lldb::SBFileSpec 173 GetRemoteInstallFileSpec (); 174 175 bool 176 SetRemoteInstallFileSpec (lldb::SBFileSpec &file); 177 178 %feature("docstring", "Returns the UUID of the module as a Python string." 179 ) GetUUIDString; 180 const char * 181 GetUUIDString () const; 182 183 bool operator==(const lldb::SBModule &rhs) const; 184 185 bool operator!=(const lldb::SBModule &rhs) const; 186 187 lldb::SBSection 188 FindSection (const char *sect_name); 189 190 lldb::SBAddress 191 ResolveFileAddress (lldb::addr_t vm_addr); 192 193 lldb::SBSymbolContext 194 ResolveSymbolContextForAddress (const lldb::SBAddress& addr, 195 uint32_t resolve_scope); 196 197 bool 198 GetDescription (lldb::SBStream &description); 199 200 uint32_t 201 GetNumCompileUnits(); 202 203 lldb::SBCompileUnit 204 GetCompileUnitAtIndex (uint32_t); 205 206 %feature("docstring", " 207 Find compile units related to *this module and passed source 208 file. 209 210 @param[in] sb_file_spec 211 A lldb::SBFileSpec object that contains source file 212 specification. 213 214 @return 215 A lldb::SBSymbolContextList that gets filled in with all of 216 the symbol contexts for all the matches.") FindCompileUnits; 217 lldb::SBSymbolContextList 218 FindCompileUnits (const lldb::SBFileSpec &sb_file_spec); 219 220 size_t 221 GetNumSymbols (); 222 223 lldb::SBSymbol 224 GetSymbolAtIndex (size_t idx); 225 226 lldb::SBSymbol 227 FindSymbol (const char *name, 228 lldb::SymbolType type = eSymbolTypeAny); 229 230 lldb::SBSymbolContextList 231 FindSymbols (const char *name, 232 lldb::SymbolType type = eSymbolTypeAny); 233 234 235 size_t 236 GetNumSections (); 237 238 lldb::SBSection 239 GetSectionAtIndex (size_t idx); 240 241 242 %feature("docstring", " 243 Find functions by name. 244 245 @param[in] name 246 The name of the function we are looking for. 247 248 @param[in] name_type_mask 249 A logical OR of one or more FunctionNameType enum bits that 250 indicate what kind of names should be used when doing the 251 lookup. Bits include fully qualified names, base names, 252 C++ methods, or ObjC selectors. 253 See FunctionNameType for more details. 254 255 @return 256 A symbol context list that gets filled in with all of the 257 matches.") FindFunctions; 258 lldb::SBSymbolContextList 259 FindFunctions (const char *name, 260 uint32_t name_type_mask = lldb::eFunctionNameTypeAny); 261 262 lldb::SBType 263 FindFirstType (const char* name); 264 265 lldb::SBTypeList 266 FindTypes (const char* type); 267 268 lldb::SBType 269 GetTypeByID (lldb::user_id_t uid); 270 271 lldb::SBType 272 GetBasicType(lldb::BasicType type); 273 274 %feature("docstring", " 275 Get all types matching type_mask from debug info in this 276 module. 277 278 @param[in] type_mask 279 A bitfield that consists of one or more bits logically OR'ed 280 together from the lldb::TypeClass enumeration. This allows 281 you to request only structure types, or only class, struct 282 and union types. Passing in lldb::eTypeClassAny will return 283 all types found in the debug information for this module. 284 285 @return 286 A list of types in this module that match type_mask") GetTypes; 287 lldb::SBTypeList 288 GetTypes (uint32_t type_mask = lldb::eTypeClassAny); 289 290 %feature("docstring", " 291 Find global and static variables by name. 292 293 @param[in] target 294 A valid SBTarget instance representing the debuggee. 295 296 @param[in] name 297 The name of the global or static variable we are looking 298 for. 299 300 @param[in] max_matches 301 Allow the number of matches to be limited to max_matches. 302 303 @return 304 A list of matched variables in an SBValueList.") FindGlobalVariables; 305 lldb::SBValueList 306 FindGlobalVariables (lldb::SBTarget &target, 307 const char *name, 308 uint32_t max_matches); 309 310 %feature("docstring", " 311 Find the first global (or static) variable by name. 312 313 @param[in] target 314 A valid SBTarget instance representing the debuggee. 315 316 @param[in] name 317 The name of the global or static variable we are looking 318 for. 319 320 @return 321 An SBValue that gets filled in with the found variable (if any).") FindFirstGlobalVariable; 322 lldb::SBValue 323 FindFirstGlobalVariable (lldb::SBTarget &target, const char *name); 324 325 lldb::ByteOrder 326 GetByteOrder (); 327 328 uint32_t 329 GetAddressByteSize(); 330 331 const char * 332 GetTriple (); 333 334 uint32_t 335 GetVersion (uint32_t *versions, 336 uint32_t num_versions); 337 338 lldb::SBFileSpec 339 GetSymbolFileSpec() const; 340 341 lldb::SBAddress 342 GetObjectFileHeaderAddress() const; 343 344 lldb::SBAddress 345 GetObjectFileEntryPointAddress() const; 346 347 %feature("docstring", " 348 Returns the number of modules in the module cache. This is an 349 implementation detail exposed for testing and should not be relied upon. 350 351 @return 352 The number of modules in the module cache.") GetNumberAllocatedModules; 353 static uint32_t 354 GetNumberAllocatedModules(); 355 356 STRING_EXTENSION(SBModule) 357 358#ifdef SWIGPYTHON 359 %pythoncode %{ 360 def __len__(self): 361 '''Return the number of symbols in a lldb.SBModule object.''' 362 return self.GetNumSymbols() 363 364 def __iter__(self): 365 '''Iterate over all symbols in a lldb.SBModule object.''' 366 return lldb_iter(self, 'GetNumSymbols', 'GetSymbolAtIndex') 367 368 def section_iter(self): 369 '''Iterate over all sections in a lldb.SBModule object.''' 370 return lldb_iter(self, 'GetNumSections', 'GetSectionAtIndex') 371 372 def compile_unit_iter(self): 373 '''Iterate over all compile units in a lldb.SBModule object.''' 374 return lldb_iter(self, 'GetNumCompileUnits', 'GetCompileUnitAtIndex') 375 376 def symbol_in_section_iter(self, section): 377 '''Given a module and its contained section, returns an iterator on the 378 symbols within the section.''' 379 for sym in self: 380 if in_range(sym, section): 381 yield sym 382 383 class symbols_access(object): 384 re_compile_type = type(re.compile('.')) 385 '''A helper object that will lazily hand out lldb.SBSymbol objects for a module when supplied an index, name, or regular expression.''' 386 def __init__(self, sbmodule): 387 self.sbmodule = sbmodule 388 389 def __len__(self): 390 if self.sbmodule: 391 return int(self.sbmodule.GetNumSymbols()) 392 return 0 393 394 def __getitem__(self, key): 395 count = len(self) 396 if type(key) is int: 397 if key < count: 398 return self.sbmodule.GetSymbolAtIndex(key) 399 elif type(key) is str: 400 matches = [] 401 sc_list = self.sbmodule.FindSymbols(key) 402 for sc in sc_list: 403 symbol = sc.symbol 404 if symbol: 405 matches.append(symbol) 406 return matches 407 elif isinstance(key, self.re_compile_type): 408 matches = [] 409 for idx in range(count): 410 symbol = self.sbmodule.GetSymbolAtIndex(idx) 411 added = False 412 name = symbol.name 413 if name: 414 re_match = key.search(name) 415 if re_match: 416 matches.append(symbol) 417 added = True 418 if not added: 419 mangled = symbol.mangled 420 if mangled: 421 re_match = key.search(mangled) 422 if re_match: 423 matches.append(symbol) 424 return matches 425 else: 426 print("error: unsupported item type: %s" % type(key)) 427 return None 428 429 def get_symbols_access_object(self): 430 '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.''' 431 return self.symbols_access (self) 432 433 def get_compile_units_access_object (self): 434 '''An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.''' 435 return self.compile_units_access (self) 436 437 def get_symbols_array(self): 438 '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.''' 439 symbols = [] 440 for idx in range(self.num_symbols): 441 symbols.append(self.GetSymbolAtIndex(idx)) 442 return symbols 443 444 class sections_access(object): 445 re_compile_type = type(re.compile('.')) 446 '''A helper object that will lazily hand out lldb.SBSection objects for a module when supplied an index, name, or regular expression.''' 447 def __init__(self, sbmodule): 448 self.sbmodule = sbmodule 449 450 def __len__(self): 451 if self.sbmodule: 452 return int(self.sbmodule.GetNumSections()) 453 return 0 454 455 def __getitem__(self, key): 456 count = len(self) 457 if type(key) is int: 458 if key < count: 459 return self.sbmodule.GetSectionAtIndex(key) 460 elif type(key) is str: 461 for idx in range(count): 462 section = self.sbmodule.GetSectionAtIndex(idx) 463 if section.name == key: 464 return section 465 elif isinstance(key, self.re_compile_type): 466 matches = [] 467 for idx in range(count): 468 section = self.sbmodule.GetSectionAtIndex(idx) 469 name = section.name 470 if name: 471 re_match = key.search(name) 472 if re_match: 473 matches.append(section) 474 return matches 475 else: 476 print("error: unsupported item type: %s" % type(key)) 477 return None 478 479 class compile_units_access(object): 480 re_compile_type = type(re.compile('.')) 481 '''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.''' 482 def __init__(self, sbmodule): 483 self.sbmodule = sbmodule 484 485 def __len__(self): 486 if self.sbmodule: 487 return int(self.sbmodule.GetNumCompileUnits()) 488 return 0 489 490 def __getitem__(self, key): 491 count = len(self) 492 if type(key) is int: 493 if key < count: 494 return self.sbmodule.GetCompileUnitAtIndex(key) 495 elif type(key) is str: 496 is_full_path = key[0] == '/' 497 for idx in range(count): 498 comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx) 499 if is_full_path: 500 if comp_unit.file.fullpath == key: 501 return comp_unit 502 else: 503 if comp_unit.file.basename == key: 504 return comp_unit 505 elif isinstance(key, self.re_compile_type): 506 matches = [] 507 for idx in range(count): 508 comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx) 509 fullpath = comp_unit.file.fullpath 510 if fullpath: 511 re_match = key.search(fullpath) 512 if re_match: 513 matches.append(comp_unit) 514 return matches 515 else: 516 print("error: unsupported item type: %s" % type(key)) 517 return None 518 519 def get_sections_access_object(self): 520 '''An accessor function that returns a sections_access() object which allows lazy section array access.''' 521 return self.sections_access (self) 522 523 def get_sections_array(self): 524 '''An accessor function that returns an array object that contains all sections in this module object.''' 525 if not hasattr(self, 'sections_array'): 526 self.sections_array = [] 527 for idx in range(self.num_sections): 528 self.sections_array.append(self.GetSectionAtIndex(idx)) 529 return self.sections_array 530 531 def get_compile_units_array(self): 532 '''An accessor function that returns an array object that contains all compile_units in this module object.''' 533 if not hasattr(self, 'compile_units_array'): 534 self.compile_units_array = [] 535 for idx in range(self.GetNumCompileUnits()): 536 self.compile_units_array.append(self.GetCompileUnitAtIndex(idx)) 537 return self.compile_units_array 538 539 symbols = property(get_symbols_array, None, doc='''A read only property that returns a list() of lldb.SBSymbol objects contained in this module.''') 540 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''') 541 sections = property(get_sections_array, None, doc='''A read only property that returns a list() of lldb.SBSection objects contained in this module.''') 542 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.''') 543 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''') 544 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.''') 545 546 def get_uuid(self): 547 return uuid.UUID (self.GetUUIDString()) 548 549 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.''') 550 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.''') 551 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.''') 552 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.''') 553 addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''') 554 triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''') 555 num_symbols = property(GetNumSymbols, None, doc='''A read only property that returns number of symbols in the module symbol table as an integer.''') 556 num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''') 557 558 %} 559#endif 560 561}; 562 563} // namespace lldb 564