SBModule#

class lldb.SBModule(*args)#

Represents an executable image and its associated object and symbol files.

The module is designed to be able to select a single slice of an executable image as it would appear on disk and during program execution.

You can retrieve SBModule from SBSymbolContext , which in turn is available from SBFrame.

SBModule supports symbol iteration, for example,

for symbol in module:
    name = symbol.GetName()
    saddr = symbol.GetStartAddress()
    eaddr = symbol.GetEndAddress()

and rich comparison methods which allow the API program to use,

if thisModule == thatModule:
    print('This module is the same as that module')

to test module equality. A module also contains object file sections, namely SBSection . SBModule supports section iteration through section_iter(), for example,

print('Number of sections: %d' % module.GetNumSections())
for sec in module.section_iter():
    print(sec)

And to iterate the symbols within a SBSection, use symbol_in_section_iter(),

# Iterates the text section and prints each symbols within each sub-section.
for subsec in text_sec:
    print(INDENT + repr(subsec))
    for sym in exe_module.symbol_in_section_iter(subsec):
        print(INDENT2 + repr(sym))
        print(INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType()))

produces this following output:

[0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text
    id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870)
    symbol type: code
    id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0)
    symbol type: code
    id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c)
    symbol type: code
    id = {0x00000023}, name = 'start', address = 0x0000000100001780
    symbol type: code
[0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs
    id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62)
    symbol type: trampoline
    id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68)
    symbol type: trampoline
    id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e)
    symbol type: trampoline
    id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74)
    symbol type: trampoline
    id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a)
    symbol type: trampoline
    id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80)
    symbol type: trampoline
    id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86)
    symbol type: trampoline
    id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c)
    symbol type: trampoline
    id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92)
    symbol type: trampoline
    id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98)
    symbol type: trampoline
    id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e)
    symbol type: trampoline
    id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4)
    symbol type: trampoline
[0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper
[0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring
[0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info
[0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame

Attributes Summary

addr_size

A read only property that returns the size in bytes of an address for this module.

byte_order

A read only property that returns an lldb enumeration value (lldb.eByteOrderLittle, lldb.eByteOrderBig, lldb.eByteOrderInvalid) that represents the byte order for this module.

compile_units

A read only property that returns a list() of lldb.SBCompileUnit objects contained in this module.

file

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.

num_sections

A read only property that returns number of sections in the module as an integer.

num_symbols

A read only property that returns number of symbols in the module symbol table as an integer.

platform_file

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.

section

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(...)]").

sections

A read only property that returns a list() of lldb.SBSection objects contained in this module.

symbol

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(...)]").

symbols

A read only property that returns a list() of lldb.SBSymbol objects contained in this module.

triple

A read only property that returns the target triple (arch-vendor-os) for this module.

uuid

A read only property that returns a standard python uuid.UUID object that represents the UUID of this module.

Methods Summary

Clear(SBModule self)

FindCompileUnits(SBModule self, ...)

Find compile units related to this module and passed source file.

FindFirstGlobalVariable(SBModule self, ...)

Find the first global (or static) variable by name.

FindFirstType(SBModule self, char const * name)

FindFunctions(SBModule self, ...)

Find functions by name.

FindGlobalVariables(SBModule self, ...)

Find global and static variables by name.

FindSection(SBModule self, ...)

FindSymbol(SBModule self, char const * name, ...)

FindSymbols(SBModule self, ...)

FindTypes(SBModule self, char const * type)

GarbageCollectAllocatedModules()

Removes all modules which are no longer needed by any part of LLDB from the module cache.

GetAddressByteSize(SBModule self)

GetBasicType(SBModule self, lldb)

GetByteOrder(SBModule self)

GetCompileUnitAtIndex(SBModule self, ...)

GetDescription(SBModule self, ...)

GetFileSpec(SBModule self)

Get const accessor for the module file specification.

GetNumCompileUnits(SBModule self)

GetNumSections(SBModule self)

GetNumSymbols(SBModule self)

GetNumberAllocatedModules()

Returns the number of modules in the module cache.

GetObjectFileEntryPointAddress(SBModule self)

GetObjectFileHeaderAddress(SBModule self)

GetObjectName()

If this Module represents a specific object or part within a larger file, returns the name of that object or part.

GetPlatformFileSpec(SBModule self)

Get accessor for the module platform file specification.

GetRemoteInstallFileSpec()

Get accessor for the remote install path for a module.

GetSectionAtIndex(SBModule self, size_t idx)

GetSymbolAtIndex(SBModule self, size_t idx)

GetSymbolFileSpec()

Get accessor for the symbol file specification.

GetTriple(SBModule self)

GetTypeByID(uid)

Get a type using its type ID.

GetTypes(SBModule self, ...)

Get all types matching type_mask from debug info in this module.

GetUUIDBytes(SBModule self)

GetUUIDString(SBModule self)

Returns the UUID of the module as a Python string.

GetVersion()

Get the module version numbers.

IsFileBacked(SBModule self)

Check if the module is file backed.

IsValid(SBModule self)

ResolveFileAddress(SBModule self, lldb)

ResolveSymbolContextForAddress(...)

SetPlatformFileSpec(SBModule self, ...)

SetRemoteInstallFileSpec(file)

Set accessor for the remote install path for a module.

compile_unit_iter()

Iterate over all compile units in a lldb.SBModule object.

get_compile_units_access_object()

An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.

get_compile_units_array()

An accessor function that returns an array object that contains all compile_units in this module object.

get_sections_access_object()

An accessor function that returns a sections_access() object which allows lazy section array access.

get_sections_array()

An accessor function that returns an array object that contains all sections in this module object.

get_symbols_access_object()

An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.

get_symbols_array()

An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.

get_uuid()

section_iter()

Iterate over all sections in a lldb.SBModule object.

symbol_in_section_iter(section)

Given a module and its contained section, returns an iterator on the symbols within the section.

Attributes Documentation

addr_size#

A read only property that returns the size in bytes of an address for this module.

byte_order#

A read only property that returns an lldb enumeration value (lldb.eByteOrderLittle, lldb.eByteOrderBig, lldb.eByteOrderInvalid) that represents the byte order for this module.

compile_units#

A read only property that returns a list() of lldb.SBCompileUnit objects contained in this module.

file#

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.

num_sections#

A read only property that returns number of sections in the module as an integer.

num_symbols#

A read only property that returns number of symbols in the module symbol table as an integer.

platform_file#

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.

section#

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.

sections#

A read only property that returns a list() of lldb.SBSection objects contained in this module.

symbol#

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

symbols#

A read only property that returns a list() of lldb.SBSymbol objects contained in this module.

triple#

A read only property that returns the target triple (arch-vendor-os) for this module.

uuid#

A read only property that returns a standard python uuid.UUID object that represents the UUID of this module.

Methods Documentation

Clear(SBModule self)#
FindCompileUnits(SBModule self, SBFileSpec sb_file_spec) → SBSymbolContextList#

Find compile units related to this module and passed source file.

@param[in] sb_file_spec

A SBFileSpec object that contains source file specification.

@return

A SBSymbolContextList that gets filled in with all of the symbol contexts for all the matches.

FindFirstGlobalVariable(SBModule self, SBTarget target, char const * name) → SBValue#

Find the first global (or static) variable by name.

@param[in] target

A valid SBTarget instance representing the debuggee.

@param[in] name

The name of the global or static variable we are looking for.

@return

An SBValue that gets filled in with the found variable (if any).

FindFirstType(SBModule self, char const * name) → SBType#
FindFunctions(SBModule self, char const * name, uint32_t name_type_mask=eFunctionNameTypeAny) → SBSymbolContextList#

Find functions by name.

@param[in] name

The name of the function we are looking for.

@param[in] name_type_mask

A logical OR of one or more FunctionNameType enum bits that indicate what kind of names should be used when doing the lookup. Bits include fully qualified names, base names, C++ methods, or ObjC selectors. See FunctionNameType for more details.

@return

A symbol context list that gets filled in with all of the matches.

FindGlobalVariables(SBModule self, SBTarget target, char const * name, uint32_t max_matches) → SBValueList#

Find global and static variables by name.

@param[in] target

A valid SBTarget instance representing the debuggee.

@param[in] name

The name of the global or static variable we are looking for.

@param[in] max_matches

Allow the number of matches to be limited to max_matches.

@return

A list of matched variables in an SBValueList.

FindSection(SBModule self, char const * sect_name) → SBSection#
FindSymbol(SBModule self, char const * name, lldb::SymbolType type=eSymbolTypeAny) → SBSymbol#
FindSymbols(SBModule self, char const * name, lldb::SymbolType type=eSymbolTypeAny) → SBSymbolContextList#
FindTypes(SBModule self, char const * type) → SBTypeList#
static GarbageCollectAllocatedModules()#

Removes all modules which are no longer needed by any part of LLDB from the module cache.

This is an implementation detail exposed for testing and should not be relied upon. Use SBDebugger::MemoryPressureDetected instead to reduce LLDB’s memory consumption during execution.

GetAddressByteSize(SBModule self) → uint32_t#
GetBasicType(SBModule self, lldb::BasicType type) → SBType#
GetByteOrder(SBModule self) → lldb::ByteOrder#
GetCompileUnitAtIndex(SBModule self, uint32_t arg2) → SBCompileUnit#
GetDescription(SBModule self, SBStream description) → bool#
GetFileSpec(SBModule self) → SBFileSpec#

Get const accessor for the module file specification.

This function returns the file for the module on the host system that is running LLDB. This can differ from the path on the platform since we might be doing remote debugging.

@return

A const reference to the file specification object.

GetNumCompileUnits(SBModule self) → uint32_t#
GetNumSections(SBModule self) → size_t#
GetNumSymbols(SBModule self) → size_t#
static GetNumberAllocatedModules() → uint32_t#

Returns the number of modules in the module cache. This is an implementation detail exposed for testing and should not be relied upon.

@return

The number of modules in the module cache.

GetObjectFileEntryPointAddress(SBModule self) → SBAddress#
GetObjectFileHeaderAddress(SBModule self) → SBAddress#
GetObjectName()#

If this Module represents a specific object or part within a larger file, returns the name of that object or part. Otherwise, returns nullptr.

GetPlatformFileSpec(SBModule self) → SBFileSpec#

Get accessor for the module platform file specification.

Platform file refers to the path of the module as it is known on the remote system on which it is being debugged. For local debugging this is always the same as Module::GetFileSpec(). But remote debugging might mention a file ‘/usr/lib/liba.dylib’ which might be locally downloaded and cached. In this case the platform file could be something like: ‘/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib’ The file could also be cached in a local developer kit directory.

@return

A const reference to the file specification object.

GetRemoteInstallFileSpec()#

Get accessor for the remote install path for a module.

When debugging to a remote platform by connecting to a remote platform, the install path of the module can be set. If the install path is set, every time the process is about to launch the target will install this module on the remote platform prior to launching.

Return type:

SBFileSpec

Returns:

A file specification object.

GetSectionAtIndex(SBModule self, size_t idx) → SBSection#
GetSymbolAtIndex(SBModule self, size_t idx) → SBSymbol#
GetSymbolFileSpec()#

Get accessor for the symbol file specification.

When debugging an object file an additional debug information can be provided in separate file. Therefore if you debugging something like ‘/usr/lib/liba.dylib’ then debug information can be located in folder like ‘/usr/lib/liba.dylib.dSYM/’.

Return type:

SBFileSpec

Returns:

A const reference to the file specification object.

GetTriple(SBModule self) → char const *#
GetTypeByID(uid)#

Get a type using its type ID.

Each symbol file reader will assign different user IDs to their types, but it is sometimes useful when debugging type issues to be able to grab a type using its type ID.

For DWARF debug info, the type ID is the DIE offset.

Parameters:

uid (int, in) – The type user ID.

Return type:

SBType

Returns:

An SBType for the given type ID, or an empty SBType if the type was not found.

GetTypes(SBModule self, uint32_t type_mask=eTypeClassAny) → SBTypeList#

Get all types matching type_mask from debug info in this module.

@param[in] type_mask

A bitfield that consists of one or more bits logically OR’ed together from the lldb::TypeClass enumeration. This allows you to request only structure types, or only class, struct and union types. Passing in lldb::eTypeClassAny will return all types found in the debug information for this module.

@return

A list of types in this module that match type_mask

GetUUIDBytes(SBModule self) → uint8_t const *#
GetUUIDString(SBModule self) → char const *#

Returns the UUID of the module as a Python string.

GetVersion()#

Get the module version numbers.

Many object files have a set of version numbers that describe the version of the executable or shared library. Typically there are major, minor and build, but there may be more. This function will extract the versions from object files if they are available.

If versions is NULL, or if num_versions is 0, the return value will indicate how many version numbers are available in this object file. Then a subsequent call can be made to this function with a value of versions and num_versions that has enough storage to store some or all version numbers.

Parameters:

  • versions (int, out) – A pointer to an array of uint32_t types that is num_versions long. If this value is NULL, the return value will indicate how many version numbers are required for a subsequent call to this function so that all versions can be retrieved. If the value is non-NULL, then at most num_versions of the existing versions numbers will be filled into versions. If there is no version information available, versions will be filled with num_versions UINT32_MAX values and zero will be returned.

  • num_versions (int, in) –

    The maximum number of entries to fill into versions. If this value is zero, then the return value will indicate how many version numbers there are in total so another call to this function can be make with adequate storage in versions to get all of the version numbers. If

    num_versions is less than the actual number of version

    numbers in this object file, only num_versions will be filled into versions (if versions is non-NULL).

Return type:

int

Returns:

This function always returns the number of version numbers that this object file has regardless of the number of version numbers that were copied into versions.

IsFileBacked(SBModule self) → bool#

Check if the module is file backed.

@return

True, if the module is backed by an object file on disk. False, if the module is backed by an object file in memory.

IsValid(SBModule self) → bool#
ResolveFileAddress(SBModule self, lldb::addr_t vm_addr) → SBAddress#
ResolveSymbolContextForAddress(SBModule self, SBAddress addr, uint32_t resolve_scope) → SBSymbolContext#
SetPlatformFileSpec(SBModule self, SBFileSpec platform_file) → bool#
SetRemoteInstallFileSpec(file)#

Set accessor for the remote install path for a module.

When debugging to a remote platform by connecting to a remote platform, the install path of the module can be set. If the install path is set, every time the process is about to launch the target will install this module on the remote platform prior to launching.

If file specifies a full path to an install location, the module will be installed to this path. If the path is relative (no directory specified, or the path is partial like “usr/lib” or “./usr/lib”, then the install path will be resolved using the platform’s current working directory as the base path.

Parameters:

file (SBFileSpec, in) – A file specification object.

compile_unit_iter()#

Iterate over all compile units in a lldb.SBModule object.

get_compile_units_access_object()#

An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.

get_compile_units_array()#

An accessor function that returns an array object that contains all compile_units in this module object.

get_sections_access_object()#

An accessor function that returns a sections_access() object which allows lazy section array access.

get_sections_array()#

An accessor function that returns an array object that contains all sections in this module object.

get_symbols_access_object()#

An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.

get_symbols_array()#

An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.

get_uuid()#
section_iter()#

Iterate over all sections in a lldb.SBModule object.

symbol_in_section_iter(section)#

Given a module and its contained section, returns an iterator on the symbols within the section.