Parse gdb machine interface output with Python
Project description
pygdbmi - Get Structured Output from GDB's Machine Interface
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.
What's in the box?
- A function to parse gdb machine interface string output and return structured data types (Python dicts) that are JSON serializable. Useful for writing the backend to a gdb frontend. For example, gdbgui uses pygdbmi on the backend.
- A Python class to control and interact with gdb as a subprocess
To get machine interface output from gdb, run gdb with the --interpreter=mi2
flag like so:
gdb --interpreter=mi2
Installation
pip install pygdbmi
Compatibility
Operating Systems
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 versions
- gdb 7.6+ has been tested. Older versions may work as well.
Examples
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)
pprint(response)
# Prints:
# {'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'}},
# 'token': None,
# 'type': 'result'}
Programmatic Control Over gdb
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.command) # print actual command run as subprocess
# Load binary a.out and get structured response
response = gdbmi.write('-file-exec-file a.out')
pprint(response)
# Prints:
# [{'message': 'thread-group-added',
# 'payload': {'id': 'i1'},
# 'stream': 'stdout',
# 'token': None,
# 'type': 'notify'},
# {'message': 'done',
# 'payload': None,
# 'stream': 'stdout',
# 'token': 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()
Parsed Output Format
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 isNone
.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 beNone
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 typesnofity
andresult
. When missing, this isNone
.
The type
is defined based on gdb's various mi output record types, and can be
result
- the result of a gdb command, such asdone
,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 output
Contributing
Documentation 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
Positional arguments passed to nox -s tests
are passed directly to pytest
. For instance, to run only the parse tests use
nox -s tests -- tests/test_gdbmiparser.py
See pytest
's documentation for more details on how to run tests.
To format code using the correct settings use
nox -s format
Or, to format only specified files, use
nox -s format -- example.py pygdbmi/IoManager.py
Making a release
Only maintainers of the pygdbmi package on PyPi can make a release.
In the following steps, replace these strings with the correct values:
<REMOTE>
is the name of the remote for the main pygdbmi repository (for instance,origin
)<VERSION>
is the version number chosen in step 2.
To make a release:
-
Checkout the
master
branch and pull from the main repository withgit pull <REMOTE> master
-
Decide the version number for the new release; we follow Semantic Versioning but prefixing the version with
0.
: given a version number 0.SECOND.THIRD.FOURTH, increment the:- SECOND component when you make incompatible API changes
- THIRD component when you add functionality in a backwards compatible manner
- FOURTH component when you make backwards compatible bug fixes
-
Update
CHANGELOG.md
to list the chosen version number instead of## dev
-
Update
__version__
inpygdbmi/__init__.py
to the chosen version number -
Create a branch, for instance using
git checkout -b before-release-<VERSION>
-
Commit your changes, for instance using
git commit -a -m 'Bump version to <VERSION> for release'
-
Check that the docs look fine by serving them locally with
nox -s serve_docs
-
Push the branch, for instance with
git push --set-upstream <REMOTE> before-release-<VERSION>
-
If tests pass on the PR you created, you can merge into
master
-
Go to the new release page and prepare the release:
- Add a tag in the form
v<VERSION>
(for examplev0.1.2.3
) - Set the title to
pygdbmi v<VERSION>
(for examplepygdbmi v0.1.2.3
) - Copy and paste the section for the new release only from
CHANGELOG.md
excluding the line with the version number - Press “Publish release”
- Add a tag in the form
-
Publish the release to PyPI with
nox -s publish
-
Publish the docs with
nox -s publish_docs
-
Verify that the PyPi page for pygdbmi looks correct
-
Verify that the published docs look correct
-
Prepare for changes for the next release by adding something like this above the previous entries in
CHANGELOG.md
(where<VERSION+1>
is<VERSION>
with the last digit increaded by 1):## <VERSION+1>.dev0 - *Replace this line with new entries*
-
Create a branch for the changes with
git checkout -b after-release-<VERSION>
-
Commit the change with
git commit -m 'Prepare for work on the next release' CHANGELOG.md
-
Push the branch with
git push --set-upstream <REMOTE> after-release-<VERSION>
-
If tests pass, merge into
master
Similar projects
- tsgdbmi A port of pygdbmi to TypeScript
- danielzfranklin/gdbmi A port of pygdbmi to Rust
Projects Using pygdbmi
- gdbgui implements a browser-based frontend to gdb, using pygdbmi on the backend
- PINCE is a gdb frontend that aims to provide a reverse engineering tool and a reusable library focused on games. It uses pygdbmi to parse gdb/mi based output for some functions
- avatar² is an orchestration framework for reversing and analysing firmware of embedded devices. It utilizes pygdbmi for internal communication to different analysis targets.
- UDB is a proprietary time-travel debugger for C and C++ based on GDB. It uses pygdbmi in its extensive test suite to parse the debugger's output.
- Know of another project? Create a PR and add it here.
Authors
- Chad Smith (main author and creator).
- Marco Barisione (co-maintainer).
- The community. Thanks especially to @mariusmue, @bobthekingofegypt, @mouuff, and @felipesere.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pygdbmi-0.11.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f7cac28e1d558927444c880ed1e65da1a5d8686121a3aac16f42fb84d3ceb60d |
|
MD5 | 0a5498c350a961b95aab4b65ebbf5ed3 |
|
BLAKE2b-256 | c84b71df806f4d260ddf01f9e431f5a6538a4155db3ec84a131d7e087178c591 |