The abstracted debugger interface.
Modules:
Classes:
-
Error– -
DisassembledInstruction– -
DebuggerType– -
StopPoint–The handle to either an insalled breakpoint or watchpoint.
-
BreakpointLocation–This is the location specification for a breakpoint.
-
WatchpointLocation–This is the location specification for a watchpoint.
-
Registers–A handle to the register values in a frame.
-
SymbolLookupType–Enum representing types of symbol lookups for filtering symbol searches.
-
Frame– -
Thread– -
MemoryMap–A wrapper around a sequence of memory ranges
-
ExecutionController– -
Process– -
TypeCode–Broad categories of types.
-
TypeField–The fields in a structured type.
-
Type–Class representing a type in the context of an inferior process.
-
Value–Class representing a value in the context of an inferior process.
-
CommandHandle–An opaque handle to an installed command.
-
EventType–Events that can be listened for and reacted to in a debugger.
-
Debugger–The base class representing a debugger.
Functions:
-
selection–Debuggers have global state. Many of our queries require that we select a
Attributes:
Bases: Exception
The handle to either an insalled breakpoint or watchpoint.
May be used in a with statement, in which case the stop point is automatically removed at the end of the statement. This allows for easy implementation of temporary breakpoints.
Methods:
-
remove–Removes the breakpoint associated with this handle.
-
set_enabled–Enables or disables this breakpoint.
-
__enter__– -
__exit__–Automatic breakpoint removal.
This is the location specification for a watchpoint.
Attributes:
-
address(int) – -
size(int) – -
watch_read(bool) – -
watch_write(bool) –
Bases: Enum
Enum representing types of symbol lookups for filtering symbol searches.
Attributes: - ANY: Represents searching for any symbol type (default). - FUNCTION: Represents searching specifically for function symbols. - VARIABLE: Represents searching specifically for variable symbols.
Attributes:
Methods:
-
lookup_symbol–Looks up and returns the address of a symbol in current frame by its name.
-
evaluate_expression–Evaluate the given expression in the context of this frame, and
-
regs–Access the values of the registers in this frame.
-
reg_write–Sets the value of the register with the given name to the given value.
-
pc–The value of the program counter for this frame.
-
sp–The value of the stack pointer for this frame.
-
parent–The parent frame of this frame, if it exists.
-
child–The child frame of this frame, if it exists.
-
sal–The filename of the source code file associated with this frame, and the
-
__eq__–Whether this frame is the same as the given frame. Two frames are the
lookup_symbol(name: str, *, type: SymbolLookupType = ANY) -> Value | None
Looks up and returns the address of a symbol in current frame by its name.
Parameters: - name (str): The name of the symbol to look up. - type (SymbolLookupType, optional): The type of symbol to search for. Defaults to SymbolLookupType.ANY.
Returns: - pwndbg.dbg_mod.Value | None: The value of the symbol if found, or None if not found.
Raises: - pwndbg.dbg_mod.Error: If symbol name contains invalid characters
evaluate_expression(expression: str, lock_scheduler: bool = False) -> Value
Evaluate the given expression in the context of this frame, and return a Value.
lock_scheduler¤
Additionally, callers of this function might specify that they want to enable scheduler locking during the evaluation of this expression. This is a GDB-only option, and is intended for cases in which the result would be incorrect without it enabled, when running in GDB. Other debuggers should ignore this parameter.
Sets the value of the register with the given name to the given value. Returns true if the register exists, false othewise. Throws an exception if the register exists but cannot be written to.
The filename of the source code file associated with this frame, and the line number associated with it, if available.
Whether this frame is the same as the given frame. Two frames are the same if they point to the same stack frame and have the same execution context.
Methods:
-
bottom_frame–Frame at the bottom of the call stack for this thread.
-
ptid–The PTID of this thread, if available.
-
index–The unique index of this thread from the perspective of the debugger.
A wrapper around a sequence of memory ranges
Methods:
Methods:
-
single_step–Steps to the next instruction.
-
cont–Continues execution until the given breakpoint or whatchpoint is hit.
Steps to the next instruction.
Throws CancelledError if a breakpoint or watchpoint is hit, the program exits, or if any other unexpected event that diverts execution happens while fulfulling the step.
Methods:
-
threads–Returns a list containing the threads in this process.
-
pid–Returns the process ID of this process if it is alive.
-
alive–Returns whether this process is alive.
-
stopped_with_signal–Returns whether this process was stopped by a signal.
-
evaluate_expression–Evaluate the given expression in the context of the current process, and
-
vmmap–Returns the virtual memory map of this process.
-
read_memory–Reads the requested number of bytes from the address given in the memory
-
write_memory–Writes as many bytes from the given data buffer as possible into the
-
find_in_memory–Searches for a bit pattern in the memory space of the process. The bit
-
is_remote–Returns whether this process is a remote process connected to using the
-
send_remote–Sends the given packet to the GDB remote debugging protocol server.
-
send_monitor–Sends the given monitor command to the GDB remote debugging protocol
-
download_remote_file–Downloads the given file from the remote host and saves it to the local
-
create_value–Create a new value in the context of this process, with the given value
-
symbol_name_at_address–Returns the name of the symbol at the given address in the program, if
-
lookup_symbol–Looks up and returns the address of a symbol by its name.
-
types_with_name–Returns a list of all types in this process that match the given name.
-
arch–The default architecture of this process.
-
break_at–Install a breakpoint or watchpoint at the given location.
-
is_linux–Returns whether the current ABI is GNU/Linux.
-
disasm–Returns the disassembled instruction at the given address in the address
-
module_section_locations–Return a list of (address, size, section_name, module_name) tuples for
-
main_module_name–Returns the name of the main module.
-
main_module_entry–Returns the entry point of the main module.
-
is_dynamically_linked–Returns whether this process makes use of dynamically linked libraries.
-
dispatch_execution_controller–Queues up the given execution controller-based coroutine for execution,
Returns whether this process was stopped by a signal.
evaluate_expression(expression: str) -> Value
Evaluate the given expression in the context of the current process, and return a Value.
Reads the requested number of bytes from the address given in the memory space of this process. Will read as many bytes as possible starting at that location, and returns how many were read.
Throws an exception if reading fails and partial is False.
Writes as many bytes from the given data buffer as possible into the given address in the memory space of this process.
Throws an exception if writing fails and partial is False.
find_in_memory(
pattern: bytearray,
start: int,
size: int,
align: int,
max_matches: int = -1,
step: int = -1,
) -> Generator[int, None, None]
Searches for a bit pattern in the memory space of the process. The bit pattern can be searched for in a given memory range, and with a given alignment. The maximum number of matches that will be generated is given by max_matches. A value of max_matches of -1 will generate all matches.
Returns whether this process is a remote process connected to using the GDB remote debugging protocol.
Sends the given packet to the GDB remote debugging protocol server. Should only be called if is_remote() is true.
Sends the given monitor command to the GDB remote debugging protocol server. Should only be called if is_remote() is true.
Downloads the given file from the remote host and saves it to the local given path. Should only be called if is_remote() is true.
Create a new value in the context of this process, with the given value and, optionally, type. If no type is provided, one will be chosen automatically.
Returns the name of the symbol at the given address in the program, if one exists.
lookup_symbol(
name: str,
*,
prefer_static: bool = False,
type: SymbolLookupType = ANY,
objfile_endswith: str | None = None,
) -> Value | None
Looks up and returns the address of a symbol by its name.
Parameters: - name (str): The name of the symbol to look up. - prefer_static (bool, optional): If True, prioritize symbols in the static block, if supported by the debugger. Defaults to False. - type (SymbolLookupType, optional): The type of symbol to search for. Defaults to SymbolLookupType.ANY. - objfile_endswith (str | None, optional): If specified, limits the search to the first object file whose name ends with the provided string.
Returns: - pwndbg.dbg_mod.Value | None: The value of the symbol if found, or None if not found.
Raises: - pwndbg.dbg_mod.Error: If no object file matching the objfile_endswith pattern is found.
types_with_name(name: str) -> Sequence[Type]
Returns a list of all types in this process that match the given name.
break_at(
location: BreakpointLocation | WatchpointLocation,
stop_handler: Callable[[StopPoint], bool] | None = None,
internal: bool = False,
) -> StopPoint
Install a breakpoint or watchpoint at the given location.
The type of the location determines whether the newly created object is a watchpoint or a breakpoint. BreakpointLocation locations yield breakpoints, while WatchpointLocation locations yield watchpoints.
Aditionally, one may specify a stop handler function, to be run when the breakpoint or whatchpoint is hit, and that determines whether execution should stop. With a return value of True being interpreted as a signal to stop, and a return value of False being interpreted as a signal to continue execution. The extent of the actions that may be taken during the stop handler is determined by the debugger.
Marking a breakpoint or watchpoint as internal hints to the implementation that the created breakpoint or watchpoint should not be directly nameable by the user, and that it should not print any messages upon being triggered. Implementations should try to honor this hint, but they are not required to in case honoring it is either not possible or comes at a significant impact to performance.
This function returns a handle to the newly created breakpoint or watchpoint.
disasm(address: int) -> DisassembledInstruction | None
Returns the disassembled instruction at the given address in the address space of the running process, or None if there's no valid instruction at that address.
Return a list of (address, size, section_name, module_name) tuples for the loaded sections in every module of this process.
Returns the name of the main module.
On remote targets, this may be prefixed with "target:" string.
Returns whether this process makes use of dynamically linked libraries.
"dynamically linked"¤
What exactly it means to be "dynamically linked" here is a little ill-defined. Ideally, this function should return true if the process uses the default dynamic linker for the system, as that would better reflect whether the process uses dynamic linking.
Currently, though, Pwndbg expects it to behave the same as a check for the string "No shared libraries loaded at this time." in the output of the info dll GDB command, which checks for the presence of other modules in the address space of the process, rather than whether or not the dynamic linker is used.
We should probably sort this out in the future.
dispatch_execution_controller(
procedure: Callable[[ExecutionController], Coroutine[Any, Any, None]],
)
Queues up the given execution controller-based coroutine for execution, sometime between the calling of this function and the
Bases: Enum
Broad categories of types.
Attributes:
TypeField(
bitpos: int,
name: str | None,
type: Type,
parent_type,
enumval: int | None = None,
artificial: bool = False,
is_base_class: bool = False,
bitsize: int = 0,
)
The fields in a structured type.
Currently this is just a mirror of gdb.Field.
Attributes:
-
bitpos– -
name– -
type– -
parent_type– -
enumval– -
artificial– -
is_base_class– -
bitsize–
Class representing a type in the context of an inferior process.
Methods:
-
func_arguments–Returns a list of function arguments type.
-
fields–List of all fields in this type, if it is a structured type.
-
has_field–Whether this type has a field with the given name.
-
array–Return a type that corresponds to an array whose elements have this type.
-
pointer–Return a pointer type that has this type as its pointee.
-
strip_typedefs–Return a type that corresponds to the base type after a typedef chain,
-
target–Return the target of this reference type, if this is a reference type.
-
keys–Returns a list containing all the field names of this type.
-
enum_member–Retrieve the integer value of an enum member.
-
offsetof–Calculate the byte offset of a field within a struct or union.
-
__eq__–Returns True if types are the same
Attributes:
-
name_identifier(str | None) –Returns the identifier of this type, eg:
-
name_to_human_readable(str) –Returns the human friendly name of this type, eg:
-
sizeof(int) –The size of this type, in bytes.
-
alignof(int) –The alignment of this type, in bytes.
-
code(TypeCode) –What category of type this object belongs to.
property ¤
Returns the identifier of this type, eg: - someStructName - someEnumName - someTypedefName
Returns None if the type is anonymous or does not have a name, such as: - Anonymous structs - Anonymous Typedefs - Basic types like char[], void, etc.
property ¤
Returns the human friendly name of this type, eg: - char [16] - int - char * - void * - fooStructName - barEnumName - barTypedefName
This function is not standardized, may return different names in gdb/lldb, eg: gdb: char [16] or char [50] or struct {...} lldb: char[16] or char[] or (anonymous struct)
You should not use this function. Only for human eyes.
func_arguments() -> list[Type] | None
Returns a list of function arguments type.
Returns:
-
list[Type] | None–List[Type] | None: The function arguments type, or None if debug information is missing.
Raises:
-
TypeError–If called on an unsupported type.
array(count: int) -> Type
Return a type that corresponds to an array whose elements have this type.
strip_typedefs() -> Type
Return a type that corresponds to the base type after a typedef chain, if this is a typedef. Returns the type itself otherwise.
Retrieve the integer value of an enum member.
It returns: - integer value, when found field - returns None, If the field does not exist
Calculate the byte offset of a field within a struct or union.
This method recursively traverses nested structures and unions, and it computes the byte-aligned offset for the specified field.
It returns: - offset in bytes if found - None if the field doesn't exist or if an unsupported alignment/bit-field is encountered
Class representing a value in the context of an inferior process.
Methods:
-
dereference–If this is a poitner value, dereferences the pointer and returns a new
-
string–If this value is a string, then this method converts it to a Python string.
-
value_to_human_readable–Converts a Value to a human-readable string representation. -
fetch_lazy–Fetches the value if it is lazy, does nothing otherwise.
-
__int__–Converts this value to an integer, if possible.
-
cast–Returns a new value with the same value as this object, but of the
-
__add__–Adds an integer to this value, if that makes sense. Throws an exception
-
__sub__–Subtract an integer from this value, if that makes sense. Throws an
-
__getitem__–Gets the value with the given name that belongs to this value. For
Attributes:
-
address(Value | None) –The address of this value, in memory, if addressable, otherwise
None. -
is_optimized_out(bool) –Whether this value is present in debugging information, but has been
-
type(Type) –The type associated with this value.
property ¤
address: Value | None
The address of this value, in memory, if addressable, otherwise None.
property ¤
Whether this value is present in debugging information, but has been optimized out of the actual program.
dereference() -> Value
If this is a poitner value, dereferences the pointer and returns a new instance of Value, containing the value pointed to by this pointer.
If this value is a string, then this method converts it to a Python string.
Converts a Value to a human-readable string representation.
The format is similar to what is produced by the `str()` function for gdb.Value,
displaying nested fields and pointers in a user-friendly way.
**Usage Notes:**
- This function is intended solely for displaying results to the user.
- The output format may differ between debugger implementations (e.g., GDB vs LLDB),
as each debugger may format values differently. For instance:
- GDB might produce: '{
value = 0, inner = { next = 0x555555558098
Returns a new value with the same value as this object, but of the given type.
__add__(rhs: int) -> Value
Adds an integer to this value, if that makes sense. Throws an exception otherwise.
Bases: Enum
Events that can be listened for and reacted to in a debugger.
The events types listed here are defined as follows
START: This event is fired some time between the creation of or attachment to the process to be debugged, and the start of its execution.STOP: This event is fired after execution of the process has been suspended, but before control is returned to the user for interactive debugging.EXIT: This event is fired after the process being debugged has been detached from or has finished executing.MEMORY_CHANGED: This event is fired when the user interactively makes changes to the memory of the process being debugged.REGISTER_CHANGED: LikeMEMORY_CHANGED, but for registers.CONTINUE: This event is fired after the user has requested for process execution to continue after it had been previously suspended.NEW_MODULE: This event is fired when a new application module has been encountered by the debugger. This usually happens when a new application module is loaded into the memory space of the process being debugged. In GDB terminology, these are calledobjfiles.
Attributes:
-
START– -
STOP– -
EXIT– -
MEMORY_CHANGED– -
REGISTER_CHANGED– -
CONTINUE– -
NEW_MODULE–
The base class representing a debugger.
Methods:
-
setup–Perform debugger-specific initialization.
-
history–The command history of the interactive session in this debugger.
-
lex_args–Lexes the given command line into a list of arguments, according to the
-
selected_inferior–The inferior process currently being focused on in this interactive session.
-
selected_thread–The thread currently being focused on in this interactive session.
-
selected_frame–The stack frame currently being focused on in this interactive session.
-
commands–List the commands available in this session.
-
add_command–Adds a command with the given name to the debugger, that invokes the
-
has_event_type–Whether the given event type is supported by this debugger. Indicates
-
event_handler–Sets up the given function to be called when an event of the given type
-
suspend_events–Suspend delivery of all events of the given type until it is resumed
-
resume_events–Resume the delivery of all events of the given type, if previously
-
set_sysroot–Sets the system root for this debugger.
-
x86_disassembly_flavor–The flavor of disassembly to use for x86 targets.
-
supports_breakpoint_creation_during_stop_handler–Whether breakpoint or watchpoint creation through
break_atis -
breakpoint_locations–Returns a list of all breakpoint locations that are currently
-
name–The type of the current debugger.
-
is_gdblib_available–Whether gdblib is available under this debugger.
-
string_limit–The maximum size of a string.
-
addrsz–Format the given address value.
-
get_cmd_window_size–The size of the command window, in characters, if available.
-
set_python_diagnostics–Enables or disables Python diagnostic messages for this debugger.
Attributes:
-
pre_ctx_lines(int) –Our prediction on how many lines of text will be printed as
property ¤
Our prediction on how many lines of text will be printed as a preamble (right after the prompt, and before the context) the next time the context is printed.
This includes any lines the underlying debugger generates.
The user never sees these lines when context-clear-screen is enabled.
Perform debugger-specific initialization.
This method should be run immediately after pwndbg.dbg is set to an instance of this class, and, as such, is allowed to run code that depends on it being set.
Because we can't really know what a given debugger object will need as part of its setup process, we allow for as many arguments as desired to be passed in, and leave it up to the implementations to decide what they need. This shouldn't be a problem, seeing as, unlike other methods in this class, this should only be called as part of the debugger-specific bringup code.
The command history of the interactive session in this debugger.
This function returns the last last items in the command history, as an oldest-to-youngest-sorted list of tuples, where the first element in each tuple is the index of the command in the history, and the second element is a string giving the command itself.
Lexes the given command line into a list of arguments, according to the conventions of the debugger being used and of the interactive session.
selected_inferior() -> Process | None
The inferior process currently being focused on in this interactive session.
selected_thread() -> Thread | None
The thread currently being focused on in this interactive session.
selected_frame() -> Frame | None
The stack frame currently being focused on in this interactive session.
add_command(
name: str, handler: Callable[[Debugger, str, bool], None], doc: str | None
) -> CommandHandle
Adds a command with the given name to the debugger, that invokes the given function every time it is called.
has_event_type(ty: EventType) -> bool
Whether the given event type is supported by this debugger. Indicates that a user either can or cannot register an event handler of this type.
Sets up the given function to be called when an event of the given type gets fired. Returns a callable that corresponds to the wrapped function. This function my be used as a decorator.
suspend_events(ty: EventType) -> None
Suspend delivery of all events of the given type until it is resumed through a call to resume_events.
Events triggered during a suspension will be ignored, and will not be delived, even after delivery is resumed.
resume_events(ty: EventType) -> None
Resume the delivery of all events of the given type, if previously suspeded through a call to suspend_events. Does nothing if the delivery has not been previously suspeded.
The flavor of disassembly to use for x86 targets.
Whether breakpoint or watchpoint creation through break_at is supported during breakpoint stop handlers.
breakpoint_locations() -> list[BreakpointLocation]
Returns a list of all breakpoint locations that are currently installed and enabled in the focused process.
Whether gdblib is available under this debugger.
The size of the command window, in characters, if available.
Enables or disables Python diagnostic messages for this debugger.
Debuggers have global state. Many of our queries require that we select a given object globally before we make them. When doing that, we must always be careful to return selection to its previous state before exiting. This class automatically manages the selection of a single object type.
Upon entrace to the with block, the element given by target will be compared to the object returned by calling get_current. If they compare different, the value previously returned by get_current is saved, and the element given by target will be selected by passing it as an argument to select, and, after execution leaves the with block, the previously saved element will be selected in the same fashion as the first element.
If the elements don't compare different, this is a no-op.