init
The abstracted debugger interface.
T = TypeVar('T')
module-attribute
¶
dbg: Debugger = None
module-attribute
¶
Arch
¶
BreakpointLocation
¶
CommandHandle
¶
An opaque handle to an installed command.
remove()
¶
Removes this command from the command palette of the debugger.
Debugger
¶
The base class representing a debugger.
add_command(name, handler, doc)
¶
Adds a command with the given name to the debugger, that invokes the given function every time it is called.
addrsz(address)
¶
Format the given address value.
commands()
¶
List the commands available in this session.
event_handler(ty)
¶
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.
get_cmd_window_size()
¶
The size of the command window, in characters, if available.
has_event_type(ty)
¶
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.
history(last=10)
¶
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.
is_gdblib_available()
¶
Whether gdblib is available under this debugger.
lex_args(command_line)
¶
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_frame()
¶
The stack frame currently being focused on in this interactive session.
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.
set_python_diagnostics(enabled)
¶
Enables or disables Python diagnostic messages for this debugger.
set_sysroot(sysroot)
¶
Sets the system root for this debugger.
setup(*args)
¶
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.
string_limit()
¶
The maximum size of a string.
supports_breakpoint_creation_during_stop_handler()
¶
Whether breakpoint or watchpoint creation through break_at
is supported during breakpoint stop handlers.
x86_disassembly_flavor()
¶
The flavor of disassembly to use for x86 targets.
DisassembledInstruction
¶
Error
¶
Bases: Exception
EventType
¶
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 calledobjfile
s.
CONTINUE = 5
class-attribute
instance-attribute
¶
EXIT = 2
class-attribute
instance-attribute
¶
MEMORY_CHANGED = 3
class-attribute
instance-attribute
¶
NEW_MODULE = 6
class-attribute
instance-attribute
¶
REGISTER_CHANGED = 4
class-attribute
instance-attribute
¶
START = 0
class-attribute
instance-attribute
¶
STOP = 1
class-attribute
instance-attribute
¶
Frame
¶
__eq__(rhs)
¶
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.
child()
¶
The child frame of this frame, if it exists.
evaluate_expression(expression, lock_scheduler=False)
¶
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.
parent()
¶
The parent frame of this frame, if it exists.
pc()
¶
The value of the program counter for this frame.
reg_write(name, val)
¶
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.
regs()
¶
Access the values of the registers in this frame.
sal()
¶
The filename of the source code file associated with this frame, and the line number associated with it, if available.
sp()
¶
The value of the stack pointer for this frame.
MemoryMap
¶
Process
¶
alive()
¶
Returns whether this process is alive.
arch()
¶
The default architecture of this process.
break_at(location, stop_handler=None, one_shot=False, internal=False)
¶
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.
Breakpoints and watchpoints marked as one_shot
are removed after they are first triggered. For the purposes of one_shot
, a breakpoint or watchpoint that has a stop handler is only considered to be triggered when its stop handler returns True
.
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.
create_value(value, type=None)
¶
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.
disasm(address)
¶
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.
download_remote_file(remote_path, local_path)
¶
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.
evaluate_expression(expression)
¶
Evaluate the given expression in the context of the current process, and return a Value
.
find_in_memory(pattern, start, size, align, max_matches=-1, step=-1)
¶
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.
is_dynamically_linked()
¶
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.
is_linux()
¶
Returns whether the current ABI is GNU/Linux.
is_remote()
¶
Returns whether this process is a remote process connected to using the GDB remote debugging protocol.
main_module_entry()
¶
Returns the entry point of the main module.
main_module_name()
¶
Returns the name of the main module.
On remote targets, this may be prefixed with "target:" string.
module_section_locations()
¶
Return a list of (address, size, section_name, module_name) tuples for the loaded sections in every module of this process.
pid()
¶
Returns the process ID of this process if it is alive.
read_memory(address, size, partial=False)
¶
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.
send_monitor(cmd)
¶
Sends the given monitor command to the GDB remote debugging protocol server. Should only be called if is_remote()
is true.
send_remote(packet)
¶
Sends the given packet to the GDB remote debugging protocol server. Should only be called if is_remote()
is true.
symbol_address_from_name(name, prefer_static=False)
¶
Returns the address of a symbol, given its name. Optionally, the user may specify that they want to prioritize symbols in the static block, if supported by the debugger.
symbol_name_at_address(address)
¶
Returns the name of the symbol at the given address in the program, if one exists.
threads()
¶
Returns a list containing the threads in this process.
types_with_name(name)
¶
Returns a list of all types in this process that match the given name.
vmmap()
¶
Returns the virtual memory map of this process.
write_memory(address, data, partial=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.
Registers
¶
A handle to the register values in a frame.
by_name(name)
¶
Gets the value of a register if it exists, None otherwise.
StopPoint
¶
Thread
¶
Type
¶
Class representing a type in the context of an inferior process.
alignof: int
property
¶
The alignment of this type, in bytes.
code: TypeCode
property
¶
What category of type this object belongs to.
sizeof: int
property
¶
The size of this type, in bytes.
array(count)
¶
Return a type that corresponds to an array whose elements have this type.
fields()
¶
List of all fields in this type, if it is a structured type.
has_field(name)
¶
Whether this type has a field with the given name.
keys()
¶
Returns a list containing all the field names of 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, if this is a typedef. Returns the type itself otherwise.
target()
¶
Return the target of this reference type, if this is a reference type.
TypeCode
¶
Bases: Enum
Broad categories of types.
ARRAY = 2
class-attribute
instance-attribute
¶
ENUM = 7
class-attribute
instance-attribute
¶
INT = 6
class-attribute
instance-attribute
¶
POINTER = 1
class-attribute
instance-attribute
¶
STRUCT = 3
class-attribute
instance-attribute
¶
TYPEDEF = 4
class-attribute
instance-attribute
¶
UNION = 5
class-attribute
instance-attribute
¶
TypeField
¶
The fields in a structured type.
Currently this is just a mirror of gdb.Field
.
artificial = artificial
instance-attribute
¶
bitpos = bitpos
instance-attribute
¶
bitsize = bitsize
instance-attribute
¶
enumval = enumval
instance-attribute
¶
is_base_class = is_base_class
instance-attribute
¶
name = name
instance-attribute
¶
parent_type = parent_type
instance-attribute
¶
type = type
instance-attribute
¶
__init__(bitpos, name, type, parent_type, enumval=None, artificial=False, is_base_class=False, bitsize=0)
¶
Value
¶
Class representing a value in the context of an inferior process.
address: Value | None
property
¶
The address of this value, in memory, if addressable, otherwise None
.
is_optimized_out: bool
property
¶
Whether this value is present in debugging information, but has been optimized out of the actual program.
type: Type
property
¶
The type associated with this value.
__add__(rhs)
¶
Adds an integer to this value, if that makes sense. Throws an exception otherwise.
__getitem__(idx)
¶
Gets the value with the given name that belongs to this value. For structure types, this is the field with the given name. For array types, this is the field at the given index. For pointer types, this is the value of *(ptr+idx)
.
__int__()
¶
Converts this value to an integer, if possible.
__repr__()
¶
__str__()
¶
__sub__(rhs)
¶
Subtract an integer from this value, if that makes sense. Throws an exception otherwise.
cast(type)
¶
Returns a new value with the same value as this object, but of the given type.
dereference()
¶
If this is a poitner value, dereferences the pointer and returns a new instance of Value, containing the value pointed to by this pointer.
fetch_lazy()
¶
Fetches the value if it is lazy, does nothing otherwise.
string()
¶
If this value is a string, then this method converts it to a Python string.
WatchpointLocation
¶
selection(target, get_current, select)
¶
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.