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.

source_location(address: Union[IntegerLike, str], /) → SourceLocationList

Find the source code location containing a code address.

The address may be given as an integer or a string. A string argument must be a symbol name or hexadecimal address, optionally followed by a + character and a decimal or hexadecimal offset. Hexadecimal numbers must be prefixed with “0x” or “0X”. Whitespace between tokens is ignored.

>>> prog.source_location("__schedule")
__schedule at kernel/sched/core.c:6646:1
>>> prog.source_location("__schedule+0x2b6")
#0  context_switch at kernel/sched/core.c:5381:9
#1  __schedule at kernel/sched/core.c:6765:8
>>> prog.source_location(0xffffffffb64d70a6)
#0  context_switch at kernel/sched/core.c:5381:9
#1  __schedule at kernel/sched/core.c:6765:8

Because of function inlining, a code address may actually correspond to multiple source code locations. So, this returns a sequence of locations, where the first item corresponds to the innermost inlined function, the second item is its caller, etc.

Note

This is similar to addr2line(1).

Parameters:

address – Code address.

Raises:

LookupError – if the source code location is not found

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

search_memory(value: Union[bytes, str], *, alignment: int = 1) → MemorySearchIterator[int]

search_memory(value: Union[IntegerLike, Object]) → MemorySearchIterator[int]

search_memory_u16(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

search_memory_u32(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

search_memory_u64(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

search_memory_word(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

search_memory_regex(pattern: bytes) → MemorySearchIterator[Tuple[int, bytes]]

search_memory_regex(pattern: str) → MemorySearchIterator[Tuple[int, str]]

See Searching Memory.

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_linux_kernel_custom(vmcoreinfo: Union[str, bytes], is_live: bool) → None

Set the program to a custom Linux kernel target.

This enables debugging a Linux kernel via a custom memory transport (e.g., RDMA, TCP/IP, or VMM introspection). It sets up page table walking for virtual address translation. It does not load any debugging symbols; see load_default_debug_info().

Physical memory segments must be registered via add_memory_segment() with physical=True before reading memory. Platform must be provided when creating the Program.

Parameters:

• vmcoreinfo – Raw vmcoreinfo data. If vmcoreinfo was already set when creating the Program, this is ignored.

• is_live – Whether the kernel is currently running.

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

  • 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() → SourceLocation

Get the source code location of this frame.

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.

Source Locations

Source locations are obtained from source_location(), Program.source_location(), or StackFrame.source().

drgn.source_location(address: Union[IntegerLike, str], /) → SourceLocationList

Find the source code location containing a code address, similarly to addr2line(1), using the default program argument.

>>> source_location("__schedule")
__schedule at kernel/sched/core.c:6646:1
>>> source_location("__schedule+0x2b6")
#0  context_switch at kernel/sched/core.c:5381:9
#1  __schedule at kernel/sched/core.c:6765:8
>>> source_location(0xffffffffb64d70a6)
#0  context_switch at kernel/sched/core.c:5381:9
#1  __schedule at kernel/sched/core.c:6765:8

See Program.source_location() for more details.

Parameters:

address – Code address as an integer, symbol name, or "symbol_name+offset" string.

class drgn.SourceLocation

Bases: NamedTuple

File, line, and column location in source code.

The attributes can be accessed by name:

>>> filename = loc.filename
>>> line = loc.line
>>> column = loc.column

or unpacked:

>>> filename, line, column = loc

str() returns a pretty-printed location:

>>> loc
context_switch at kernel/sched/core.c:5381:9

filename: str

Source file name, or empty string if unknown.

line: int

Source line number, or 0 if unknown.

column: int

Source column, or 0 if unknown.

name() → Optional[str]

Get the name of the function or symbol at this source location, or None if it could not be determined.

class drgn.SourceLocationList

A sequence of SourceLocation.

This is a read-only list of source code locations:

>>> locs = prog.source_location(0xffffffffb64d70a6)
>>> print(repr(locs))
<_drgn.SourceLocationList object at 0x7fb5d1f8e0e0>
>>> print(repr(locs[0]))
<_drgn.SourceLocation object at 0x7fb5d1feb8d0>
>>> print(repr(locs[1]))
<_drgn.SourceLocation object at 0x7fb5d1feb880>

For code address lookups where the address is in an inlined function, the first item corresponds to the innermost inlined function, the second item is its caller, etc.

str() returns a pretty-printed list of locations:

>>> locs
#0  context_switch at kernel/sched/core.c:5381:9
#1  __schedule at kernel/sched/core.c:6765:8

prog: Final[Program]

Program that this source location list is from.

Searching Memory

Memory can be searched for specific values or patterns with the following functions.

drgn.search_memory(value: Union[bytes, str], *, alignment: int = 1) → MemorySearchIterator[int]

Search for all non-overlapping occurrences of a byte string in the default program’s memory.

for address in search_memory(b"VMCOREINFO"):
    print(hex(address))

Parameters:

• value – Byte string to search for. If given as a str, then this searches for its UTF-8 encoding.

• alignment – Only consider addresses aligned to this value (i.e., address % alignment == 0). Must be a power of two.

Returns:

Iterator of addresses where the string is found.

drgn.search_memory(value: Union[IntegerLike, Object]) → MemorySearchIterator[int]

Search for all occurrences of a value in the default program’s memory.

ptr = stack_trace(pid)[2]["ptr"]
for address in search_memory(ptr):
    print(hex(address))

Parameters:

value – Value to search for. If given as an int, then it is interpreted as a program word-sized, naturally aligned unsigned integer. If given as an Object, then its size and alignment are determined from its type.

Returns:

Iterator of addresses where the value is found.

drgn.search_memory_u16(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

drgn.search_memory_u32(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

drgn.search_memory_u64(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

drgn.search_memory_word(*values: Union[IntegerLike, Tuple[IntegerLike, IntegerLike]], ignore_mask: IntegerLike = 0) → MemorySearchIterator[Tuple[int, int]]

Search for all occurrences of one or more unsigned integers in the default program’s memory.

search_memory_u16(), search_memory_u32(), and search_memory_u64() search for 16-, 32- or 64-bit unsigned integers, respectively. search_memory_word() searches for program word-sized unsigned integers. Natural alignment is assumed (i.e., 2-byte alignment for 16-bit integers, 4-byte alignment for 32-bit integers, 8-byte alignment for 64-bit integers).

for address, value in search_memory_word(
    0xdead000000000100, 0xdead000000000122
):
    print(hex(address), hex(value))

for address, value in search_memory_word(
    0xdead000000000000, ignore_mask=0xffff
):
    print(hex(address), hex(value))

obj = prog["obj"]
for address, value in search_memory_word(
    (obj.address_, obj.address_ + sizeof(obj) - 1)
):
    print(hex(address), hex(value))

Parameters:

• values – Values to search for. Each value may be a single integer or a (min, max) range (where both ends are included).

• ignore_mask – Mask of bits to ignore when comparing to single integers given in values. This is not used when comparing to ranges.

Returns:

Iterator of addresses where the value is found and the found value.

drgn.search_memory_regex(pattern: bytes) → MemorySearchIterator[Tuple[int, bytes]]

drgn.search_memory_regex(pattern: str) → MemorySearchIterator[Tuple[int, str]]

Search for all non-overlapping matches of a regular expression pattern in the program’s memory.

# Search for anything that looks like root's password encrypted in
# /etc/shadow.
for address, match in search_memory_regex(rb"root:\$\w+\$[ -9;-~]+:"):
    print(hex(address), match)

Parameters:

pattern – PCRE regular expression to search for. If given as bytes, then search for 8-bit strings. If given as str, then search for Unicode strings. Note that lookbehind assertions are not allowed.

Returns:

Iterator of addresses where a match is found and the matching string.

To search programs other than the default program, these are also available as methods (Program.search_memory(), Program.search_memory_u16(), Program.search_memory_u32(), Program.search_memory_u64(), Program.search_memory_word(), and Program.search_memory_regex()).

These functions/methods all return the following special iterator type.

class drgn.MemorySearchIterator

Bases: Iterator[T]

Iterator returned by memory searches.

set_address_range(min_address: Optional[IntegerLike] = None, max_address: Optional[IntegerLike] = None, physical: bool = False) → Self

Set the address range to limit a memory search to.

This returns the iterator itself, so it can be used conveniently when the iterator is created:

for address in search_memory(b"VMCOREINFO").set_address_range(physical=True):
    print(hex(address))

It can also be called during or after iteration, allowing an iterator to be reused for searching multiple ranges:

it = search_memory_regex(some_complex_pattern)

for min_address, max_address in address_ranges:
    it.set_address_range(min_address, max_address)
    for address, match in it:
        print(hex(address), match)

Parameters:

• min_address – Minimum address to search (inclusive). Defaults to the program’s minimum address.

• max_address – Maximum address to search (inclusive). Defaults to the program’s maximum address.

• physical – Whether to search physical memory. Defaults to False (virtual memory).

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 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: Union[Type, str], /) → int

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

This corresponds to _Alignof() in C.

Parameters:

type – Type. If given as a string, it is looked up in the default program.

Raises:

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

drgn.offsetof(type: Union[Type, str], 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. If given as a string, it is looked up in the default program.

• 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. Address ranges may not overlap.

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, str], /) → int

Get the size of a Type or Object in bytes.

Parameters:

type_or_obj – Entity to get the size of. If given as a string, it is looked up (first as a type, then as an object) in the default program.

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.display_str(tp: Type[T]) → Type[T]

Decorator for types which should be displayed in the cli using str()

Many types, like drgn.StackTrace, are formatted in the CLI using str() rather than repr(). This activates their __str__() method rather than the more verbose __repr__(), which results in a more user-friendly output. To achieve this behavior with your own types, apply this decorator:

>>> @drgn.cli.display_str
... class Task(NamedTuple):
...     pid: int
...     comm: str
...     def __str__(self):
...         return f"PID: {self.pid:6d}  COMM: {self.comm}"
...
>>> print(repr(Task(1, "init")))
Task(pid=1, comm='init')
>>> print(str(Task(1, "init")))
PID:      1  COMM: init
>>> Task(1, "init")
PID:      1  COMM: init

Parameters:

tp – type to register for display with str

Returns:

the same type

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.

Commands

Functions for defining drgn CLI commands and running them programmatically.

For documentation of available commands and command syntax, see Commands.

drgn.commands.run_command(prog: drgn.Program, command: str, *, globals: Optional[Dict[str, Any]] = None, onerror: Optional[Callable[[Exception], None]] = None) → Any

Run a drgn command.

Parameters:

• prog – Program to run command on.

• command – Command string (including arguments, redirections, pipes, etc.) to run.

• globals – Global variables to run command with. Defaults to the caller’s global variables.

• onerror – Callback for handling errors (e.g., logging them). By default, errors are raised as exceptions.

Returns:

The command’s return value. Note that most commands return None.

class drgn.commands.CommandError

Bases: Exception

Error raised when a command fails.

class drgn.commands.CommandArgumentError

Bases: CommandError

Error raised when a command’s arguments cannot be parsed.

class drgn.commands.CommandExitStatusError

Bases: CommandError

Error raised when a command pipeline exits with a non-zero status.

command: str

Command pipeline that failed.

exit_status: int

Exit status, or negative signal number if terminated by a signal.

class drgn.commands.CommandNotFoundError

Bases: CommandError

Error raised when a command cannot be found.

name: str

Command name that could not be found.

class drgn.commands.CommandNamespace

Command namespace.

Commands are registered to a specific namespace and can only be found or run in that namespace. This allows reusing drgn’s command system for commands that shouldn’t be exposed directly to the CLI.

CommandNamespace(*, func_name_prefix: str = '_cmd_', argparse_types: Sequence[Tuple[str, Callable[[str], Any]]] = ())

Create a command namespace.

Parameters:

• func_name_prefix – Function name prefix expected by command(), custom_command(), and raw_command().

• argparse_types – (name, callable) tuples to register as argparse types for commands in this namespace. See argparse.ArgumentParser.register().

register(name: str, command: Command[Any]) → None

Register a command in this namespace.

lookup(prog: drgn.Program, name: str) → Command[object]

Find a command in this namespace.

Parameters:

name – Command name.

Raises:

CommandNotFoundError – if a command with the given name is not found

enabled(prog: drgn.Program) → Iterable[Tuple[str, Command[object]]]

Get all enabled commands in this namespace.

Returns:

Iterable of (name, command) tuples.

run(prog: drgn.Program, command: str, *, globals: Optional[Dict[str, Any]] = None, onerror: Optional[Callable[[Exception], None]] = None) → Any

Run a drgn command in this namespace.

Arguments and return value are the same as run_command().

drgn.commands.DEFAULT_COMMAND_NAMESPACE: CommandNamespace

Default command namespace used by the drgn CLI.

class drgn.commands.Command

Bases: Protocol[T]

Command implementation.

Commands can usually be defined with command(), custom_command(), or raw_command(), but this can be used when even more control is needed.

description() → str

Return a one-line description of the command.

format_usage() → str

Return the usage string.

format_help(*, indent: str = '') → str

Return the help string.

Parameters:

indent – String to prepend to each line.

enabled(prog: drgn.Program) → bool

Return whether the command should be enabled for the given program.

parse(source: str, /) → ParsedCommand[T]

Parse the command string after the command name.

This must separate redirections and pipes from arguments.

Parameters:

source – Command string after command name (arguments, redirections, pipes, etc.).

run(prog: drgn.Program, name: str, args: T, /, *, globals: Dict[str, Any]) → Any

Run the command.

Parameters:

• prog – Program.

• name – Name that the command was invoked as.

• args – Command arguments returned in ParsedCommand.args by parse().

Additional keyword arguments may also be passed. To allow for future extensions, implementations of this method should add a variable keyword parameter (i.e., **kwargs) and ignore unneeded keyword arguments:

class MyCommand:
    ...
    def run(
        self, prog: Program, name: str, args: Sequence[str], **kwargs: Any
    ) -> None:
        ...

The current keyword parameters are:

Parameters:

globals – Dictionary of global variables.

Returns:

Anything, but usually None.

class drgn.commands.ParsedCommand

Bases: Generic[T]

Parsed command string.

args: T

Arguments.

redirections: Sequence[ShellRedirection]

Shell redirections.

pipeline: Optional[str]

Pipeline.

class drgn.commands.ShellRedirection

Bases: NamedTuple

Shell redirection.

fd: int

File descriptor to redirect.

op: RedirectOp

Redirection operator ("<", ">", etc.).

path: str

Path to redirect to.

drgn.commands.parse_shell_command(source: str, unquote: bool = True) → ParsedCommand[Sequence[str]]

Parse a shell command string.

Parameters:

• source – Command string after command name (arguments, redirections, pipes, etc.).

• unquote – Whether to unquote/unescape arguments.

drgn.commands.unquote_shell_word(word: str) → str

Unquote/unescape a quoted and/or escaped word in shell syntax.

>>> print(unquote_shell_word(r"f'o'o\ bar"))
foo bar

drgn.commands.command(*, name: Optional[str] = None, description: str, usage: Optional[str] = None, long_description: Optional[str] = None, epilog: Optional[str] = None, arguments: Sequence[Union[argument, argument_group, mutually_exclusive_group]] = (), enabled: Callable[[drgn.Program], bool] = _always_enabled, namespace: CommandNamespace = DEFAULT_COMMAND_NAMESPACE) → CommandFuncDecorator

Decorator to register a command.

Commands registered with this decorator parse options specified in arguments using argparse. See custom_command() and raw_command() for alternatives that doesn’t use argparse.

See CommandFunc for the signature of the command function.

Descriptions and help strings may have multiple lines (unlike the default argparse formatting).

There are also a couple of argparse argument types provided for convenience:

1. "hexadecimal": a hexadecimal integer.

2. "decimal_or_hexadecimal: a decimal or hexadecimal integer, preferring decimal if ambiguous.

import argparse
from typing import Any

from drgn import Program
from drgn.commands import command


@command(description="do nothing")
def _cmd_true(
    prog: Program, name: str, args: argparse.Namespace, **kwargs: Any
) -> None:
    pass

Parameters:

• name – Command name. If not given, the name of the decorated function must begin with _cmd_, and the command name is the function name with that prefix removed.

• description – Mandatory one-line description of the command.

• usage – Usage string in reStructuredText format. Generated from arguments automatically if not given.

• long_description – Optional longer description of the command.

• epilog – Optional additional information to show at the end of help output.

• arguments – Arguments, argument groups, and mutually exclusive groups accepted by the command.

• enabled – Callback returning whether the command should be enabled for a given program. Defaults to always enabled.

• namespace – Namespace to register command to.

class drgn.commands.CommandFunc

Bases: Protocol

Signature of a command function for command().

__call__(prog: drgn.Program, name: str, args: argparse.Namespace, /, *, parser: argparse.ArgumentParser, globals: Dict[str, Any]) → Any

Parameters:

• prog – Program.

• name – Name that the command was invoked as.

• args – Parsed arguments as an argparse.Namespace.

• parser – Argument parser.

See Command.run() for other keyword parameters.

Returns:

Anything, but usually None.

class drgn.commands.argument(*args: Any, **kwargs: Any)

Command line argument for command().

Arguments are the same as argparse.ArgumentParser.add_argument().

import argparse
from typing import Any

from drgn import Program
from drgn.commands import argument, command


@command(
    description="concatenate and print files",
    arguments=(
        argument("-n", help="number output lines"),
        argument("file", nargs="*", help="input files"),
    ),
)
def _cmd_cat(
    prog: Program, name: str, args: argparse.Namespace, **kwargs: Any
) -> None:
    ...

drgn.commands.drgn_argument: argument

Command line argument for command() named --drgn indicating that the command should print how to do the equivalent operation using drgn APIs.

This helps onboard users from simple commands to more complex use cases requiring programmability.

By convention, it should normally be the last argument.

import argparse
from typing import Any

from drgn import Program
from drgn.commands import argument, command, drgn_argument


@command(
    description="print a stack trace"
    arguments=(
        argument("tid", type=int, help="thread ID"),
        drgn_argument,
    ),
)
def _cmd_bt(
    prog: Program, name: str, args: argparse.Namespace, **kwargs: Any
) -> None:
    if args.drgn:
        print("trace = stack_trace(tid)")
        print("print(trace)")
        return
    print(prog.stack_trace(args.tid))

class drgn.commands.argument_group(*arguments: Union[argument, mutually_exclusive_group], title: str, description: Optional[str] = None)

Group of arguments for command().

See argparse.ArgumentParser.add_argument_group().

import argparse
from typing import Any

from drgn import Program
from drgn.commands import argument, argument_group, command


@command(
    description="print matching lines",
    arguments=(
        argument_group(
            argument("-A", type=int, help="print lines after match"),
            argument("-B", type=int, help="print lines before match"),
            title="context line options",
        )
        argument("pattern", help="pattern to search for"),
    ),
)
def _cmd_grep(
    prog: Program, name: str, args: argparse.Namespace, **kwargs: Any
) -> None:
    ...

Parameters:

• arguments – Arguments and mutually exclusive groups in the group.

• title – Title to group arguments under.

• description – Description of group.

class drgn.commands.mutually_exclusive_group(*arguments: argument, required: bool = False)

Mutually exclusive group of arguments for command().

See argparse.ArgumentParser.add_mutually_exclusive_group().

This is often nested in an argument_group():

import argparse
from typing import Any

from drgn import Program
from drgn.commands import (
    argument,
    argument_group,
    command,
    mutually_exclusive_group,
)


@command(
    description="print matching lines",
    arguments=(
        argument_group(
            mutually_exclusive_group(
                argument(
                    "-E",
                    action="store_true",
                    help="use extended regular expressions",
                ),
                argument(
                    "-F",
                    action="store_true",
                    help="match a fixed string",
                ),
            ),
            title="pattern syntax",
        )
        argument("pattern", help="pattern to search for"),
    ),
)
def _cmd_grep(
    prog: Program, name: str, args: argparse.Namespace, **kwargs: Any
) -> None:
    ...

It can also be passed directly to command():

@command(
    description="print matching lines",
    arguments=(
        mutually_exclusive_group(
            argument(
                "-E",
                action="store_true",
                help="use extended regular expressions",
            ),
            argument(
                "-F",
                action="store_true",
                help="match a fixed string",
            ),
        ),
        argument("pattern", help="pattern to search for"),
    ),
)
def _cmd_grep(
    prog: Program, name: str, args: argparse.Namespace, **kwargs: Any
) -> None:
    ...

Parameters:

• arguments – Arguments in the group.

• required – Whether exactly one of the arguments is required.

drgn.commands.custom_command(*, name: Optional[str] = None, description: str, usage: Optional[str] = None, long_description: Optional[str] = None, epilog: Optional[str] = None, arguments: Optional[Sequence[Union[argument, argument_group, mutually_exclusive_group]]] = None, parse: Callable[[str], ParsedCommand[T]], enabled: Callable[[drgn.Program], bool] = _always_enabled, namespace: CommandNamespace = DEFAULT_COMMAND_NAMESPACE) → CustomCommandFuncDecorator[T]

Decorator to register a command with its own custom syntax (instead of command line options).

See CustomCommandFunc for the signature of the command function.

import ast
import dataclasses
import re
from typing import Any

from drgn import Program
from drgn.commands import ParsedCommand, custom_command, parse_shell_command


def _parse_literal_eval(source: str) -> ParsedCommand[str]:
    match = re.fullmatch(r"([^<>|]*)(.*)", source)
    parsed = parse_shell_command(match.group(2))
    if parsed.args:
        raise SyntaxError("arguments after redirections are not supported")
    return dataclasses.replace(parsed, args=match.group(1))


@custom_command(
    description="evaluate a Python literal",
    usage="**literal_eval** *EXPR*",
    long_description="This evaluates and returns a Python literal"
    " (for example, a string, integer, list, etc.).",
    parse=_parse_literal_eval,
)
def _cmd_literal_eval(
    prog: Program, name: str, args: str, **kwargs: Any
) -> Any:
    return ast.literal_eval(args)

Parameters:

• name – Command name. If not given, the name of the decorated function must begin with _cmd_, and the command name is the function name with that prefix removed.

• description – Mandatory one-line description of the command.

• usage – Usage string in reStructuredText format. Mandatory if arguments not given, otherwise generated from arguments automatically if not given.

• long_description – Longer description of the command. Mandatory if arguments not given, optional otherwise.

• epilog – Optional additional information to show at the end of help output.

• arguments – Arguments, argument groups, and mutually exclusive groups accepted by the command. Used only for generating help output.

• parse – Callback to parse the command string after the command name. This must separate redirections and pipes from arguments.

• enabled – Callback returning whether the command should be enabled for a given program. Defaults to always enabled.

• namespace – Namespace to register command to.

class drgn.commands.CustomCommandFunc

Bases: Protocol[T_contra]

Signature of a custom command function for custom_command().

__call__(prog: drgn.Program, name: str, args: T_contra, /, *, parser: argparse.ArgumentParser, globals: Dict[str, Any]) → Any

Parameters:

• prog – Program.

• name – Name that the command was invoked as.

• args – Command arguments parsed by parse argument to custom_command().

• parser – Argument parser.

See Command.run() for other keyword parameters.

Returns:

Anything, but usually None.

drgn.commands.raw_command

Special case of custom_command() where the arguments are the command string verbatim.

Note that this cannot support redirections or pipes.

from typing import Any

from drgn import Program
from drgn.commands import argument, raw_command


@raw_command(
    description="display text verbatim",
    arguments=(
        argument("text", help="text to display"),
    ),
)
def _cmd_echo(
    prog: Program, name: str, args: str, **kwargs: Any
) -> Any:
    print(args)

class drgn.commands.DrgnCodeBuilder

Helper class for generating code for drgn_argument().

This handles joining multiple fragments of code and adding imports. Imports are deduplicated, sorted, and prepended to the final output.

append(code: str) → None

Append a code fragment to the output.

begin_block(code: str, end: str = '') → DrgnCodeBlockContext

Append a code fragment that begins an indented block.

This can be used to wrap code that may or may not need to be executed in a conditional or loop.

Subsequent lines added with append() will be indented accordingly until the block is ended with end_block():

if condition:
    code.begin_block(f"if {condition}:\n")
code.append("do_something()\n")
if condition:
    code.end_block()

Alternatively, this can be used as a context manager:

with code.begin_block(f"while {condition}:\n")
    code.append("do_something()\n")

Parameters:

• code – Code fragment whose last non-whitespace line begins the block (e.g., an if or for statement). This can also be empty to begin a “fake” block that doesn’t affect indentation but still pairs with a end_block() call.

• end – Code fragment to append when the block is ended. This is useful for try statements.

end_block() → None

End the most recently begun indented block.

See begin_block().

add_import(module: str) → None

Add an import to the output.

Parameters:

modules – Module to import.

add_from_import(module: str, *names: str) → None

Add a from module import name1, name2, ... import to the output.

Parameters:

• module – Module name.

• names – Names to import from module.

begin_retry_loop_if_live(num_attempts: int) → DrgnCodeBlockContext

Begin a loop that retries on transient FaultError or ValidationError errors if the program is live.

This must be paired with end_block() or used as a context manager.

Parameters:

num_attempts – Maximum number of attempts.

get() → str

Get the output as a string.

print() → None

Write the output to standard output.

has_declaration(variable: str) → bool

Return true if the variable is declared in the code.

Built-in commands exported as the “builtin_commands” plugin. All commands built into drgn should be defined in this package.

Functions for defining Linux kernel-specific commands.

drgn.commands.linux.linux_kernel_command(*args: Any, **kwargs: Any) → Any

Like command(), but only enables the command when debugging the Linux kernel.

If enabled is given, it is also checked in addition to the Linux kernel check.

drgn.commands.linux.linux_kernel_custom_command(*args: Any, **kwargs: Any) → Any

Like linux_kernel_command() but for custom_command().

drgn.commands.linux.linux_kernel_raw_command(*args: Any, **kwargs: Any) → Any

Like linux_kernel_command() but for raw_command().

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. Plugins can also register commands.

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.