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.

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) except that this raises KeyError instead of LookupError if no objects with the given name are found.

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:

LookupError – 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:

LookupError – 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:

LookupError – 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:

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

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 are multiple matching symbols with the same binding, 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'
Parameters:
  • address – The starting address.

  • size – The 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_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 Symbols.

  • 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]]

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

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.

module(address: IntegerLike, /) Module

Find the module containing the given address.

Addresses are matched based on Module.address_range.

Parameters:

address – Address to search for.

Raises:

LookupError – if no module contains the given address

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 Modules 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:

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

cache: Dict[Any, Any]

Dictionary for caching program metadata.

This isn’t used by drgn 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']
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.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 ("", ".debug", "/usr/lib/debug"), which should work out of the box on most Linux distributions.

This controls searches by build ID (see try_build_id) and debug link (see try_debug_link), 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 absolute 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.

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 directories for a file with a matching name and checksum. Relative paths in directories are relative to the directory containing the loaded file. An empty path in directories means the directory containing the loaded file.

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 path means to check standard paths (e.g., /boot/vmlinux-release, /lib/modules/release) absolutely and under each absolute 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: 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], *, 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.

absent_: Final[bool]

Whether this object is absent.

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

address_: Final[Optional[int]]

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

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__(idx: IntegerLike) Object

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

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

This is only valid for pointers and arrays.

Note

Negative indices behave as they would in the object’s language (as opposed to the Python semantics of indexing from the end of the array).

Parameters:

idx – The array index.

Raises:

TypeError – if this object is not a pointer or array

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

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

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""))
(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, 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.

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

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

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

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.

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

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

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_range: Optional[Tuple[int, int]]

Address range where this module is loaded.

This is a tuple of the start (inclusive) and end (exclusive) addresses. If the module is not loaded in memory, then both are 0. 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.

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.

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:

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 an arbitrary name and ID number.

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-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), True)
>>> prog.extra_module("foo", 1234)
>>> prog.extra_module("foo", 1234, create=True)
(prog.extra_module(name='foo', id=0x4d2), False)
Program.main_module(name: Optional[Path] = None, *, create: Literal[False] = False) MainModule

Find the main module.

Parameters:

nameModule.name, or None to match any name

Raises:

LookupError – if main module has not been created or its name doesn’t match

Program.main_module(name: Path, *, create: Literal[True]) Tuple[MainModule, bool]

Find or create the main module.

Parameters:

nameModule.name

Returns:

Module and True if it was newly created or False if it was found.

Raises:

LookupError – if main module was already created with a different name

Program.shared_library_module(name: Path, dynamic_address: IntegerLike, *, create: Literal[False] = False) SharedLibraryModule

Find a shared library module.

Parameters:
Returns:

Shared library module with the given name and dynamic address.

Raises:

LookupError – if no matching module has been created

Program.shared_library_module(name: Path, dynamic_address: IntegerLike, *, create: Literal[True]) Tuple[SharedLibraryModule, bool]

Find or create a shared library module.

Parameters:
Returns:

Module and True if it was newly created or False if it was found.

Program.vdso_module(name: Path, dynamic_address: IntegerLike, *, create: Literal[False] = False) VdsoModule

Find a vDSO module.

Parameters:
Returns:

vDSO module with the given name and dynamic address.

Raises:

LookupError – if no matching module has been created

Program.vdso_module(name: Path, dynamic_address: IntegerLike, *, create: Literal[True]) Tuple[VdsoModule, bool]

Find or create a vDSO module.

Parameters:
Returns:

Module and True if it was newly created or False if it was found.

Program.relocatable_module(name: Path, address: IntegerLike, *, create: Literal[False] = False) RelocatableModule

Find a relocatable module.

Parameters:
Returns:

Relocatable module with the given name and address.

Raises:

LookupError – if no matching module has been created

Program.relocatable_module(name: Path, address: IntegerLike, *, create: Literal[True]) Tuple[RelocatableModule, bool]

Find or create a relocatable module.

Parameters:
Returns:

Module and True if it was newly created or False if it was found.

Program.linux_kernel_loadable_module(module_obj: Object, *, create: Literal[False] = False) RelocatableModule

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

Note that kernel modules are represented as relocatable modules.

Parameters:

module_objstruct module or struct module * object for the kernel module.

Returns:

Relocatable module with a name and address matching module_obj.

Raises:

LookupError – if no matching module has been created

Program.linux_kernel_loadable_module(module_obj: Object, *, create: Literal[True]) Tuple[RelocatableModule, bool]

Find or create a Linux kernel loadable module from a struct module object.

If a new module is created, its address_range and section_addresses are set from module_obj.

Parameters:

module_objstruct module or struct module * object for the kernel module.

Returns:

Module and True if it was newly created or False if it was found.

Program.extra_module(name: Path, id: IntegerLike = 0, *, create: Literal[False] = False) ExtraModule

Find an extra module.

Parameters:
Returns:

Extra module with the given name and ID number.

Raises:

LookupError – if no matching module has been created

Program.extra_module(name: Path, id: IntegerLike = 0, *, create: Literal[True]) Tuple[ExtraModule, bool]

Find or create an extra module.

Parameters:
Returns:

Module and True if it was newly created or False if it was found.

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

class drgn.IntegerLike

Bases: Protocol

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.

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: 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.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 Programs from concurrent threads.