pygdb2 0.1

Control GDB from within the Python program being debugged

pygdb2 is a python module which allows you to send commands to the underlying gdb process. For example, it can be used to automatically and programmatically add breakpoints and watchpoints.

How to install

Make sure that pygdb2 is installed:

$ pip install pygdb2

Then, you need to activate the GDB integration by putting this line inside your ~/.gdbinit:

python import pygdb2

How to use it

You need to launch your python program inside gdb using the special pyrun command:

$ gdb --args python myscript.py
...
(gdb) pyrun
...

From the python program, you can use pygdb2.set_trace() to enter the gdb prompt, or pygdb2.execute() to send commands to gdb.

At the (gdb) prompt, it is possible to invoke the pdb command to enter in the corresponding debugger at the Python level.

Example

For example, the following code adds a watchpoint for a particular region of memory created with ctypes:

import ctypes
import pygdb2

def main():
    buf = ctypes.c_int()
    buf.value = 42
    adr = ctypes.cast(ctypes.pointer(buf), ctypes.c_void_p)
    # enter gdb when we write to this memory
    pygdb2.execute("watch *(int*)%d" % adr.value)

    i = 0
    while i < 5:
        print i
        i += 1
        if i == 2:
            buf.value = 43 # GDB stops here

Here is an example of a gdb/pdb session:

$ gdb --args python set_watchpoint.py
...
(gdb) # lines prefixed "pygdb2:" contain the command coming from pygdb2.execute()
(gdb) pyrun
...
pygdb2: watch *(int*)14079984
Hardware watchpoint 1: *(int*)14079984
0
1
Hardware watchpoint 1: *(int*)14079984

Old value = 42
New value = 43
i_set (ptr=0xd6d7f0, value=<value optimized out>, size=4) at /build/buildd/python2.7-2.7.1/Modules/_ctypes/cfield.c:663
663 /build/buildd/python2.7-2.7.1/Modules/_ctypes/cfield.c: No such file or directory.
    in /build/buildd/python2.7-2.7.1/Modules/_ctypes/cfield.c

(gdb) # now we are debugging at the C level
(gdb) # in particular, we are inside function of _ctypes
(gdb) # which sets the value of the buffer

(gdb) # Let's jump to the Python level
(gdb) pdb
Signal received, entering pdb
Traceback:
  File "set_watchpoint.py", line 20, in <module>
    main()
  File "set_watchpoint.py", line 16, in main
    buf.value = 43 # we should enter gdb here
> /home/antocuni/env/src/pygdb2/pygdb2/test/set_watchpoint.py(12)main()
-> while i < 5:
(Pdb++) print i
2
(Pdb++) c
2
3
4

Program exited normally.
(gdb) q

Using signals

pygdb2 uses both SIGUSR1 and SIGUSR2 to communicate with gdb, so if your program also needs those, you might have conflicts.