/README

  1.. -*- restructuredtext -*-
  2
  3pygdb2: control GDB from within the Python program being debugged
  4==================================================================
  5
  6``pygdb2`` is a python module which allows you to send commands to the
  7underlying ``gdb`` process.  For example, it can be used to automatically and
  8programmatically add breakpoints and watchpoints.
  9
 10How to install
 11--------------
 12
 13Make sure that ``pygdb2`` is installed::
 14
 15    $ pip install pygdb2
 16
 17Then, you need to activate the GDB integration by putting this line inside
 18your ``~/.gdbinit``::
 19
 20    python import pygdb2
 21
 22
 23How to use it
 24--------------
 25
 26You need to launch your python program inside ``gdb`` using the special
 27``pyrun`` command::
 28
 29    $ gdb --args python myscript.py
 30    ...
 31    (gdb) pyrun
 32    ...
 33
 34From the python program, you can use ``pygdb2.set_trace()`` to enter the ``gdb``
 35prompt, or ``pygdb2.execute()`` to send commands to ``gdb``.
 36
 37At the ``(gdb)`` prompt, it is possible to invoke the ``pdb`` command to enter
 38in the corresponding debugger at the Python level.
 39
 40
 41Example
 42-------
 43
 44For example, the following code adds a watchpoint for a particular
 45region of memory created with ``ctypes``::
 46
 47    import ctypes
 48    import pygdb2
 49
 50    def main():
 51        buf = ctypes.c_int()
 52        buf.value = 42
 53        adr = ctypes.cast(ctypes.pointer(buf), ctypes.c_void_p)
 54        # enter gdb when we write to this memory
 55        pygdb2.execute("watch *(int*)%d" % adr.value)
 56
 57        i = 0
 58        while i < 5:
 59            print i
 60            i += 1
 61            if i == 2:
 62                buf.value = 43 # GDB stops here
 63
 64Here is an example of a gdb/pdb session::
 65
 66    $ gdb --args python set_watchpoint.py
 67    ...
 68    (gdb) # lines prefixed "pygdb2:" contain the command coming from pygdb2.execute()
 69    (gdb) pyrun
 70    ...
 71    pygdb2: watch *(int*)14079984
 72    Hardware watchpoint 1: *(int*)14079984
 73    0
 74    1
 75    Hardware watchpoint 1: *(int*)14079984
 76
 77    Old value = 42
 78    New value = 43
 79    i_set (ptr=0xd6d7f0, value=<value optimized out>, size=4) at /build/buildd/python2.7-2.7.1/Modules/_ctypes/cfield.c:663
 80    663	/build/buildd/python2.7-2.7.1/Modules/_ctypes/cfield.c: No such file or directory.
 81        in /build/buildd/python2.7-2.7.1/Modules/_ctypes/cfield.c
 82
 83    (gdb) # now we are debugging at the C level
 84    (gdb) # in particular, we are inside function of _ctypes
 85    (gdb) # which sets the value of the buffer
 86
 87    (gdb) # Let's jump to the Python level
 88    (gdb) pdb
 89    Signal received, entering pdb
 90    Traceback:
 91      File "set_watchpoint.py", line 20, in <module>
 92        main()
 93      File "set_watchpoint.py", line 16, in main
 94        buf.value = 43 # we should enter gdb here
 95    > /home/antocuni/env/src/pygdb2/pygdb2/test/set_watchpoint.py(12)main()
 96    -> while i < 5:
 97    (Pdb++) print i
 98    2
 99    (Pdb++) c
100    2
101    3
102    4
103
104    Program exited normally.
105    (gdb) q
106
107
108
109Using signals
110-----------------
111
112``pygdb2`` uses both ``SIGUSR1`` and ``SIGUSR2`` to communicate with ``gdb``,
113so if your program also needs those, you might have conflicts.
114