Programmable debugger
Go to file
Omar Sandoval e5bc41f16c libdrgn: add latest elf.h and dwarf.h to support elfutils 0.165
The oldest LTS version of Ubuntu, 16.04, has elfutils 0.165. This
version is missing some ELF and DWARF definitions used by drgn. Add
copies of elf.h from glibc 2.33 and dwarf.h and elfutils/known-dwarf.h
from elfutils 0.183 to get the latest definitions and drop the minimum
required version of elfutils further to 0.165.

Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-03-21 23:18:39 -07:00
.github/workflows Remove bundled version of elfutils 2021-03-16 00:52:09 -07:00
docs libdrgn: add latest elf.h and dwarf.h to support elfutils 0.165 2021-03-21 23:18:39 -07:00
drgn Remove unused 'type: ignore' comment for pkgutil.read_code() 2021-01-22 11:27:10 -08:00
examples/linux Format imports with isort 2020-08-20 16:55:07 -07:00
libdrgn libdrgn: add latest elf.h and dwarf.h to support elfutils 0.165 2021-03-21 23:18:39 -07:00
scripts libdrgn: add latest elf.h and dwarf.h to support elfutils 0.165 2021-03-21 23:18:39 -07:00
tests libdrgn: python: identify bit fields in TypeMember.__repr__ 2021-03-17 12:02:53 -07:00
tools Format imports with isort 2020-08-20 16:55:07 -07:00
vmtest vmtest: manage: use str() instead of repr() for Path in error message 2021-02-21 03:08:36 -08:00
_drgn.pyi libdrgn: replace elfutils DWARF unwinder with our own 2021-03-15 16:43:12 -07:00
.editorconfig editorconfig: Update styles for pyi and c files 2020-02-27 09:37:26 -08:00
.git-blame-ignore-revs Add .git-blame-ignore-revs 2020-01-14 12:03:26 -08:00
.gitignore Generate version.py instead of using pkg_resources 2020-10-20 02:40:16 -07:00
.readthedocs.yml Add type hint stubs and generate documentation from them 2020-02-25 13:39:06 -08:00
CONTRIBUTING.rst CONTRIBUTING: add guidelines for good commits 2021-01-12 16:56:54 -08:00
COPYING License under GPL-3.0 or later 2018-04-15 15:03:33 -07:00
MANIFEST.in Add examples and tools to source distribution 2020-04-27 16:53:14 -07:00
pyproject.toml Format imports with isort 2020-08-20 16:55:07 -07:00
README.rst libdrgn: add latest elf.h and dwarf.h to support elfutils 0.165 2021-03-21 23:18:39 -07:00
setup.py Remove bundled version of elfutils 2021-03-16 00:52:09 -07:00
util.py vmtest: use pathlib 2020-10-14 11:37:31 -07:00

drgn
====

.. image:: https://img.shields.io/pypi/v/drgn
    :target: https://pypi.org/project/drgn/
    :alt: PyPI

.. image:: https://github.com/osandov/drgn/workflows/CI/badge.svg
    :target: https://github.com/osandov/drgn/actions
    :alt: CI 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 gawk gcc libelf libtool make pkgconf python python-setuptools

Debian/Ubuntu:

.. code-block:: console

    $ sudo apt-get install autoconf automake gawk gcc libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-setuptools

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 elfutils-devel gawk gcc libtool make pkgconf python3 python3-devel python3-setuptools

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