Programmable debugger
Go to file
Omar Sandoval 129f1493b8 libdrgn: split kernel-specific stuff out of program.c
Almost half of program.c is stuff specific to the Linux kernel, so let's
separate that out (and combine it with the existing kernel module code).
2019-07-08 16:53:58 -07:00
docs libdrgn/python: add Program.cache 2019-06-28 16:15:07 -07:00
drgn helpers: fix for_each_{disk,partition}() on kernels >= v5.1 2019-06-28 16:52:51 -07:00
examples/linux examples: fix fs_inodes.py 2019-04-11 15:11:36 -07:00
libdrgn libdrgn: split kernel-specific stuff out of program.c 2019-07-08 16:53:58 -07:00
scripts libdrgn: expose primitive type concept to public interface 2019-05-06 14:55:34 -07:00
tests libdrgn/python: implement Program.__contains__ 2019-06-28 16:02:52 -07:00
.gitignore Document with Sphinx 2019-04-11 12:48:15 -07:00
.readthedocs.yml Document with Sphinx 2019-04-11 12:48:15 -07:00
.travis.yml Configure Travis CI 2019-04-11 14:17:44 -07:00
COPYING License under GPL-3.0 or later 2018-04-15 15:03:33 -07:00
MANIFEST.in Document with Sphinx 2019-04-11 12:48:15 -07:00
README.rst Clarify that --kernel is the default in a couple more places 2019-06-28 14:05:07 -07:00
setup.py setup.py: improve autotools glue 2019-05-03 10:23:02 -07:00

drgn
====

.. 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

.. start-introduction

drgn (pronounced "dragon") is a debugger-as-a-library. In contrast to existing
debuggers like `GDB <https://www.gnu.org/software/gdb/>`_ which focus on
breakpoint-based debugging, drgn excels in live introspection. 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"

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 planned.

.. end-introduction

Documentation can be found at `drgn.readthedocs.io
<https://drgn.readthedocs.io>`_.

Installation
------------

Install the following dependencies:

* Python 3.6 or newer
* elfutils development libraries (libelf and libdw)
* GNU autotools (autoconf, automake, and libtool) and pkgconf

Then, run:

.. code-block:: console

    $ git clone https://github.com/osandov/drgn.git
    $ cd drgn
    $ python3 setup.py build
    $ sudo python3 setup.py install

See the `installation documentation
<https://drgn.readthedocs.io/en/latest/installation.html>`_ for more details.

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 2018-2019 Omar Sandoval

drgn is licensed under the `GPLv3
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later.

.. end-license