Metadata-Version: 1.0
Name: pygdb2
Version: 0.1
Summary: Control GDB from within the Python program being debugged
Home-page: https://bitbucket.org/antocuni/pygdb2/
Author: Antonio Cuni
Author-email: anto.cuni@gmail.com
License: BSD
Description: .. -*- restructuredtext -*-
        
        pygdb2: 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.
        
        
Platform: unix
Platform: linux
