Documentation https://cs01.github.io/pygdbmi
Source Code https://github.com/cs01/pygdbmi
Python (py) gdb machine interface (mi)
GDB/MI is a line based machine oriented text interface to GDB and is activated by specifying using the --interpreter command line option (see Mode Options). It is specifically intended to support the development of systems which use the debugger as just one small component of a larger system.
To get machine interface output from gdb, run gdb with the --interpreter=mi2
flag like so:
gdb --interpreter=mi2
pip install pygdbmi
Cross platform support for Linux, macOS and Windows
Linux/Unix
Ubuntu 14.04 and 16.04 have been tested to work. Other versions likely work as well.
macOS
Note: the error please check gdb is codesigned - see taskgated(8)
can be fixed by codesigning gdb with these instructions. If the error is not fixed, please create an issue in github.
Windows
Windows 10 has been tested to work with MinGW and cygwin.
gdb mi defines a syntax for its output that is suitable for machine readability and scripting: example output:
-> -break-insert main
<- ^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"}
<- (gdb)
Use pygdbmi.gdbmiparser.parse_response
to turn that string output into a JSON serializable dictionary
from pygdbmi import gdbmiparser
from pprint import pprint
response = gdbmiparser.parse_response('^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"')
pprint(response)
> {'message': 'done',
'payload': {'bkpt': {'addr': '0x08048564',
'disp': 'keep',
'enabled': 'y',
'file': 'myprog.c',
'fullname': '/home/myprog.c',
'func': 'main',
'line': '68',
'number': '1',
'thread-groups': ['i1'],
'times': '0',
'type': 'breakpoint'}},
'type': 'result'}
But how do you get the gdb output into Python in the first place? If you want, pygdbmi
also has a class to control gdb as subprocess. You can write commands, and get structured output back:
from pygdbmi.gdbcontroller import GdbController
from pprint import pprint
# Start gdb process
gdbmi = GdbController()
print(gdbmi.get_subprocess_cmd()) # print actual command run as subprocess
# Load binary a.out and get structured response
response = gdbmi.write('-file-exec-file a.out')
pprint(response)
[{'message': u'thread-group-added',
'payload': {u'id': u'i1'},
'type': 'notify'},
{'message': u'done', 'payload': None, 'type': 'result'}]
Now do whatever you want with gdb. All gdb commands, as well as gdb machine interface commands are acceptable. gdb mi commands give better structured output that is machine readable, rather than gdb console output. mi commands begin with a -
.
response = gdbmi.write('-break-insert main') # machine interface (MI) commands start with a '-'
response = gdbmi.write('break main') # normal gdb commands work too, but the return value is slightly different
response = gdbmi.write('-exec-run')
response = gdbmi.write('run')
response = gdbmi.write('-exec-next', timeout_sec=0.1) # the wait time can be modified from the default of 1 second
response = gdbmi.write('next')
response = gdbmi.write('next', raise_error_on_timeout=False)
response = gdbmi.write('next', raise_error_on_timeout=True, timeout_sec=0.01)
response = gdbmi.write('-exec-continue')
response = gdbmi.send_signal_to_gdb('SIGKILL') # name of signal is okay
response = gdbmi.send_signal_to_gdb(2) # value of signal is okay too
response = gdbmi.interrupt_gdb() # sends SIGINT to gdb
response = gdbmi.write('continue')
response = gdbmi.exit()
Each parsed gdb response consists of a list of dictionaries. Each dictionary has keys message
, payload
, token
, and type
.
message
contains a textual message from gdb, which is not always present. When missing, this is None
.payload
contains the content of gdb's output, which can contain any of the following: dictionary
, list
, string
. This too is not always present, and can be None
depending on the response.token
If an input command was prefixed with a (optional) token then the corresponding output for that command will also be prefixed by that same token. This field is only present for pygdbmi output types nofity
and result
. When missing, this is None
.The type
is defined based on gdb's various mi output record types, and can be
result
- the result of a gdb command, such as done
, running
, error
, etc.notify
- additional async changes that have occurred, such as breakpoint modifiedconsole
- textual responses to cli commandslog
- debugging messages from gdb's internalsoutput
- output from targettarget
- output from remote targetdone
- when gdb has finished its outputDocumentation fixes, bug fixes, performance improvements, and functional improvements are welcome. You may want to create an issue before beginning work to make sure I am interested in merging it to the master branch.
pygdbmi uses nox for automation.
See available tasks with
nox -l
Run tests and lint with
nox -s tests
nox -s lint
pygdbmi
was written by Chad Smith with contributions from the community. Thanks especially to @mariusmue, @bobthekingofegypt, @mouuff, and @felipesere.