drgn
====

Synopsis
--------

| **drgn** [*OPTION*...]
| **drgn** [*OPTION*...] *SCRIPT* [*ARGUMENT*...]
| **drgn** [*OPTION*...] **-e** *CODE* [*ARGUMENT*...]

Description
-----------

:command:`drgn` (pronounced "dragon") is a debugger with an emphasis on
programmability. It provides APIs for using the types, variables, and stack
traces in a program or core dump from Python, allowing for easy, expressive
scripting and more complex debugging.

Full documentation is available online at https://drgn.readthedocs.io/.

For in-program documentation, try ``help(drgn)``.

Options
-------

.. program:: drgn

If no positional arguments are given (and :option:`-e` is not given), then drgn
runs in *interactive mode*: commands are read from the terminal. Relevant
helpers are automatically imported. An empty string is prepended to
:py:data:`sys.path`.

If positional arguments are given (and :option:`-e` is not given), then drgn
runs in *script mode*: *SCRIPT* is executed with the given *ARGUMENT*\ s.
Nothing is imported automatically. :py:data:`sys.argv[0] <sys.argv>` is set to
*SCRIPT* and the remaining arguments are added to :py:data:`sys.argv`. The
parent directory of *SCRIPT* is prepended to :py:data:`sys.path`.

.. option:: -e {CODE}

    Evaluate the given code and exit. Relevant helpers are automatically
    imported. :py:data:`sys.argv[0] <sys.argv>` is set to *-e* and the
    remaining arguments are added to :py:data:`sys.argv`. An empty string is
    prepended to :py:data:`sys.path`.

Program Selection
^^^^^^^^^^^^^^^^^

One of these options may be given to specify what program to debug.

.. option:: -k, --kernel

    Debug the running kernel. This is the default.

.. option:: -c, --core {PATH}

    Debug the given core dump.

.. option:: -p, --pid {PID}

    Debug the running process with the given process ID.

.. option:: --qemu {ADDRESS}

   Debug a QEMU guest over the QEMU Machine Protocol (QMP) at the given
   address, which may be a Unix domain socket path or a TCP address as
   ``host:port``.

Debugging Symbols
^^^^^^^^^^^^^^^^^

.. option:: -s, --symbols {PATH}

    Load debugging symbols from the given file. If the file does not correspond
    to a loaded executable, library, or module, then a warning is printed and
    it is ignored; see :option:`--extra-symbols` for an alternative.

    This option may be given more than once.

.. option:: --main-symbols

    Only load debugging symbols for the main executable and those added with
    :option:`-s` or :option:`--extra-symbols`.

.. option:: --no-default-symbols

    Don't load any debugging symbols that were not explicitly added with
    :option:`-s` or :option:`--extra-symbols`.

.. option:: --extra-symbols {PATH}

    Load additional debugging symbols from the given file, which is assumed not
    to correspond to a loaded executable, library, or module.

    This option may be given more than once.

The following options correspond to :py:attr:`drgn.Program.debug_info_options`
in the Python API.

.. option:: --try-symbols-by {METHOD[,METHOD...]}

    Enable loading debugging symbols using the given methods. *METHOD* may be:

    * The name of a debugging information finder (``standard``, ``debuginfod``,
      or any added by plugins).
    * ``module-name``: if the name of a module looks like a filesystem path, try the
      file at that path.
    * ``build-id``: search by build ID.
    * ``debug-link``: search by debug link (e.g., ``.gnu_debuglink``).
    * ``procfs``: try :file:`/proc/{pid}/exe` or :file:`/proc/{pid}/map_files`.
    * ``embedded-vdso``: try vDSO data saved in a core dump.
    * ``reuse``: try reusing a previously used file.
    * ``supplementary``: try finding supplementary files (e.g.,
      ``.gnu_debugaltlink``).
    * ``kmod=depmod``: search using *depmod* metadata.
    * ``kmod=walk``: search by walking kernel directories.
    * ``kmod=depmod-or-walk``: search using *depmod* metadata if it is
      available or by walking kernel directories if *depmod* metadata does not
      exist.
    * ``kmod=depmod-and-walk``: search using *depmod* metadata if it is
      available, then by walking kernel directories if *depmod* metadata does
      not exist or does not contain the desired module.

    Multiple methods may be enabled by passing a comma-separated list. This
    option may be given more than once, in which case the lists will be
    combined.

.. option:: --no-symbols-by {METHOD[,METHOD...]}

    Disable loading debugging symbols using the given methods. *METHOD* may be
    the name of a debugging information finder, ``module-name``, ``build-id``,
    ``debug-link``, ``procfs``, ``embedded-vdso``, ``reuse``,
    ``supplementary``, or ``kmod``.

    Multiple methods may be disabled by passing a comma-separated list. This
    option may be given more than once, in which case the lists will be
    combined.

Debugging Symbol Directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These options correspond to :attr:`drgn.DebugInfoOptions.directories` in the
Python API.

.. option:: --debug-directory {PATH}

    Search for debugging symbols in the given directory.

    By default, these directories are used for searches by build ID, debug
    link, for supplementary files, and for kernel files.

    This option may be given more than once to search in multiple directories.

.. option:: --no-default-debug-directories

    Don't search for debugging symbols in the standard directories or those
    added by plugins.

These options correspond to
:attr:`drgn.DebugInfoOptions.debug_link_directories` in the Python API.

.. option:: --debug-link-directory {PATH}

    Search for debugging symbols by debug link in the given directory.

    ``$ORIGIN`` (or ``${ORIGIN}``) is replaced with the absolute path of the
    directory containing the loaded file.

    This option may be given more than once to search in multiple directories.

.. option:: --no-default-debug-link-directories

    Don't search for debugging symbols by debug link in the standard
    directories or those added by plugins.

These options correspond to :attr:`drgn.DebugInfoOptions.kernel_directories` in
the Python API.

.. option:: --kernel-directory {PATH}

    Search for the kernel image and loadable kernel modules in the given
    directory.

    This option may be given more than once to search in multiple directories.

.. option:: --no-default-kernel-directories

    Don't search for the kernel image and loadable kernel modules in the
    standard directories or those added by plugins.

Logging
^^^^^^^

.. option:: --log-level {\{debug,info,warning,error,critical,none\}}

    Log messages of at least the given level to standard error. The default is
    *warning*.

.. option:: -q, --quiet

    Don't print any logs or download progress. This is equivalent to
    :option:`--log-level none <--log-level>`.

Generic Information
^^^^^^^^^^^^^^^^^^^

.. option:: -h, --help

    Show a help message and exit.

.. option:: --version

    Show :command:`drgn`'s version information and exit.
