mirror of
https://github.com/JakeHillion/drgn.git
synced 2024-12-23 01:33:06 +00:00
Programmable debugger
f41cc7fb48
The helpers implemented in C have Python wrappers only for the purpose of documentation. This is because drgndoc ignores all imports when recursively documenting attributes. However, mypy uses the convention that aliased imports (i.e., import ... as ... or from ... import ... as ...) are considered re-exported, so we can follow that convention and include aliased imports. (mypy also considered attributes in __all__ as re-exported, so we should probably follow that in the future, too, but for now aliased imports are enough). This lets us get rid of the Python wrappers. Signed-off-by: Omar Sandoval <osandov@osandov.com> |
||
---|---|---|
docs | ||
drgn | ||
examples/linux | ||
libdrgn | ||
scripts | ||
tests | ||
tools | ||
vmtest | ||
_drgn.pyi | ||
.editorconfig | ||
.git-blame-ignore-revs | ||
.gitignore | ||
.readthedocs.yml | ||
.travis.yml | ||
CONTRIBUTING.rst | ||
COPYING | ||
MANIFEST.in | ||
README.rst | ||
setup.py | ||
util.py |
drgn ==== .. image:: https://img.shields.io/pypi/v/drgn :target: https://pypi.org/project/drgn/ :alt: PyPI .. image:: https://travis-ci.org/osandov/drgn.svg?branch=master :target: https://travis-ci.org/osandov/drgn :alt: Build Status .. image:: https://readthedocs.org/projects/drgn/badge/?version=latest :target: https://drgn.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black .. start-introduction drgn (pronounced "dragon") is a debugger with an emphasis on programmability. drgn exposes the types and variables in a program for easy, expressive scripting in Python. For example, you can debug the Linux kernel: .. code-block:: pycon >>> from drgn.helpers.linux import list_for_each_entry >>> for mod in list_for_each_entry('struct module', ... prog['modules'].address_of_(), ... 'list'): ... if mod.refcnt.counter > 10: ... print(mod.name) ... (char [56])"snd" (char [56])"evdev" (char [56])"i915" Although other debuggers like `GDB <https://www.gnu.org/software/gdb/>`_ have scripting support, drgn aims to make scripting as natural as possible so that debugging feels like coding. This makes it well-suited for introspecting the complex, inter-connected state in large programs. It is also designed as a library that can be used to build debugging and introspection tools; see the official `tools <https://github.com/osandov/drgn/tree/master/tools>`_. drgn was developed for debugging the Linux kernel (as an alternative to the `crash <http://people.redhat.com/anderson/>`_ utility), but it can also debug userspace programs written in C. C++ support is in progress. .. end-introduction Documentation can be found at `drgn.readthedocs.io <https://drgn.readthedocs.io>`_. Installation ------------ .. start-install-dependencies Install dependencies: Arch Linux: .. code-block:: console $ sudo pacman -S --needed autoconf automake bison bzip2 flex gawk gcc libtool make pkgconf python python-setuptools xz zlib Debian/Ubuntu: .. code-block:: console $ sudo apt-get install autoconf automake bison flex gawk gcc libbz2-dev liblzma-dev libtool make pkgconf python3 python3-dev python3-setuptools zlib1g-dev Note that Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship Python versions which are too old. Python 3.6 or newer must be installed manually. Fedora: .. code-block:: console $ sudo dnf install autoconf automake bison bzip2-devel flex gawk gcc libtool make pkgconf python3 python3-devel python3-setuptools xz-devel zlib-devel Optionally, install: * `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ if you want support for kdump-compressed kernel core dumps .. end-install-dependencies Then, run: .. code-block:: console $ sudo pip3 install drgn See the `installation documentation <https://drgn.readthedocs.io/en/latest/installation.html>`_ for more options. Quick Start ----------- .. start-quick-start drgn debugs the running kernel by default; run ``sudo drgn``. To debug a running program, run ``sudo drgn -p $PID``. To debug a core dump (either a kernel vmcore or a userspace core dump), run ``drgn -c $PATH``. The program must have debugging symbols available. Then, you can access variables in the program with ``prog['name']``, access structure members with ``.``, use various predefined helpers, and more: .. code-block:: pycon $ sudo drgn >>> prog['init_task'].comm (char [16])"swapper/0" >>> d_path(fget(find_task(prog, 1), 0).f_path.address_of_()) b'/dev/null' >>> max(task.stime for task in for_each_task(prog)) (u64)4192109975952 >>> sum(disk.gendisk.part0.nr_sects for disk in for_each_disk(prog)) (sector_t)999705952 .. end-quick-start See the `user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>`_ for more information. License ------- .. start-license Copyright (c) Facebook, Inc. and its affiliates. drgn is licensed under the `GPLv3 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later. .. end-license