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=None)

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

Parameters

platform (Optional[Platform]) – The platform of the program, or None if it should be determined automatically when a core dump or symbol file is added.

flags

Flags which apply to this program.

Vartype

ProgramFlags

platform

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

Vartype

Optional[Platform]

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 is Language.C. For userspace programs, this is determined from the language of main in the program, falling back to Language.C. This heuristic may change in the future.

Vartype

Language

__getitem__(name)

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 (str) – Object name.

Return type

Object

__contains__(name)

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

Parameters

name (str) – Object name.

Return type

bool

variable(name, filename=None)

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 (str) – The variable name.

  • filename (Optional[str]) – 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

Return type

Object

constant(name, filename=None)

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 (str) – The constant name.

  • filename (Optional[str]) – 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

Return type

Object

function(name, filename=None)

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 (str) – The function name.

  • filename (Optional[str]) – 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

Return type

Object

object(name, flags=FindObjectFlags.ANY, filename=None)

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

Parameters
  • name (str) – The object name.

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

  • filename (Optional[str]) – 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

Return type

Object

symbol(address_or_name)

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

Parameters

address_or_name (Union[IntegerLike, str]) – The address or name.

Raises

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

Return type

Symbol

stack_trace(thread)

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 (Union[Object, IntegerLike]) – Thread ID, struct pt_regs object, or struct task_struct * object.

Return type

StackTrace

type(name, filename=None)

Get the type with the given name.

>>> prog.type('long')
prog.int_type(name='long', size=8, is_signed=True)
Parameters
  • name (str) – The type name.

  • filename (Optional[str]) – 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

Return type

Type

read(address, size, physical=False)

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 (IntegerLike) – The starting address.

  • size (IntegerLike) – The number of bytes to read.

  • physical (bool) – 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

Return type

bytes

read_u8(address, physical=False)
Return type

int

read_u16(address, physical=False)
Return type

int

read_u32(address, physical=False)
Return type

int

read_u64(address, physical=False)
Return type

int

read_word(address, physical=False)

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 (IntegerLike) – Address of the integer.

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

Raises

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

Return type

int

add_memory_segment(address, size, read_fn, physical=False)

Define a region of memory in the program.

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

Parameters
  • address (IntegerLike) – Address of the segment.

  • size (IntegerLike) – Size of the segment in bytes.

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

  • read_fn (Callable[[int, int, int, bool], bytes]) – 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.

Return type

None

add_type_finder(fn)

Register a callback for finding types in the program.

Callbacks are called in reverse order of the order they were added until the type is found. So, more recently added callbacks take precedence.

Parameters

fn (Callable[[TypeKind, str, Optional[str]], Type]) – Callable taking a TypeKind, name, and filename: (kind, name, filename). The filename should be matched with filename_matches(). This should return a Type.

Return type

None

add_object_finder(fn)

Register a callback for finding objects in the program.

Callbacks are called in reverse order of the order they were added until the object is found. So, more recently added callbacks take precedence.

Parameters

fn (Callable[[Program, str, FindObjectFlags, Optional[str]], Object]) – Callable taking a program, name, FindObjectFlags, and filename: (prog, name, flags, filename). The filename should be matched with filename_matches(). This should return an Object.

Return type

None

set_core_dump(path)

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 (Path) – Core dump file path.

Return type

None

set_kernel()

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

Return type

None

set_pid(pid)

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 (int) – Process ID.

Return type

None

load_debug_info(paths=None, default=False, main=False)

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 (Optional[Iterable[Path]]) – Paths of binary files.

  • default (bool) –

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

    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

Return type

None

load_default_debug_info()

Load debugging information which can automatically be determined from the program.

This is equivalent to load_debug_info(None, True).

Return type

None

cache

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']
Vartype

Dict[Any, Any]

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

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

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, needle)

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 (Optional[str]) – Path of file containing definition.

  • needle (Optional[str]) – Filename to match.

Return type

bool

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)

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

Parameters

path (Path) – Core dump file path.

Return type

Program

drgn.program_from_kernel()

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

Return type

Program

drgn.program_from_pid(pid)

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

Parameters

pid (int) – Process ID of the program to debug.

Return type

Program

Platforms

class drgn.Platform

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

Platform(arch, flags=None)

Create a Platform.

Parameters
arch

Instruction set architecture of this platform.

Vartype

Architecture

flags

Flags which apply to this platform.

Vartype

PlatformFlags

registers

Processor registers on this platform.

Vartype

Sequence[Register]

class drgn.Architecture

Bases: enum.Enum

An Architecture represents an instruction set architecture.

X86_64

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

PPC64

The 64-bit PowerPC architecture.

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

Names of this register.

Vartype

Sequence[str]

drgn.host_platform

The platform of the host which is running drgn.

Vartype

Platform

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

Name of the programming language.

Vartype

str

C

The C programming language.

Vartype

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, type, value, *, bit_field_size=None)

Create a value object given its type and value.

Parameters
Object(prog, *, value)

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 (Union[int, float, bool]) – Value of the literal.

Object(prog, type, *, address, bit_offset=0, bit_field_size=None)

Create a reference object.

Parameters
  • address (IntegerLike) – Address of the object in the program.

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

Object(prog, type, *, bit_field_size=None)

Create an absent object.

prog_

Program that this object is from.

Vartype

Program

type_

Type of this object.

Vartype

Type

absent_

Whether this object is absent.

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

Vartype

bool

address_

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

Vartype

Optional[int]

bit_offset_

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.

Vartype

Optional[int]

bit_field_size_

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

Vartype

Optional[int]

__getattribute__(name)

Implement self.name.

If name is an attribute of the Object class, then this returns that attribute. Otherwise, it is equivalent to member_().

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

name (str) – Attribute name.

Return type

Object

__getitem__(idx)

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

>>> print(prog['init_task'].comm[0])
(char)115

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 (IntegerLike) – The array index.

Raises

TypeError – if this object is not a pointer or array

Return type

Object

__len__()

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

Return type

int

value_()

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)

Return type

Any

string_()

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

Return type

bytes

member_(name)

Get a member of this object.

This is valid for structures, unions, and pointers to either.

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 member or method.

Parameters

name (str) – 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

Return type

Object

address_of_()

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

Return type

Object

read_()

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)

Return type

Object

to_bytes_()

Return the binary representation of this object’s value.

Return type

bytes

classmethod from_bytes_(prog, type, bytes, *, bit_offset=0, bit_field_size=None)

Return a value object from its binary representation.

Parameters
  • prog (Program) – Program to create the object in.

  • type (Union[str, Type]) – Type of the object.

  • bytes (bytes) – Buffer containing value of the object.

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

  • bit_field_size (Optional[IntegerLike]) – 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.

Return type

Object

format_(*, columns=None, dereference=None, symbolize=None, string=None, char=None, type_name=None, member_type_names=None, element_type_names=None, members_same_line=None, elements_same_line=None, member_names=None, element_indices=None, implicit_members=None, implicit_elements=None)

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 (Optional[IntegerLike]) – Number of columns to limit output to when the expression can be reasonably wrapped. Defaults to no limit.

  • dereference (Optional[bool]) – 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 (Optional[bool]) – Include a symbol name and offset for pointer objects. Defaults to True.

  • string (Optional[bool]) – 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 (Optional[bool]) – Format objects with character type as character literals. For C, this applies to char, signed char, and unsigned char. Defaults to False.

  • type_name (Optional[bool]) – Include the type name of this object. Defaults to True.

  • member_type_names (Optional[bool]) – Include the type names of structure, union, and class members. Defaults to True.

  • element_type_names (Optional[bool]) – Include the type names of array elements. Defaults to False.

  • members_same_line (Optional[bool]) – 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 (Optional[bool]) – Place multiple array elements on the same line if they fit within the specified number of columns. Defaults to True.

  • member_names (Optional[bool]) – Include the names of structure, union, and class members. Defaults to True.

  • element_indices (Optional[bool]) – Include the indices of array elements. Defaults to False.

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

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

Return type

str

drgn.NULL(prog, type)

Get an object representing NULL casted to the given type.

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

Parameters
Return type

Object

drgn.cast(type, obj)

Get the value of the given object casted to another type.

Objects with a scalar type (integer, boolean, enumerated, floating-point, or pointer) can be casted to a different scalar type. Other objects can only be casted to the same type. This always results in a value object. See also drgn.reinterpret().

Parameters
Return type

Object

drgn.reinterpret(type, obj)

Get a copy of the given object reinterpreted as another type and/or byte order.

This reinterprets the raw memory of the object, so an object can be reinterpreted as any other type. However, value objects with a scalar type cannot be reinterpreted, as their memory layout in the program is not known. Reinterpreting a reference results in a reference, and reinterpreting a value results in a value. See also drgn.cast().

Parameters
  • type (Union[str, Type]) – The type to reinterpret as.

  • obj (Object) – The object to reinterpret.

Return type

Object

drgn.container_of(ptr, type, member)

Get the containing object of a pointer object.

This corresponds to the container_of() macro in C.

Parameters
  • ptr (Object) – Pointer to member in containing object.

  • type (Union[str, Type]) – Type of containing object.

  • member (str) – 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

Return type

Object

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.

name

Name of this symbol.

Vartype

str

address

Start address of this symbol.

Vartype

int

size

Size of this symbol in bytes.

Vartype

int

binding

Linkage behavior and visibility of this symbol.

Vartype

SymbolBinding

kind

Kind of entity represented by this symbol.

Vartype

SymbolKind

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 Program.stack_trace().

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.

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

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

Vartype

Optional[str]

is_inline

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

Vartype

bool

interrupted

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.

Vartype

bool

pc

Program counter at this stack frame.

Vartype

int

__getitem__(name)

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 (str) – Object name.

Return type

Object

__contains__(name)

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

Parameters

name (str) – Object name.

Return type

bool

source()

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

Return type

Tuple[str, int, int]

symbol()

Get the function symbol at this stack frame.

This is equivalent to:

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

Symbol

register(reg)

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

Parameters

reg (str) – Register name.

Raises
  • ValueError – if the register name is not recognized

  • LookupError – if the register value is not known

Return type

int

registers()

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

Return type

Dict[str, int]

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

Program that this type is from.

Vartype

Program

kind

Kind of this type.

Vartype

TypeKind

primitive

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

Vartype

Optional[PrimitiveType]

qualifiers

Bitmask of this type’s qualifier.

Vartype

Qualifiers

language

Programming language of this type.

Vartype

Language

name

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

Vartype

str

tag

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

Vartype

Optional[str]

size

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.

Vartype

Optional[int]

length

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

Vartype

Optional[int]

is_signed

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

Vartype

bool

byteorder

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.

Vartype

str

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.

Vartype

Type

members

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

Vartype

Optional[Sequence[TypeMember]]

enumerators

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

Vartype

Optional[Sequence[TypeEnumerator]]

parameters

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

Vartype

Sequence[TypeParameter]

is_variadic

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

Vartype

bool

template_parameters

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

Vartype

Sequence[TypeTemplateParameter]

type_name()

Get a descriptive full name of this type.

Return type

str

is_complete()

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.

Return type

bool

qualified(qualifiers)

Get a copy of this type with different qualifiers.

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

Parameters

qualifiers (Qualifiers) – New type qualifiers.

Return type

Type

unqualified()

Get a copy of this type with no qualifiers.

Return type

Type

member(name)

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

Return type

TypeMember

has_member(name)

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 (str) – Name of the member.

Raises

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

Return type

bool

class drgn.TypeMember

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

TypeMember(object_or_type, name=None, bit_offset=0)

Create a TypeMember.

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

Vartype

Object

type

Member type.

This is a shortcut for TypeMember.object.type.

Vartype

Type

name

Member name, or None if the member is unnamed.

Vartype

Optional[str]

bit_offset

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

Vartype

int

offset

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

Vartype

int

bit_field_size

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

Vartype

Optional[int]

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, value)

Create a TypeEnumerator.

Parameters
name

Enumerator name.

Vartype

str

value

Enumerator value.

Vartype

int

class drgn.TypeParameter

A TypeParameter represents a parameter of a function type.

TypeParameter(default_argument_or_type, name=None)

Create a TypeParameter.

Parameters
default_argument

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.

Vartype

Object

type

Parameter type.

This is the same as TypeParameter.default_argument.type_.

Vartype

Type

name

Parameter name, or None if the parameter is unnamed.

Vartype

Optional[str]

class drgn.TypeTemplateParameter

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

TypeTemplateParameter(argument, name=None, is_default=False)

Create a TypeTemplateParameter.

Parameters
argument

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.

Vartype

Union[Type, Object]

name

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

Vartype

Optional[str]

is_default

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.

Vartype

bool

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.

COMPLEX

Complex 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.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.offsetof(type, member)

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

This corresponds to offsetof() in C.

Parameters
  • type (Type) – Structure, union, or class type.

  • member (str) – 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

Return type

int

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.NONE, language=None)

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

Parameters
Return type

Type

Program.int_type(name, size, is_signed, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.bool_type(name, size, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.float_type(name, size, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.struct_type(tag, size, members, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.struct_type(tag, size=None, members=None, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

Create a new incomplete structure type.

Return type

Type

Program.union_type(tag, size, members, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

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

Return type

Type

Program.union_type(tag, size=None, members=None, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

Create a new incomplete union type.

Return type

Type

Program.class_type(tag, size, members, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

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

Return type

Type

Program.class_type(tag, size=None, members=None, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

Create a new incomplete class type.

Return type

Type

Program.enum_type(tag, type, enumerators, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.enum_type(tag, type=None, enumerators=None, *, qualifiers=Qualifiers.NONE, language=None)

Create a new incomplete enumerated type.

Return type

Type

Program.typedef_type(name, type, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.pointer_type(type, size=None, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.array_type(type, length=None, *, qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Program.function_type(type, parameters, is_variadic=False, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)

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

Parameters
Return type

Type

Miscellaneous

drgn.sizeof(type_or_obj)

Get the size of a Type or Object in bytes.

Parameters

type_or_obj (Union[Type, Object]) – Entity to get the size of.

Raises

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

Return type

int

drgn.execscript(path, *args)

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(prog)
    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(prog, 357954))
'/usr/bin/vim'
Parameters
  • path (str) – File path of the script.

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

Return type

None

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

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, address)
Parameters
message

Error message.

Vartype

str

address

Address that couldn’t be accessed.

Vartype

int

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.