init

Removes this command from the command palette of the debugger.

Adds a command with the given name to the debugger, that invokes the given function every time it is called.

Format the given address value.

List the commands available in this session.

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.

The size of the command window, in characters, if available.

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.

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.

Whether gdblib is available under this debugger.

Lexes the given command line into a list of arguments, according to the conventions of the debugger being used and of the interactive session.

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 stack frame currently being focused on in this interactive session.

The inferior process currently being focused on in this interactive session.

The thread currently being focused on in this interactive session.

Enables or disables Python diagnostic messages for this debugger.

Sets the system root for this debugger.

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 maximum size of a string.

Whether breakpoint or watchpoint creation through break_at is supported during breakpoint stop handlers.

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.

The flavor of disassembly to use for x86 targets.

Continues execution until the given breakpoint or whatchpoint is hit.

Throws CancelledError if a breakpoint or watchpoint is hit that is not the one given in until, the program exits, or if any other unexpected event happens.

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.

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.

The child frame of this frame, if it exists.

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.

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

The parent frame of this frame, if it exists.

The value of the program counter for this frame.

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.

Access the values of the registers in this frame.

The filename of the source code file associated with this frame, and the line number associated with it, if available.

The value of the stack pointer for this frame.

Returns whether this memory map was generated from a QEMU target.

Returns all ranges in this memory map.

Returns whether this process is alive.

The default architecture of this process.

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.

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 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.

Queues up the given execution controller-based coroutine for execution, sometime between the calling of this function and the

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 the given expression in the context of the current process, and return a Value.

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 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.

Returns whether the current ABI is GNU/Linux.

Returns whether this process is a remote process connected to using the GDB remote debugging protocol.

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.

Returns the entry point of the main module.

Returns the name of the main module.

On remote targets, this may be prefixed with "target:" string.

Return a list of (address, size, section_name, module_name) tuples for the loaded sections in every module of this process.

Returns the process ID of this process if it is alive.

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.

Sends the given monitor command to the GDB remote debugging protocol server. Should only be called if is_remote() is true.

Sends the given packet to the GDB remote debugging protocol server. Should only be called if is_remote() is true.

Returns whether this process was stopped by a signal.

Returns the name of the symbol at the given address in the program, if one exists.

Returns a list containing the threads in this process.

Returns a list of all types in this process that match the given name.

Returns the virtual memory map of this process.

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.

Gets the value of a register if it exists, None otherwise.

Removes the breakpoint associated with this handle.

Enables or disables this breakpoint.

Frame at the bottom of the call stack for this thread.

The unique index of this thread from the perspective of the debugger.

The PTID of this thread, if available.

Returns True if types are the same

Return a type that corresponds to an array whose elements have this type.

Retrieve the integer value of an enum member.

It returns: - integer value, when found field - returns None, If the field does not exist

List of all fields in this type, if it is a structured type.

Returns a list of function arguments type.

Returns:

Raises:

Whether this type has a field with the given name.

Returns a list containing all the field names of this type.

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

Return a pointer type that has this type as its pointee.

Return a type that corresponds to the base type after a typedef chain, if this is a typedef. Returns the type itself otherwise.

Return the target of this reference type, if this is a reference type.

Adds an integer to this value, if that makes sense. Throws an exception otherwise.

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).

Converts this value to an integer, if possible.

Subtract an integer from this value, if that makes sense. Throws an exception otherwise.

Returns a new value with the same value as this object, but of the given type.

If this is a poitner value, dereferences the pointer and returns a new instance of Value, containing the value pointed to by this pointer.

Fetches the value if it is lazy, does nothing otherwise.

If this value is a string, then this method converts it to a Python string.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

    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 } }' - LLDB might produce: '(inner_a_node) *$PWNDBG_CREATED_VALUE_0 = { value = 0 inner = { next = 0x0000555555558098 } }' - As such, this function should not be relied upon for parsing or programmatic use.