Expand description
§LLDB
This crate provides a safe binding to the public API for LLDB, the debugger provided by the LLVM project. LLDB provides a modern, high performance debugger framework and is the default debugger for macOS and iOS.
§Installation
This crate works with Cargo and is on crates.io.
Add it to your Cargo.toml
like so:
lldb = "0.0.12"
§macOS Installation Notes
On macOS, this library relies upon being able to find
the LLDB.framework
that is provided by Xcode.app.
In your own application, you will need to configure the
@rpath
for your executable to point to the location
of the LLDB.framework
that you are using. Doing this
automatically is not currently supported by Cargo.
For testing, you can use the version provided by Xcode.app by setting an environment variable:
export DYLD_FRAMEWORK_PATH=/Applications/Xcode.app/Contents/SharedFrameworks
§Linux Installation Notes
Install the lldb
and lldb-dev
packages for your platform so that
you have both LLDB itself installed as well as the headers and
other support files required.
§Windows Installation Notes
Support for building this has not yet been provided for Windows. Contributions are welcome!
§Usage
The primary entry point is SBDebugger
. This will be how you
create a debug target and begin the actually interesting stuff.
§Important Classes
The LLDB API provides many structs and a wide range of functionality. Some of the most common usages will involve these structs and their corresponding methods:
SBDebugger
: Manages the entire debug experience and createsSBTarget
s.SBTarget
: The target program running under the debugger.SBProcess
: The process associated with the target program.SBThread
: A thread of execution.SBProcess
containsSBThread
s.SBFrame
: One of the stack frames associated with a thread.SBThread
containsSBFrame
s.SBSymbolContext
: A container that stores various debugger related info.SBValue
: The value of a variable, a register, or an expression.SBModule
: An executable image and its associated object and symbol files.SBTarget
containsSBModule
s.SBBreakpoint
: A logical breakpoint and its associated settings.SBTarget
containsSBBreakpoint
s.SBSymbol
: The symbol possibly associated with a stack frame.SBCompileUnit
: A compilation unit, or compiled source file.SBFunction
: A generic function, which can be inlined or not.SBBlock
: A lexical block.SBFunction
containsSBBlock
s.SBLineEntry
: Specifies an association with a contiguous range of instructions and a source file location.SBCompileUnit
containsSBLineEntry
s.
§Support and Maintenance
I am developing this library largely on my own so far. I am able to offer support and maintenance, but would very much appreciate donations via Patreon. I can also provide commercial support, so feel free to contact me.
Re-exports§
pub use lldb_sys as sys;
Structs§
- Command
Flags - Emulate
Instruction Options - File
Permissions - Function
Name Type - Image
Token - The token to unload image
- Launch
Flags - Permissions
- SBAddress
- A section + offset based address class.
- SBAttach
Info - Configuration for attaching to a process.
- SBBlock
- A lexical block.
- SBBreakpoint
- A logical breakpoint and its associated settings.
- SBBreakpoint
List - A list of breakpoints.
- SBBreakpoint
List Iter - An iterator over the breakpoints in an
SBBreakpointList
. - SBBreakpoint
Location - One unique instance (by address) of a logical breakpoint.
- SBBreakpoint
Location Iter - An iterator over the locations in an
SBBreakpoint
. - SBBroadcaster
- An entity which can broadcast events.
- SBCommand
Interpreter - SBCompile
Unit - A compilation unit or compiled source file.
- SBData
- A block of data.
- SBDebugger
- Creates
SBTarget
s, provides access to them and manages the overall debugging experience. - SBDebugger
Target Iter - Iterate over the targets known to a debugger.
- SBError
- A container for holding any error code and an error message.
- SBEvent
- An event.
- SBExpression
Options - SBFile
- Represents a file.
- SBFile
Spec - A file specification that divides the path into a directory and basename.
- SBFile
Spec List - A list of filespecs.
- SBFile
Spec List Iter - An iterator over the filespecs in an
SBFileSpecList
. - SBFrame
- One of the stack frames associated with a thread.
- SBFunction
- A generic function, which can be inlined or not.
- SBInstruction
- A machine instruction.
- SBInstruction
List - A list of machine instructions.
- SBInstruction
List Iter - An iterator over the instructions in an
SBInstructionList
. - SBLaunch
Info - Configuration for launching a process.
- SBLine
Entry - Specifies an association with a contiguous range of instructions and a source file location.
- SBListener
- Listen for debugger events.
- SBMemory
Region Info - Information about memory regions within a process.
- SBMemory
Region Info List - A list of memory regions.
- SBMemory
Region Info List Iter - An iterator over the memory regions in an
SBMemoryRegionInfoList
. - SBModule
- An executable image and its associated object and symbol files.
- SBModule
Section Iter - Iterate over the sections in a module.
- SBModule
Spec - A description of an
SBModule
. - SBModule
Symbols Iter - Iterate over the symbols in a module.
- SBPlatform
- A platform that can represent the current host or a remote host debug platform.
- SBProcess
- The process associated with the target program.
- SBProcess
Event - SBProcess
Event Restarted Reason Iter - Iterate over the restart reasons in a process event.
- SBProcess
Info - Describes an existing process and any discoverable information that pertains to that process.
- SBProcess
Queue Iter - Iterate over the queues in a process.
- SBProcess
Thread Iter - Iterate over the threads in a process.
- SBQueue
- A
libdispatch
(aka Grand Central Dispatch) queue. - SBQueue
Item - A work item enqueued on a libdispatch aka Grand Central Dispatch (GCD) queue.
- SBQueue
Queue Item Iter - Iterate over the queue items in a queue.
- SBQueue
Thread Iter - Iterate over the threads associated with a queue.
- SBSection
- Represents an executable image section.
- SBSection
SubSection Iter - Iterate over the subsections in a section.
- SBStream
- A destination for streaming data output. By default, this is a string stream, but it can be redirected to a file.
- SBString
List - A list of strings.
- SBString
List Iter - An iterator over an
SBStringList
. - SBStructured
Data - The value of a variable, register or expression.
- SBSymbol
- The symbol possibly associated with a stack frame.
- SBSymbol
Context - A container that stores various debugger related info.
- SBSymbol
Context List - A list of symbol contexts.
- SBTarget
- The target program running under the debugger.
- SBTarget
Breakpoint Iter - Iterate over the breakpoints in a target.
- SBTarget
Event - SBTarget
Event Module Iter - Iterate over the modules referenced from a target event.
- SBTarget
Module Iter - Iterate over the modules in a target.
- SBTarget
Watchpoint Iter - Iterate over the watchpoints in a target.
- SBThread
- A thread of execution.
- SBThread
Event - A thread event.
- SBThread
Frame Iter - Iterate over the frames in a thread.
- SBType
- SBType
List - A list of types.
- SBType
List Iter - An iterator over the types in an
SBTypeList
. - SBValue
- The value of a variable, register or expression.
- SBValue
List - A list of values.
- SBValue
List Iter - An iterator over the values in an
SBValueList
. - SBVariables
Options - SBWatchpoint
- An instance of a watch point for a specific target program.
- Symbol
Context Item - These mask bits allow a common interface for queries that can limit the amount of information that gets parsed to only the information that is requested. These bits also can indicate what actually did get resolved during query function calls.
- Type
Class - Type
Flags - Type
Options - Watchpoint
Kind
Enums§
- Access
Type - Basic
Type - Breakpoint
Event Type - Byte
Order - Byte order definitions.
- Command
Argument Type - Connection
Status - Description
Level - Disassembly
Flavor - Which syntax should be used in disassembly?
- Dynamic
Value Type - Encoding
- Register encoding definitions.
- Error
Type - Expression
Evaluation Phase - Expression
Results - Format
- Display format definitions.
- Frame
Comparison - GdbSignal
- Input
Reader Action - Input
Reader Granularity - Instrumentation
Runtime Type - Language
Type - Match
Type - Member
Function Kind - Path
Type - Queue
Item Kind - Queue
Kind - Register
Kind - Return
Status - RunMode
- Thread run modes.
- Script
Language - Section
Type - State
Type - Process and thread states.
- Stop
Reason - Thread stop reasons.
- Symbol
Type - Template
Argument Kind - Type
Summary Capping - Value
Type - Watchpoint
Event Type
Type Aliases§
- lldb_
addr_ t - Storage for the value of an address.
- lldb_
offset_ t - Storage for an offset between 2 addresses in memory.
- lldb_
pid_ t - Storage for an OS process ID.
- lldb_
tid_ t - Storage for an OS thread ID.
- lldb_
user_ id_ t - Storage for an OS user ID.