drgn/docs/advanced_usage.rst
Omar Sandoval 78192cd61e libdrgn: add environment variable to see more missing debug info errors
Sometimes, I'd like to see all of the missing debug info errors rather
than just the first 5. Allow setting this through the
DRGN_MAX_DEBUG_INFO_ERRORS environment variable.
2019-10-02 17:22:12 -07:00

97 lines
3.1 KiB
ReStructuredText

Advanced Usage
==============
.. highlight:: pycon
The :doc:`user_guide` covers basic usage of drgn, but drgn also supports more
advanced use cases which are covered here.
Loading Debugging Symbols
-------------------------
drgn will automatically load debugging information based on the debugged
program (e.g., from loaded kernel modules or loaded shared libraries).
:meth:`drgn.Program.load_debug_info()` can be used to load additional debugging
information::
>>> prog.load_debug_info(['./libfoo.so', '/usr/lib/libbar.so'])
Library
-------
In addition to the CLI, drgn is also available as a library.
:func:`drgn.program_from_core_dump()`, :func:`drgn.program_from_kernel()`, and
:func:`drgn.program_from_pid()` correspond to the ``-c``, ``-k``, and ``-p``
command line options, respectively; they return a :class:`drgn.Program` that
can be used just like the one initialized by the CLI::
>>> import drgn
>>> prog = drgn.program_from_kernel()
C Library
---------
The core functionality of drgn is implemented in C and is available as a C
library, ``libdrgn``. See |drgn.h|_.
.. |drgn.h| replace:: ``drgn.h``
.. _drgn.h: https://github.com/osandov/drgn/blob/master/libdrgn/drgn.h
Full documentation can be generated by running ``doxygen`` in the ``libdrgn``
directory of the source code. Note that the API and ABI are not yet stable.
Custom Programs
---------------
The main components of a :class:`drgn.Program` are the program memory, types,
and symbols. The CLI and equivalent library interfaces automatically determine
these. However, it is also possible to create a "blank" ``Program`` and plug in
the main components.
:meth:`drgn.Program.add_memory_segment()` defines a range of memory and how to
read that memory. The following example uses a Btrfs filesystem image as the
program "memory":
.. code-block:: python3
import drgn
import os
def btrfs_debugger(dev):
file = open(dev, 'rb')
size = file.seek(0, 2)
def read_file(address, count, physical, offset):
file.seek(offset)
return file.read(count)
platform = drgn.Platform(drgn.Architecture.UNKNOWN,
drgn.PlatformFlags.IS_LITTLE_ENDIAN)
prog = drgn.Program(platform)
prog.add_memory_segment(0, None, size, read_file)
prog.load_debug_info([f'/lib/modules/{os.uname().release}/kernel/fs/btrfs/btrfs.ko'])
return prog
prog = btrfs_debugger('/dev/sda')
print(drgn.Object(prog, 'struct btrfs_super_block', address=65536))
:meth:`drgn.Program.add_type_finder()` and
:meth:`drgn.Program.add_symbol_finder()` are the equivalent methods for
plugging in types and symbols.
Environment Variables
---------------------
Some of drgn's behavior can be modified through environment variables:
``DRGN_MAX_DEBUG_INFO_ERRORS``
The maximum number of individual errors to report in a
:exc:`drgn.MissingDebugInfoError`. Any additional errors are truncated. The
default is 5; -1 is unlimited.
``DRGN_USE_LIBKDUMPFILE_FOR_ELF``
Whether drgn should use libkdumpfile for ELF vmcores (0 or 1). The default
is 1 if drgn was built with libkdumpfile support.