API Reference

Programs

class drgn.Program

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

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

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

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

Parameters:

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

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

flags: ProgramFlags

Flags which apply to this program.

platform: Optional[Platform]

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

language: Language

Default programming language of the program.

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

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

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

__getitem__(name: str) → Object

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

This is equivalent to prog.object(name) except that this raises KeyError instead of LookupError if no objects with the given name are found.

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

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

name – Object name.

__contains__(name: str) → bool

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

Parameters:

name – Object name.

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

Get the variable with the given name.

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

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

Parameters:

  • name – The variable name.

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

Raises:

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

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

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

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

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

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

Parameters:

  • name – The constant name.

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

Raises:

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

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

Get the function with the given name.

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

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

Parameters:

  • name – The function name.

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

Raises:

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

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

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

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

Parameters:

  • name – The object name.

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

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

Raises:

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

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

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

Global symbols are preferred over weak symbols, and weak symbols are preferred over other symbols. In other words: if a matching SymbolBinding.GLOBAL or SymbolBinding.UNIQUE symbol is found, it is returned. Otherwise, if a matching SymbolBinding.WEAK symbol is found, it is returned. Otherwise, any matching symbol (e.g., SymbolBinding.LOCAL) is returned. If there are multiple matching symbols with the same binding, one is returned arbitrarily. To retrieve all matching symbols, use symbols().

Parameters:

address_or_name – Address or name to search for.

Raises:

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

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

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

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

Parameters:

address_or_name – Address or name to search for.

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

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

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

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

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

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

Parameters:

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

stack_trace_from_pcs(pcs: Sequence[IntegerLike]) → StackTrace

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

Parameters:

pcs – List of program counters.

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

Get the type with the given name.

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

  • name – The type name.

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

Raises:

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

type(type: Type, /) → Type

Return the given type.

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

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

type – Type.

Returns:

The exact same type.

threads() → Iterator[Thread]

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

thread(tid: IntegerLike) → Thread

Get the thread with the given thread ID.

Parameters:

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

Raises:

LookupError – if no thread has the given thread ID

main_thread() → Thread

Get the main thread of the program.

This is only defined for userspace programs.

Raises:

ValueError – if the program is the Linux kernel

crashed_thread() → Thread

Get the thread that caused the program to crash.

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

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

Raises:

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

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

Read size bytes of memory starting at address in the program. The address may be virtual (the default) or physical if the program supports it.

>>> prog.read(0xffffffffbe012b40, 16)
b'swapper/0'
Parameters:

  • address – The starting address.

  • size – The number of bytes to read.

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

Raises:

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

  • ValueError – if size is negative

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

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

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

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

Parameters:

  • address – Address of the integer.

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

Raises:

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

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

Define a region of memory in the program.

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

Parameters:

  • address – Address of the segment.

  • size – Size of the segment in bytes.

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

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

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

Register a callback for finding types in the program.

This does not enable the finder unless enable_index is given.

Parameters:

  • name – Finder name.

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

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

Raises:

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

registered_type_finders() → Set[str]

Return the names of all registered type finders.

set_enabled_type_finders(names: Sequence[str]) → None

Set the list of enabled type finders.

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

Finders that are not in the list are not called.

Parameters:

names – Names of finders to enable, in order.

Raises:

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

enabled_type_finders() → List[str]

Return the names of enabled type finders, in order.

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

Register a callback for finding objects in the program.

This does not enable the finder unless enable_index is given.

Parameters:

  • name – Finder name.

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

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

Raises:

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

registered_object_finders() → Set[str]

Return the names of all registered object finders.

set_enabled_object_finders(names: Sequence[str]) → None

Set the list of enabled object finders.

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

Finders that are not in the list are not called.

Parameters:

names – Names of finders to enable, in order.

Raises:

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

enabled_object_finders() → List[str]

Return the names of enabled object finders, in order.

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

Register a callback for finding symbols in the program.

This does not enable the finder unless enable_index is given.

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

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

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

Parameters:

  • name – Finder name.

  • fn – Callable taking (prog, name, address, one) and returning a sequence of Symbols.

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

Raises:

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

registered_symbol_finders() → Set[str]

Return the names of all registered symbol finders.

set_enabled_symbol_finders(names: Sequence[str]) → None

Set the list of enabled symbol finders.

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

Finders that are not in the list are not called.

Parameters:

names – Names of finders to enable, in order.

Raises:

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

enabled_symbol_finders() → List[str]

Return the names of enabled symbol finders, in order.

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

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

Deprecated since version 0.0.27: Use register_type_finder() instead.

The differences from register_type_finder() are:

  1. fn is not passed prog.

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

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

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

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

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

Deprecated since version 0.0.27: Use register_object_finder() instead.

The differences from register_object_finder() are:

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

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

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

Set the program to a core dump.

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

Parameters:

path – Core dump file path or open file descriptor.

set_kernel() → None

Set the program to the running operating system kernel.

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

set_pid(pid: int) → None

Set the program to a running process.

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

Parameters:

pid – Process ID.

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

Load debugging information for a list of executable or library files.

Note that this is parallelized, so it is usually faster to load multiple files at once rather than one by one.

Parameters:

  • paths – Paths of binary files.

  • default –

    Also load debugging information which can automatically be determined from the program.

    For the Linux kernel, this tries to load vmlinux and any loaded kernel modules from a few standard locations.

    For userspace programs, this tries to load the executable and any loaded libraries.

    This implies main=True.

  • main –

    Also load debugging information for the main executable.

    For the Linux kernel, this tries to load vmlinux.

    This is currently ignored for userspace programs.

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 debugging information which can automatically be determined from the program.

This is equivalent to load_debug_info(None, True).

cache: Dict[Any, Any]

Dictionary for caching program metadata.

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

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

Bases: enum.Flag

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

IS_LINUX_KERNEL

The program is the Linux kernel.

IS_LIVE

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

IS_LOCAL

The program is running on the local machine.

class drgn.FindObjectFlags

Bases: enum.Flag

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

CONSTANT
FUNCTION
VARIABLE
ANY
class drgn.Thread

A thread in a program.

tid: Final[int]

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

name: Optional[str]

Thread name, or None if unknown.

See PR_SET_NAME and /proc/pid/comm.

Note

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

object: Final[Object]

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

stack_trace() → StackTrace

Get the stack trace for this thread.

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

Filenames

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

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

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

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

Parameters:

  • haystack – Path of file containing definition.

  • needle – Filename to match.

Program Constructors

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

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

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

Parameters:

path – Core dump file path or open file descriptor.

drgn.program_from_kernel() → Program

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

drgn.program_from_pid(pid: int) → Program

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

Parameters:

pid – Process ID of the program to debug.

Default Program

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

Note

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

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

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

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

  3. Otherwise, the default program is used.

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

drgn.get_default_prog() → Program

Get the default program for the current thread.

Raises:

NoDefaultProgramError – if the default program is not set

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

Set the default program for the current thread.

Parameters:

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

class drgn.NoDefaultProgramError

Bases: Exception

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

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

Platforms

class drgn.Platform

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

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

Create a Platform.

Parameters:
arch: Final[Architecture]

Instruction set architecture of this platform.

flags: Final[PlatformFlags]

Flags which apply to this platform.

registers: Final[Sequence[Register]]

Processor registers on this platform.

class drgn.Architecture

Bases: enum.Enum

An Architecture represents an instruction set architecture.

X86_64

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

I386

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

AARCH64

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

ARM

The 32-bit Arm architecture.

PPC64

The 64-bit PowerPC architecture.

RISCV64

The 64-bit RISC-V architecture.

RISCV32

The 32-bit RISC-V architecture.

S390X

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

S390

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

UNKNOWN

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

class drgn.PlatformFlags

Bases: enum.Flag

PlatformFlags are flags describing a Platform.

IS_64_BIT

Platform is 64-bit.

IS_LITTLE_ENDIAN

Platform is little-endian.

class drgn.Register

A Register represents information about a processor register.

names: Final[Sequence[str]]

Names of this register.

drgn.host_platform: Platform

The platform of the host which is running drgn.

Languages

class drgn.Language

A Language represents a programming language supported by drgn.

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

name: Final[str]

Name of the programming language.

C: ClassVar[Language]

The C programming language.

CPP: ClassVar[Language]

The C++ programming language.

Objects

class drgn.Object

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

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

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

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

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

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

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

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

Note

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

Objects support the following operators:

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

  • Bitwise operators: <<, >>, &, |, ^, ~

  • Relational operators: ==, !=, <, >, <=, >=

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

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

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

  • Array length: len()

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

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

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

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

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

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

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

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

Create a value object given its type and value.

Parameters:

  • prog – Program to create the object in.

  • type – Type of the object.

  • value – Value of the object. See value_().

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

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

Create a value object from a “literal”.

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

Parameters:

value – Value of the literal.

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

Create a reference object.

Parameters:

  • address – Address of the object in the program.

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

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

Create an absent object.

prog_: Final[Program]

Program that this object is from.

type_: Final[Type]

Type of this object.

absent_: Final[bool]

Whether this object is absent.

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

address_: Final[Optional[int]]

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

bit_offset_: Final[Optional[int]]

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

bit_field_size_: Final[Optional[int]]

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

__getattr__(name: str) → Object

Implement self.name.

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

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

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

name – Attribute name.

__getitem__(idx: IntegerLike) → Object

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

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

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

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

This is only valid for pointers and arrays.

Note

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

Parameters:

idx – The array index.

Raises:

TypeError – if this object is not a pointer or array

__len__() → int

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

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

This is only valid for arrays.

Raises:

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

value_() → Any

Get the value of this object as a Python object.

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

Raises:

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

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

string_() → bytes

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

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

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

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

Raises:

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

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

member_(name: str) → Object

Get a member of this object.

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

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

Parameters:

name – Name of the member.

Raises:

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

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

address_of_() → Object

Get a pointer to this object.

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

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

Raises:

ValueError – if this object is a value

read_() → Object

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

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

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

Raises:

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

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

to_bytes_() → bytes

Return the binary representation of this object’s value.

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

Return a value object from its binary representation.

>>> print(Object.from_bytes_(prog, "int", b""))
(int)16
Parameters:

  • prog – Program to create the object in.

  • type – Type of the object.

  • bytes – Buffer containing value of the object.

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

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

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

Format this object in programming language syntax.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Get an object representing NULL casted to the given type.

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

Parameters:

  • prog – The program.

  • type – The type.

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

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

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

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

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

Parameters:

  • type – Type to cast to.

  • obj – Object to cast.

Returns:

Casted object. This is always a value object.

Raises:

TypeError – if casting obj to type is not allowed

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

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

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

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

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

Parameters:

  • type – Type to convert to.

  • obj – Object to convert.

Returns:

Converted object. This is always a value object.

Raises:

TypeError – if converting obj to type is not allowed

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

Get the representation of an object reinterpreted as another type.

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

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

Note

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

Parameters:

  • type – Type to reinterpret as.

  • obj – Object to reinterpret.

Returns:

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

Raises:

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

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

Get the containing object of a pointer object.

This corresponds to the container_of() macro in C.

Parameters:

  • ptr – Pointer to member in containing object.

  • type – Type of containing object.

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

Returns:

Pointer to containing object.

Raises:

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

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

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

Symbols

class drgn.Symbol

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

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

Create a Symbol.

Parameters:
name: Final[str]

Name of this symbol.

address: Final[int]

Start address of this symbol.

size: Final[int]

Size of this symbol in bytes.

binding: Final[SymbolBinding]

Linkage behavior and visibility of this symbol.

kind: Final[SymbolKind]

Kind of entity represented by this symbol.

class drgn.SymbolBinding

Bases: enum.Enum

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

UNKNOWN

Unknown.

LOCAL

Not visible outside of the object file containing its definition.

GLOBAL

Globally visible.

WEAK

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

UNIQUE

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

class drgn.SymbolKind

Bases: enum.Enum

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

UNKNOWN

Unknown or not defined.

OBJECT

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

FUNC

Function or other executable code.

SECTION

Object file section.

FILE

Source file.

COMMON

Data object in common block.

TLS

Thread-local storage entity.

IFUNC

Indirect function.

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[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. It may be desirable to use the symbol name or program counter as a fallback:

name = frame.name
if name is None:
    try:
        name = frame.symbol().name
    except LookupError:
        name = hex(frame.pc)
is_inline: Final[bool]

Whether this frame is for an inlined call.

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

interrupted: Final[bool]

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

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

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

pc: Final[int]

Program counter at this stack frame.

sp: Final[int]

Stack pointer at this stack frame.

__getitem__(name: str) → Object

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

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

Parameters:

name – Object name.

__contains__(name: str) → bool

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

Parameters:

name – Object name.

locals() → List[str]

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

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

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

Get the source code location of this frame.

Returns:

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

Raises:

LookupError – if the source code location is not available

symbol() → Symbol

Get the function symbol at this stack frame.

This is equivalent to:

prog.symbol(frame.pc - (0 if frame.interrupted else 1))
register(reg: str) → int

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

Parameters:

reg – Register name.

Raises:

  • ValueError – if the register name is not recognized

  • LookupError – if the register value is not known

registers() → Dict[str, int]

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

Types

class drgn.Type

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

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

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

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

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

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

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

prog: Final[Program]

Program that this type is from.

kind: Final[TypeKind]

Kind of this type.

primitive: Final[Optional[PrimitiveType]]

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

qualifiers: Final[Qualifiers]

Bitmask of this type’s qualifier.

language: Final[Language]

Programming language of this type.

name: Final[str]

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

tag: Final[Optional[str]]

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

size: Final[Optional[int]]

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

length: Final[Optional[int]]

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

is_signed: Final[bool]

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

byteorder: Final[str]

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

type: Final[Type]

Type underlying this type, defined as follows:

  • For typedef types, the aliased type.

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

  • For pointer types, the referenced type.

  • For array types, the element type.

  • For function types, the return type.

For other types, this attribute is not present.

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

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

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

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

parameters: Final[Sequence[TypeParameter]]

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

is_variadic: Final[bool]

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

template_parameters: Final[Sequence[TypeTemplateParameter]]

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

type_name() → str

Get a descriptive full name of this type.

is_complete() → bool

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

qualified(qualifiers: Qualifiers) → Type

Get a copy of this type with different qualifiers.

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

Parameters:

qualifiers – New type qualifiers.

unqualified() → Type

Get a copy of this type with no qualifiers.

member(name: str) → TypeMember

Look up a member in this type by name.

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

Parameters:

name – Name of the member.

Raises:

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

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

has_member(name: str) → bool

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

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

Parameters:

name – Name of the member.

Raises:

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

class drgn.TypeMember

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

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

Create a TypeMember.

Parameters:
object: Final[Object]

Member as an Object.

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

type: Final[Type]

Member type.

This is a shortcut for TypeMember.object.type.

name: Final[Optional[str]]

Member name, or None if the member is unnamed.

bit_offset: Final[int]

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

offset: Final[int]

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

bit_field_size: Final[Optional[int]]

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

This is a shortcut for TypeMember.object.bit_field_size_.

class drgn.TypeEnumerator

A TypeEnumerator represents a constant in an enumerated type.

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

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

Create a TypeEnumerator.

Parameters:
name: Final[str]

Enumerator name.

value: Final[int]

Enumerator value.

class drgn.TypeParameter

A TypeParameter represents a parameter of a function type.

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

Create a TypeParameter.

Parameters:
default_argument: Final[Object]

Default argument for parameter.

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

Note

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

type: Final[Type]

Parameter type.

This is the same as TypeParameter.default_argument.type_.

name: Final[Optional[str]]

Parameter name, or None if the parameter is unnamed.

class drgn.TypeTemplateParameter

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

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

Create a TypeTemplateParameter.

Parameters:
argument: Final[Union[Type, Object]]

Template argument.

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

name: Final[Optional[str]]

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

is_default: Final[bool]

Whether argument is the default for the template parameter.

Note

There are two ways to interpret this:

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

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

Compilers are inconsistent about which interpretation they use.

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

class drgn.TypeKind

Bases: enum.Enum

A TypeKind represents a kind of type.

VOID

Void type.

INT

Integer type.

BOOL

Boolean type.

FLOAT

Floating-point type.

STRUCT

Structure type.

UNION

Union type.

CLASS

Class type.

ENUM

Enumerated type.

TYPEDEF

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

POINTER

Pointer type.

ARRAY

Array type.

FUNCTION

Function type.

class drgn.TypeKindSet

Bases: collections.abc.Set[TypeKind]

Immutable set of TypeKinds.

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

Bases: enum.Enum

A PrimitiveType represents a primitive type known to drgn.

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

Bases: enum.Flag

Qualifiers are modifiers on types.

NONE

No qualifiers.

CONST

Constant type.

VOLATILE

Volatile type.

RESTRICT

Restrict type.

ATOMIC

Atomic type.

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

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

This corresponds to _Alignof() in C.

Raises:

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

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

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

This corresponds to offsetof() in C.

Parameters:

  • type – Structure, union, or class type.

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

Raises:

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

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

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

Type Constructors

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

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

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

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

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

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

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

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

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

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

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

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

Create a new incomplete structure type.

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

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

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

Create a new incomplete union type.

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

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

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

Create a new incomplete class type.

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

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

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

Create a new incomplete enumerated type.

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

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

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

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

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

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

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

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

Parameters:

Miscellaneous

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

Get the size of a Type or Object in bytes.

Parameters:

type_or_obj – Entity to get the size of.

Raises:

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

drgn.execscript(path: str, *args: str) → None

Execute a script.

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

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

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

import sys

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

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

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

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

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

  • path – File path of the script.

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

class drgn.IntegerLike

Bases: Protocol

An int or integer-like object.

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

drgn.Path: TypeAlias

Filesystem path.

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

Exceptions

class drgn.FaultError

Bases: Exception

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

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

Error message.

address: int

Address that couldn’t be accessed.

class drgn.MissingDebugInfoError

Bases: Exception

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

class drgn.ObjectAbsentError

Bases: Exception

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

class drgn.OutOfBoundsError

Bases: Exception

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

CLI

Functions for embedding the drgn CLI.

drgn.cli.version_header() → str

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

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

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

Run drgn’s Interactive Mode until the user exits.

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

Parameters:

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

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

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

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

Note

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

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

Logging

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

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.