# API Reference

## Programs

class drgn.Program

  A `Program` represents a crashed or running program. It can be used to lookup type definitions, access variables, and read arbitrary memory.

  The main functionality of a `Program` is looking up objects (i.e., variables, constants, or functions). This is usually done with the `[]` operator.

  Program(platform: Optional[Platform] = None, *, vmcoreinfo: Union[bytes, str, None] = None)

    Create a `Program` with no target program. It is usually more convenient to use one of the Program Constructors.

    Parameters:

      - platform – The platform of the program, or `None` if it should be determined automatically when a core dump or symbol file is added.

      - vmcoreinfo – Optionally provide the `VMCOREINFO` note data for Linux kernel core dumps, which will override any detected data. When not provided or `None`, automatically detect the info.

  flags: ProgramFlags

    Flags which apply to this program.

  platform: Optional[Platform]

    Platform that this program runs on, or `None` if it has not been determined yet.

  core_dump_path: Optional[str]

    Path of the core dump that this program was created from, or `None` if it was not created from a core dump.

  language: Language

    Default programming language of the program.

    This is used for interpreting the type name given to `type()` and when creating an `Object` without an explicit type.

    For the Linux kernel, this defaults to `Language.C`. For userspace programs, this defaults to the language of `main` in the program, falling back to `Language.C`. This heuristic may change in the future.

    This can be explicitly set to a different language (e.g., if the heuristic was incorrect).

  __getitem__(name: str) → Object

    Implement `self[name]`. Get the object (variable, constant, or function) with the given name.

    This is equivalent to `prog.object(name)`.

    If there are multiple objects with the same name, one is returned arbitrarily. In this case, the `variable()`, `constant()`, `function()`, or `object()` methods can be used instead.

        >>> prog['jiffies']
        Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)

    Parameters:

      name – Object name.

  __contains__(name: str) → bool

    Implement `name in self`. Return whether an object (variable, constant, or function) with the given name exists in the program.

    Parameters:

      name – Object name.

  variable(name: str, filename: Optional[str] = None) → Object

    Get the variable with the given name.

        >>> prog.variable('jiffies')
        Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)

    This is equivalent to `prog.object(name, FindObjectFlags.VARIABLE, filename)`.

    Parameters:

      - name – The variable name.

      - filename – The source code file that contains the definition. See Filenames.

    Raises:

      ObjectNotFoundError – if no variables with the given name are found in the given file

  constant(name: str, filename: Optional[str] = None) → Object

    Get the constant (e.g., enumeration constant) with the given name.

    Note that support for macro constants is not yet implemented for DWARF files, and most compilers don’t generate macro debugging information by default anyways.

        >>> prog.constant('PIDTYPE_MAX')
        Object(prog, 'enum pid_type', value=4)

    This is equivalent to `prog.object(name, FindObjectFlags.CONSTANT, filename)`.

    Parameters:

      - name – The constant name.

      - filename – The source code file that contains the definition. See Filenames.

    Raises:

      ObjectNotFoundError – if no constants with the given name are found in the given file

  function(name: str, filename: Optional[str] = None) → Object

    Get the function with the given name.

        >>> prog.function('schedule')
        Object(prog, 'void (void)', address=0xffffffff94392370)

    This is equivalent to `prog.object(name, FindObjectFlags.FUNCTION, filename)`.

    Parameters:

      - name – The function name.

      - filename – The source code file that contains the definition. See Filenames.

    Raises:

      ObjectNotFoundError – if no functions with the given name are found in the given file

  object(name: str, flags: FindObjectFlags = FindObjectFlags.ANY, filename: Optional[str] = None) → Object

    Get the object (variable, constant, or function) with the given name.

    When debugging the Linux kernel, this can look up certain special objects documented in Linux Kernel Special Objects, sometimes without any debugging information loaded.

    Parameters:

      - name – The object name.

      - flags – Flags indicating what kind of object to look for.

      - filename – The source code file that contains the definition. See Filenames.

    Raises:

      ObjectNotFoundError – if no objects with the given name are found in the given file

  symbol(address_or_name: Union[IntegerLike, str], /) → Symbol

    Get a symbol containing the given address, or a symbol with the given name.

    If there are multiple symbols containing a given address, then this will attempt to find the closest match.

    If searching by name or if there is a tie, global symbols are preferred over weak symbols, and weak symbols are preferred over other symbols. In other words: if a matching `SymbolBinding.GLOBAL` or `SymbolBinding.UNIQUE` symbol is found, it is returned. Otherwise, if a matching `SymbolBinding.WEAK` symbol is found, it is returned. Otherwise, any matching symbol (e.g., `SymbolBinding.LOCAL`) is returned. If there is still a tie, one is returned arbitrarily. To retrieve all matching symbols, use `symbols()`.

    Parameters:

      address_or_name – Address or name to search for.

    Raises:

      LookupError – if no symbol contains the given address or matches the given name

  symbols(address_or_name: Union[None, IntegerLike, str] = None, /) → List[Symbol]

    Get a list of global and local symbols, optionally matching a name or address.

    If a string argument is given, this returns all symbols matching that name. If an integer-like argument given, this returns a list of all symbols containing that address. If no argument is given, all symbols in the program are returned. In all cases, the symbols are returned in an unspecified order.

    Parameters:

      address_or_name – Address or name to search for.

  stack_trace(thread: Union[Object, IntegerLike]) → StackTrace

    Get the stack trace for the given thread in the program.

    `thread` may be a thread ID (as defined by gettid(2)), in which case this will unwind the stack for the thread with that ID. The ID may be a Python `int` or an integer `Object`

    `thread` may also be a `struct pt_regs` or `struct pt_regs *` object, in which case the initial register values will be fetched from that object.

    Finally, if debugging the Linux kernel, `thread` may be a `struct task_struct *` object, in which case this will unwind the stack for that task. See `drgn.helpers.linux.pid.find_task()`.

    This is implemented for the Linux kernel (both live and core dumps) as well as userspace core dumps; it is not yet implemented for live userspace processes.

    Parameters:

      thread – Thread ID, `struct pt_regs` object, or `struct task_struct *` object.

  stack_trace_from_pcs(pcs: Sequence[IntegerLike]) → StackTrace

    Get a stack trace with the supplied list of program counters.

    Parameters:

      pcs – List of program counters.

  type(name: str, filename: Optional[str] = None) → Type

    Get the type with the given name.

        >>> prog.type('long')
        prog.int_type(name='long', size=8, is_signed=True)

    Parameters:

      - name – The type name.

      - filename – The source code file that contains the definition. See Filenames.

    Raises:

      LookupError – if no types with the given name are found in the given file

  type(type: Type, /) → Type

    Return the given type.

    This is mainly useful so that helpers can use `prog.type()` to get a `Type` regardless of whether they were given a `str` or a `Type`. For example:

        def my_helper(obj: Object, type: Union[str, Type]) -> bool:
            # type may be str or Type.
            type = obj.prog_.type(type)
            # type is now always Type.
            return sizeof(obj) > sizeof(type)

    Parameters:

      type – Type.

    Returns:

      The exact same type.

  threads() → Iterator[Thread]

    Get an iterator over all of the threads in the program.

  thread(tid: IntegerLike) → Thread

    Get the thread with the given thread ID.

    Parameters:

      tid – Thread ID (as defined by gettid(2)).

    Raises:

      LookupError – if no thread has the given thread ID

  main_thread() → Thread

    Get the main thread of the program.

    This is only defined for userspace programs.

    Raises:

      ValueError – if the program is the Linux kernel

  crashed_thread() → Thread

    Get the thread that caused the program to crash.

    For userspace programs, this is the thread that received the fatal signal (e.g., `SIGSEGV` or `SIGQUIT`).

    For the kernel, this is the thread that panicked (either directly or as a result of an oops, `BUG_ON()`, etc.).

    Raises:

      ValueError – if the program is live (i.e., not a core dump)

  read(address: IntegerLike, size: IntegerLike, physical: bool = False) → bytes

    Read size bytes of memory starting at address in the program.

    The address may be virtual (the default) or physical if the program supports it.

        >>> prog.read(0xffffffffbe012b40, 16)
        b'swapper/0\x00\x00\x00\x00\x00\x00\x00'

    Parameters:

      - address – Starting address.

      - size – Number of bytes to read.

      - physical – Whether address is a physical memory address. If `False`, then it is a virtual memory address. Physical memory can usually only be read when the program is an operating system kernel.

    Raises:

      - FaultError – if the address range is invalid or the type of address (physical or virtual) is not supported by the program

      - ValueError – if size is negative

  read_c_string(address: IntegerLike, physical: bool = False, *, max_size: IntegerLike = ...) → bytes

    Read a null-terminated string starting at address in the program.

        >>> prog.read_c_string(0xffffffffbe012b40)
        b'swapper/0'
        >>> prog.read_c_string(0xffffffffbe012b40, max_size=4)
        b'swap'
        >>> prog.read_c_string(0xffffffffbe012b40, max_size=10)
        b'swapper/0'

    Parameters:

      - address – Starting address.

      - physical – Whether address is a physical memory address; see `read()`.

      - max_size – Stop after this many bytes are read, not including the null byte. The default is no limit.

    Raises:

      - FaultError – if an invalid address is accessed before finding a null terminator, or if the type of address (physical or virtual) is not supported by the program

      - ValueError – if max_size is negative

  read_u8(address: IntegerLike, physical: bool = False) → int
  read_u16(address: IntegerLike, physical: bool = False) → int
  read_u32(address: IntegerLike, physical: bool = False) → int
  read_u64(address: IntegerLike, physical: bool = False) → int
  read_word(address: IntegerLike, physical: bool = False) → int

    Read an unsigned integer from the program’s memory in the program’s byte order.

    `read_u8()`, `read_u16()`, `read_u32()`, and `read_u64()` read an 8-, 16-, 32-, or 64-bit unsigned integer, respectively. `read_word()` reads a program word-sized unsigned integer.

    For signed integers, alternate byte order, or other formats, you can use `read()` and `int.from_bytes()` or the `struct` module.

    Parameters:

      - address – Address of the integer.

      - physical – Whether address is a physical memory address; see `read()`.

    Raises:

      FaultError – if the address is invalid; see `read()`

  add_memory_segment(address: IntegerLike, size: IntegerLike, read_fn: Callable[[int, int, int, bool], bytes], physical: bool = False) → None

    Define a region of memory in the program.

    If it overlaps a previously registered segment, the new segment takes precedence.

    Parameters:

      - address – Address of the segment.

      - size – Size of the segment in bytes.

      - physical – Whether to add a physical memory segment. If `False`, then this adds a virtual memory segment.

      - read_fn – Callable to call to read memory from the segment. It is passed the address being read from, the number of bytes to read, the offset in bytes from the beginning of the segment, and whether the address is physical: `(address, count, offset, physical)`. It should return the requested number of bytes as `bytes` or another buffer type.

  register_type_finder(name: str, fn: Callable[[Program, TypeKindSet, str, Optional[str]], Optional[Type]], *, enable_index: Optional[int] = None) → None

    Register a callback for finding types in the program.

    This does not enable the finder unless enable_index is given.

    Parameters:

      - name – Finder name.

      - fn – Callable taking the program, a `TypeKindSet`, name, and filename: `(prog, kinds, name, filename)`. The filename should be matched with `filename_matches()`. This should return a `Type` or `None` if not found.

      - enable_index – Insert the finder into the list of enabled type finders at the given index. If -1 or greater than the number of enabled finders, insert it at the end. If `None` or not given, don’t enable the finder.

    Raises:

      ValueError – if there is already a finder with the given name

  registered_type_finders() → Set[str]

    Return the names of all registered type finders.

  set_enabled_type_finders(names: Sequence[str]) → None

    Set the list of enabled type finders.

    Finders are called in the same order as the list until a type is found.

    Finders that are not in the list are not called.

    Parameters:

      names – Names of finders to enable, in order.

    Raises:

      ValueError – if no finder has a given name or the same name is given more than once

  enabled_type_finders() → List[str]

    Return the names of enabled type finders, in order.

  register_object_finder(name: str, fn: Callable[[Program, str, FindObjectFlags, Optional[str]], Optional[Object]], *, enable_index: Optional[int] = None) → None

    Register a callback for finding objects in the program.

    This does not enable the finder unless enable_index is given.

    Parameters:

      - name – Finder name.

      - fn – Callable taking the program, name, `FindObjectFlags`, and filename: `(prog, name, flags, filename)`. The filename should be matched with `filename_matches()`. This should return an `Object` or `None` if not found.

      - enable_index – Insert the finder into the list of enabled object finders at the given index. If -1 or greater than the number of enabled finders, insert it at the end. If `None` or not given, don’t enable the finder.

    Raises:

      ValueError – if there is already a finder with the given name

  registered_object_finders() → Set[str]

    Return the names of all registered object finders.

  set_enabled_object_finders(names: Sequence[str]) → None

    Set the list of enabled object finders.

    Finders are called in the same order as the list until an object is found.

    Finders that are not in the list are not called.

    Parameters:

      names – Names of finders to enable, in order.

    Raises:

      ValueError – if no finder has a given name or the same name is given more than once

  enabled_object_finders() → List[str]

    Return the names of enabled object finders, in order.

  register_symbol_finder(name: str, fn: Callable[[Program, Optional[str], Optional[int], bool], Sequence[Symbol]], *, enable_index: Optional[int] = None) → None

    Register a callback for finding symbols in the program.

    This does not enable the finder unless enable_index is given.

    The callback should take four arguments: the program, a name, an address, and a boolean flag one. It should return a list of symbols or an empty list if no matches are found.

    If name is not `None`, then only symbols with that name should be returned. If address is not `None`, then only symbols containing that address should be returned. If neither is `None`, then the returned symbols must match both. If both are `None`, then all symbols should be considered matching.

    When the one flag is `False`, the callback should return a list of all matching symbols. When it is `True`, it should return a list with at most one symbol which is the best match.

    Parameters:

      - name – Finder name.

      - fn – Callable taking `(prog, name, address, one)` and returning a sequence of `Symbol`s.

      - enable_index – Insert the finder into the list of enabled finders at the given index. If -1 or greater than the number of enabled finders, insert it at the end. If `None` or not given, don’t enable the finder.

    Raises:

      ValueError – if there is already a finder with the given name

  registered_symbol_finders() → Set[str]

    Return the names of all registered symbol finders.

  set_enabled_symbol_finders(names: Sequence[str]) → None

    Set the list of enabled symbol finders.

    Finders are called in the same order as the list. When the one flag is set, the search will short-circuit after the first finder which returns a result, and subsequent finders will not be called. Otherwise, all callbacks will be called, and all results will be returned.

    Finders that are not in the list are not called.

    Parameters:

      names – Names of finders to enable, in order.

    Raises:

      ValueError – if no finder has a given name or the same name is given more than once

  enabled_symbol_finders() → List[str]

    Return the names of enabled symbol finders, in order.

  add_type_finder(fn: Callable[[TypeKind, str, Optional[str]], Optional[Type]]) → None

    Deprecated method to register and enable a callback for finding types in the program.

    Deprecated since version 0.0.27: Use `register_type_finder()` instead.

    The differences from `register_type_finder()` are:

    1. fn is not passed prog.

    2. fn is passed a `TypeKind` instead of a `TypeKindSet`. If multiple kinds are being searched for, fn will be called multiple times.

    3. A name for the finder is generated from fn.

    4. The finder is always enabled before any existing finders.

  add_object_finder(fn: Callable[[Program, str, FindObjectFlags, Optional[str]], Optional[Object]]) → None

    Deprecated method to register and enable a callback for finding objects in the program.

    Deprecated since version 0.0.27: Use `register_object_finder()` instead.

    The differences from `register_object_finder()` are:

    1. A name for the finder is generated from fn.

    2. The finder is always enabled before any existing finders.

  set_core_dump(path: Union[Path, int]) → None

    Set the program to a core dump.

    This loads the memory segments from the core dump and determines the mapped executable and libraries. It does not load any debugging symbols; see `load_default_debug_info()`.

    Parameters:

      path – Core dump file path or open file descriptor.

  set_kernel() → None

    Set the program to the running operating system kernel.

    This loads the memory of the running kernel and thus requires root privileges. It does not load any debugging symbols; see `load_default_debug_info()`.

  set_pid(pid: int) → None

    Set the program to a running process.

    This loads the memory of the process and determines the mapped executable and libraries. It does not load any debugging symbols; see `load_default_debug_info()`.

    Parameters:

      pid – Process ID.

  modules() → Iterator[Module]

    Get an iterator over all of the created modules in the program.

  loaded_modules() → Iterator[Tuple[Module, bool]]

    Get an iterator over executables, libraries, etc. that are loaded in the program, creating modules to represent them.

    Modules are created lazily as items are consumed.

    This may automatically load some debugging information necessary to enumerate the modules. Other than that, it does not load debugging information.

    See `load_debug_info()` for a higher-level interface that does load debugging information.

    Returns:

      Iterator of module and `True` if it was newly created or `False` if it was previously found.

  create_loaded_modules() → None

    Determine what executables, libraries, etc. are loaded in the program and create modules to represent them.

    This is a shortcut for exhausting a `loaded_modules()` iterator. It is equivalent to:

        for _ in prog.loaded_modules():
            pass

  module(address_or_name: Union[IntegerLike, str], /) → Module

    Find the module containing the given address, or the module with the given name.

    Addresses are matched based on `Module.address_ranges`.

    If there are multiple modules with the given name, one is returned arbitrarily.

    Parameters:

      address_or_name – Address or name to search for.

    Raises:

      LookupError – if no module contains the given address or has the given name

  register_debug_info_finder(name: str, fn: Callable[[Sequence[Module]], None], *, enable_index: Optional[int] = None) → None

    Register a callback for finding debugging information.

    This does not enable the finder unless enable_index is given.

    Parameters:

      - name – Finder name.

      - fn –

        Callable taking a list of `Module`s that want debugging information.

        This should check `Module.wants_loaded_file()` and `Module.wants_debug_file()` and do one of the following for each module:

        - Obtain and/or locate a file wanted by the module and call `Module.try_file()`.

        - Install files for a later finder to use.

        - Set `Module.loaded_file_status` or `Module.debug_file_status` to `ModuleFileStatus.DONT_NEED` if the finder believes that the file is not needed.

        - Ignore it, for example if the finder doesn’t know how to find the wanted files for the module.

      - enable_index – Insert the finder into the list of enabled object finders at the given index. If -1 or greater than the number of enabled finders, insert it at the end. If `None` or not given, don’t enable the finder.

    Raises:

      ValueError – if there is already a finder with the given name

  registered_debug_info_finders() → Set[str]

    Return the names of all registered debugging information finders.

  set_enabled_debug_info_finders(names: Sequence[str]) → None

    Set the list of enabled debugging information finders.

    Finders are called in the same order as the list until all wanted files have been found.

    Finders that are not in the list are not called.

    Parameters:

      names – Names of finders to enable, in order.

    Raises:

      ValueError – if no finder has a given name or the same name is given more than once

  enabled_debug_info_finders() → List[str]

    Return the names of enabled debugging information finders, in order.

  debug_info_options: DebugInfoOptions

    Default options for debugging information searches.

  load_debug_info(paths: Optional[Iterable[Path]] = (), default: bool = False, main: bool = False) → None

    Load debugging information for the given set of files and/or modules.

    This determines what executables, libraries, etc. are loaded in the program (see `loaded_modules()`) and tries to load their debugging information from the given paths.

    Note

    It is much more efficient to load multiple files at once rather than one by one when possible.

    Parameters:

      - paths –

        Paths of binary files to try.

        Files that don’t correspond to any loaded modules are ignored. See `ExtraModule` for a way to provide arbitrary debugging information.

      - default –

        Try to load all debugging information for all loaded modules.

        The files in paths are tried first before falling back to the enabled debugging information finders.

        This implies `main=True`.

      - main –

        Try to load all debugging information for the main module.

        The files in paths are tried first before falling back to the enabled debugging information finders.

    Raises:

      MissingDebugInfoError – if debugging information was not available for some files; other files with debugging information are still loaded

  load_default_debug_info() → None

    Load all debugging information that can automatically be determined from the program.

    This is equivalent to `load_debug_info(default=True)`.

  load_module_debug_info(*modules: Module) → None

    Load debugging information for the given modules using the enabled debugging information finders.

    The files to search for are controlled by `Module.loaded_file_status` and `Module.debug_file_status`.

  find_standard_debug_info(modules: Iterable[Module], options: Optional[DebugInfoOptions] = None) → None

    Load debugging information for the given modules from the standard locations.

    This is equivalent to the `standard` debugging information finder that is registered by default. It is intended for use by other debugging information finders that need a variation of the standard finder (e.g., after installing something or setting specific options).

    Parameters:

      - modules – Modules to load debugging information for.

      - options – Options to use when searching for debugging information. If `None` or not given, this uses `self.debug_info_options`.

  address_size() → int

    Get the size of an address in this program, in bytes.

    Raises:

      ValueError – if the size of an address is not known because `platform` has not been determined yet

  cache: Dict[Any, Any]

    Dictionary for caching program metadata.

    This isn’t used by the `Program` itself. It is intended to be used by helpers to cache metadata about the program. For example, if a helper for a program depends on the program version or an optional feature, the helper can detect it and cache it for subsequent invocations:

        def my_helper(prog):
            try:
                have_foo = prog.cache["have_foo"]
            except KeyError:
                have_foo = detect_foo_feature(prog)
                prog.cache["have_foo"] = have_foo
            if have_foo:
                return prog["foo"]
            else:
                return prog["bar"]

  config: Dict[str, Any]

    Dictionary for configuration options.

    This isn’t used by the `Program` itself. It can be used to store configuration options for commands and helpers.

class drgn.ProgramFlags

  Bases: `enum.Flag`

  `ProgramFlags` are flags that can apply to a `Program` (e.g., about what kind of program it is).

  IS_LINUX_KERNEL

    The program is the Linux kernel.

  IS_LIVE

    The program is currently running (e.g., it is the running operating system kernel or a running process).

  IS_LOCAL

    The program is running on the local machine.

class drgn.FindObjectFlags

  Bases: `enum.Flag`

  `FindObjectFlags` are flags for `Program.object()`. These can be combined to search for multiple kinds of objects at once.

  CONSTANT
  FUNCTION
  VARIABLE
  ANY

class drgn.ObjectNotFoundError(*args: object, name: str)

  Bases: `KeyError`

  > Error raised when an object is not found in a program.

  name: str

    Object name that was not found.

class drgn.DebugInfoOptions

  Options for debugging information searches.

  All of these options can be reassigned.

  DebugInfoOptions(options: Optional[DebugInfoOptions] = None, /, *, directories: Iterable[Path] = ..., try_module_name: bool = ..., try_build_id: bool = ..., try_debug_link: bool = ..., try_procfs: bool = ..., try_embedded_vdso: bool = ..., try_reuse: bool = ..., try_supplementary: bool = ..., kernel_directories: Iterable[Path] = ..., try_kmod: KmodSearchMethod = ...)

    Create a `DebugInfoOptions`.

    Parameters:

      options – If given, create a copy of the given options. Otherwise, use the default options.

    Any remaining arguments override the copied/default options.

  directories: Tuple[str, ...]

    Directories to search for debugging information files.

    Defaults to `("/usr/lib/debug",)`, which should work out of the box on most Linux distributions. Empty strings are not allowed.

    By default, this is used for searches by build ID (see `try_build_id`), debug link (see `debug_link_directories`), for supplementary files (see `try_supplementary`), and for kernel files (see `kernel_directories`).

  try_module_name: bool

    If the name of a module resembles a filesystem path, try the file at that path.

    Defaults to `True`.

  try_build_id: bool

    Try finding files using build IDs.

    Defaults to `True`.

    A build ID is a unique byte string present in a module’s loaded file and debug file. If configured correctly, it is also present in core dumps and provides a reliable way to identify the correct files for a module.

    Searches by build ID check under each path in `directories` for a file named `.build-id/xx/yyyy` (for loaded files) or `.build-id/xx/yyyy.debug` (for debug files), where `xxyyyy` is the lowercase hexadecimal representation of the build ID.

  debug_link_directories: Tuple[str, ...]

    Directories to search for debug links.

    Defaults to `("$ORIGIN", "$ORIGIN/.debug", "")`, which should work out of the box on most Linux distributions.

    `$ORIGIN` (or `${ORIGIN}`) is replaced with the absolute path of the directory containing the loaded file. An empty string means to check under each path in `directories` (i.e., `path$ORIGIN` for each path in `directories`).

    See `try_debug_link`.

  try_debug_link: bool

    Try finding files using debug links.

    Defaults to `True`.

    A debug link is a pointer in a module’s loaded file to its debug file. It consists of a name and a checksum.

    Searches by debug link check every path in `debug_link_directories` for a file with a matching name and checksum.

  try_procfs: bool

    For local processes, try getting files via the `proc` filesystem (e.g., proc_pid_exe(5), proc_pid_map_files(5)).

    Defaults to `True`.

  try_embedded_vdso: bool

    Try reading the vDSO embedded in a process’s memory/core dump.

    Defaults to `True`.

    The entire (stripped) vDSO is included in core dumps, so this is a reliable way to get it.

  try_reuse: bool

    Try reusing a module’s loaded file as its debug file and vice versa.

    Defaults to `True`.

  try_supplementary: bool

    Try finding supplementary files.

    Defaults to `True`.

  kernel_directories: Tuple[str, ...]

    Directories to search for the kernel image and loadable kernel modules.

    Defaults to `("",)`.

    An empty string means to check standard paths (e.g., `/boot/vmlinux-release`, `/lib/modules/release`) absolutely and under each path in `directories`.

  try_kmod: KmodSearchMethod

    How to search for loadable kernel modules.

    Defaults to `KmodSearchMethod.DEPMOD_OR_WALK`.

class drgn.KmodSearchMethod

  Bases: `enum.Enum`

  Methods of searching for loadable kernel module debugging information.

  In addition to searching by build ID, there are currently two methods of searching for debugging information specific to loadable kernel modules:

  1. Using depmod(8) metadata. This looks for depmod metadata (specifically, `modules.dep.bin`) at the top level of each directory in `DebugInfoOptions.kernel_directories` (an empty path means `/lib/modules/release`). The metadata is used to quickly find the path of each module, which is then checked relative to each directory specified by `DebugInfoOptions.kernel_directories`.

     This method is faster but typically only applicable to installed kernels.

  2. Walking kernel directories. This traverses each directory specified by `DebugInfoOptions.kernel_directories` looking for `.ko` files. Module names are matched to filenames before the `.ko` extension and with dashes (`-`) replaced with underscores (`_`).

     This method is slower but not limited to installed kernels.

  Debugging information searches can be configured to use one, both, or neither method.

  NONE

    Don’t search using kernel module-specific methods.

  DEPMOD

    Search using depmod metadata.

  WALK

    Search by walking kernel directories.

  DEPMOD_OR_WALK

    Search using depmod metadata, falling back to walking kernel directories only if no depmod metadata is found.

    Since depmod metadata is expected to be reliable if present, this is the default.

  DEPMOD_AND_WALK

    Search using depmod metadata and by walking kernel directories.

    Unlike `DEPMOD_OR_WALK`, if depmod metadata is found but doesn’t result in the desired debugging information, this will still walk kernel directories.

class drgn.Thread

  A thread in a program.

  tid: Final[int]

    Thread ID (as defined by gettid(2)).

  name: Optional[str]

    Thread name, or `None` if unknown.

    See PR_SET_NAME and /proc/pid/comm.

    Note

    Linux userspace core dumps only save the name of the main thread, so `name` will be `None` for other threads.

  object: Final[Object]

    If the program is the Linux kernel, the `struct task_struct *` object for this thread. Otherwise, not defined.

  stack_trace() → StackTrace

    Get the stack trace for this thread.

    This is equivalent to `prog.stack_trace(thread.tid)`. See `Program.stack_trace()`.

### Filenames

The `Program.type()`, `Program.object()`, `Program.variable()`, `Program.constant()`, and `Program.function()` methods all take a filename parameter to distinguish between multiple definitions with the same name. The filename refers to the source code file that contains the definition. It is matched with `filename_matches()`. If multiple definitions match, one is returned arbitrarily.

drgn.filename_matches(haystack: Optional[str], needle: Optional[str]) → bool

  Return whether a filename containing a definition (haystack) matches a filename being searched for (needle).

  The filename is matched from right to left, so `'stdio.h'`, `'include/stdio.h'`, `'usr/include/stdio.h'`, and `'/usr/include/stdio.h'` would all match a definition in `/usr/include/stdio.h`. If needle is `None` or empty, it matches any definition. If haystack is `None` or empty, it only matches if needle is also `None` or empty.

  Parameters:

    - haystack – Path of file containing definition.

    - needle – Filename to match.

### Program Constructors

The drgn command line interface automatically creates a `Program` named `prog`. However, drgn may also be used as a library without the CLI, in which case a `Program` must be created manually.

drgn.program_from_core_dump(path: Union[Path, int]) → Program

  Create a `Program` from a core dump file. The type of program (e.g., userspace or kernel) is determined automatically.

  Parameters:

    path – Core dump file path or open file descriptor.

drgn.program_from_kernel() → Program

  Create a `Program` from the running operating system kernel. This requires root privileges.

drgn.program_from_pid(pid: int) → Program

  Create a `Program` from a running program with the given PID. This requires appropriate permissions (on Linux, ptrace(2) attach permissions).

  Parameters:

    pid – Process ID of the program to debug.

### Default Program

Most functions that take a `Program` can be called without the prog argument. In that case, the default program argument is used, which is determined by the rules below.

Note

In the drgn CLI, you probably don’t need to care about these details. Simply omit prog:

    # Equivalent in the CLI.
    find_task(pid)
    find_task(prog, pid)
    find_task(prog["init_pid_ns"].address_of_(), pid)

1. If prog is given explicitly, either as a positional or keyword argument, then it is used.

2. Otherwise, if the first argument is an `Object`, then `Object.prog_` is used.

3. Otherwise, the default program is used.

The default program is set automatically in the CLI. Library users can get and set it manually. The default program is a per-thread setting. See Thread Safety.

drgn.get_default_prog() → Program

  Get the default program for the current thread.

  Raises:

    NoDefaultProgramError – if the default program is not set

drgn.set_default_prog(prog: Optional[Program], /) → None

  Set the default program for the current thread.

  Parameters:

    prog – Program to set as the default, or `None` to unset it.

class drgn.NoDefaultProgramError

  Bases: `Exception`

  Error raised when trying to use the default program when it is not set.

For helpers, it is recommended to use the decorators from the `drgn.helpers.common.prog` module instead.

### Platforms

class drgn.Platform

  A `Platform` represents the environment (i.e., architecture and ABI) that a program runs on.

  Platform(arch: Architecture, flags: Optional[PlatformFlags] = None)

    Create a `Platform`.

    Parameters:

      - arch – `Platform.arch`

      - flags – `Platform.flags`; if `None`, default flags for the architecture are used.

  arch: Final[Architecture]

    Instruction set architecture of this platform.

  flags: Final[PlatformFlags]

    Flags which apply to this platform.

  registers: Final[Sequence[Register]]

    Processor registers on this platform.

class drgn.Architecture

  Bases: `enum.Enum`

  An `Architecture` represents an instruction set architecture.

  X86_64

    The x86-64 architecture, a.k.a. AMD64 or Intel 64.

  I386

    The 32-bit x86 architecture, a.k.a. i386 or IA-32.

  AARCH64

    The AArch64 architecture, a.k.a. ARM64.

  ARM

    The 32-bit Arm architecture.

  PPC64

    The 64-bit PowerPC architecture.

  RISCV64

    The 64-bit RISC-V architecture.

  RISCV32

    The 32-bit RISC-V architecture.

  S390X

    The s390x architecture, a.k.a. IBM Z or z/Architecture.

  S390

    The 32-bit s390 architecture, a.k.a. System/390.

  UNKNOWN

    An architecture which is not known to drgn. Certain features are not available when the architecture is unknown, but most of drgn will still work.

class drgn.PlatformFlags

  Bases: `enum.Flag`

  `PlatformFlags` are flags describing a `Platform`.

  IS_64_BIT

    Platform is 64-bit.

  IS_LITTLE_ENDIAN

    Platform is little-endian.

class drgn.Register

  A `Register` represents information about a processor register.

  names: Final[Sequence[str]]

    Names of this register.

drgn.host_platform: Platform

  The platform of the host which is running drgn.

### Languages

class drgn.Language

  A `Language` represents a programming language supported by drgn.

  This class cannot be constructed; there are singletons for the supported languages.

  name: Final[str]

    Name of the programming language.

  C: ClassVar[Language]

    The C programming language.

  CPP: ClassVar[Language]

    The C++ programming language.

## Objects

class drgn.Object

  An `Object` represents a symbol or value in a program. An object may exist in the memory of the program (a reference), it may be a constant or temporary computed value (a value), or it may be absent entirely (an absent object).

  All instances of this class have two attributes: `prog_`, the program that the object is from; and `type_`, the type of the object. Reference objects also have an `address_` and a `bit_offset_`. Objects may also have a `bit_field_size_`.

  `repr()` of an object returns a Python representation of the object:

      >>> print(repr(prog['jiffies']))
      Object(prog, 'volatile unsigned long', address=0xffffffffbf005000)

  `str()` returns a “pretty” representation of the object in programming language syntax:

      >>> print(prog['jiffies'])
      (volatile unsigned long)4326237045

  The output format of `str()` can be modified by using the `format_()` method instead:

      >>> sysname = prog['init_uts_ns'].name.sysname
      >>> print(sysname)
      (char [65])"Linux"
      >>> print(sysname.format_(type_name=False))
      "Linux"
      >>> print(sysname.format_(string=False))
      (char [65]){ 76, 105, 110, 117, 120 }

  Note

  The drgn CLI is set up so that objects are displayed in the “pretty” format instead of with `repr()` (the latter is the default behavior of Python’s interactive mode). Therefore, it’s usually not necessary to call `print()` in the drgn CLI.

  Objects support the following operators:

  - Arithmetic operators: `+`, `-`, `*`, `/`, `%`

  - Bitwise operators: `<<`, `>>`, `&`, `|`, `^`, `~`

  - Relational operators: `==`, `!=`, `<`, `>`, `<=`, `>=`

  - Subscripting: `[]` (Python does not have a unary `*` operator, so pointers are dereferenced with `ptr[0]`)

  - Member access: `.` (Python does not have a `->` operator, so `.` is also used to access members of pointers to structures)

  - The address-of operator: `drgn.Object.address_of_()` (this is a method because Python does not have a `&` operator)

  - Array length: `len()`

  These operators all have the semantics of the program’s programming language. For example, adding two objects from a program written in C results in an object with a type and value according to the rules of C:

      >>> Object(prog, 'unsigned long', 2**64 - 1) + Object(prog, 'int', 1)
      Object(prog, 'unsigned long', value=0)

  If only one operand to a binary operator is an object, the other operand will be converted to an object according to the language’s rules for literals:

      >>> Object(prog, 'char', 0) - 1
      Object(prog, 'int', value=-1)

  The standard `int()`, `float()`, and `bool()` functions convert an object to that Python type. Conversion to `bool` uses the programming language’s notion of “truthiness”. Additionally, certain Python functions will automatically coerce an object to the appropriate Python type (e.g., `hex()`, `round()`, and `list subscripting`).

  Object attributes and methods are named with a trailing underscore to avoid conflicting with structure, union, or class members. The attributes and methods always take precedence; use `member_()` if there is a conflict.

  Objects are usually obtained directly from a `Program`, but they can be constructed manually, as well (for example, if you got a variable address from a log file).

  Object(prog: Program, type: Union[str, Type], value: Union[IntegerLike, float, bool, Mapping[str, Any], Sequence[Any]], *, bit_field_size: Optional[IntegerLike] = None)

    Create a value object given its type and value.

    Parameters:

      - prog – Program to create the object in.

      - type – Type of the object.

      - value – Value of the object. See `value_()`.

      - bit_field_size – Size in bits of the object if it is a bit field. The default is `None`, which means the object is not a bit field.

  Object(prog: Program, *, value: Union[int, float, bool])

    Create a value object from a “literal”.

    This is used to emulate a literal number in the source code of the program. The type is deduced from value according to the language’s rules for literals.

    Parameters:

      value – Value of the literal.

  Object(prog: Program, type: Union[str, Type], *, address: IntegerLike, bit_offset: IntegerLike = 0, bit_field_size: Optional[IntegerLike] = None)

    Create a reference object.

    Parameters:

      - address – Address of the object in the program.

      - bit_offset – Offset in bits from address to the beginning of the object.

  Object(prog: Program, type: Union[str, Type], *, absence_reason: AbsenceReason = AbsenceReason.OTHER, bit_field_size: Optional[IntegerLike] = None)

    Create an absent object.

  prog_: Final[Program]

    Program that this object is from.

  type_: Final[Type]

    Type of this object.

  address_: Final[Optional[int]]

    Address of this object if it is a reference, `None` if it is a value or absent.

  absent_: Final[bool]

    Whether this object is absent.

    This is `False` for all values and references (even if the reference has an invalid address).

  absence_reason_: Final[Optional[AbsenceReason]]

    Reason that this object is absent.

    This is `None` for all values and references.

  bit_offset_: Final[Optional[int]]

    Offset in bits from this object’s address to the beginning of the object if it is a reference, `None` otherwise. This can only be non-zero for scalars.

  bit_field_size_: Final[Optional[int]]

    Size in bits of this object if it is a bit field, `None` if it is not.

  __getattr__(name: str) → Object

    Implement `self.name`.

    This corresponds to both the member access (`.`) and member access through pointer (`->`) operators in C.

    Note that if name is an attribute or method of the `Object` class, then that takes precedence. Otherwise, this is equivalent to `member_()`.

        >>> print(prog['init_task'].pid)
        (pid_t)0

    Parameters:

      name – Attribute name.

  __getitem__(i: IntegerLike) → Object

    Implement `self[i]`. Get the array element at the given index.

    This is only valid for pointers and arrays.

        >>> print(prog["init_task"].comm[1])
        (char)119

    `[0]` is also the equivalent of the pointer dereference (`*`) operator in C:

        >>> ptr_to_ptr
        *(void **)0xffff9b86801e2968 = 0xffff9b86801e2460
        >>> print(ptr_to_ptr[0])
        (void *)0xffff9b86801e2460

    Note

    Negative indices are relative to the start of the pointer/array (like in C), not relative to the end (like for Python lists).

        >>> ptr[-2].address_of_() == ptr - 2
        True

    Parameters:

      i – Index.

    Raises:

      TypeError – if this object is not a pointer or array

  __getitem__(s: slice) → Object

    Implement `self[start:stop]`. Get an array slice.

    This is only valid for pointers and arrays. It creates a new array for the range of elements from the (inclusive) start index to the (exclusive) stop index. The length of the resulting array is therefore the stop index minus the start index, or zero if the stop index is less than the start index.

    If the start index is omitted, it defaults to 0. If the stop index is omitted, it defaults to the length of the array (in which case the object must be a complete array).

    For example, this can be used to get a subset of an array:

        >>> prog["init_task"].comm[1:3]
        (char [2])"wa"

    Or to get a complete array from a pointer/incomplete array with a separate length:

        >>> poll_list
        *(struct poll_list *)0xffffa3d3c126fa70 = {
                .next = (struct poll_list *)0x0,
                .len = (unsigned int)2,
                .entries = (struct pollfd []){},
        }
        >>> poll_list.entries[:poll_list.len]
        (struct pollfd [2]){
                {
                        .fd = (int)6,
                        .events = (short)1,
                        .revents = (short)0,
                },
                {
                        .fd = (int)14,
                        .events = (short)1,
                        .revents = (short)0,
                },
        }

    Note

    Negative indices are relative to the start of the pointer/array (like in C), not relative to the end (like for Python lists).

        >>> prog['init_task'].comm[-2:]
        (char [18])""
        >>> prog['init_task'].comm[:-2]
        (char [0]){}

    Parameters:

      s – Slice.

    Raises:

      - TypeError – if this object is not a pointer or array

      - TypeError – if the stop index is omitted and this object is not an array with complete type

  __len__() → int

    Implement `len(self)`. Get the number of elements in this object.

        >>> len(prog["init_task"].comm)
        16

    This is only valid for arrays.

    Raises:

      TypeError – if this object is not an array with complete type

  value_() → Any

    Get the value of this object as a Python object.

    For basic types (integer, floating-point, boolean), this returns an object of the directly corresponding Python type (`int`, `float`, `bool`). For pointers, this returns the address value of the pointer. For enums, this returns an `int`. For structures and unions, this returns a `dict` of members. For arrays, this returns a `list` of values.

    Note

    Helpers that wish to accept an argument that may be an `Object` or an `int` should use `operator.index()` and `IntegerLike` instead:

        import operator
        from drgn import IntegerLike

        def my_helper(i: IntegerLike) -> ...:
            value = operator.index(i)  # Returns an int
            ...

    Raises:

      - FaultError – if reading the object causes a bad memory access

      - TypeError – if this object has an unreadable type (e.g., `void`)

  string_() → bytes

    Read a null-terminated string pointed to by this object.

    This is only valid for pointers and arrays. The element type is ignored; this operates byte-by-byte.

    For pointers and flexible arrays, this stops at the first null byte.

    For complete arrays, this stops at the first null byte or at the end of the array.

    Raises:

      - FaultError – if reading the string causes a bad memory access

      - TypeError – if this object is not a pointer or array

  member_(name: str) → Object

    Get a member of this object.

    This is valid for structures, unions, classes, and pointers to any of those. If the object is a pointer, it is automatically dereferenced first.

    Normally the dot operator (`.`) can be used to accomplish the same thing, but this method can be used if there is a name conflict with an `Object` attribute or method.

    Parameters:

      name – Name of the member.

    Raises:

      - TypeError – if this object is not a structure, union, class, or a pointer to one of those

      - LookupError – if this object does not have a member with the given name

  subobject_(designator: str) → Object

    Get a subobject (member or element) of this object.

    Usually, a combination of the `.` and `[]` operators can be used instead, but this can be used as:

    1. A variant of `member_()` that doesn’t automatically dereference pointers.

    2. A generalization of `offsetof()`.

        >>> prog["init_task"].subobject_("comm[0]") == prog["init_task"].comm[0]
        True

    Parameters:

      designator – One or more member references or array subscripts.

  address_of_() → Object

    Get a pointer to this object.

    This corresponds to the address-of (`&`) operator in C. It is only possible for reference objects, as value objects don’t have an address in the program.

    As opposed to `address_`, this returns an `Object`, not an `int`.

    Raises:

      ValueError – if this object is a value

  read_() → Object

    Read this object (which may be a reference or a value) and return it as a value object.

    This is useful if the object can change in the running program (but of course nothing stops the program from modifying the object while it is being read).

    As opposed to `value_()`, this returns an `Object`, not a standard Python type.

    Raises:

      - FaultError – if reading this object causes a bad memory access

      - TypeError – if this object has an unreadable type (e.g., `void`)

  to_bytes_() → bytes

    Return the binary representation of this object’s value.

  classmethod from_bytes_(prog: Program, type: Union[str, Type], bytes: collections.abc.Buffer, *, bit_offset: IntegerLike = 0, bit_field_size: Optional[IntegerLike] = None) → Object

    Return a value object from its binary representation.

        >>> print(Object.from_bytes_(prog, "int", b"\x10\x00\x00\x00"))
        (int)16

    Parameters:

      - prog – Program to create the object in.

      - type – Type of the object.

      - bytes – Buffer containing value of the object.

      - bit_offset – Offset in bits from the beginning of bytes to the beginning of the object.

      - bit_field_size – Size in bits of the object if it is a bit field. The default is `None`, which means the object is not a bit field.

  format_(*, columns: Optional[IntegerLike] = None, integer_base: Optional[IntegerLike] = None, dereference: Optional[bool] = None, symbolize: Optional[bool] = None, string: Optional[bool] = None, char: Optional[bool] = None, type_name: Optional[bool] = None, member_type_names: Optional[bool] = None, element_type_names: Optional[bool] = None, members_same_line: Optional[bool] = None, elements_same_line: Optional[bool] = None, member_names: Optional[bool] = None, element_indices: Optional[bool] = None, implicit_members: Optional[bool] = None, implicit_elements: Optional[bool] = None) → str

    Format this object in programming language syntax.

    Various format options can be passed (as keyword arguments) to control the output. Options that aren’t passed or are passed as `None` fall back to a default. Specifically, `obj.format_()` (i.e., with no passed options) is equivalent to `str(obj)`.

        >>> workqueues = prog['workqueues']
        >>> print(workqueues)
        (struct list_head){
                .next = (struct list_head *)0xffff932ecfc0ae10,
                .prev = (struct list_head *)0xffff932e3818fc10,
        }
        >>> print(workqueues.format_(type_name=False,
        ...                          member_type_names=False,
        ...                          member_names=False,
        ...                          members_same_line=True))
        { 0xffff932ecfc0ae10, 0xffff932e3818fc10 }

    Parameters:

      - columns – Number of columns to limit output to when the expression can be reasonably wrapped. Defaults to no limit.

      - integer_base – Base to format integers in (8, 10, or 16). Defaults to 10.

      - dereference – If this object is a pointer, include the dereferenced value. This does not apply to structure, union, or class members, or array elements, as dereferencing those could lead to an infinite loop. Defaults to `True`.

      - symbolize – Include a symbol name and offset for pointer objects. Defaults to `True`.

      - string – Format the values of objects with string type as strings. For C, this applies to pointers to and arrays of `char`, `signed char`, and `unsigned char`. Defaults to `True`.

      - char – Format objects with character type as character literals. For C, this applies to `char`, `signed char`, and `unsigned char`. Defaults to `False`.

      - type_name – Include the type name of this object. Defaults to `True`.

      - member_type_names – Include the type names of structure, union, and class members. Defaults to `True`.

      - element_type_names – Include the type names of array elements. Defaults to `False`.

      - members_same_line – Place multiple structure, union, and class members on the same line if they fit within the specified number of `columns`. Defaults to `False`.

      - elements_same_line – Place multiple array elements on the same line if they fit within the specified number of `columns`. Defaults to `True`.

      - member_names – Include the names of structure, union, and class members. Defaults to `True`.

      - element_indices – Include the indices of array elements. Defaults to `False`.

      - implicit_members – Include structure, union, and class members which have an implicit value (i.e., for C, zero-initialized). Defaults to `True`.

      - implicit_elements – Include array elements which have an implicit value (i.e., for C, zero-initialized). Defaults to `False`.

class drgn.AbsenceReason

  Bases: `enum.Enum`

  Reason an object is :ref:absent <absent-objects>`.

  OTHER

    Another reason not listed below.

  OPTIMIZED_OUT

    Object was optimized out by the compiler.

  NOT_IMPLEMENTED

    Encountered unknown debugging information.

drgn.NULL(prog: Program, type: Union[str, Type]) → Object

  Get an object representing `NULL` casted to the given type.

  This is equivalent to `Object(prog, type, 0)`.

  Parameters:

    - prog – The program.

    - type – The type.

drgn.cast(type: Union[str, Type], obj: Object) → Object

  Get the value of an object explicitly casted to another type.

  This uses the programming language’s rules for explicit conversions, like the cast operator.

      >>> cast("unsigned int", Object(prog, "float", 2.0))
      (unsigned int)2
      >>> cast("void *", Object(prog, "int", 0))
      (void *)0x0

  See also `implicit_convert()` for implicit conversions (which usually do stricter type checking) and `reinterpret()` for reinterpreting the raw memory of an object.

  Parameters:

    - type – Type to cast to.

    - obj – Object to cast.

  Returns:

    Casted object. This is always a value object.

  Raises:

    TypeError – if casting obj to type is not allowed

drgn.implicit_convert(type: Union[str, Type], obj: Object, *, bit_field_size: Optional[IntegerLike] = None) → Object

  Get the value of an object implicitly converted to another type.

  This uses the programming language’s rules for implicit conversions, like when assigning to a variable or passing arguments to a function call.

      >>> implicit_convert("unsigned int", Object(prog, "float", 2.0))
      (unsigned int)2
      >>> implicit_convert("void *", Object(prog, "int", 0))
      Traceback (most recent call last):
        ...
      TypeError: cannot convert 'int' to incompatible type 'void *'

  See also `cast()` for explicit conversions and `reinterpret()` for reinterpreting the raw memory of an object.

  Parameters:

    - type – Type to convert to.

    - obj – Object to convert.

    - bit_field_size – Size in bits if converting to a bit field. The default is `None`, which means the result is not a bit field.

  Returns:

    Converted object. This is always a value object.

  Raises:

    TypeError – if converting obj to type is not allowed

drgn.reinterpret(type: Union[str, Type], obj: Object) → Object

  Get the representation of an object reinterpreted as another type.

  This reinterprets the raw memory of the object, so an object can be reinterpreted as any other type.

      >>> reinterpret("unsigned int", Object(prog, "float", 2.0))
      (unsigned int)1073741824

  Note

  You usually want `cast()` or `implicit_convert()` instead, which convert the value of an object instead of its in-memory representation.

  Parameters:

    - type – Type to reinterpret as.

    - obj – Object to reinterpret.

  Returns:

    Reinterpreted object. If obj is a reference object, then this is a reference object. If obj is a value object, then this is a value object.

  Raises:

    OutOfBoundsError – if obj is a value object and type is larger than obj

drgn.container_of(ptr: Object, type: Union[str, Type], member: str) → Object

  Get the containing object of a pointer object.

  This corresponds to the `container_of()` macro in C.

  Parameters:

    - ptr – Pointer to member in containing object.

    - type – Type of containing object.

    - member – Name of member in containing object. May include one or more member references and zero or more array subscripts.

  Returns:

    Pointer to containing object.

  Raises:

    - TypeError – if ptr is not a pointer or type is not a structure, union, or class type

    - ValueError – if the member is not byte-aligned (e.g., because it is a bit field)

    - LookupError – if type does not have a member with the given name

## Symbols

class drgn.Symbol

  A `Symbol` represents an entry in the symbol table of a program, i.e., an identifier along with its corresponding address range in the program.

  Symbol(name: str, address: int, size: int, binding: SymbolBinding, kind: SymbolKind)

    Create a `Symbol`.

    Parameters:

      - name – `Symbol.name`

      - address – `Symbol.address`

      - size – `Symbol.size`

      - binding – `Symbol.binding`

      - kind – `Symbol.kind`

  name: Final[str]

    Name of this symbol.

  address: Final[int]

    Start address of this symbol.

  size: Final[int]

    Size of this symbol in bytes.

  binding: Final[SymbolBinding]

    Linkage behavior and visibility of this symbol.

  kind: Final[SymbolKind]

    Kind of entity represented by this symbol.

class drgn.SymbolBinding

  Bases: `enum.Enum`

  A `SymbolBinding` describes the linkage behavior and visibility of a symbol.

  UNKNOWN

    Unknown.

  LOCAL

    Not visible outside of the object file containing its definition.

  GLOBAL

    Globally visible.

  WEAK

    Globally visible but may be overridden by a non-weak global symbol.

  UNIQUE

    Globally visible even if dynamic shared object is loaded locally. See GCC’s `-fno-gnu-unique` option.

class drgn.SymbolKind

  Bases: `enum.Enum`

  A `SymbolKind` describes the kind of entity that a symbol represents.

  UNKNOWN

    Unknown or not defined.

  OBJECT

    Data object (e.g., variable or array).

  FUNC

    Function or other executable code.

  SECTION

    Object file section.

  FILE

    Source file.

  COMMON

    Data object in common block.

  TLS

    Thread-local storage entity.

  IFUNC

    Indirect function.

class drgn.SymbolIndex

  A `SymbolIndex` contains a static set of symbols and allows efficient lookup by name and address.

  With `Program.register_symbol_finder()`, you can add a callback to provide custom symbol finding logic. However, in many cases, all that is necessary is to provide drgn with a list of symbols that you know to be part of the program. This object allows you to do that. It efficiently implements the Symbol Finder API given a static set of symbols. For example:

      >>> prog = drgn.Program()
      >>> symbol = drgn.Symbol("foo", 0x123, 1, drgn.SymbolBinding.GLOBAL, drgn.SymbolKind.OBJECT)
      >>> finder = drgn.SymbolIndex([symbol])
      >>> prog.register_symbol_finder("SymbolIndex", finder, enable_index=0)
      >>> prog.symbols()
      [Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)]
      >>> prog.symbol("bar")
      Traceback (most recent call last):
        File "<console>", line 1, in <module>
      LookupError: not found
      >>> prog.symbol("foo")
      Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)
      >>> prog.symbol(0x100)
      Traceback (most recent call last):
        File "<console>", line 1, in <module>
      LookupError: not found
      >>> prog.symbol(0x123)
      Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)

  SymbolIndex(symbols: Iterable[Symbol])

    Create a `SymbolIndex` from a sequence of symbols

    The returned symbol index satisfies the Symbol Finder API. It supports overlapping symbol address ranges and duplicate symbol names. However, in the case of these sorts of conflicts, it doesn’t provide any guarantee on the order of the results, or which result is returned when a single symbol is requested.

    Parameters:

      symbols – An iterable of symbols

    Returns:

      A callable object suitable to provide to `Program.register_symbol_finder()`.

  __call__(prog: Program, name: Optional[str], address: Optional[int], one: bool) → List[Symbol]

    Lookup symbol by name, address, or both.

    Parameters:

      - prog – (unused) the program looking up this symbol

      - name – if given, only return symbols with this name

      - address – if given, only return symbols spanning this address

      - one – if given, limit the result to a single symbol

    Returns:

      a list of matching symbols (empty if none are found)

## Stack Traces

Stack traces are retrieved with `stack_trace()`, `Program.stack_trace()`, or `Thread.stack_trace()`.

drgn.stack_trace(thread: Union[Object, IntegerLike]) → StackTrace

  Get the stack trace for the given thread using the default program argument.

  See `Program.stack_trace()` for more details.

  Parameters:

    thread – Thread ID, `struct pt_regs` object, or `struct task_struct *` object.

class drgn.StackTrace

  A `StackTrace` is a sequence of `StackFrame`.

  `len(trace)` is the number of stack frames in the trace. `trace[0]` is the innermost stack frame, `trace[1]` is its caller, and `trace[len(trace) - 1]` is the outermost frame. Negative indexing also works: `trace[-1]` is the outermost frame and `trace[-len(trace)]` is the innermost frame. It is also iterable:

      for frame in trace:
          if frame.name == 'io_schedule':
              print('Thread is doing I/O')

  `str()` returns a pretty-printed stack trace:

      >>> prog.stack_trace(1)
      #0  context_switch (kernel/sched/core.c:4339:2)
      #1  __schedule (kernel/sched/core.c:5147:8)
      #2  schedule (kernel/sched/core.c:5226:3)
      #3  do_wait (kernel/exit.c:1534:4)
      #4  kernel_wait4 (kernel/exit.c:1678:8)
      #5  __do_sys_wait4 (kernel/exit.c:1706:13)
      #6  do_syscall_64 (arch/x86/entry/common.c:47:14)
      #7  entry_SYSCALL_64+0x7c/0x15b (arch/x86/entry/entry_64.S:112)
      #8  0x4d49dd

  The format is subject to change. The drgn CLI is set up so that stack traces are displayed with `str()` by default.

  prog: Final[Program]

    Program that this stack trace is from.

class drgn.StackFrame

  A `StackFrame` represents a single frame in a thread’s call stack.

  `str()` returns a pretty-printed stack frame:

      >>> prog.stack_trace(1)[0]
      #0 at 0xffffffffb64ac287 (__schedule+0x227/0x606) in context_switch at kernel/sched/core.c:4339:2 (inlined)

  This includes more information than when printing the full stack trace. The format is subject to change. The drgn CLI is set up so that stack frames are displayed with `str()` by default.

  The `[]` operator can look up function parameters, local variables, and global variables in the scope of the stack frame:

      >>> prog.stack_trace(1)[0]['prev'].pid
      (pid_t)1
      >>> prog.stack_trace(1)[0]['scheduler_running']
      (int)1

  name: Final[str]

    Name of the function or symbol at this frame.

    This tries to get the best available name for this frame in the following order:

    1. The name of the function in the source code based on debugging information (`frame.function_name`).

    2. The name of the symbol in the binary (`frame.symbol().name`).

    3. The program counter in hexadecimal (`hex(frame.pc)`).

    4. The string “???”.

  function_name: Final[Optional[str]]

    Name of the function at this frame, or `None` if it could not be determined.

    The name cannot be determined if debugging information is not available for the function, e.g., because it is implemented in assembly.

  is_inline: Final[bool]

    Whether this frame is for an inlined call.

    An inline frame shares the same stack frame in memory as its caller. Therefore, it has the same registers (including program counter and thus symbol).

  interrupted: Final[bool]

    Whether this stack frame was interrupted (for example, by a hardware interrupt, signal, trap, etc.).

    If this is `True`, then the register values in this frame are the values at the time that the frame was interrupted.

    This is `False` if the frame is for a function call, in which case the register values are the values when control returns to this frame. In particular, the program counter is the return address, which is typically the instruction after the call instruction.

  pc: Final[int]

    Program counter at this stack frame.

  sp: Final[int]

    Stack pointer at this stack frame.

  __getitem__(name: str) → Object

    Implement `self[name]`. Get the object (variable, function parameter, constant, or function) with the given name in the scope of this frame.

    If the object exists but has been optimized out, this returns an absent object.

    Parameters:

      name – Object name.

  __contains__(name: str) → bool

    Implement `name in self`. Return whether an object with the given name exists in the scope of this frame.

    Parameters:

      name – Object name.

  locals() → List[str]

    Get a list of the names of all local objects (local variables, function parameters, local constants, and nested functions) in the scope of this frame.

    Not all names may have present values, but they can be used with the `[]` operator to check.

  source() → Tuple[str, int, int]

    Get the source code location of this frame.

    Returns:

      Location as a `(filename, line, column)` triple.

    Raises:

      LookupError – if the source code location is not available

  symbol() → Symbol

    Get the function symbol at this stack frame.

    This is equivalent to:

        prog.symbol(frame.pc - (0 if frame.interrupted else 1))

  register(reg: str) → int

    Get the value of the given register at this stack frame.

    Parameters:

      reg – Register name.

    Raises:

      - ValueError – if the register name is not recognized

      - LookupError – if the register value is not known

  registers() → Dict[str, int]

    Get the values of all available registers at this stack frame as a dictionary with the register names as keys.

## Types

class drgn.Type

  A `Type` object describes a type in a program. Each kind of type (e.g., integer, structure) has different attributes (e.g., name, size). Types can also have qualifiers (e.g., constant, atomic). Accessing an attribute which does not apply to a type raises an `AttributeError`.

  `repr()` of a `Type` returns a Python representation of the type:

      >>> print(repr(prog.type('sector_t')))
      prog.typedef_type(name='sector_t', type=prog.int_type(name='unsigned long', size=8, is_signed=False))

  `str()` returns a representation of the type in programming language syntax:

      >>> print(prog.type('sector_t'))
      typedef unsigned long sector_t

  The drgn CLI is set up so that types are displayed with `str()` instead of `repr()` by default.

  This class cannot be constructed directly. Instead, use one of the Type Constructors.

  prog: Final[Program]

    Program that this type is from.

  kind: Final[TypeKind]

    Kind of this type.

  primitive: Final[Optional[PrimitiveType]]

    If this is a primitive type (e.g., `int` or `double`), the kind of primitive type. Otherwise, `None`.

  qualifiers: Final[Qualifiers]

    Bitmask of this type’s qualifier.

  language: Final[Language]

    Programming language of this type.

  name: Final[str]

    Name of this type. This is present for integer, boolean, floating-point, and typedef types.

  tag: Final[Optional[str]]

    Tag of this type, or `None` if this is an anonymous type. This is present for structure, union, class, and enumerated types.

  size: Final[Optional[int]]

    Size of this type in bytes, or `None` if this is an incomplete type. This is present for integer, boolean, floating-point, structure, union, class, and pointer types.

  length: Final[Optional[int]]

    Number of elements in this type, or `None` if this is an incomplete type. This is only present for array types.

  is_signed: Final[bool]

    Whether this type is signed. This is only present for integer types.

  byteorder: Final[str]

    Byte order of this type: `'little'` if it is little-endian, or `'big'` if it is big-endian. This is present for integer, boolean, floating-point, and pointer types.

  type: Final[Type]

    Type underlying this type, defined as follows:

    - For typedef types, the aliased type.

    - For enumerated types, the compatible integer type, which is `None` if this is an incomplete type.

    - For pointer types, the referenced type.

    - For array types, the element type.

    - For function types, the return type.

    For other types, this attribute is not present.

  members: Final[Optional[Sequence[TypeMember]]]

    List of members of this type, or `None` if this is an incomplete type. This is present for structure, union, and class types.

  enumerators: Final[Optional[Sequence[TypeEnumerator]]]

    List of enumeration constants of this type, or `None` if this is an incomplete type. This is only present for enumerated types.

  parameters: Final[Sequence[TypeParameter]]

    List of parameters of this type. This is only present for function types.

  is_variadic: Final[bool]

    Whether this type takes a variable number of arguments. This is only present for function types.

  template_parameters: Final[Sequence[TypeTemplateParameter]]

    List of template parameters of this type. This is present for structure, union, class, and function types.

  type_name() → str

    Get a descriptive full name of this type.

  variable_declaration(name: str) → str

    Format a variable declaration with this type.

        >>> prog.type("int [4]").variable_declaration("my_array")
        'int my_array[4]'

    Parameters:

      name – Name of the variable.

    Returns:

      Variable declaration in programming language syntax.

  is_complete() → bool

    Get whether this type is complete (i.e., the type definition is known). This is always `False` for void types. It may be `False` for structure, union, class, enumerated, and array types, as well as typedef types where the underlying type is one of those. Otherwise, it is always `True`.

  qualified(qualifiers: Qualifiers) → Type

    Get a copy of this type with different qualifiers.

    Note that the original qualifiers are replaced, not added to.

    Parameters:

      qualifiers – New type qualifiers.

  unqualified() → Type

    Get a copy of this type with no qualifiers.

  unaliased() → Type

    Get a copy of this type with all top-level typedefs removed.

    For example, given the following typedefs:

        typedef long long __kernel_loff_t;
        typedef __kernel_loff_t loff_t;

    Then:

        >>> print(prog.type("loff_t").unaliased())
        long long

    But in this example:

        typedef loff_t *loffp_t;

    Only `loffp_t` is at the top level, not `loff_t`:

        >>> print(prog.type("loffp_t").unaliased())
        loff_t *

  unaliased_kind() → TypeKind

    Get the kind of this type with all typedefs removed.

    This is a shortcut for `Type.unaliased().kind`.

  member(name: str) → TypeMember

    Look up a member in this type by name.

    If this type has any unnamed members, this also matches members of those unnamed members, recursively. If the member is found in an unnamed member, `TypeMember.bit_offset` and `TypeMember.offset` are adjusted accordingly.

    Parameters:

      name – Name of the member.

    Raises:

      - TypeError – if this type is not a structure, union, or class type

      - LookupError – if this type does not have a member with the given name

  has_member(name: str) → bool

    Return whether this type has a member with the given name.

    If this type has any unnamed members, this also matches members of those unnamed members, recursively.

    Parameters:

      name – Name of the member.

    Raises:

      TypeError – if this type is not a structure, union, or class type

class drgn.TypeMember

  A `TypeMember` represents a member of a structure, union, or class type.

  TypeMember(object_or_type: Union[Object, Type, Callable[[], Union[Object, Type]]], name: Optional[str] = None, bit_offset: int = 0)

    Create a `TypeMember`.

    Parameters:

      - object_or_type –

        One of:

        1. `TypeMember.object` as an `Object`.

        2. `TypeMember.type` as a `Type`. In this case, `object` is set to an absent object with that type.

        3. A callable that takes no arguments and returns one of the above. It is called when `object` or `type` is first accessed, and the result is cached.

      - name – `TypeMember.name`

      - bit_offset – `TypeMember.bit_offset`

  object: Final[Object]

    Member as an `Object`.

    This is the default initializer for the member, or an absent object if the member has no default initializer. (However, the DWARF specification as of version 5 does not actually support default member initializers, so this is usually absent.)

  type: Final[Type]

    Member type.

    This is a shortcut for `TypeMember.object.type`.

  name: Final[Optional[str]]

    Member name, or `None` if the member is unnamed.

  bit_offset: Final[int]

    Offset of the member from the beginning of the type in bits.

  offset: Final[int]

    Offset of the member from the beginning of the type in bytes. If the offset is not byte-aligned, accessing this attribute raises `ValueError`.

  bit_field_size: Final[Optional[int]]

    Size in bits of this member if it is a bit field, `None` if it is not.

    This is a shortcut for `TypeMember.object.bit_field_size_`.

class drgn.TypeEnumerator

  A `TypeEnumerator` represents a constant in an enumerated type.

  Its name and value may be accessed as attributes or unpacked:

      >>> prog.type('enum pid_type').enumerators[0].name
      'PIDTYPE_PID'
      >>> name, value = prog.type('enum pid_type').enumerators[0]
      >>> value
      0

  TypeEnumerator(name: str, value: int)

    Create a `TypeEnumerator`.

    Parameters:

      - name – `TypeEnumerator.name`

      - value – `TypeEnumerator.value`

  name: Final[str]

    Enumerator name.

  value: Final[int]

    Enumerator value.

class drgn.TypeParameter

  A `TypeParameter` represents a parameter of a function type.

  TypeParameter(default_argument_or_type: Union[Object, Type, Callable[[], Union[Object, Type]]], name: Optional[str] = None)

    Create a `TypeParameter`.

    Parameters:

      - default_argument_or_type –

        One of:

        1. `TypeParameter.default_argument` as an `Object`.

        2. `TypeParameter.type` as a `Type`. In this case, `default_argument` is set to an absent object with that type.

        3. A callable that takes no arguments and returns one of the above. It is called when `default_argument` or `type` is first accessed, and the result is cached.

      - name – `TypeParameter.name`

  default_argument: Final[Object]

    Default argument for parameter.

    If the parameter does not have a default argument, then this is an absent object.

    Note

    Neither GCC nor Clang emits debugging information for default arguments (as of GCC 10 and Clang 11), and drgn does not yet parse it, so this is usually absent.

  type: Final[Type]

    Parameter type.

    This is the same as `TypeParameter.default_argument.type_`.

  name: Final[Optional[str]]

    Parameter name, or `None` if the parameter is unnamed.

class drgn.TypeTemplateParameter

  A `TypeTemplateParameter` represents a template parameter of a structure, union, class, or function type.

  TypeTemplateParameter(argument: Union[Type, Object, Callable[[], Union[Type, Object]]], name: Optional[str] = None, is_default: bool = False)

    Create a `TypeTemplateParameter`.

    Parameters:

      - argument –

        One of:

        1. `TypeTemplateParameter.argument` as a `Type` if the parameter is a type template parameter.

        2. `TypeTemplateParameter.argument` as a non-absent `Object` if the parameter is a non-type template parameter.

        3. A callable that takes no arguments and returns one of the above. It is called when `argument` is first accessed, and the result is cached.

      - name – `TypeTemplateParameter.name`

      - is_default – `TypeTemplateParameter.is_default`

  argument: Final[Union[Type, Object]]

    Template argument.

    If this is a type template parameter, then this is a `Type`. If this is a non-type template parameter, then this is an `Object`.

  name: Final[Optional[str]]

    Template parameter name, or `None` if the parameter is unnamed.

  is_default: Final[bool]

    Whether `argument` is the default for the template parameter.

    Note

    There are two ways to interpret this:

    > 1. The argument was omitted entirely and thus defaulted to the default argument.

    > 2. The (specified or defaulted) argument is the same as the default argument.

    Compilers are inconsistent about which interpretation they use.

    GCC added this information in version 4.9. Clang added it in version 11 (and only when emitting DWARF version 5). If the program was compiled by an older version, this is always false.

class drgn.TypeKind

  Bases: `enum.Enum`

  A `TypeKind` represents a kind of type.

  VOID

    Void type.

  INT

    Integer type.

  BOOL

    Boolean type.

  FLOAT

    Floating-point type.

  STRUCT

    Structure type.

  UNION

    Union type.

  CLASS

    Class type.

  ENUM

    Enumerated type.

  TYPEDEF

    Type definition (a.k.a. alias) type.

  POINTER

    Pointer type.

  ARRAY

    Array type.

  FUNCTION

    Function type.

class drgn.TypeKindSet

  Bases: `collections.abc.Set`[`TypeKind`]

  Immutable set of `TypeKind`s.

      >>> kinds = TypeKindSet({TypeKind.STRUCT, TypeKind.CLASS})
      >>> TypeKind.STRUCT in kinds
      True
      >>> TypeKind.INT in kinds
      False
      >>> for kind in kinds:
      ...     print(kind)
      ...
      TypeKind.STRUCT
      TypeKind.CLASS

class drgn.PrimitiveType

  Bases: `enum.Enum`

  A `PrimitiveType` represents a primitive type known to drgn.

  C_VOID
  C_CHAR
  C_SIGNED_CHAR
  C_UNSIGNED_CHAR
  C_SHORT
  C_UNSIGNED_SHORT
  C_INT
  C_UNSIGNED_INT
  C_LONG
  C_UNSIGNED_LONG
  C_LONG_LONG
  C_UNSIGNED_LONG_LONG
  C_BOOL
  C_FLOAT
  C_DOUBLE
  C_LONG_DOUBLE
  C_SIZE_T
  C_PTRDIFF_T

class drgn.Qualifiers

  Bases: `enum.Flag`

  `Qualifiers` are modifiers on types.

  NONE

    No qualifiers.

  CONST

    Constant type.

  VOLATILE

    Volatile type.

  RESTRICT

    Restrict type.

  ATOMIC

    Atomic type.

drgn.alignof(type: Type, /) → int

  Get the alignment requirement (in bytes) of a `Type`.

  This corresponds to `_Alignof()` in C.

  Raises:

    TypeError – if type is a function type or an incomplete type

drgn.offsetof(type: Type, member: str) → int

  Get the offset (in bytes) of a member in a `Type`.

  This corresponds to `offsetof()` in C.

  Parameters:

    - type – Structure, union, or class type.

    - member – Name of member. May include one or more member references and zero or more array subscripts.

  Raises:

    - TypeError – if type is not a structure, union, or class type

    - ValueError – if the member is not byte-aligned (e.g., because it is a bit field)

    - LookupError – if type does not have a member with the given name

### Type Constructors

Custom drgn types can be created with the following factory functions. These can be used just like types obtained from `Program.type()`.

Program.void_type(*, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new void type. It has kind `TypeKind.VOID`.

  Parameters:

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.int_type(name: str, size: IntegerLike, is_signed: bool, byteorder: Optional[str] = None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new integer type. It has kind `TypeKind.INT`.

  Parameters:

    - name – `Type.name`

    - size – `Type.size`

    - is_signed – `Type.is_signed`

    - byteorder – `Type.byteorder`, or `None` to use the program’s default byte order.

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.bool_type(name: str, size: IntegerLike, byteorder: Optional[str] = None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new boolean type. It has kind `TypeKind.BOOL`.

  Parameters:

    - name – `Type.name`

    - size – `Type.size`

    - byteorder – `Type.byteorder`, or `None` to use the program’s default byte order.

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.float_type(name: str, size: IntegerLike, byteorder: Optional[str] = None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new floating-point type. It has kind `TypeKind.FLOAT`.

  Parameters:

    - name – `Type.name`

    - size – `Type.size`

    - byteorder – `Type.byteorder`, or `None` to use the program’s default byte order.

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.struct_type(tag: Optional[str], size: IntegerLike, members: Sequence[TypeMember], *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new structure type. It has kind `TypeKind.STRUCT`.

  Parameters:

    - tag – `Type.tag`

    - size – `Type.size`

    - members – `Type.members`

    - template_parameters – `Type.template_parameters`

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.struct_type(tag: Optional[str], size: None = None, members: None = None, *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new incomplete structure type.

Program.union_type(tag: Optional[str], size: IntegerLike, members: Sequence[TypeMember], *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new union type. It has kind `TypeKind.UNION`. Otherwise, this is the same as as `struct_type()`.

Program.union_type(tag: Optional[str], size: None = None, members: None = None, *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new incomplete union type.

Program.class_type(tag: Optional[str], size: IntegerLike, members: Sequence[TypeMember], *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new class type. It has kind `TypeKind.CLASS`. Otherwise, this is the same as as `struct_type()`.

Program.class_type(tag: Optional[str], size: None = None, members: None = None, *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new incomplete class type.

Program.enum_type(tag: Optional[str], type: Type, enumerators: Sequence[TypeEnumerator], *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new enumerated type. It has kind `TypeKind.ENUM`.

  Parameters:

    - tag – `Type.tag`

    - type – The compatible integer type (`Type.type`)

    - enumerators – `Type.enumerators`

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.enum_type(tag: Optional[str], type: None = None, enumerators: None = None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new incomplete enumerated type.

Program.typedef_type(name: str, type: Type, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new typedef type. It has kind `TypeKind.TYPEDEF`.

  Parameters:

    - name – `Type.name`

    - type – The aliased type (`Type.type`)

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.pointer_type(type: Type, size: Optional[int] = None, byteorder: Optional[str] = None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new pointer type. It has kind `TypeKind.POINTER`,

  Parameters:

    - type – The referenced type (`Type.type`)

    - size – `Type.size`, or `None` to use the program’s default pointer size.

    - byteorder – `Type.byteorder`, or `None` to use the program’s default byte order.

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.array_type(type: Type, length: Optional[int] = None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new array type. It has kind `TypeKind.ARRAY`.

  Parameters:

    - type – The element type (`Type.type`)

    - length – `Type.length`

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

Program.function_type(type: Type, parameters: Sequence[TypeParameter], is_variadic: bool = False, *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) → Type

  Create a new function type. It has kind `TypeKind.FUNCTION`.

  Parameters:

    - type – The return type (`Type.type`)

    - parameters – `Type.parameters`

    - is_variadic – `Type.is_variadic`

    - template_parameters – `Type.template_parameters`

    - qualifiers – `Type.qualifiers`

    - lang – `Type.language`

## Modules

class drgn.Module

  A `Module` represents an executable, library, or other binary file used by a program. It has several subclasses representing specific types of modules.

  Modules are uniquely identified by their type, name, and a type-specific value.

  Modules have several attributes that are determined automatically whenever possible but may be overridden manually if needed.

  Modules can be assigned files that provide debugging and runtime information:

  - The “loaded file” is the file containing the executable code, data, etc. used by the program at runtime.

  - The “debug file” is the file containing debugging information (e.g., DWARF).

    The loaded file and debug file may be the same file, for example, an unstripped binary. They may be different files if the binary was stripped and its debugging information was split into a separate file.

  - The debug file may depend on a “supplementary debug file” such as one generated by dwz(1). If so, then the supplementary debug file must be found before the debug file can be used.

  prog: Final[Program]

    Program that this module is from.

  name: Final[str]

    Name of this module.

    Its exact meaning varies by module type.

  address_ranges: Optional[Sequence[Tuple[int, int]]]

    Address ranges where this module is loaded.

    This is a sequence of tuples of the start (inclusive) and end (exclusive) addresses. For each range, the start address is strictly less than the end address. If the module is not loaded in memory, then the sequence is empty. If not known yet, then this is `None`.

    `Program.loaded_modules()` sets this automatically from the program state/core dump when possible. Otherwise, for `MainModule`, `SharedLibraryModule`, and `VdsoModule`, it may be set automatically when a file is assigned to the module. It is never set automatically for `ExtraModule`. It can also be set manually.

    Other than Linux kernel loadable modules, most modules have only one address range. See `address_range`.

  address_range: Optional[Tuple[int, int]]

    Address range where this module is loaded.

    This is an alias of `address_ranges[0]` with a couple of small differences:

    - If the module has more than one address range, then reading this raises a `ValueError`.

    - If the module is not loaded in memory, then this is `(0, 0)`.

  build_id: Optional[bytes]

    Unique byte string (e.g., GNU build ID) identifying files used by this module.

    If not known, then this is `None`.

    `Program.loaded_modules()` sets this automatically from the program state/core dump when possible. Otherwise, when a file is assigned to the module, it is set to the file’s build ID if it is not already set. It can also be set manually.

  object: Object

    The object associated with this module.

    For Linux kernel loadable modules, this is the `struct module *` associated with the kernel module. For other kinds, this is currently an absent object. The object may be set manually.

  loaded_file_status: ModuleFileStatus

    Status of the module’s loaded file.

  loaded_file_path: Optional[str]

    Absolute path of the module’s loaded file, or `None` if not known.

  loaded_file_bias: Optional[int]

    Difference between the load address in the program and addresses in the loaded file itself.

    This is often non-zero due to address space layout randomization (ASLR).

    It is set automatically based on the module type when the loaded file is added:

    - For `MainModule`, it is set based on metadata from the process or core dump (the auxiliary vector for userspace programs, the `VMCOREINFO` note for the Linux kernel).

    - For `SharedLibraryModule` and `VdsoModule`, it is set to `dynamic_address` minus the address of the dynamic section in the file.

    - For `RelocatableModule`, it is set to zero. Addresses are adjusted according to `section_addresses` instead.

    - For `ExtraModule`, if `address_ranges` is set to a single range before the file is added, then the bias is set to `address_ranges[0][0]` (i.e., the module’s start address) minus the file’s start address. If `address_ranges` is not set when the file is added, is empty, or comprises more than one range, then the bias is set to zero.

    This cannot be set manually.

  debug_file_status: ModuleFileStatus

    Status of the module’s debug file.

  debug_file_path: Optional[str]

    Absolute path of the module’s debug file, or `None` if not known.

  debug_file_bias: Optional[int]

    Difference between the load address in the program and addresses in the debug file.

    See `loaded_file_bias`.

  supplementary_debug_file_kind: Optional[SupplementaryFileKind]

    Kind of the module’s supplementary debug file, or `None` if not known or not needed.

  supplementary_debug_file_path: Optional[str]

    Absolute path of the module’s supplementary debug file, or `None` if not known or not needed.

  wants_loaded_file() → bool

    Return whether this module wants a loaded file.

    This should be preferred over checking `loaded_file_status` directly since this is future-proof against new status types being added. It is currently equivalent to `module.loaded_file_status == ModuleFileStatus.WANT`.

  wants_debug_file() → bool

    Return whether this module wants a debug file.

    This should be preferred over checking `debug_file_status` directly since this is future-proof against new status types being added. It is currently equivalent to `module.debug_file_status == ModuleFileStatus.WANT or module.debug_file_status == ModuleFileStatus.WANT_SUPPLEMENTARY`.

  wanted_supplementary_debug_file() → WantedSupplementaryFile

    Return information about the supplementary debug file that this module currently wants.

    Raises:

      ValueError – if the module doesn’t currently want a supplementary debug file (i.e., `module.debug_file_status != ModuleFileStatus.WANT_SUPPLEMENTARY`)

  try_file(path: Path, *, fd: int = -1, force: bool = False) → None

    Try to use the given file for this module.

    If the file does not appear to belong to this module, then it is ignored. This currently checks that the file and the module have the same build ID.

    If `loaded_file_status` is `WANT` and the file is loadable, then it is used as the loaded file and `loaded_file_status` is set to `HAVE`.

    If `debug_file_status` is `WANT` or `WANT_SUPPLEMENTARY` and the file provides debugging information, then it is used as the debug file and `debug_file_status` is set to `HAVE`. However, if the file requires a supplementary debug file, then it is not used as the debug file yet and `debug_file_status` is set to `WANT_SUPPLEMENTARY` instead.

    If `debug_file_status` is `WANT_SUPPLEMENTARY` and the file matches `wanted_supplementary_debug_file()`, then the previously found file is used as the debug file, the given file is used as the supplementary debug file, and `debug_file_status` is set to `HAVE`.

    The file may be used as both the loaded file and debug file if applicable.

    Parameters:

      - path – Path to file.

      - fd – If nonnegative, an open file descriptor referring to the file. This always takes ownership of the file descriptor even if the file is not used or on error, so the caller must not close it.

      - force – If `True`, then don’t check whether the file matches the module.

class drgn.MainModule

  Bases: `Module`

  Main module.

  There is only one main module in a program. For userspace programs, it is the executable, and its name is usually the absolute path of the executable. For the Linux kernel, it is the kernel image, a.k.a. `vmlinux`, and its name is “kernel”.

class drgn.SharedLibraryModule

  Bases: `Module`

  Shared library (a.k.a. dynamic library, dynamic shared object, or `.so`) module.

  Shared libraries are uniquely identified by their name (usually the absolute path of the shared object file) and dynamic address.

  dynamic_address: Final[int]

    Address of the shared object’s dynamic section.

class drgn.VdsoModule

  Bases: `Module`

  Virtual dynamic shared object (vDSO) module.

  The vDSO is a special shared library automatically loaded into a process by the kernel; see vdso(7). It is uniquely identified by its name (the `SONAME` field of the shared object file) and dynamic address.

  dynamic_address: Final[int]

    Address of the shared object’s dynamic section.

class drgn.RelocatableModule

  Bases: `Module`

  Relocatable object module.

  A relocatable object is an object file requiring a linking step to assign section addresses and adjust the file to reference those addresses.

  Linux kernel loadable modules (`.ko` files) are a special kind of relocatable object.

  For userspace programs, relocatable objects are usually intermediate products of the compilation process (`.o` files). They are not typically loaded at runtime. However, drgn allows manually defining a relocatable module and assigning its section addresses if needed.

  Relocatable modules are uniquely identified by a name and address.

  address: Final[int]

    Address identifying the module.

    For Linux kernel loadable modules, this is the module base address.

  section_addresses: MutableMapping[str, int]

    Mapping from section names to assigned addresses.

    Once a file has been assigned to the module, this can no longer be modified.

    `Program.linux_kernel_loadable_module()` and `Program.loaded_modules()` prepopulate this for Linux kernel loadable modules.

class drgn.ExtraModule

  Bases: `Module`

  Module with extra debugging information.

  For advanced use cases, it may be necessary to manually add debugging information that does not fit into any of the categories above. `ExtraModule` is intended for these use cases. For example, it can be used to add debugging information from a standalone file that is not in use by a particular program.

  Extra modules are uniquely identified by a name and ID number. Both the name and ID number are arbitrary.

  id: Final[int]

    Arbitrary identification number.

class drgn.ModuleFileStatus

  Bases: `enum.Enum`

  Status of a file in a `Module`.

  This is usually used to communicate with debugging information finders; see `Program.register_debug_info_finder()`.

  WANT

    File has not been found and should be searched for.

  HAVE

    File has already been found and assigned.

  DONT_WANT

    File has not been found, but it should not be searched for.

    `Module.try_file()` and debugging information finders are required to honor this and will never change it. However, other operations may reset this to `WANT` when they load debugging information automatically.

  DONT_NEED

    File has not been found and is not needed (e.g., because its debugging information is not applicable or is provided through another mechanism).

    In contrast to `DONT_WANT`, drgn itself will never change this to `WANT`.

  WANT_SUPPLEMENTARY

    File has been found, but it requires a supplementary file before it can be used. See `Module.wanted_supplementary_debug_file()`.

class drgn.WantedSupplementaryFile

  Bases: `NamedTuple`

  Information about a wanted supplementary file.

  kind: SupplementaryFileKind

    Kind of supplementary file.

  path: str

    Path of main file that wants the supplementary file.

  supplementary_path: str

    Path to the supplementary file.

    This may be absolute or relative to `path`.

  checksum: bytes

    Unique identifier of the supplementary file.

    The interpretation depends on `kind`.

class drgn.SupplementaryFileKind

  Bases: `enum.Enum`

  Kind of supplementary file.

  Note

  DWARF 5 supplementary files are not currently supported but may be in the future.

  DWARF package files are not considered supplementary files. They are considered part of the debug file and must have the same path as the debug file plus a “.dwp” extension.

  GNU_DEBUGALTLINK

    GNU-style supplementary debug file referred to by a `.gnu_debugaltlink` section.

    Its `checksum` is the file’s GNU build ID.

### Module Lookups/Constructors

For each module type, there is a corresponding method to create a module of that type or find one that was previously created:

    >>> prog.extra_module("foo", 1234)
    Traceback (most recent call last):
      ...
    LookupError: module not found
    >>> prog.extra_module("foo", 1234, create=True)
    prog.extra_module(name='foo', id=0x4d2)
    >>> prog.extra_module("foo", 1234)
    prog.extra_module(name='foo', id=0x4d2)

Program.main_module() → MainModule

  Find the main module.

  Raises:

    LookupError – if the main module has not been created

Program.main_module(name: Path, *, create: bool = False) → MainModule

  Find the main module.

  Parameters:

    - name – `Module.name`

    - create – Create the module if it doesn’t exist.

  Raises:

    LookupError – if the main module has not been created and create is `False`, or if the main module has already been created with a different name

Program.shared_library_module(name: Path, dynamic_address: IntegerLike, *, create: bool = False) → SharedLibraryModule

  Find a shared library module.

  Parameters:

    - name – `Module.name`

    - dynamic_address – `SharedLibraryModule.dynamic_address`

    - create – Create the module if it doesn’t exist.

  Returns:

    Shared library module with the given name and dynamic address.

  Raises:

    LookupError – if no matching module has been created and create is `False`

Program.vdso_module(name: Path, dynamic_address: IntegerLike, *, create: bool = False) → VdsoModule

  Find a vDSO module.

  Parameters:

    - name – `Module.name`

    - dynamic_address – `VdsoModule.dynamic_address`

    - create – Create the module if it doesn’t exist.

  Returns:

    vDSO module with the given name and dynamic address.

  Raises:

    LookupError – if no matching module has been created and create is `False`

Program.relocatable_module(name: Path, address: IntegerLike, *, create: bool = False) → RelocatableModule

  Find a relocatable module.

  Parameters:

    - name – `Module.name`

    - address – `RelocatableModule.address`

    - create – Create the module if it doesn’t exist.

  Returns:

    Relocatable module with the given name and address.

  Raises:

    LookupError – if no matching module has been created and create is `False`

Program.linux_kernel_loadable_module(module_obj: Object, *, create: bool = False) → RelocatableModule

  Find a Linux kernel loadable module from a `struct module *` object.

  Note that kernel modules are represented as relocatable modules.

  Parameters:

    - module_obj – `struct module *` object for the kernel module.

    - create – Create the module if it doesn’t exist.

  Returns:

    Relocatable module with a name and address matching module_obj.

  Raises:

    LookupError – if no matching module has been created and create is `False`

Program.extra_module(name: Path, id: IntegerLike = 0, *, create: bool = False) → ExtraModule

  Find an extra module.

  Parameters:

    - name – `Module.name`

    - id – `ExtraModule.id`

    - create – Create the module if it doesn’t exist.

  Returns:

    Extra module with the given name and ID number.

  Raises:

    LookupError – if no matching module has been created and create is `False`

## Miscellaneous

drgn.sizeof(type_or_obj: Union[Type, Object], /) → int

  Get the size of a `Type` or `Object` in bytes.

  Parameters:

    type_or_obj – Entity to get the size of.

  Raises:

    TypeError – if the type does not have a size (e.g., because it is incomplete or void)

drgn.execscript(path: str, *args: str, globals: Optional[Dict[str, Any]] = None) → None

  Execute a script.

  The script is executed in the same context as the caller: currently defined globals are available to the script, and globals defined by the script are added back to the calling context.

  This is most useful for executing scripts from interactive mode. For example, you could have a script named `exe.py`:

      """Get all tasks executing a given file."""

      import sys

      from drgn.helpers.linux.fs import d_path
      from drgn.helpers.linux.pid import find_task

      def task_exe_path(task):
          if task.mm:
              return d_path(task.mm.exe_file.f_path).decode()
          else:
              return None

      tasks = [
          task for task in for_each_task()
          if task_exe_path(task) == sys.argv[1]
      ]

  Then, you could execute it and use the defined variables and functions:

      >>> execscript('exe.py', '/usr/bin/bash')
      >>> tasks[0].pid
      (pid_t)358442
      >>> task_exe_path(find_task(357954))
      '/usr/bin/vim'

  Parameters:

    - path – File path of the script.

    - args – Zero or more additional arguments to pass to the script. This is a variable argument list.

    - globals – If provided, globals to use instead of the caller’s.

drgn.IntegerLike: TypeAlias

  An `int` or integer-like object.

  Parameters annotated with this type expect an integer which may be given as a Python `int` or an `Object` with integer type.

  This is equivalent to `typing.SupportsIndex`.

drgn.Path: TypeAlias

  Filesystem path.

  Parameters annotated with this type accept a filesystem path as `str`, `bytes`, or `os.PathLike`.

## Exceptions

class drgn.FaultError

  Bases: `Exception`

  This error is raised when a bad memory access is attempted (i.e., when accessing a memory address which is not valid in a program).

  FaultError(message: str, address: int)
    Parameters:

      - message – `FaultError.message`

      - address – `FaultError.address`

  message: str

    Error message.

  address: int

    Address that couldn’t be accessed.

class drgn.MissingDebugInfoError

  Bases: `Exception`

  This error is raised when one or more files in a program do not have debug information.

class drgn.ObjectAbsentError

  Bases: `Exception`

  This error is raised when attempting to use an absent object.

class drgn.OutOfBoundsError

  Bases: `Exception`

  This error is raised when attempting to access beyond the bounds of a value object.

## CLI

Functions for embedding the drgn CLI.

drgn.cli.version_header() → str

  Return the version header printed at the beginning of a drgn session.

  The `run_interactive()` function does not include this banner at the beginning of an interactive session. Use this function to retrieve one line of text to add to the beginning of the drgn banner, or print it before calling `run_interactive()`.

drgn.cli.default_globals(prog: drgn.Program) → Dict[str, Any]

  Return the default globals for an interactive drgn session

  Parameters:

    prog – the program which will be debugged

  Returns:

    a dict of globals

drgn.cli.run_interactive(prog: drgn.Program, banner_func: Optional[Callable[[str], str]] = None, globals_func: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None, quiet: bool = False) → None

  Run drgn’s Interactive Mode until the user exits.

  This function allows your application to embed the same REPL that drgn provides when it is run on the command line in interactive mode.

  Parameters:

    - prog – Pre-configured program to run against. Available as a global named `prog` in the CLI.

    - banner_func – Optional function to modify the printed banner. Called with the default banner, and must return a string to use as the new banner. The default banner does not include the drgn version, which can be retrieved via `version_header()`.

    - globals_func – Optional function to modify globals provided to the session. Called with a dictionary of default globals, and must return a dictionary to use instead.

    - quiet – Ignored. Will be removed in the future.

  Note

  This function uses `readline` and modifies some settings. Unfortunately, it is not possible for it to restore all settings. In particular, it clears the `readline` history and resets the TAB keybinding to the default.

  Applications using `readline` should save their history and clear any custom settings before calling this function. After calling this function, applications should restore their history and settings before using `readline`.

## Plugins

drgn can be extended with plugins. A drgn plugin is a Python module defining one or more hook functions that are called at specific times.

By default, drgn loads installed modules registered as entry points for the `drgn.plugins` group. The `DRGN_PLUGINS` and `DRGN_DISABLE_PLUGINS` environment variables can be used to configure this.

The following hooks are currently defined:

drgn_prog_set(prog: drgn.Program) → None

  Called after the program target has been set (e.g., one of `drgn.Program.set_core_dump()`, `drgn.Program.set_kernel()`, or `drgn.Program.set_pid()` has been called).

A `drgn_priority` integer attribute can be assigned to a hook function to define when it is called relative to other plugins. Hook functions with lower `drgn_priority` values are called earlier. Functions with equal `drgn_priority` values are called in an unspecified order. The default if not defined is 50.

See Writing Plugins for an example.

## Logging

drgn logs using the standard `logging` module to a logger named `"drgn"`.

drgn will also display progress bars on standard error if standard error is a terminal, the `"drgn"` logger has a `StreamHandler` for `stderr`, and its log level is less than or equal to `WARNING`.

## Thread Safety

Only one thread at a time should access the same `Program` (including `Object`, `Type`, `StackTrace`, etc. from that program). It is safe to use different `Program`s from concurrent threads.