SBDebugger

class lldb.SBDebugger(*args)

SBDebugger is the primordial object that creates SBTargets and provides access to them. It also manages the overall debugging experiences.

For example (from example/disasm.py),:

import lldb
import os
import sys

def disassemble_instructions (insts):
    for i in insts:
        print i

...

# Create a new debugger instance
debugger = lldb.SBDebugger.Create()

# When we step or continue, don't return from the function until the process
# stops. We do this by setting the async mode to false.
debugger.SetAsync (False)

# Create a target from a file and arch
print('Creating a target for '%s'' % exe)

target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)

if target:
    # If the target is valid set a breakpoint at main
    main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename());

    print main_bp

    # Launch the process. Since we specified synchronous mode, we won't return
    # from this function until we hit the breakpoint at main
    process = target.LaunchSimple (None, None, os.getcwd())

    # Make sure the launch went ok
    if process:
        # Print some simple process info
        state = process.GetState ()
        print process
        if state == lldb.eStateStopped:
            # Get the first thread
            thread = process.GetThreadAtIndex (0)
            if thread:
                # Print some simple thread info
                print thread
                # Get the first frame
                frame = thread.GetFrameAtIndex (0)
                if frame:
                    # Print some simple frame info
                    print frame
                    function = frame.GetFunction()
                    # See if we have debug info (a function)
                    if function:
                        # We do have a function, print some info for the function
                        print function
                        # Now get all instructions for this function and print them
                        insts = function.GetInstructions(target)
                        disassemble_instructions (insts)
                    else:
                        # See if we have a symbol in the symbol table for where we stopped
                        symbol = frame.GetSymbol();
                        if symbol:
                            # We do have a symbol, print some info for the symbol
                            print symbol
                            # Now get all instructions for this symbol and print them
                            insts = symbol.GetInstructions(target)
                            disassemble_instructions (insts)

                    registerList = frame.GetRegisters()
                    print('Frame registers (size of register set = %d):' % registerList.GetSize())
                    for value in registerList:
                        #print value
                        print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren()))
                        for child in value:
                            print('Name: ', child.GetName(), ' Value: ', child.GetValue())

            print('Hit the breakpoint at main, enter to continue and wait for program to exit or 'Ctrl-D'/'quit' to terminate the program')
            next = sys.stdin.readline()
            if not next or next.rstrip('\n') == 'quit':
                print('Terminating the inferior process...')
                process.Kill()
            else:
                # Now continue to the program exit
                process.Continue()
                # When we return from the above function we will hopefully be at the
                # program exit. Print out some process info
                print process
        elif state == lldb.eStateExited:
            print('Didn't hit the breakpoint at main, program has exited...')
        else:
            print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state))
            process.Kill()

Sometimes you need to create an empty target that will get filled in later. The most common use for this is to attach to a process by name or pid where you don’t know the executable up front. The most convenient way to do this is:

target = debugger.CreateTarget('')
error = lldb.SBError()
process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error)

or the equivalent arguments for SBTarget.AttachToProcessWithID .

Methods Summary

Clear(SBDebugger self)
Create() Create(bool source_init_files) -> SBDebugger Create(bool source_init_files, lldb::LogOutputCallback log_callback) -> SBDebugger
CreateCategory(SBDebugger self, …)
CreateTarget(SBDebugger self, …) CreateTarget(SBDebugger self, char const * filename) -> SBTarget
CreateTargetWithFileAndArch(SBDebugger self, …)
CreateTargetWithFileAndTargetTriple(…)
DeleteCategory(SBDebugger self, …)
DeleteTarget(SBDebugger self, SBTarget target) Return true if target is deleted from the target list of the debugger.
Destroy(SBDebugger debugger)
DispatchInput(SBDebugger self, void const * data)
DispatchInputEndOfFile(SBDebugger self)
DispatchInputInterrupt(SBDebugger self)
EnableLog(SBDebugger self, …)
FindDebuggerWithID(int id)
FindTargetWithFileAndArch(SBDebugger self, …)
FindTargetWithProcessID(SBDebugger self, lldb)
GetAsync(SBDebugger self)
GetAvailablePlatformInfoAtIndex(…) Get the name and description of one of the available platforms.
GetBuildConfiguration()
GetCategory(SBDebugger self, …) GetCategory(SBDebugger self, lldb::LanguageType lang_type) -> SBTypeCategory
GetCategoryAtIndex(SBDebugger self, …)
GetCloseInputOnEOF(SBDebugger self)
GetCommandInterpreter(SBDebugger self)
GetDefaultArchitecture(char * arch_name, …)
GetDefaultCategory(SBDebugger self)
GetDescription(SBDebugger self, …)
GetDummyTarget(SBDebugger self) The dummy target holds breakpoints and breakpoint names that will prime newly created targets.
GetErrorFile(SBDebugger self)
GetErrorFileHandle(SBDebugger self)
GetFilterForType(SBDebugger self, …)
GetFormatForType(SBDebugger self, …)
GetID(SBDebugger self)
GetIndexOfTarget(SBDebugger self, …)
GetInputFile(SBDebugger self)
GetInputFileHandle(SBDebugger self)
GetInstanceName(SBDebugger self)
GetInternalVariableValue(…)
GetListener(SBDebugger self)
GetNumAvailablePlatforms(SBDebugger self) Get the number of available platforms.
GetNumCategories(SBDebugger self)
GetNumPlatforms(SBDebugger self) Get the number of currently active platforms.
GetNumTargets(SBDebugger self)
GetOutputFile(SBDebugger self)
GetOutputFileHandle(SBDebugger self)
GetPlatformAtIndex(SBDebugger self, uint32_t idx) Get one of the currently active platforms.
GetPrompt(SBDebugger self)
GetReproducerPath(SBDebugger self)
GetScriptLanguage(SBDebugger self)
GetScriptingLanguage(SBDebugger self, …)
GetSelectedPlatform(SBDebugger self)
GetSelectedTarget(SBDebugger self)
GetSourceManager(SBDebugger self)
GetSummaryForType(SBDebugger self, …)
GetSyntheticForType(SBDebugger self, …)
GetTargetAtIndex(SBDebugger self, uint32_t idx)
GetTerminalWidth(SBDebugger self)
GetUseColor(SBDebugger self)
GetUseExternalEditor(SBDebugger self)
GetVersionString()
HandleCommand(SBDebugger self, …)
HandleProcessEvent(SBDebugger self, …) HandleProcessEvent(SBDebugger self, SBProcess process, SBEvent event, lldb::FileSP arg4, lldb::FileSP arg5)
Initialize()
InitializeWithErrorHandling()
IsValid(SBDebugger self)
MemoryPressureDetected()
RunCommandInterpreter(SBDebugger self, …) Launch a command interpreter session.
RunREPL(SBDebugger self, lldb, …)
SetAsync(SBDebugger self, bool b)
SetCloseInputOnEOF(SBDebugger self, bool b)
SetCurrentPlatform(SBDebugger self, …)
SetCurrentPlatformSDKRoot(SBDebugger self, …)
SetDefaultArchitecture(char const * arch_name)
SetErrorFile(SBDebugger self, SBFile file) SetErrorFile(SBDebugger self, lldb::FileSP file) -> SBError
SetErrorFileHandle(file, transfer_ownership) DEPRECATED, use SetErrorFile
SetInputFile(SBDebugger self, SBFile file) SetInputFile(SBDebugger self, lldb::FileSP file) -> SBError
SetInputFileHandle(file, transfer_ownership) DEPRECATED, use SetInputFile
SetInternalVariable(char const * var_name, …)
SetLoggingCallback(SBDebugger self, lldb)
SetOutputFile(SBDebugger self, SBFile file) SetOutputFile(SBDebugger self, lldb::FileSP file) -> SBError
SetOutputFileHandle(file, transfer_ownership) DEPRECATED, use SetOutputFile
SetPrompt(SBDebugger self, char const * prompt)
SetScriptLanguage(SBDebugger self, lldb)
SetSelectedPlatform(SBDebugger self, …)
SetSelectedTarget(SBDebugger self, …)
SetTerminalWidth(SBDebugger self, …)
SetUseColor(SBDebugger self, bool use_color)
SetUseExternalEditor(SBDebugger self, bool input)
SkipLLDBInitFiles(SBDebugger self, bool b)
StateAsCString(lldb)
StateIsRunningState(lldb)
StateIsStoppedState(lldb)
Terminate()

Methods Documentation

Clear(SBDebugger self)
static Create() → SBDebugger

Create(bool source_init_files) -> SBDebugger Create(bool source_init_files, lldb::LogOutputCallback log_callback) -> SBDebugger

CreateCategory(SBDebugger self, char const * category_name) → SBTypeCategory
CreateTarget(SBDebugger self, char const * filename, char const * target_triple, char const * platform_name, bool add_dependent_modules, SBError sb_error) → SBTarget

CreateTarget(SBDebugger self, char const * filename) -> SBTarget

CreateTargetWithFileAndArch(SBDebugger self, char const * filename, char const * archname) → SBTarget
CreateTargetWithFileAndTargetTriple(SBDebugger self, char const * filename, char const * target_triple) → SBTarget
DeleteCategory(SBDebugger self, char const * category_name) → bool
DeleteTarget(SBDebugger self, SBTarget target) → bool

Return true if target is deleted from the target list of the debugger.

static Destroy(SBDebugger debugger)
DispatchInput(SBDebugger self, void const * data)
DispatchInputEndOfFile(SBDebugger self)
DispatchInputInterrupt(SBDebugger self)
EnableLog(SBDebugger self, char const * channel, char const ** types) → bool
static FindDebuggerWithID(int id) → SBDebugger
FindTargetWithFileAndArch(SBDebugger self, char const * filename, char const * arch) → SBTarget
FindTargetWithProcessID(SBDebugger self, lldb::pid_t pid) → SBTarget
GetAsync(SBDebugger self) → bool
GetAvailablePlatformInfoAtIndex(SBDebugger self, uint32_t idx) → SBStructuredData

Get the name and description of one of the available platforms.

@param idx Zero-based index of the platform for which info should be
retrieved, must be less than the value returned by GetNumAvailablePlatforms().
static GetBuildConfiguration() → SBStructuredData
GetCategory(SBDebugger self, char const * category_name) → SBTypeCategory

GetCategory(SBDebugger self, lldb::LanguageType lang_type) -> SBTypeCategory

GetCategoryAtIndex(SBDebugger self, uint32_t arg2) → SBTypeCategory
GetCloseInputOnEOF(SBDebugger self) → bool
GetCommandInterpreter(SBDebugger self) → SBCommandInterpreter
static GetDefaultArchitecture(char * arch_name, size_t arch_name_len) → bool
GetDefaultCategory(SBDebugger self) → SBTypeCategory
GetDescription(SBDebugger self, SBStream description) → bool
GetDummyTarget(SBDebugger self) → SBTarget

The dummy target holds breakpoints and breakpoint names that will prime newly created targets.

GetErrorFile(SBDebugger self) → SBFile
GetErrorFileHandle(SBDebugger self) → lldb::FileSP
GetFilterForType(SBDebugger self, SBTypeNameSpecifier arg2) → SBTypeFilter
GetFormatForType(SBDebugger self, SBTypeNameSpecifier arg2) → SBTypeFormat
GetID(SBDebugger self) → lldb::user_id_t
GetIndexOfTarget(SBDebugger self, SBTarget target) → uint32_t
GetInputFile(SBDebugger self) → SBFile
GetInputFileHandle(SBDebugger self) → lldb::FileSP
GetInstanceName(SBDebugger self) → char const *
static GetInternalVariableValue(char const * var_name, char const * debugger_instance_name) → SBStringList
GetListener(SBDebugger self) → SBListener
GetNumAvailablePlatforms(SBDebugger self) → uint32_t

Get the number of available platforms.

GetNumCategories(SBDebugger self) → uint32_t
GetNumPlatforms(SBDebugger self) → uint32_t

Get the number of currently active platforms.

GetNumTargets(SBDebugger self) → uint32_t
GetOutputFile(SBDebugger self) → SBFile
GetOutputFileHandle(SBDebugger self) → lldb::FileSP
GetPlatformAtIndex(SBDebugger self, uint32_t idx) → SBPlatform

Get one of the currently active platforms.

GetPrompt(SBDebugger self) → char const *
GetReproducerPath(SBDebugger self) → char const *
GetScriptLanguage(SBDebugger self) → lldb::ScriptLanguage
GetScriptingLanguage(SBDebugger self, char const * script_language_name) → lldb::ScriptLanguage
GetSelectedPlatform(SBDebugger self) → SBPlatform
GetSelectedTarget(SBDebugger self) → SBTarget
GetSourceManager(SBDebugger self) → SBSourceManager
GetSummaryForType(SBDebugger self, SBTypeNameSpecifier arg2) → SBTypeSummary
GetSyntheticForType(SBDebugger self, SBTypeNameSpecifier arg2) → SBTypeSynthetic
GetTargetAtIndex(SBDebugger self, uint32_t idx) → SBTarget
GetTerminalWidth(SBDebugger self) → uint32_t
GetUseColor(SBDebugger self) → bool
GetUseExternalEditor(SBDebugger self) → bool
static GetVersionString() → char const *
HandleCommand(SBDebugger self, char const * command)
HandleProcessEvent(SBDebugger self, SBProcess process, SBEvent event, SBFile out, SBFile err)

HandleProcessEvent(SBDebugger self, SBProcess process, SBEvent event, lldb::FileSP arg4, lldb::FileSP arg5)

static Initialize()
static InitializeWithErrorHandling() → SBError
IsValid(SBDebugger self) → bool
static MemoryPressureDetected()
RunCommandInterpreter(SBDebugger self, bool auto_handle_events, bool spawn_thread, SBCommandInterpreterRunOptions options, int & num_errors, bool & quit_requested, bool & stopped_for_crash)

Launch a command interpreter session. Commands are read from standard input or from the input handle specified for the debugger object. Output/errors are similarly redirected to standard output/error or the configured handles.

@param[in] auto_handle_events If true, automatically handle resulting events. @param[in] spawn_thread If true, start a new thread for IO handling. @param[in] options Parameter collection of type SBCommandInterpreterRunOptions. @param[in] num_errors Initial error counter. @param[in] quit_requested Initial quit request flag. @param[in] stopped_for_crash Initial crash flag.

@return A tuple with the number of errors encountered by the interpreter, a boolean indicating whether quitting the interpreter was requested and another boolean set to True in case of a crash.

Example:

# Start an interactive lldb session from a script (with a valid debugger object
# created beforehand):
n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True,
    False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)
RunREPL(SBDebugger self, lldb::LanguageType language, char const * repl_options) → SBError
SetAsync(SBDebugger self, bool b)
SetCloseInputOnEOF(SBDebugger self, bool b)
SetCurrentPlatform(SBDebugger self, char const * platform_name) → SBError
SetCurrentPlatformSDKRoot(SBDebugger self, char const * sysroot) → bool
static SetDefaultArchitecture(char const * arch_name) → bool
SetErrorFile(SBDebugger self, SBFile file) → SBError

SetErrorFile(SBDebugger self, lldb::FileSP file) -> SBError

SetErrorFileHandle(file, transfer_ownership)

DEPRECATED, use SetErrorFile

SetInputFile(SBDebugger self, SBFile file) → SBError

SetInputFile(SBDebugger self, lldb::FileSP file) -> SBError

SetInputFileHandle(file, transfer_ownership)

DEPRECATED, use SetInputFile

static SetInternalVariable(char const * var_name, char const * value, char const * debugger_instance_name) → SBError
SetLoggingCallback(SBDebugger self, lldb::LogOutputCallback log_callback)
SetOutputFile(SBDebugger self, SBFile file) → SBError

SetOutputFile(SBDebugger self, lldb::FileSP file) -> SBError

SetOutputFileHandle(file, transfer_ownership)

DEPRECATED, use SetOutputFile

SetPrompt(SBDebugger self, char const * prompt)
SetScriptLanguage(SBDebugger self, lldb::ScriptLanguage script_lang)
SetSelectedPlatform(SBDebugger self, SBPlatform platform)
SetSelectedTarget(SBDebugger self, SBTarget target)
SetTerminalWidth(SBDebugger self, uint32_t term_width)
SetUseColor(SBDebugger self, bool use_color) → bool
SetUseExternalEditor(SBDebugger self, bool input) → bool
SkipLLDBInitFiles(SBDebugger self, bool b)
static StateAsCString(lldb::StateType state) → char const *
static StateIsRunningState(lldb::StateType state) → bool
static StateIsStoppedState(lldb::StateType state) → bool
static Terminate()