pygdbmi

Warnings

• breaking The `GdbController` class API changed significantly in version 0.10.0.0. The constructor now expects `command: Optional[List[str]]` and `time_to_check_for_additional_output_sec: Optional[int]]`. Several methods like `GdbController.verify_valid_gdb_subprocess()` were removed, and the `NoGdbProcessError` exception was also removed.
  Fix: Review your `GdbController` instantiation and method calls. Update to the new constructor signature and remove calls to deprecated methods and exception handling for `NoGdbProcessError`. For Python 3.5, upgrade your Python version as support was dropped.
• breaking Support for Python 3.5 was dropped in `pygdbmi` v0.10.0.0, and support for Python 3.6 was dropped in v0.10.0.2.
  Fix: Ensure your project is running on Python 3.7 or newer to use `pygdbmi` versions 0.10.0.2 and above. Python 3.9 and 3.10 are explicitly supported from v0.10.0.2.
• breaking The `pygdbmi.IoManager.make_non_blocking` function was removed from the public API in version 0.11.0.0 as it was considered an internal utility not meant for public consumption.
  Fix: Remove any direct calls to `pygdbmi.IoManager.make_non_blocking` from your code. This function was an internal detail and should not have been used directly.
• gotcha When using GDB versions 8.1 and newer, the output from the `run` command might be split into multiple parts. This can cause `pygdbmi` to only catch the initial part, leading to `GdbTimeOutError` if subsequent calls to `get_gdb_response()` are not handled correctly to fetch all parts of the response.
  Fix: Be aware of GDB's output behavior with newer versions. If encountering timeouts after a `run` command, you may need to adjust `time_to_check_for_additional_output_sec` in `GdbController` or implement more robust polling for `get_gdb_response()` to ensure all output is consumed.
• gotcha To ensure GDB outputs machine-readable interface (MI) format, it must be launched with the `--interpreter=mi2` flag. If this flag is omitted, `pygdbmi` will receive standard console output which it cannot reliably parse into structured data.
  Fix: Always pass `--interpreter=mi2` as part of the GDB command list when initializing `GdbController`, e.g., `GdbController(command=['gdb', '--interpreter=mi2'])`.

Install

• pip install pygdbmi

Imports

• GdbController

  from pygdbmi.gdbcontroller import GdbController

• parse_response

  from pygdbmi.gdbmiparser import parse_response

• NoGdbProcessError

  Removed in v0.10.0.0

  `NoGdbProcessError` was removed as part of the `GdbController` API changes in v0.10.0.0. Handlers for GDB process issues should now rely on `subprocess.CalledProcessError` or similar standard Python exceptions for subprocess management.

Quickstart

This quickstart demonstrates how to use `GdbController` to interact with a GDB subprocess programmatically, including loading a binary, setting a breakpoint, running, and continuing execution. It also shows how to directly parse a raw GDB MI output string using `gdbmiparser.parse_response`. A simple C program is compiled and used as the debug target for the demonstration.

from pygdbmi.gdbcontroller import GdbController
from pprint import pprint
import os
import subprocess
import shutil

# NOTE: This example assumes 'make' and 'gdb' are available in your PATH.
# Create a dummy C program for debugging
if not os.path.exists('sample_app'):
    os.makedirs('sample_app')
with open('sample_app/main.c', 'w') as f:
    f.write('int main() { int x = 1; x++; return 0; }')

if shutil.which('gcc') and shutil.which('make'):
    subprocess.run(['gcc', 'main.c', '-o', 'pygdbmiapp', '-g'], cwd='sample_app', check=True)
    binary_path = os.path.abspath('sample_app/pygdbmiapp')
else:
    print("Warning: 'gcc' or 'make' not found. Quickstart will only demonstrate parsing.")
    binary_path = None

gdbmi = GdbController()

try:
    if binary_path:
        print(f"\nDebugging: {binary_path}")
        # Load the binary
        responses = gdbmi.write(f"-file-exec-and-symbols {binary_path}")
        print("Load binary response:")
        pprint(responses)

        # Set a breakpoint at main
        responses = gdbmi.write("-break-insert main")
        print("Breakpoint response:")
        pprint(responses)

        # Run the program
        responses = gdbmi.write("-exec-run")
        print("Run response:")
        pprint(responses)

        # Continue to finish
        responses = gdbmi.write("-exec-continue")
        print("Continue response:")
        pprint(responses)

    # Example of parsing raw MI output
    print("\nParsing raw GDB MI output:")
    raw_mi_output = '^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x08048564",func="main",file="myprog.c",fullname="/home/myprog.c",line="68",thread-groups=["i1"],times="0"}'
    parsed_response = gdbmi.gdbmiparser.parse_response(raw_mi_output)
    pprint(parsed_response)

finally:
    # Ensure gdb process is terminated
    gdbmi.exit()
    print("\nGDB process exited.")
    # Clean up dummy app
    shutil.rmtree('sample_app', ignore_errors=True)