• Instead of *ptr, dereference a pointer with ptr[0].
• Instead of ptr->member, access a member through a pointer with ptr.member.
• Instead of &var, get the address of a variable with var.address_of_().

• The drgn.Object.value_() method gets the value of the object with the directly corresponding Python type (i.e., integers and pointers become int, floating-point types become float, booleans become bool, arrays become list, structures and unions become dict).
• The drgn.Object.string_() method gets a null-terminated string as bytes from an array or pointer.
• The int(), float(), and bool() functions do an explicit conversion to that Python type.

• History
• Tab completion
• Automatic import of relevant helpers
• Pretty printing of objects and types

DRGN_MAX_DEBUG_INFO_ERRORS

The maximum number of individual errors to report in a drgn.MissingDebugInfoError. Any additional errors are truncated. The default is 5; -1 is unlimited.

DRGN_PREFER_ORC_UNWINDER

Whether to prefer using ORC over DWARF for stack unwinding (0 or 1). The default is 0. Note that drgn will always fall back to ORC for functions lacking DWARF call frame information and vice versa. This environment variable is mainly intended for testing and may be ignored in the future.

DRGN_USE_LIBDWFL_REPORT

Whether drgn should use libdwfl to find debugging information for core dumps instead of its own implementation (0 or 1). The default is 0. This environment variable is mainly intended as an escape hatch in case of bugs in drgn's implementation and will be ignored in the future.

DRGN_USE_LIBKDUMPFILE_FOR_ELF

Whether drgn should use libkdumpfile for ELF vmcores (0 or 1). The default is 0. This functionality will be removed in the future.

DRGN_USE_SYS_MODULE

Whether drgn should use /sys/module to find information about loaded kernel modules for the running kernel instead of getting them from the core dump (0 or 1). The default is 1. This environment variable is mainly intended for testing and may be ignored in the future.

PYTHON_BASIC_REPL

If non-empty, don't try to use the new interactive REPL added in Python 3.13. drgn makes use of the new REPL through internal implementation details since there is not yet a public API for it. If it breaks, this may be used as an escape hatch.

UTS_RELEASE

Object type: const char []

This corresponds to the UTS_RELEASE macro in the Linux kernel source code. This is the exact kernel release (i.e., the output of uname -r).

To use this as a Python string, you must convert it:

>>> release = prog["UTS_RELEASE"].string_().decode("ascii")

This is available without debugging information.

PAGE_SIZE

Object type: unsigned long

PAGE_SHIFT

Object type: unsigned int

PAGE_MASK

Object type: unsigned long

These correspond to the macros of the same name in the Linux kernel source code. The page size is the smallest contiguous unit of physical memory which can be allocated or mapped by the kernel.

>>> prog['PAGE_SIZE']
(unsigned long)4096
>>> prog['PAGE_SHIFT']
(int)12
>>> prog['PAGE_MASK']
(unsigned long)18446744073709547520
>>> 1 << prog['PAGE_SHIFT'] == prog['PAGE_SIZE']
True
>>> ~(prog['PAGE_SIZE'] - 1) == prog['PAGE_MASK']
True
    

These are available without debugging information.

jiffies

Object type: volatile unsigned long

This is a counter of timer ticks. It is actually an alias of jiffies_64 on 64-bit architectures, or the least significant 32 bits of jiffies_64 on 32-bit architectures. Since this alias is defined via the linker, drgn handles it specially.

This is not available without debugging information.

vmemmap

Object type: struct page *

This is a pointer to the "virtual memory map", an array of struct page for each physical page of memory. While the purpose and implementation details of this array are beyond the scope of this documentation, it is enough to say that it is represented in the kernel source in an architecture-dependent way, frequently as a macro or constant. The definition provided by drgn ensures that users can access it without resorting to architecture-specific logic.

This is not available without debugging information.

VMCOREINFO

Object type: const char []

This is the data contained in the vmcoreinfo note, which is present either as an ELF note in /proc/kcore or ELF vmcores, or as a special data section in kdump-formatted vmcores. The vmcoreinfo note contains critical data necessary for interpreting the kernel image, such as KASLR offsets and data structure locations.

In the Linux kernel, this data is normally stored in a variable called vmcoreinfo_data. However, drgn reads this information from ELF note or from the diskdump header. It is possible (in rare cases, usually with vmcores created by hypervisors) for a vmcore to contain vmcoreinfo which differs from the data in vmcoreinfo_data, so it is important to distinguish the contents. For that reason, we use the name VMCOREINFO to distinguish it from the kernel variable vmcoreinfo_data.

This is available without debugging information.

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.

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)

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

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.

class drgn.Thread

A thread in a program.

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.

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.

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

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.

drgn.get_default_prog() -> Program

Get the default program for the current thread.

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

Set the default program for the current thread.

class drgn.NoDefaultProgramError

Bases: Exception

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

class drgn.Platform

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

class drgn.Architecture

Bases: enum.Enum

An Architecture represents an instruction set architecture.

class drgn.PlatformFlags

Bases: enum.Flag

PlatformFlags are flags describing a Platform.

class drgn.Register

A Register represents information about a processor register.

drgn.host_platform: Platform

The platform of the host which is running drgn.

class drgn.Language

A Language represents a programming language supported by drgn.

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

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:

Objects support the following operators:

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

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

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.

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.

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:

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.

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.

class drgn.SymbolBinding

Bases: enum.Enum

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

class drgn.SymbolKind

Bases: enum.Enum

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

class drgn.SymbolIndex

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

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

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


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


  File "<console>", line 1, in <module>
LookupError: not found
>>> prog.symbol(0x123)
Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)

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.

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 = frame.name
if name is None:


    try:


        name = frame.symbol().name


    except LookupError:


        name = hex(frame.pc)

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

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.

class drgn.TypeMember

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

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
    

class drgn.TypeParameter

A TypeParameter represents a parameter of a function type.

class drgn.TypeTemplateParameter

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

class drgn.TypeKind

Bases: enum.Enum

A TypeKind represents a kind of 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.

class drgn.Qualifiers

Bases: enum.Flag

Qualifiers are modifiers on types.

drgn.alignof(type: Type, /) -> int

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

This corresponds to _Alignof() in C.

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

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

This corresponds to offsetof() in C.

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

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

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.

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.

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.

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.

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.

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.

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,

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.

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.

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

Get the size of a Type or Object in bytes.

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'

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.

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

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.

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.

NOTE:

class drgn.helpers.ValidationError

Bases: Exception

Error raised by a validator when an inconsistent or invalid state is detected.

drgn.helpers.common.format.escape_ascii_character(c: int, escape_single_quote: bool = False, escape_double_quote: bool = False, escape_backslash: bool = False) -> str

Format an ASCII byte value as a character, possibly escaping it. Non-printable characters are always escaped. Non-printable characters other than \0, \a, \b, \t, \n, \v, \f, and \r are escaped in hexadecimal format (e.g., \x7f). By default, printable characters are never escaped.

drgn.helpers.common.format.escape_ascii_string(buffer: Iterable[int], escape_single_quote: bool = False, escape_double_quote: bool = False, escape_backslash: bool = False) -> str

Escape an iterable of ASCII byte values (e.g., bytes or bytearray). See escape_ascii_character().

drgn.helpers.common.format.decode_flags(value: drgn.IntegerLike, flags: Iterable[Tuple[str, int]], bit_numbers: bool = True) -> str

Get a human-readable representation of a bitmask of flags.

By default, flags are specified by their bit number:

>>> decode_flags(2, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'ITALIC'
    

They can also be specified by their value:

>>> decode_flags(2, [("BOLD", 1), ("ITALIC", 2), ("UNDERLINE", 4)],
...              bit_numbers=False)
'ITALIC'
    

Multiple flags are combined with "|":

>>> decode_flags(5, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'BOLD|UNDERLINE'
    

If there are multiple names for the same bit, they are all included:

>>> decode_flags(2, [("SMALL", 0), ("BIG", 1), ("LARGE", 1)])
'BIG|LARGE'
    

If there are any unknown bits, their raw value is included:

>>> decode_flags(27, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'BOLD|ITALIC|0x18'
    

Zero is returned verbatim:

>>> decode_flags(0, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'0'
    

drgn.helpers.common.format.decode_enum_type_flags(value: drgn.IntegerLike, type: drgn.Type, bit_numbers: bool = True) -> str

Get a human-readable representation of a bitmask of flags where the flags are specified by an enumerated drgn.Type.

This supports enums where the values are bit numbers:

>>> print(bits_enum)
enum style_bits {


        BOLD = 0,


        ITALIC = 1,


        UNDERLINE = 2,
}
>>> decode_enum_type_flags(5, bits_enum)
'BOLD|UNDERLINE'
    

Or the values of the flags:

>>> print(flags_enum)
enum style_flags {


        BOLD = 1,


        ITALIC = 2,


        UNDERLINE = 4,
}
>>> decode_enum_type_flags(5, flags_enum, bit_numbers=False)
'BOLD|UNDERLINE'
    

See decode_flags().

drgn.helpers.common.format.number_in_binary_units(n: SupportsFloat, precision: int = 1) -> str

Format a number in binary units (i.e., "K" is 1024, "M" is 10242, etc.).

>>> number_in_binary_units(1280)
'1.2K'
    

A precision can be specified:

>>> number_in_binary_units(1280, precision=2)
'1.25K'
    

Exact numbers are printed without a fractional part:

>>> number_in_binary_units(1024 * 1024)
'1M'
    

Numbers less than 1024 are not scaled:

>>> number_in_binary_units(10)
'10'
    

drgn.helpers.common.memory.identify_address(prog: drgn.Program, addr: drgn.IntegerLike, *, cache: Optional[Dict[Any, Any]] = None) -> Optional[str]

Try to identify what an address refers to.

For all programs, this will identify addresses as follows:

Additionally, for the Linux kernel, this will identify:

This may recognize other types of addresses in the future.

drgn.helpers.common.memory.print_annotated_memory(prog: drgn.Program, address: drgn.IntegerLike, size: drgn.IntegerLike, physical: bool = False) -> None

Print the contents of a range of memory, annotating values that can be identified.

Currently, this will identify any addresses in the memory range with identify_address().

See print_annotated_stack() for a similar function that annotates stack traces.

>>> print_annotated_memory(0xffffffff963eb200, 56)
ADDRESS           VALUE
ffffffff963eb200: 00000000000000b8
ffffffff963eb208: 000000000000a828
ffffffff963eb210: 0000000000000000
ffffffff963eb218: ffff8881042948e0 [slab object: mnt_cache+0x20]
ffffffff963eb220: ffff88810074a540 [slab object: dentry+0x0]
ffffffff963eb228: ffff8881042948e0 [slab object: mnt_cache+0x20]
ffffffff963eb230: ffff88810074a540 [slab object: dentry+0x0]
    

drgn.helpers.common.prog.takes_program_or_default(f: TakesProgram[P, R]) -> TakesProgramOrDefault[P, R]

Wrap a function taking a Program so that it uses the default program argument if omitted.

@takes_program_or_default
def my_helper(prog: Program, n: IntegerLike) -> Foo:


    ...
my_helper(1)
# is equivalent to
my_helper(get_default_prog(), 1)
obj = Object(...)
my_helper(obj)
# is equivalent to
my_helper(obj.prog_, obj)

drgn.helpers.common.prog.takes_object_or_program_or_default(f: Callable[Concatenate[drgn.Program, Optional[drgn.Object], P], R]) -> TakesObjectOrProgramOrDefault[P, R]

Wrap a function taking a Program and an optional Object so that it accepts a Program or an Object or neither, in which case the default program argument is used.

@takes_object_or_program_or_default
def my_helper(prog: Program, obj: Optional[Object], n: IntegerLike) -> Foo:


    ...
my_helper(prog, 1)
# is equivalent to
my_helper.__wrapped__(prog, None, 1)
obj = Object(...)
my_helper(obj, 1)
# is equivalent to
my_helper.__wrapped__(obj.prog_, obj, 1)
my_helper(1)
# is equivalent to
my_helper.__wrapped__(get_default_prog(), None, 1)
one_obj = Object(..., 1)
my_helper(one_obj)
# is equivalent to
my_helper.__wrapped__(one_obj.prog_, None, one_obj)

WARNING:

# NOT ALLOWED
@takes_object_or_program_or_default
def my_helper(prog: Program, obj: Optional[Object], foo: str = ""): ...
# OK
@takes_object_or_program_or_default
def my_helper(prog: Program, obj: Optional[Object], *, foo: str = ""): ...

NOTE:

drgn.helpers.common.stack.print_annotated_stack(trace: drgn.StackTrace) -> None

Print the contents of stack memory in a stack trace, annotating values that can be identified.

Currently, this will identify any addresses on the stack with identify_address().

See print_annotated_memory() for a similar function that annotates arbitrary memory ranges.

>>> print_annotated_stack(stack_trace(1))
STACK POINTER     VALUE
[stack frame #0 at 0xffffffff8dc93c41 (__schedule+0x429/0x488) in context_switch at ./kernel/sched/core.c:5209:2 (inlined)]
[stack frame #1 at 0xffffffff8dc93c41 (__schedule+0x429/0x488) in __schedule at ./kernel/sched/core.c:6521:8]
ffffa903c0013d28: ffffffff8d8497bf [function symbol: __flush_tlb_one_user+0x5]
ffffa903c0013d30: 000000008d849eb5
ffffa903c0013d38: 0000000000000001
ffffa903c0013d40: 0000000000000004
ffffa903c0013d48: efdea37bb7cb1f00
ffffa903c0013d50: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d58: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d60: ffffa903c0013e10
ffffa903c0013d68: ffff926641177ff0 [slab object: mm_struct+0x70]
ffffa903c0013d70: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d78: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d80: ffffffff8dc93d29 [function symbol: schedule+0x89]
...
    

drgn.helpers.common.type.enum_type_to_class(type: drgn.Type, name: str, exclude: Container[str] = (), prefix: str = '') -> Type[enum.IntEnum]

Get an enum.IntEnum class from an enumerated drgn.Type.

drgn.helpers.common.type.member_at_offset(type: drgn.Type, offset: drgn.IntegerLike) -> str

Return the name of the member at an offset in a type.

This is effectively the opposite of offsetof().

>>> prog.type('struct list_head')
struct list_head {


        struct list_head *next;


        struct list_head *prev;
}
>>> member_at_offset(prog.type('struct list_head'), 0)
'next'
>>> member_at_offset(prog.type('struct list_head'), 8)
'prev'
    

This includes nested structures and array elements:

>>> prog.type('struct sigpending')
struct sigpending {


        struct list_head list;


        sigset_t signal;
}
>>> prog.type('sigset_t')
typedef struct {


        unsigned long sig[1];
} sigset_t
>>> member_at_offset(prog.type('struct sigpending'), 0)
'list.next'
>>> member_at_offset(prog.type('struct sigpending'), 8)
'list.prev'
>>> member_at_offset(prog.type('struct sigpending'), 16)
'signal.sig[0]'
    

This also includes all possible matches for a union:

>>> prog.type('union mc_target')
union mc_target {


        struct folio *folio;


        swp_entry_t ent;
}
>>> prog.type('swp_entry_t')
typedef struct {


        unsigned long val;
} swp_entry_t
>>> member_at_offset(prog.type('union mc_target'), 0)
'folio or ent.val'
    

Offsets in the middle of a member are represented:

>>> member_at_offset(prog.type('struct list_head'), 4)
'next+0x4'
    

Offsets in padding or past the end of the type are also represented:

>>> prog.type('struct autogroup')
struct autogroup {


        struct kref kref;


        struct task_group *tg;


        struct rw_semaphore lock;


        unsigned long id;


        int nice;
}
>>> member_at_offset(prog.type('struct autogroup'), 4)
'<padding between kref and tg>'
>>> member_at_offset(prog.type('struct autogroup'), 70)
'<padding at end>'
>>> member_at_offset(prog.type('struct autogroup'), 72)
'<end>'
>>> member_at_offset(prog.type('struct autogroup'), 80)
'<past end>'
    

drgn.helpers.experimental.kmodify.write_memory(prog: drgn.Program, address: drgn.IntegerLike, value: bytes) -> None

Write a byte string to kernel memory.

>>> os.uname().sysname
'Linux'
>>> write_memory(prog["init_uts_ns"].name.sysname.address_, b"Lol\0")
>>> os.uname().sysname
'Lol'
    

WARNING:

drgn.helpers.experimental.kmodify.write_object(object: drgn.Object, value: Any, *, dereference: Optional[bool] = None) -> None

Write to an object in kernel memory.

>>> os.system("uptime -p")
up 12 minutes
>>> write_object(prog["init_time_ns"].offsets.boottime.tv_sec, 1000000000)
>>> os.system("uptime -p")
up 3 decades, 1 year, 37 weeks, 1 hour, 59 minutes
    

WARNING:

drgn.helpers.experimental.kmodify.call_function(prog: drgn.Program, func: Union[str, drgn.Object], *args: Any) -> drgn.Object

Call a function in the kernel.

Arguments can be either Objects or Python values. The function return value is returned as an Object:

>>> # GFP_KERNEL isn't in the kernel debug info
>>> # We have to use this trick to get it.
>>> for flag in prog["gfpflag_names"]:
...     if flag.name.string_() == b"GFP_KERNEL":
...             GFP_KERNEL = flag.mask
...             break
...
>>> # kmalloc() is actually a macro.
>>> # We have to call the underlying function.
>>> p = call_function("__kmalloc_noprof", 13, GFP_KERNEL)
>>> p
(void *)0xffff991701ef43c0
>>> identify_address(p)
'slab object: kmalloc-16+0x0'
>>> call_function("kfree", p)
(void)<absent>
>>> identify_address(p)
'free slab object: kmalloc-16+0x0'
    

Variadic functions are also supported:

>>> call_function("_printk", "Hello, world! %d\n", Object(prog, "int", 1234))
(int)18
>>> os.system("dmesg | tail -1")
[ 1138.223004] Hello, world! 1234
    

Constructed values can be passed by pointer using pass_pointer():

>>> sb = prog["init_fs"].root.mnt.mnt_sb
>>> sb.s_shrink.scan_objects
(unsigned long (*)(struct shrinker *, struct shrink_control *))super_cache_scan+0x0 = 0xffffffffbda4c487
>>> sc = pass_pointer(Object(prog, "struct shrink_control",
...                   {"gfp_mask": GFP_KERNEL, "nr_to_scan": 100, "nr_scanned": 100}))
>>> call_function(sb.s_shrink.scan_objects, sb.s_shrink, sc)
(unsigned long)31
    

If the function modifies the passed value, the pass_pointer object is updated:

>>> sc.object
(struct shrink_control){


        .gfp_mask = (gfp_t)3264,


        .nid = (int)0,


        .nr_to_scan = (unsigned long)1,


        .nr_scanned = (unsigned long)100,


        .memcg = (struct mem_cgroup *)0x0,
}
    

NOTE:

WARNING:

class drgn.helpers.experimental.kmodify.pass_pointer(object: Any)

Wrapper used to pass values to call_function() by pointer.

drgn.helpers.linux.bitops.for_each_set_bit(bitmap: drgn.Object, size: drgn.IntegerLike) -> Iterator[int]

Iterate over all set (one) bits in a bitmap.

drgn.helpers.linux.bitops.for_each_clear_bit(bitmap: drgn.Object, size: drgn.IntegerLike) -> Iterator[int]

Iterate over all clear (zero) bits in a bitmap.

drgn.helpers.linux.bitops.test_bit(nr: drgn.IntegerLike, bitmap: drgn.Object) -> bool

Return whether a bit in a bitmap is set.

drgn.helpers.linux.block.disk_devt(disk: drgn.Object) -> drgn.Object

Get a disk's device number.

drgn.helpers.linux.block.disk_name(disk: drgn.Object) -> bytes

Get the name of a disk (e.g., sda).

drgn.helpers.linux.block.bdev_partno(bdev: drgn.Object) -> drgn.Object

Get the partition number of a block device.

drgn.helpers.linux.block.for_each_disk(prog: drgn.Program) -> Iterator[drgn.Object]

Iterate over all disks in the system.

drgn.helpers.linux.block.print_disks(prog: drgn.Program) -> None

Print all of the disks in the system.

drgn.helpers.linux.block.part_devt(part: drgn.Object) -> drgn.Object

Get a partition's device number.

drgn.helpers.linux.block.part_name(part: drgn.Object) -> bytes

Get the name of a partition (e.g., sda1).

drgn.helpers.linux.block.for_each_partition(prog: drgn.Program) -> Iterator[drgn.Object]

Iterate over all partitions in the system.

drgn.helpers.linux.block.print_partitions(prog: drgn.Program) -> None

Print all of the partitions in the system.

drgn.helpers.linux.boot.kaslr_offset(prog: drgn.Program) -> int

Get the kernel address space layout randomization offset (zero if it is disabled).

drgn.helpers.linux.boot.pgtable_l5_enabled(prog: drgn.Program) -> bool

Return whether 5-level paging is enabled.

drgn.helpers.linux.bpf.bpf_btf_for_each(prog: drgn.Program) -> Iterator[drgn.Object]

Iterate over all BTF objects.

This is only supported since Linux v4.18.

drgn.helpers.linux.bpf.bpf_link_for_each(prog: drgn.Program) -> Iterator[drgn.Object]

Iterate over all BPF links.

This is only supported since Linux v5.8.

drgn.helpers.linux.bpf.bpf_map_for_each(prog: drgn.Program) -> Iterator[drgn.Object]

Iterate over all BPF maps.

This is only supported since Linux v4.13.

drgn.helpers.linux.bpf.bpf_prog_for_each(prog: drgn.Program) -> Iterator[drgn.Object]

Iterate over all BPF programs.

This is only supported since Linux v4.13.

drgn.helpers.linux.bpf.cgroup_bpf_prog_for_each(cgrp: drgn.Object, bpf_attach_type: drgn.IntegerLike) -> Iterator[drgn.Object]

Iterate over all cgroup BPF programs of the given attach type attached to the given cgroup.

drgn.helpers.linux.bpf.cgroup_bpf_prog_for_each_effective(cgrp: drgn.Object, bpf_attach_type: drgn.IntegerLike) -> Iterator[drgn.Object]

Iterate over all effective cgroup BPF programs of the given attach type for the given cgroup.

drgn.helpers.linux.cgroup.sock_cgroup_ptr(skcd: drgn.Object) -> drgn.Object

Get the cgroup for a socket from the given struct sock_cgroup_data * (usually from struct sock::sk_cgrp_data).

drgn.helpers.linux.cgroup.cgroup_parent(cgrp: drgn.Object) -> drgn.Object

Return the parent cgroup of the given cgroup if it exists, NULL otherwise.

drgn.helpers.linux.cgroup.cgroup_name(cgrp: drgn.Object) -> bytes

Get the name of the given cgroup.

drgn.helpers.linux.cgroup.cgroup_path(cgrp: drgn.Object) -> bytes

Get the full path of the given cgroup.

drgn.helpers.linux.cgroup.cgroup_get_from_path(prog: drgn.Program, path: drgn.Path) -> drgn.Object

Look up a cgroup from its default hierarchy path .

drgn.helpers.linux.cgroup.css_next_child(pos: drgn.Object, parent: drgn.Object) -> drgn.Object

Get the next child (or NULL if there is none) of the given parent starting from the given position (NULL to initiate traversal).

drgn.helpers.linux.cgroup.css_next_descendant_pre(pos: drgn.Object, root: drgn.Object) -> drgn.Object

Get the next pre-order descendant (or NULL if there is none) of the given css root starting from the given position (NULL to initiate traversal).

drgn.helpers.linux.cgroup.css_for_each_child(css: drgn.Object) -> Iterator[drgn.Object]

Iterate through children (offline included) of the given css.

drgn.helpers.linux.cgroup.css_for_each_descendant_pre(css: drgn.Object) -> Iterator[drgn.Object]

Iterate through the given css's descendants (offline included) in pre-order.

drgn.helpers.linux.cpumask.cpu_online_mask(prog: drgn.Program) -> drgn.Object

Return the mask of online CPUs.

drgn.helpers.linux.cpumask.cpu_possible_mask(prog: drgn.Program) -> drgn.Object

Return the mask of possible CPUs.

drgn.helpers.linux.cpumask.cpu_present_mask(prog: drgn.Program) -> drgn.Object

Return the mask of present CPUs.

drgn.helpers.linux.cpumask.for_each_cpu(mask: drgn.Object) -> Iterator[int]

Iterate over all of the CPUs in the given mask.

drgn.helpers.linux.cpumask.for_each_online_cpu(prog: drgn.Program) -> Iterator[int]

Iterate over all online CPUs.

drgn.helpers.linux.cpumask.for_each_possible_cpu(prog: drgn.Program) -> Iterator[int]

Iterate over all possible CPUs.

drgn.helpers.linux.cpumask.for_each_present_cpu(prog: drgn.Program) -> Iterator[int]

Iterate over all present CPUs.

drgn.helpers.linux.cpumask.cpumask_to_cpulist(mask: drgn.Object) -> str

Return a CPU mask as a CPU list string.

>>> cpumask_to_cpulist(mask)
0-3,8-11
    

drgn.helpers.linux.device.MAJOR(dev: drgn.IntegerLike) -> int

Return the major ID of a kernel dev_t.

drgn.helpers.linux.device.MINOR(dev: drgn.IntegerLike) -> int

Return the minor ID of a kernel dev_t.

drgn.helpers.linux.device.MKDEV(major: drgn.IntegerLike, minor: drgn.IntegerLike) -> int

Return a kernel dev_t from the major and minor IDs.

drgn.helpers.linux.fs.path_lookup(root: Union[drgn.Object, drgn.Program], path: drgn.Path, *, allow_negative: bool = False) -> drgn.Object

Look up the given path name.

>>> path_lookup('/usr/include/stdlib.h')
...
Exception: could not find '/usr/include/stdlib.h' in dcache
>>> open('/usr/include/stdlib.h').close()
>>> path_lookup('/usr/include/stdlib.h')
(struct path){


        .mnt = (struct vfsmount *)0xffff8b70413cdca0,


        .dentry = (struct dentry *)0xffff8b702ac2c480,
}

drgn.helpers.linux.fs.d_path(path: drgn.Object) -> bytes

Return the full path of a dentry given a struct path.

drgn.helpers.linux.fs.d_path(vfsmnt: drgn.Object, dentry: drgn.Object) -> bytes

Return the full path of a dentry given a mount and dentry.

drgn.helpers.linux.fs.d_path(dentry: drgn.Object) -> bytes

Return the full path of a dentry.

Since a mount is not provided, this arbitrarily selects a mount to determine the path.

drgn.helpers.linux.fs.dentry_path(dentry: drgn.Object) -> bytes

Return the path of a dentry from the root of its filesystem.

drgn.helpers.linux.fs.inode_path(inode: drgn.Object) -> Optional[bytes]

Return any path of an inode from the root of its filesystem.

drgn.helpers.linux.fs.inode_paths(inode: drgn.Object) -> Iterator[bytes]

Return an iterator over all of the paths of an inode from the root of its filesystem.

drgn.helpers.linux.fs.mount_src(mnt: drgn.Object) -> bytes

Get the source device name for a mount.

drgn.helpers.linux.fs.mount_dst(mnt: drgn.Object) -> bytes

Get the path of a mount point.

drgn.helpers.linux.fs.mount_fstype(mnt: drgn.Object) -> bytes

Get the filesystem type of a mount.

drgn.helpers.linux.fs.for_each_mount(ns: Union[drgn.Object, drgn.Program], *, src: Optional[drgn.Path] = None, dst: Optional[drgn.Path] = None, fstype: Optional[Union[str, bytes]] = None) -> Iterator[drgn.Object]

Iterate over all of the mounts in a given namespace.

drgn.helpers.linux.fs.print_mounts(ns: Union[drgn.Object, drgn.Program], *, src: Optional[drgn.Path] = None, dst: Optional[drgn.Path] = None, fstype: Optional[Union[str, bytes]] = None) -> None

Print the mount table of a given namespace. The arguments are the same as for_each_mount(). The output format is similar to /proc/mounts but prints the value of each struct mount *.

drgn.helpers.linux.fs.fget(task: drgn.Object, fd: drgn.IntegerLike) -> drgn.Object

Return the kernel file descriptor of the fd of a given task.

drgn.helpers.linux.fs.for_each_file(task: drgn.Object) -> Iterator[Tuple[int, drgn.Object]]

Iterate over all of the files open in a given task.

drgn.helpers.linux.fs.print_files(task: drgn.Object) -> None

Print the open files of a given task.

drgn.helpers.linux.idr.idr_find(idr: drgn.Object, id: drgn.IntegerLike) -> drgn.Object

Look up the entry with the given ID in an IDR.

drgn.helpers.linux.idr.idr_for_each(idr: drgn.Object) -> Iterator[Tuple[int, drgn.Object]]

Iterate over all of the pointers in an IDR.

drgn.helpers.linux.idr.idr_for_each_entry(idr: drgn.Object, type: Union[str, drgn.Type]) -> Iterator[Tuple[int, drgn.Object]]

Iterate over all of the entries with the given type in an IDR.

drgn.helpers.linux.kallsyms.load_vmlinux_kallsyms(prog: drgn.Program) -> drgn.SymbolIndex

Create a kallsyms index for vmlinux

This function loads the kallsyms for the core kernel and returns a symbol index. This function does not require that any debuginfo is loaded for the kernel: it either relies on /proc/kallsyms (which requires running drgn as root) or it parses internal data structures using information found from the VMCOREINFO note (which requires Linux 6.0 or later, or a backport of commit f09bddbd86619 ("vmcoreinfo: add kallsyms_num_syms symbol") and its dependencies).

drgn.helpers.linux.kallsyms.load_module_kallsyms(prog: drgn.Program) -> drgn.SymbolIndex

Return a symbol index containing all module symbols from kallsyms

For kernels built with CONFIG_KALLSYMS, loaded kernel modules contain an ELF symbol table in kernel memory. This function can parse those data structures and create a symbol index usable by drgn. However, it requires that you already have debuginfo for the vmlinux image.

drgn.helpers.linux.kconfig.get_kconfig(prog: drgn.Program) -> Mapping[str, str]

Get the kernel build configuration as a mapping from the option name to the value.

>>> get_kconfig()['CONFIG_SMP']
'y'
>>> get_kconfig()['CONFIG_HZ']
'300'
    

This is only supported if the kernel was compiled with CONFIG_IKCONFIG. Note that most Linux distributions do not enable this option.

drgn.helpers.linux.kernfs.kernfs_name(kn: drgn.Object) -> bytes

Get the name of the given kernfs node.

drgn.helpers.linux.kernfs.kernfs_path(kn: drgn.Object) -> bytes

Get full path of the given kernfs node.

drgn.helpers.linux.kernfs.kernfs_walk(parent: drgn.Object, path: drgn.Path) -> drgn.Object

Find the kernfs node with the given path from the given parent kernfs node.

drgn.helpers.linux.list.list_empty(head: drgn.Object) -> bool

Return whether a list is empty.

drgn.helpers.linux.list.list_is_singular(head: drgn.Object) -> bool

Return whether a list has only one element.

drgn.helpers.linux.list.list_count_nodes(head: drgn.Object) -> int

Return the number of nodes in a list.

drgn.helpers.linux.list.list_first_entry(head: drgn.Object, type: Union[str, drgn.Type], member: str) -> drgn.Object

Return the first entry in a list.

The list is assumed to be non-empty.

See also list_first_entry_or_null().

drgn.helpers.linux.list.list_first_entry_or_null(head: drgn.Object, type: Union[str, drgn.Type], member: str) -> drgn.Object

Return the first entry in a list or NULL if the list is empty.

See also list_first_entry().

drgn.helpers.linux.list.list_last_entry(head: drgn.Object, type: Union[str, drgn.Type], member: str) -> drgn.Object

Return the last entry in a list.

The list is assumed to be non-empty.

drgn.helpers.linux.list.list_next_entry(pos: drgn.Object, member: str) -> drgn.Object

Return the next entry in a list.

drgn.helpers.linux.list.list_prev_entry(pos: drgn.Object, member: str) -> drgn.Object

Return the previous entry in a list.

drgn.helpers.linux.list.list_for_each(head: drgn.Object) -> Iterator[drgn.Object]

Iterate over all of the nodes in a list.

drgn.helpers.linux.list.list_for_each_reverse(head: drgn.Object) -> Iterator[drgn.Object]

Iterate over all of the nodes in a list in reverse order.

drgn.helpers.linux.list.list_for_each_entry(type: Union[str, drgn.Type], head: drgn.Object, member: str) -> Iterator[drgn.Object]

Iterate over all of the entries in a list.

drgn.helpers.linux.list.list_for_each_entry_reverse(type: Union[str, drgn.Type], head: drgn.Object, member: str) -> Iterator[drgn.Object]

Iterate over all of the entries in a list in reverse order.

drgn.helpers.linux.list.validate_list(head: drgn.Object) -> None

Validate that the next and prev pointers in a list are consistent.

drgn.helpers.linux.list.validate_list_for_each(head: drgn.Object) -> Iterator[drgn.Object]

Like list_for_each(), but validates the list like validate_list() while iterating.

drgn.helpers.linux.list.validate_list_for_each_entry(type: Union[str, drgn.Type], head: drgn.Object, member: str) -> Iterator[drgn.Object]

Like list_for_each_entry(), but validates the list like validate_list() while iterating.

drgn.helpers.linux.list.hlist_empty(head: drgn.Object) -> bool

Return whether a hash list is empty.

drgn.helpers.linux.list.hlist_for_each(head: drgn.Object) -> Iterator[drgn.Object]

Iterate over all of the nodes in a hash list.

drgn.helpers.linux.list.hlist_for_each_entry(type: Union[str, drgn.Type], head: drgn.Object, member: str) -> Iterator[drgn.Object]

Iterate over all of the entries in a hash list.

drgn.helpers.linux.list_nulls.is_a_nulls(pos: drgn.Object) -> bool

Return whether a a pointer is a nulls marker.

drgn.helpers.linux.list_nulls.hlist_nulls_empty(head: drgn.Object) -> bool

Return whether a nulls hash list is empty.

drgn.helpers.linux.list_nulls.hlist_nulls_for_each_entry(type: Union[str, drgn.Type], head: drgn.Object, member: str) -> Iterator[drgn.Object]

Iterate over all the entries in a nulls hash list.

drgn.helpers.linux.llist.llist_empty(head: drgn.Object) -> bool

Return whether an llist is empty.

drgn.helpers.linux.llist.llist_is_singular(head: drgn.Object) -> bool

Return whether an llist has only one element.

drgn.helpers.linux.llist.llist_first_entry(head: drgn.Object, type: Union[str, drgn.Type], member: str) -> drgn.Object

Return the first entry in an llist.

The list is assumed to be non-empty.

See also llist_first_entry_or_null().

drgn.helpers.linux.llist.llist_first_entry_or_null(head: drgn.Object, type: Union[str, drgn.Type], member: str) -> drgn.Object

Return the first entry in an llist or NULL if the llist is empty.

See also llist_first_entry().

drgn.helpers.linux.llist.llist_next_entry(pos: drgn.Object, member: str) -> drgn.Object

Return the next entry in an llist.

drgn.helpers.linux.llist.llist_for_each(node: drgn.Object) -> Iterator[drgn.Object]

Iterate over all of the nodes in an llist starting from a given node.

drgn.helpers.linux.llist.llist_for_each_entry(type: Union[str, drgn.Type], node: drgn.Object, member: str) -> Iterator[drgn.Object]

Iterate over all of the entries in an llist starting from a given node.

drgn.helpers.linux.mapletree.mtree_load(mt: drgn.Object, index: drgn.IntegerLike, *, advanced: bool = False) -> drgn.Object

Look up the entry at a given index in a maple tree.

>>> entry = mtree_load(task.mm.mm_mt.address_of_(), 0x55d65cfaa000)
>>> cast("struct vm_area_struct *", entry)
*(struct vm_area_struct *)0xffff97ad82bfc930 = {


    ...
}
    

drgn.helpers.linux.mapletree.mt_for_each(mt: drgn.Object, *, advanced: bool = False) -> Iterator[Tuple[int, int, drgn.Object]]

Iterate over all of the entries and their ranges in a maple tree.

>>> for first_index, last_index, entry in mt_for_each(task.mm.mm_mt.address_of_()):
...     print(hex(first_index), hex(last_index), entry)
...
0x55d65cfaa000 0x55d65cfaafff (void *)0xffff97ad82bfc930
0x55d65cfab000 0x55d65cfabfff (void *)0xffff97ad82bfc0a8
0x55d65cfac000 0x55d65cfacfff (void *)0xffff97ad82bfc000
0x55d65cfad000 0x55d65cfadfff (void *)0xffff97ad82bfcb28
...
    

1.

If the address is invalid.

2.

If the address is swapped or paged out.

3.

If the address is in high memory. High memory is only used for userspace memory by 32-bit systems with a lot of physical memory, and only if CONFIG_HIGHMEM is enabled.

3a. If the page table is in high memory. This is only possible if CONFIG_HIGHPTE is enabled.

drgn.helpers.linux.mm.PageActive(page: drgn.Object) -> bool

Return whether the PG_active flag is set on a page.

drgn.helpers.linux.mm.PageChecked(page: drgn.Object) -> bool

Return whether the PG_checked flag is set on a page.

drgn.helpers.linux.mm.PageDirty(page: drgn.Object) -> bool

Return whether the PG_dirty flag is set on a page.

drgn.helpers.linux.mm.PageDoubleMap(page: drgn.Object) -> bool

Return whether the PG_double_map flag is set on a page.

drgn.helpers.linux.mm.PageError(page: drgn.Object) -> bool

Return whether the PG_error flag is set on a page.

drgn.helpers.linux.mm.PageForeign(page: drgn.Object) -> bool

Return whether the PG_foreign flag is set on a page.

drgn.helpers.linux.mm.PageHWPoison(page: drgn.Object) -> bool

Return whether the PG_hwpoison flag is set on a page.

drgn.helpers.linux.mm.PageHasHWPoisoned(page: drgn.Object) -> bool

Return whether the PG_has_hwpoisoned flag is set on a page.

drgn.helpers.linux.mm.PageIdle(page: drgn.Object) -> bool

Return whether the PG_idle flag is set on a page.

drgn.helpers.linux.mm.PageIsolated(page: drgn.Object) -> bool

Return whether the PG_isolated flag is set on a page.

drgn.helpers.linux.mm.PageLRU(page: drgn.Object) -> bool

Return whether the PG_lru flag is set on a page.

drgn.helpers.linux.mm.PageLocked(page: drgn.Object) -> bool

Return whether the PG_locked flag is set on a page.

drgn.helpers.linux.mm.PageMappedToDisk(page: drgn.Object) -> bool

Return whether the PG_mappedtodisk flag is set on a page.

drgn.helpers.linux.mm.PageMlocked(page: drgn.Object) -> bool

Return whether the PG_mlocked flag is set on a page.

drgn.helpers.linux.mm.PageOwnerPriv1(page: drgn.Object) -> bool

Return whether the PG_owner_priv_1 flag is set on a page.

drgn.helpers.linux.mm.PagePinned(page: drgn.Object) -> bool

Return whether the PG_pinned flag is set on a page.

drgn.helpers.linux.mm.PagePrivate(page: drgn.Object) -> bool

Return whether the PG_private flag is set on a page.

drgn.helpers.linux.mm.PagePrivate2(page: drgn.Object) -> bool

Return whether the PG_private_2 flag is set on a page.

drgn.helpers.linux.mm.PageReadahead(page: drgn.Object) -> bool

Return whether the PG_readahead flag is set on a page.

drgn.helpers.linux.mm.PageReclaim(page: drgn.Object) -> bool

Return whether the PG_reclaim flag is set on a page.

drgn.helpers.linux.mm.PageReferenced(page: drgn.Object) -> bool

Return whether the PG_referenced flag is set on a page.

drgn.helpers.linux.mm.PageReported(page: drgn.Object) -> bool

Return whether the PG_reported flag is set on a page.

drgn.helpers.linux.mm.PageReserved(page: drgn.Object) -> bool

Return whether the PG_reserved flag is set on a page.

drgn.helpers.linux.mm.PageSavePinned(page: drgn.Object) -> bool

Return whether the PG_savepinned flag is set on a page.

drgn.helpers.linux.mm.PageSkipKASanPoison(page: drgn.Object) -> bool

Return whether the PG_skip_kasan_poison flag is set on a page.

drgn.helpers.linux.mm.PageSlobFree(page: drgn.Object) -> bool

Return whether the PG_slob_free flag is set on a page.