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
.Attributes Summary
Methods Summary
AddDestroyCallback
(destroy_callback)Add a callback for when the debugger is destroyed.
Cancel a previously requested interrupt.
Clear
()Clear this debugger instance.
Create
(*args)Overload 1: Create a new debugger instance (deprecated).
CreateCategory
(category_name)Create a new type category.
CreateTarget
(*args)Overload 1: Create a target with the specified parameters.
CreateTargetWithFileAndArch
(filename, archname)Create a target with the specified file and architecture.
Create a target with the specified file and target triple.
DeleteCategory
(category_name)Delete a type category.
DeleteTarget
(SBDebugger self, SBTarget target)Return true if target is deleted from the target list of the debugger.
Destroy
(debugger)Destroy a debugger instance.
DispatchInput
(data)Dispatch input to the debugger.
Signal end-of-file to the current input dispatch.
Interrupt the current input dispatch.
EnableLog
(channel, categories)Enable logging for a specific channel and category.
Find a debugger by ID.
FindTargetWithFileAndArch
(filename, arch)Find a target with the specified file and architecture.
Find a target with the specified process ID.
GetAsync
()Get whether the debugger is running in asynchronous mode.
Get the name and description of one of the available platforms.
Get the broadcaster that allows subscribing to events from this debugger.
Get the broadcaster class name.
Get the build configuration as structured data.
GetCategory
(*args)Overload 1: Get a type category by name.
GetCategoryAtIndex
(index)Get a type category by index.
Get whether to close input on EOF (deprecated).
Get the command interpreter for this debugger.
GetDefaultArchitecture
(arch_name, arch_name_len)Get the default architecture.
Get the default type category.
GetDescription
(description)Get a description of this debugger.
GetDiagnosticFromEvent
(event)Get diagnostic information from an event.
GetDummyTarget
(SBDebugger self)The dummy target holds breakpoints and breakpoint names that will prime newly created targets.
Get the error file for the debugger.
GetErrorFileHandle
(SBDebugger self)GetFilterForType
(type_name_spec)Get the filter for a type.
GetFormatForType
(type_name_spec)Get the format for a type.
GetID
()Get the unique ID of this debugger.
GetIndexOfTarget
(target)Get the index of a target.
Get the input file for the debugger.
GetInputFileHandle
(SBDebugger self)Get the instance name of this debugger.
GetInternalVariableValue
(var_name, ...)Get the value of an internal variable.
Get the listener associated with this debugger.
GetNumAvailablePlatforms
(SBDebugger self)Get the number of available platforms.
Get the number of type categories.
GetNumPlatforms
(SBDebugger self)Get the number of currently active platforms.
Get the number of targets in the debugger.
Get the output file for the debugger.
GetOutputFileHandle
(SBDebugger self)GetPlatformAtIndex
(SBDebugger self, uint32_t idx)Get one of the currently active platforms.
GetProgressDataFromEvent
(event)Get progress data from an event.
GetProgressFromEvent
(event)Get progress data from a SBEvent whose type is eBroadcastBitProgress.
Get the command prompt string.
Get the current REPL language.
Get the path to the reproducer.
GetScriptInterpreterInfo
(language)Get information about a script interpreter as structured data.
Get the current scripting language.
GetScriptingLanguage
(script_language_name)Get the scripting language by name.
Get the selected platform.
Get the currently selected target.
GetSetting
([setting])Get debugger settings as structured data.
Get the source manager for this debugger.
GetSummaryForType
(type_name_spec)Get the summary for a type.
GetSyntheticForType
(type_name_spec)Get the synthetic for a type.
GetTargetAtIndex
(idx)Get a target by index.
Get the terminal height.
Get the terminal width.
Get whether color is being used in output.
Get whether an external editor is being used.
Get whether the source cache is being used.
Get the LLDB version string.
HandleCommand
(command)Execute a command in the command interpreter.
HandleProcessEvent
(*args)Overload 1: Handle a process event.
Initialize LLDB and its subsystems.
Initialize the LLDB debugger subsystem with error handling.
Check if an interrupt has been requested.
IsValid
()Check if this is a valid SBDebugger object.
LoadTraceFromFile
(error, trace_description_file)Load a trace from a trace description file.
Notify the debugger that system memory pressure has been detected.
Configure LLDB to print diagnostic information when it crashes.
Configure LLDB to print a stack trace when it crashes.
RemoveDestroyCallback
(token)Remove a destroy callback.
Request an interrupt of the current operation.
Clear collected statistics for targets belonging to this debugger.
Restore the previously saved terminal state.
RunCommandInterpreter
(SBDebugger self, ...)Launch a command interpreter session.
RunREPL
(language, repl_options)Run a REPL (Read-Eval-Print Loop) for the specified language.
Save the current terminal state.
SetAsync
(b)Set whether the debugger should run in asynchronous mode.
Set whether to close input on EOF (deprecated).
SetCurrentPlatform
(platform_name)Set the current platform by name.
SetCurrentPlatformSDKRoot
(sysroot)Set the SDK root for the current platform.
SetDefaultArchitecture
(arch_name)Set the default architecture.
SetDestroyCallback
(destroy_callback)Set a callback for when the debugger is destroyed (deprecated).
SetErrorFile
(*args)Overload 1: Set the error file for the debugger.
SetErrorFileHandle
(file, transfer_ownership)DEPRECATED, use SetErrorFile
SetInputFile
(*args)Overload 1: Set the input file for the debugger.
SetInputFileHandle
(file, transfer_ownership)DEPRECATED, use SetInputFile
SetInputString
(data)Set the input from a string.
SetInternalVariable
(var_name, value, ...)Set an internal variable.
SetLoggingCallback
(log_callback)Set a callback for log output.
SetOutputFile
(*args)Overload 1: Set the output file for the debugger.
SetOutputFileHandle
(file, transfer_ownership)DEPRECATED, use SetOutputFile
SetPrompt
(prompt)Set the command prompt string.
SetREPLLanguage
(repl_lang)Set the current REPL language.
SetScriptLanguage
(script_lang)Set the current scripting language.
SetSelectedPlatform
(platform)Set the selected platform.
SetSelectedTarget
(target)Set the selected target.
Set whether to show inline diagnostics.
SetTerminalHeight
(term_height)Set the terminal height.
SetTerminalWidth
(term_width)Set the terminal width.
SetUseColor
(use_color)Set whether to use color in output.
SetUseExternalEditor
(input)Set whether to use an external editor.
SetUseSourceCache
(use_source_cache)Set whether to use the source cache.
Set whether to skip loading application-specific .lldbinit files.
Set whether to skip loading .lldbinit files.
StateAsCString
(state)Convert a state type to a string.
StateIsRunningState
(state)Check if a state is a running state.
StateIsStoppedState
(state)Check if a state is a stopped state.
SupportsLanguage
(language)Check if a specific language is supported by LLDB.
Terminate LLDB and its subsystems.
Attributes Documentation
- eBroadcastBitError = <Mock name='mock.SBDebugger_eBroadcastBitError' id='130029409381664'>#
- eBroadcastBitExternalProgress = <Mock name='mock.SBDebugger_eBroadcastBitExternalProgress' id='130029401866208'>#
- eBroadcastBitExternalProgressCategory = <Mock name='mock.SBDebugger_eBroadcastBitExternalProgressCategory' id='130029401866160'>#
- eBroadcastBitProgress = <Mock name='mock.SBDebugger_eBroadcastBitProgress' id='130029401865968'>#
- eBroadcastBitProgressCategory = <Mock name='mock.SBDebugger_eBroadcastBitProgressCategory' id='130029401866112'>#
- eBroadcastBitWarning = <Mock name='mock.SBDebugger_eBroadcastBitWarning' id='130029401866016'>#
- version = <Mock name='mock.SBDebugger_GetVersionString()' id='130029406640400'>#
Methods Documentation
- AddDestroyCallback(destroy_callback)#
Add a callback for when the debugger is destroyed. Returns a token that can be used to remove the callback.
- CancelInterruptRequest()#
Cancel a previously requested interrupt.
- Clear()#
Clear this debugger instance.
This will close all IO handlers and reset the debugger to its initial state.
- static Create(*args)#
Overload 1: Create a new debugger instance (deprecated).
Overload 2: Create a new debugger instance.
If source_init_files is true, the debugger will source .lldbinit files from the home directory and current directory.
Overload 3: Create a new debugger instance with a custom log handler and user data passed to the log callback.
If source_init_files is true, the debugger will source .lldbinit files from the home directory and current directory.
- CreateCategory(category_name)#
Create a new type category.
- CreateTarget(*args)#
Overload 1: Create a target with the specified parameters.
Overload 2: Create a target with the specified file.
- CreateTargetWithFileAndArch(filename, archname)#
Create a target with the specified file and architecture.
- CreateTargetWithFileAndTargetTriple(filename, target_triple)#
Create a target with the specified file and target triple.
- DeleteCategory(category_name)#
Delete a type category.
- DeleteTarget(SBDebugger self, SBTarget target) bool #
Return true if target is deleted from the target list of the debugger.
- static Destroy(debugger)#
Destroy a debugger instance.
- DispatchInput(data)#
Dispatch input to the debugger.
- DispatchInputEndOfFile()#
Signal end-of-file to the current input dispatch.
- DispatchInputInterrupt()#
Interrupt the current input dispatch.
- EnableLog(channel, categories)#
Enable logging for a specific channel and category.
- static FindDebuggerWithID(id)#
Find a debugger by ID. Returns an invalid debugger if not found.
- FindTargetWithFileAndArch(filename, arch)#
Find a target with the specified file and architecture.
- FindTargetWithProcessID(pid)#
Find a target with the specified process ID.
- GetAsync()#
Get whether the debugger is running in asynchronous mode.
- 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().
- GetBroadcaster()#
Get the broadcaster that allows subscribing to events from this debugger.
- static GetBroadcasterClass()#
Get the broadcaster class name.
- static GetBuildConfiguration()#
Get the build configuration as structured data.
- GetCategory(*args)#
Overload 1: Get a type category by name.
Overload 2: Get a type category by language.
- GetCategoryAtIndex(index)#
Get a type category by index.
- GetCloseInputOnEOF()#
Get whether to close input on EOF (deprecated).
- GetCommandInterpreter()#
Get the command interpreter for this debugger.
- static GetDefaultArchitecture(arch_name, arch_name_len)#
Get the default architecture.
- GetDefaultCategory()#
Get the default type category.
- GetDescription(description)#
Get a description of this debugger.
- static GetDiagnosticFromEvent(event)#
Get diagnostic information from an event.
- GetDummyTarget(SBDebugger self) SBTarget #
The dummy target holds breakpoints and breakpoint names that will prime newly created targets.
- GetErrorFile()#
Get the error file for the debugger.
- GetErrorFileHandle(SBDebugger self) lldb::FileSP #
- GetFilterForType(type_name_spec)#
Get the filter for a type.
- GetFormatForType(type_name_spec)#
Get the format for a type.
- GetID()#
Get the unique ID of this debugger.
- GetIndexOfTarget(target)#
Get the index of a target.
- GetInputFile()#
Get the input file for the debugger.
- GetInputFileHandle(SBDebugger self) lldb::FileSP #
- GetInstanceName()#
Get the instance name of this debugger.
- static GetInternalVariableValue(var_name, debugger_instance_name)#
Get the value of an internal variable.
- GetListener()#
Get the listener associated with this debugger.
- GetNumAvailablePlatforms(SBDebugger self) uint32_t #
Get the number of available platforms.
- GetNumCategories()#
Get the number of type categories.
- GetNumPlatforms(SBDebugger self) uint32_t #
Get the number of currently active platforms.
- GetNumTargets()#
Get the number of targets in the debugger.
- GetOutputFile()#
Get the output file for the debugger.
- GetOutputFileHandle(SBDebugger self) lldb::FileSP #
- GetPlatformAtIndex(SBDebugger self, uint32_t idx) SBPlatform #
Get one of the currently active platforms.
- static GetProgressDataFromEvent(event)#
Get progress data from an event.
- static GetProgressFromEvent(event)#
Get progress data from a SBEvent whose type is eBroadcastBitProgress.
- Parameters:
[in] โ event The event to extract the progress information from.
[out] โ progress_id The unique integer identifier for the progress to report.
[out] โ completed The amount of work completed. If completed is zero, then this event is a progress started event. If completed is equal to total, then this event is a progress end event. Otherwise completed indicates the current progress update.
[out] โ total The total amount of work units that need to be completed. If this value is UINT64_MAX, then an indeterminate progress indicator should be displayed.
[out] โ is_debugger_specific Set to true if this progress is specific to this debugger only. Many progress events are not specific to a debugger instance, like any progress events for loading information in modules since LLDB has a global module cache that all debuggers use.
- Return type:
string
- Returns:
The message for the progress. If the returned value is NULL, then event was not a eBroadcastBitProgress event.
- GetPrompt()#
Get the command prompt string.
- GetREPLLanguage()#
Get the current REPL language.
- GetReproducerPath()#
Get the path to the reproducer.
- GetScriptInterpreterInfo(language)#
Get information about a script interpreter as structured data.
- GetScriptLanguage()#
Get the current scripting language.
- GetScriptingLanguage(script_language_name)#
Get the scripting language by name.
- GetSelectedPlatform()#
Get the selected platform.
- GetSelectedTarget()#
Get the currently selected target.
- GetSetting(setting=None)#
Get debugger settings as structured data.
Client can specify empty string or null to get all settings.
Example usages: lldb::SBStructuredData settings = debugger.GetSetting(); lldb::SBStructuredData settings = debugger.GetSetting(nullptr); lldb::SBStructuredData settings = debugger.GetSetting(โโ); lldb::SBStructuredData settings = debugger.GetSetting(โtarget.arg0โ); lldb::SBStructuredData settings = debugger.GetSetting(โtargetโ);
- GetSourceManager()#
Get the source manager for this debugger.
- GetSummaryForType(type_name_spec)#
Get the summary for a type.
- GetSyntheticForType(type_name_spec)#
Get the synthetic for a type.
- GetTargetAtIndex(idx)#
Get a target by index.
- GetTerminalHeight()#
Get the terminal height.
- GetTerminalWidth()#
Get the terminal width.
- GetUseColor()#
Get whether color is being used in output.
- GetUseExternalEditor()#
Get whether an external editor is being used.
- GetUseSourceCache()#
Get whether the source cache is being used.
- static GetVersionString()#
Get the LLDB version string.
- HandleCommand(command)#
Execute a command in the command interpreter.
- HandleProcessEvent(*args)#
Overload 1: Handle a process event.
Overload 2: Handle a process event using FileSP objects.
- static Initialize()#
Initialize LLDB and its subsystems.
This function should be called before any other LLDB functions. It initializes all required subsystems for proper LLDB functionality.
- static InitializeWithErrorHandling()#
Initialize the LLDB debugger subsystem with error handling.
Similar to Initialize(), but returns an error if initialization fails.
- InterruptRequested()#
Check if an interrupt has been requested.
- IsValid()#
Check if this is a valid SBDebugger object.
- LoadTraceFromFile(error, trace_description_file)#
Load a trace from a trace description file.
This will create Targets, Processes and Threads based on the contents of the file.
- Parameters:
error (
SBError
, out) โ An error if the trace could not be created.trace_description_file (
SBFileSpec
, in) โ The file containing the necessary information to load the trace.
- Return type:
- Returns:
An SBTrace object representing the loaded trace.
- static MemoryPressureDetected()#
Notify the debugger that system memory pressure has been detected.
This can be used to free up memory resources by clearing caches.
- static PrintDiagnosticsOnError()#
Configure LLDB to print diagnostic information when it crashes.
- static PrintStackTraceOnError()#
Configure LLDB to print a stack trace when it crashes.
- RemoveDestroyCallback(token)#
Remove a destroy callback.
- RequestInterrupt()#
Request an interrupt of the current operation.
- ResetStatistics()#
Clear collected statistics for targets belonging to this debugger.
This includes clearing symbol table and debug info parsing/index time for all modules, breakpoint resolve time, and target statistics.
- RestoreInputTerminalState()#
Restore the previously saved terminal state.
- 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(language, repl_options)#
Run a REPL (Read-Eval-Print Loop) for the specified language.
- SaveInputTerminalState()#
Save the current terminal state.
This should be called before modifying terminal settings.
- SetAsync(b)#
Set whether the debugger should run in asynchronous mode.
When in asynchronous mode, events are processed on a background thread.
- SetCloseInputOnEOF(b)#
Set whether to close input on EOF (deprecated).
- SetCurrentPlatform(platform_name)#
Set the current platform by name.
- SetCurrentPlatformSDKRoot(sysroot)#
Set the SDK root for the current platform.
- static SetDefaultArchitecture(arch_name)#
Set the default architecture.
- SetDestroyCallback(destroy_callback)#
Set a callback for when the debugger is destroyed (deprecated).
- SetErrorFile(*args)#
Overload 1: Set the error file for the debugger.
Overload 2: Set the error file for the debugger using a FileSP.
- SetErrorFileHandle(file, transfer_ownership)#
DEPRECATED, use SetErrorFile
- SetInputFile(*args)#
Overload 1: Set the input file for the debugger.
Overload 2: Set the input file for the debugger using a FileSP.
- SetInputFileHandle(file, transfer_ownership)#
DEPRECATED, use SetInputFile
- SetInputString(data)#
Set the input from a string.
- static SetInternalVariable(var_name, value, debugger_instance_name)#
Set an internal variable.
- SetLoggingCallback(log_callback)#
Set a callback for log output.
- SetOutputFile(*args)#
Overload 1: Set the output file for the debugger.
Overload 2: Set the output file for the debugger using a FileSP.
- SetOutputFileHandle(file, transfer_ownership)#
DEPRECATED, use SetOutputFile
- SetPrompt(prompt)#
Set the command prompt string.
- SetREPLLanguage(repl_lang)#
Set the current REPL language.
- SetScriptLanguage(script_lang)#
Set the current scripting language.
- SetSelectedPlatform(platform)#
Set the selected platform.
- SetSelectedTarget(target)#
Set the selected target.
- SetShowInlineDiagnostics(b)#
Set whether to show inline diagnostics.
- SetTerminalHeight(term_height)#
Set the terminal height.
- SetTerminalWidth(term_width)#
Set the terminal width.
- SetUseColor(use_color)#
Set whether to use color in output.
- SetUseExternalEditor(input)#
Set whether to use an external editor.
- SetUseSourceCache(use_source_cache)#
Set whether to use the source cache.
- SkipAppInitFiles(b)#
Set whether to skip loading application-specific .lldbinit files.
- SkipLLDBInitFiles(b)#
Set whether to skip loading .lldbinit files.
- static StateAsCString(state)#
Convert a state type to a string.
- static StateIsRunningState(state)#
Check if a state is a running state.
- static StateIsStoppedState(state)#
Check if a state is a stopped state.
- static SupportsLanguage(language)#
Check if a specific language is supported by LLDB.
- static Terminate()#
Terminate LLDB and its subsystems.
This should be called when LLDB is no longer needed.