Provided by: python3-drgn_0.0.23-1_amd64 
NAME
drgn - drgn 0.0.23
drgn (pronounced "dragon") is a debugger with an emphasis on programmability. drgn
exposes the types and variables in a program for easy, expressive scripting in Python. For
example, you can debug the Linux kernel:
>>> from drgn.helpers.linux import list_for_each_entry
>>> for mod in list_for_each_entry('struct module',
... prog['modules'].address_of_(),
... 'list'):
... if mod.refcnt.counter > 10:
... print(mod.name)
...
(char [56])"snd"
(char [56])"evdev"
(char [56])"i915"
Although other debuggers like GDB have scripting support, drgn aims to make scripting as
natural as possible so that debugging feels like coding. This makes it well-suited for
introspecting the complex, inter-connected state in large programs.
Additionally, drgn is designed as a library that can be used to build debugging and
introspection tools; see the official tools.
drgn was developed at Meta for debugging the Linux kernel (as an alternative to the crash
utility), but it can also debug userspace programs written in C. C++ support is in
progress.
In addition to the main Python API, an experimental C library, libdrgn, is also available.
See the Installation instructions. Then, start with the User Guide.
LICENSE
Copyright (c) Meta Platforms, Inc. and affiliates.
drgn is licensed under the LGPLv2.1 or later.
ACKNOWLEDGEMENTS
drgn is named after this because dragons eat dwarves.
TABLE OF CONTENTS
Installation
There are several options for installing drgn.
Dependencies
drgn depends on:
• Python 3.6 or newer
• elfutils 0.165 or newer
It optionally depends on:
• libkdumpfile for makedumpfile compressed kernel core dump format support
The build requires:
• GCC
• GNU Make
• pkgconf
• setuptools
Building from the Git repository (rather than a release tarball) additionally requires:
• autoconf
• automake
• libtool
Installation
Package Manager
drgn can be installed using the package manager on some Linux distributions.
• Fedora >= 32
$ sudo dnf install drgn
• RHEL/CentOS >= 8
Enable EPEL. Then:
$ sudo dnf install drgn
• Arch Linux
Install the drgn package from the AUR.
• Debian >= 12 (Bookworm)
$ sudo apt install python3-drgn
• openSUSE
$ sudo zypper install python3-drgn
• Ubuntu
Enable the michel-slm/kernel-utils PPA. Then:
$ sudo apt install python3-drgn
pip
If your Linux distribution doesn't package the latest release of drgn, you can install it
with pip.
First, install pip. Then, run:
$ sudo pip3 install drgn
This will install a binary wheel by default. If you get a build error, then pip wasn't
able to use the binary wheel. Install the dependencies listed below and try again.
Note that RHEL/CentOS 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship
Python versions which are too old. Python 3.6 or newer must be installed.
From Source
To get the development version of drgn, you will need to build it from source. First,
install dependencies:
• Fedora
$ sudo dnf install autoconf automake elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
• RHEL/CentOS
$ sudo dnf install autoconf automake elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
Optionally, install libkdumpfile-devel from EPEL on RHEL/CentOS >= 8 or install
libkdumpfile from source if you want support for the makedumpfile format.
Replace dnf with yum for RHEL/CentOS < 8.
• Debian/Ubuntu
$ sudo apt-get install autoconf automake gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
Optionally, install libkdumpfile from source if you want support for the makedumpfile
format.
• Arch Linux
$ sudo pacman -S --needed autoconf automake gcc git libelf libtool make pkgconf python python-pip python-setuptools
Optionally, install libkdumpfile from the AUR or from source if you want support for the
makedumpfile format.
• openSUSE
$ sudo zypper install autoconf automake gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
Then, run:
$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install
Virtual Environment
The above options all install drgn globally. You can also install drgn in a virtual
environment, either with pip:
$ python3 -m venv drgnenv
$ source drgnenv/bin/activate
(drgnenv) $ pip3 install drgn
(drgnenv) $ drgn --help
Or from source:
$ python3 -m venv drgnenv
$ source drgnenv/bin/activate
(drgnenv) $ python3 setup.py install
(drgnenv) $ drgn --help
Running Locally
If you build drgn from source, you can also run it without installing it:
$ python3 setup.py build_ext -i
$ python3 -m drgn --help
User Guide
Quick Start
drgn debugs the running kernel by default; run sudo drgn. To debug a running program, run
sudo drgn -p $PID. To debug a core dump (either a kernel vmcore or a userspace core dump),
run drgn -c $PATH. Make sure to install debugging symbols for whatever you are debugging.
Then, you can access variables in the program with prog['name'] and access structure
members with .:
$ sudo drgn
>>> prog['init_task'].comm
(char [16])"swapper/0"
You can use various predefined helpers:
>>> len(list(bpf_prog_for_each(prog)))
11
>>> task = find_task(prog, 115)
>>> cmdline(task)
[b'findmnt', b'-p']
You can get stack traces with prog.stack_trace() and access parameters or local variables
with stack_trace['name']:
>>> trace = prog.stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]['list']
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'
Core Concepts
The most important interfaces in drgn are programs, objects, and helpers.
Programs
A program being debugged is represented by an instance of the drgn.Program class. The drgn
CLI is initialized with a Program named prog; unless you are using the drgn library
directly, this is usually the only Program you will need.
A Program is used to look up type definitions, access variables, and read arbitrary
memory:
>>> prog.type('unsigned long')
prog.int_type(name='unsigned long', size=8, is_signed=False)
>>> prog['jiffies']
Object(prog, 'volatile unsigned long', address=0xffffffffbe405000)
>>> prog.read(0xffffffffbe411e10, 16)
b'swapper/0\x00\x00\x00\x00\x00\x00\x00'
The drgn.Program.type(), drgn.Program.variable(), drgn.Program.constant(), and
drgn.Program.function() methods look up those various things in a program.
drgn.Program.read() reads memory from the program's address space. The [] operator looks
up a variable, constant, or function:
>>> prog['jiffies'] == prog.variable('jiffies')
True
It is usually more convenient to use the [] operator rather than the variable(),
constant(), or function() methods unless the program has multiple objects with the same
name, in which case the methods provide more control.
Objects
Variables, constants, functions, and computed values are all called objects in drgn.
Objects are represented by the drgn.Object class. An object may exist in the memory of the
program (a reference):
>>> Object(prog, 'int', address=0xffffffffc09031a0)
Or, an object may be a constant or temporary computed value (a value):
>>> Object(prog, 'int', value=4)
What makes drgn scripts expressive is that objects can be used almost exactly like they
would be in the program's own source code. For example, structure members can be accessed
with the dot (.) operator, arrays can be subscripted with [], arithmetic can be performed,
and objects can be compared:
>>> print(prog['init_task'].comm[0])
(char)115
>>> print(repr(prog['init_task'].nsproxy.mnt_ns.mounts + 1))
Object(prog, 'unsigned int', value=34)
>>> prog['init_task'].nsproxy.mnt_ns.pending_mounts > 0
False
A common use case is converting a drgn.Object to a Python value so it can be used by a
standard Python library. There are a few ways to do this:
• 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.
Objects have several attributes; the most important are drgn.Object.prog_ and
drgn.Object.type_. The former is the drgn.Program that the object is from, and the latter
is the drgn.Type of the object.
Note that all attributes and methods of the Object class end with an underscore (_) in
order to avoid conflicting with structure or union members. The Object attributes and
methods always take precedence; use drgn.Object.member_() if there is a conflict.
References vs. Values
The main difference between reference objects and value objects is how they are evaluated.
References are read from the program's memory every time they are evaluated; values simply
return the stored value (drgn.Object.read_() reads a reference object and returns it as a
value object):
>>> import time
>>> jiffies = prog['jiffies']
>>> jiffies.value_()
4391639989
>>> time.sleep(1)
>>> jiffies.value_()
4391640290
>>> jiffies2 = jiffies.read_()
>>> jiffies2.value_()
4391640291
>>> time.sleep(1)
>>> jiffies2.value_()
4391640291
>>> jiffies.value_()
4391640593
References have a drgn.Object.address_ attribute, which is the object's address as a
Python int. This is slightly different from the drgn.Object.address_of_() method, which
returns the address as a drgn.Object. Of course, both references and values can have a
pointer type; address_ refers to the address of the pointer object itself, and
drgn.Object.value_() refers to the value of the pointer (i.e., the address it points to):
>>> address = prog['jiffies'].address_
>>> type(address)
<class 'int'>
>>> print(hex(address))
0xffffffffbe405000
>>> jiffiesp = prog['jiffies'].address_of_()
>>> jiffiesp
Object(prog, 'volatile unsigned long *', value=0xffffffffbe405000)
>>> print(hex(jiffiesp.value_()))
0xffffffffbe405000
Absent Objects
In addition to reference objects and value objects, objects may also be absent.
>>> Object(prog, "int").value_()
Traceback (most recent call last):
File "<console>", line 1, in <module>
_drgn.ObjectAbsentError: object absent
This represents an object whose value or address is not known. For example, this can
happen if the object was optimized out of the program by the compiler.
Any attempt to operate on an absent object results in a drgn.ObjectAbsentError exception,
although basic information including its type may still be accessed.
Helpers
Some programs have common data structures that you may want to examine. For example,
consider linked lists in the Linux kernel:
struct list_head {
struct list_head *next, *prev;
};
#define list_for_each(pos, head) \
for (pos = (head)->next; pos != (head); pos = pos->next)
When working with these lists, you'd probably want to define a function:
def list_for_each(head):
pos = head.next
while pos != head:
yield pos
pos = pos.next
Then, you could use it like so for any list you need to look at:
>>> for pos in list_for_each(head):
... do_something_with(pos)
Of course, it would be a waste of time and effort for everyone to have to define these
helpers for themselves, so drgn includes a collection of helpers for many use cases. See
Helpers.
Validators
Validators are a special category of helpers that check the consistency of a data
structure. In general, helpers assume that the data structures that they examine are
valid. Validators do not make this assumption and do additional (potentially expensive)
checks to detect broken invariants, corruption, etc.
Validators raise drgn.helpers.ValidationError if the data structure is not valid or
drgn.FaultError if the data structure is invalid in a way that causes a bad memory access.
They have names prefixed with validate_.
For example, drgn.helpers.linux.list.validate_list() checks the consistency of a linked
list in the Linux kernel (in particular, the consistency of the next and prev pointers):
>>> validate_list(prog["my_list"].address_of_())
drgn.helpers.ValidationError: (struct list_head *)0xffffffffc029e460 next 0xffffffffc029e000 has prev 0xffffffffc029e450
drgn.helpers.linux.list.validate_list_for_each_entry() does the same checks while also
returning the entries in the list for further validation:
def validate_my_list(prog):
for entry in validate_list_for_each_entry(
"struct my_entry",
prog["my_list"].address_of_(),
"list",
):
if entry.value < 0:
raise ValidationError("list contains negative entry")
Other Concepts
In addition to the core concepts above, drgn provides a few additional abstractions.
Threads
The drgn.Thread class represents a thread. drgn.Program.threads(), drgn.Program.thread(),
drgn.Program.main_thread(), and drgn.Program.crashed_thread() can be used to find threads:
>>> for thread in prog.threads():
... print(thread.tid)
...
39143
39144
>>> print(prog.main_thread().tid)
39143
>>> print(prog.crashed_thread().tid)
39144
Stack Traces
drgn represents stack traces with the drgn.StackTrace and drgn.StackFrame classes.
drgn.Thread.stack_trace() and drgn.Program.stack_trace() return the call stack for a
thread. The [] operator looks up an object in the scope of a StackFrame:
>>> trace = prog.stack_trace(115)
>>> trace
#0 context_switch (./kernel/sched/core.c:4683:2)
#1 __schedule (./kernel/sched/core.c:5940:8)
#2 schedule (./kernel/sched/core.c:6019:3)
#3 schedule_hrtimeout_range_clock (./kernel/time/hrtimer.c:2148:3)
#4 poll_schedule_timeout (./fs/select.c:243:8)
#5 do_poll (./fs/select.c:961:8)
#6 do_sys_poll (./fs/select.c:1011:12)
#7 __do_sys_poll (./fs/select.c:1076:8)
#8 __se_sys_poll (./fs/select.c:1064:1)
#9 __x64_sys_poll (./fs/select.c:1064:1)
#10 do_syscall_x64 (./arch/x86/entry/common.c:50:14)
#11 do_syscall_64 (./arch/x86/entry/common.c:80:7)
#12 entry_SYSCALL_64+0x7c/0x15b (./arch/x86/entry/entry_64.S:113)
#13 0x7f3344072af7
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> prog['do_poll']
(int (struct poll_list *list, struct poll_wqueues *wait, struct timespec64 *end_time))<absent>
>>> trace[5]['list']
*(struct poll_list *)0xffffacca402e3b50 = {
.next = (struct poll_list *)0x0,
.len = (int)1,
.entries = (struct pollfd []){},
}
Symbols
The symbol table of a program is a list of identifiers along with their address and size.
drgn represents symbols with the drgn.Symbol class, which is returned by
drgn.Program.symbol().
Types
drgn automatically obtains type definitions from the program. Types are represented by the
drgn.Type class and created by various factory functions like drgn.Program.int_type():
>>> prog.type('int')
prog.int_type(name='int', size=4, is_signed=True)
You won't usually need to work with types directly, but see Types if you do.
Platforms
Certain operations and objects in a program are platform-dependent; drgn allows accessing
the platform that a program runs with the drgn.Platform class.
Command Line Interface
The drgn CLI is basically a wrapper around the drgn library which automatically creates a
drgn.Program. The CLI can be run in interactive mode or script mode.
Script Mode
Script mode is useful for reusable scripts. Simply pass the path to the script along with
any arguments:
$ cat script.py
import sys
from drgn.helpers.linux import find_task
pid = int(sys.argv[1])
uid = find_task(prog, pid).cred.uid.val.value_()
print(f'PID {pid} is being run by UID {uid}')
$ sudo drgn script.py 601
PID 601 is being run by UID 1000
It's even possible to run drgn scripts directly with the proper shebang:
$ cat script2.py
#!/usr/bin/env drgn
mounts = prog['init_task'].nsproxy.mnt_ns.mounts.value_()
print(f'You have {mounts} filesystems mounted')
$ sudo ./script2.py
You have 36 filesystems mounted
Interactive Mode
Interactive mode uses the Python interpreter's interactive mode and adds a few nice
features, including:
• History
• Tab completion
• Automatic import of relevant helpers
• Pretty printing of objects and types
The default behavior of the Python REPL is to print the output of repr(). For drgn.Object
and drgn.Type, this is a raw representation:
>>> print(repr(prog['jiffies']))
Object(prog, 'volatile unsigned long', address=0xffffffffbe405000)
>>> print(repr(prog.type('atomic_t')))
prog.typedef_type(name='atomic_t', type=prog.struct_type(tag=None, size=4, members=(TypeMember(prog.type('int'), name='counter', bit_offset=0),)))
The standard print() function uses the output of str(). For drgn objects and types, this
is a representation in programming language syntax:
>>> print(prog['jiffies'])
(volatile unsigned long)4395387628
>>> print(prog.type('atomic_t'))
typedef struct {
int counter;
} atomic_t
In interactive mode, the drgn CLI automatically uses str() instead of repr() for objects
and types, so you don't need to call print() explicitly:
$ sudo drgn
>>> prog['jiffies']
(volatile unsigned long)4395387628
>>> prog.type('atomic_t')
typedef struct {
int counter;
} atomic_t
Next Steps
Refer to the API Reference. Look through the Helpers. Read some Case Studies. Browse
through the tools. Check out the community contributions.
Advanced Usage
The User Guide covers basic usage of drgn, but drgn also supports more advanced use cases
which are covered here.
Loading Debugging Symbols
drgn will automatically load debugging information based on the debugged program (e.g.,
from loaded kernel modules or loaded shared libraries). drgn.Program.load_debug_info()
can be used to load additional debugging information:
>>> prog.load_debug_info(['./libfoo.so', '/usr/lib/libbar.so'])
Library
In addition to the CLI, drgn is also available as a library.
drgn.program_from_core_dump(), drgn.program_from_kernel(), and drgn.program_from_pid()
correspond to the -c, -k, and -p command line options, respectively; they return a
drgn.Program that can be used just like the one initialized by the CLI:
>>> import drgn
>>> prog = drgn.program_from_kernel()
C Library
The core functionality of drgn is implemented in C and is available as a C library,
libdrgn. See drgn.h.
Full documentation can be generated by running doxygen in the libdrgn directory of the
source code. Note that the API and ABI are not yet stable.
Custom Programs
The main components of a drgn.Program are the program memory, types, and symbols. The CLI
and equivalent library interfaces automatically determine these. However, it is also
possible to create a "blank" Program and plug in the main components. The
drgn.cli.run_interactive() function allows you to run the same drgn CLI once you've
created a drgn.Program, so it's easy to make a custom program which allows interactive
debugging.
drgn.Program.add_memory_segment() defines a range of memory and how to read that memory.
The following example uses a Btrfs filesystem image as the program "memory":
import drgn
import os
import sys
from drgn.cli import run_interactive
def btrfs_debugger(dev):
file = open(dev, 'rb')
size = file.seek(0, 2)
def read_file(address, count, offset, physical):
file.seek(offset)
return file.read(count)
platform = drgn.Platform(drgn.Architecture.UNKNOWN,
drgn.PlatformFlags.IS_LITTLE_ENDIAN)
prog = drgn.Program(platform)
prog.add_memory_segment(0, size, read_file)
prog.load_debug_info([f'/lib/modules/{os.uname().release}/kernel/fs/btrfs/btrfs.ko'])
return prog
prog = btrfs_debugger(sys.argv[1] if len(sys.argv) >= 2 else '/dev/sda')
print(drgn.Object(prog, 'struct btrfs_super_block', address=65536))
run_interactive(prog, banner_func=lambda _: "BTRFS debugger")
drgn.Program.add_type_finder() and drgn.Program.add_object_finder() are the equivalent
methods for plugging in types and objects.
Environment Variables
Some of drgn's behavior can be modified through environment variables:
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.
Linux Kernel Special Objects
When debugging the Linux kernel, there are some special drgn.Objects accessible with
drgn.Program.object() and drgn.Program[]. Some of these are available even without
debugging information, thanks to metadata called "vmcoreinfo" which is present in kernel
core dumps. These special objects include:
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.
API Reference
Programs
class drgn.Program
A Program represents a crashed or running program. It can be used to lookup type
definitions, access variables, and read arbitrary memory.
The main functionality of a Program is looking up objects (i.e., variables,
constants, or functions). This is usually done with the [] operator.
Program(platform: Optional[Platform] = None)
Create a Program with no target program. It is usually more convenient to
use one of the Program Constructors.
Parameters
platform -- The platform of the program, or None if it should be
determined automatically when a core dump or symbol file is added.
flags: ProgramFlags
Flags which apply to this program.
platform: Optional[Platform]
Platform that this program runs on, or None if it has not been determined
yet.
language: Language
Default programming language of the program.
This is used for interpreting the type name given to type() and when
creating an Object without an explicit type.
For the Linux kernel, this defaults to Language.C. For userspace programs,
this defaults to the language of main in the program, falling back to
Language.C. This heuristic may change in the future.
This can be explicitly set to a different language (e.g., if the heuristic
was incorrect).
__getitem__(name: str) -> Object
Implement self[name]. Get the object (variable, constant, or function) with
the given name.
This is equivalent to prog.object(name) except that this raises KeyError
instead of LookupError if no objects with the given name are found.
If there are multiple objects with the same name, one is returned
arbitrarily. In this case, the variable(), constant(), function(), or
object() methods can be used instead.
>>> prog['jiffies']
Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
Parameters
name -- Object name.
__contains__(name: str) -> bool
Implement name in self. Return whether an object (variable, constant, or
function) with the given name exists in the program.
Parameters
name -- Object name.
variable(name: str, filename: Optional[str] = None) -> Object
Get the variable with the given name.
>>> prog.variable('jiffies')
Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
This is equivalent to prog.object(name, FindObjectFlags.VARIABLE, filename).
Parameters
• name -- The variable name.
• filename -- The source code file that contains the definition. See
Filenames.
Raises LookupError -- if no variables with the given name are found in the
given file
constant(name: str, filename: Optional[str] = None) -> Object
Get the constant (e.g., enumeration constant) with the given name.
Note that support for macro constants is not yet implemented for DWARF
files, and most compilers don't generate macro debugging information by
default anyways.
>>> prog.constant('PIDTYPE_MAX')
Object(prog, 'enum pid_type', value=4)
This is equivalent to prog.object(name, FindObjectFlags.CONSTANT, filename).
Parameters
• name -- The constant name.
• filename -- The source code file that contains the definition. See
Filenames.
Raises LookupError -- if no constants with the given name are found in the
given file
function(name: str, filename: Optional[str] = None) -> Object
Get the function with the given name.
>>> prog.function('schedule')
Object(prog, 'void (void)', address=0xffffffff94392370)
This is equivalent to prog.object(name, FindObjectFlags.FUNCTION, filename).
Parameters
• name -- The function name.
• filename -- The source code file that contains the definition. See
Filenames.
Raises LookupError -- if no functions with the given name are found in the
given file
object(name: str, flags: FindObjectFlags = FindObjectFlags.ANY, filename:
Optional[str] = None) -> Object
Get the object (variable, constant, or function) with the given name.
When debugging the Linux kernel, this can look up certain special objects
documented in Linux Kernel Special Objects, sometimes without any debugging
information loaded.
Parameters
• name -- The object name.
• flags -- Flags indicating what kind of object to look for.
• filename -- The source code file that contains the definition. See
Filenames.
Raises LookupError -- if no objects with the given name are found in the
given file
symbol(address_or_name: Union[IntegerLike, str]) -> Symbol
Get a symbol containing the given address, or a symbol with the given name.
Global symbols are preferred over weak symbols, and weak symbols are
preferred over other symbols. In other words: if a matching
SymbolBinding.GLOBAL or SymbolBinding.UNIQUE symbol is found, it is
returned. Otherwise, if a matching SymbolBinding.WEAK symbol is found, it is
returned. Otherwise, any matching symbol (e.g., SymbolBinding.LOCAL) is
returned. If there are multiple matching symbols with the same binding, one
is returned arbitrarily. To retrieve all matching symbols, use symbols().
Parameters
address_or_name -- Address or name to search for. This parameter is
positional-only.
Raises LookupError -- if no symbol contains the given address or matches the
given name
symbols(address_or_name: Union[None, IntegerLike, str] = None) -> List[Symbol]
Get a list of global and local symbols, optionally matching a name or
address.
If a string argument is given, this returns all symbols matching that name.
If an integer-like argument given, this returns a list of all symbols
containing that address. If no argument is given, all symbols in the program
are returned. In all cases, the symbols are returned in an unspecified
order.
Parameters
address_or_name -- Address or name to search for. This parameter is
positional-only.
stack_trace(thread: Union[Object, IntegerLike]) -> StackTrace
Get the stack trace for the given thread in the program.
thread may be a thread ID (as defined by gettid(2)), in which case this will
unwind the stack for the thread with that ID. The ID may be a Python int or
an integer Object
thread may also be a struct pt_regs or struct pt_regs * object, in which
case the initial register values will be fetched from that object.
Finally, if debugging the Linux kernel, thread may be a struct task_struct *
object, in which case this will unwind the stack for that task. See
drgn.helpers.linux.pid.find_task().
This is implemented for the Linux kernel (both live and core dumps) as well
as userspace core dumps; it is not yet implemented for live userspace
processes.
Parameters
thread -- Thread ID, struct pt_regs object, or struct task_struct *
object.
type(name: str, filename: Optional[str] = None) -> Type
Get the type with the given name.
>>> prog.type('long')
prog.int_type(name='long', size=8, is_signed=True)
Parameters
• name -- The type name.
• filename -- The source code file that contains the definition. See
Filenames.
Raises LookupError -- if no types with the given name are found in the given
file
type(type: Type) -> Type
Return the given type.
This is mainly useful so that helpers can use prog.type() to get a Type
regardless of whether they were given a str or a Type. For example:
def my_helper(obj: Object, type: Union[str, Type]) -> bool:
# type may be str or Type.
type = obj.prog_.type(type)
# type is now always Type.
return sizeof(obj) > sizeof(type)
Parameters
type -- Type.
Returns
The exact same type.
threads() -> Iterator[Thread]
Get an iterator over all of the threads in the program.
thread(tid: IntegerLike) -> Thread
Get the thread with the given thread ID.
Parameters
tid -- Thread ID (as defined by gettid(2)).
Raises LookupError -- if no thread has the given thread ID
main_thread() -> Thread
Get the main thread of the program.
This is only defined for userspace programs.
Raises ValueError -- if the program is the Linux kernel
crashed_thread() -> Thread
Get the thread that caused the program to crash.
For userspace programs, this is the thread that received the fatal signal
(e.g., SIGSEGV or SIGQUIT).
For the kernel, this is the thread that panicked (either directly or as a
result of an oops, BUG_ON(), etc.).
Raises ValueError -- if the program is live (i.e., not a core dump)
read(address: IntegerLike, size: IntegerLike, physical: bool = False) -> bytes
Read size bytes of memory starting at address in the program. The address
may be virtual (the default) or physical if the program supports it.
>>> prog.read(0xffffffffbe012b40, 16)
b'swapper/0'
Parameters
• address -- The starting address.
• size -- The number of bytes to read.
• physical -- Whether address is a physical memory address. If False,
then it is a virtual memory address. Physical memory can usually
only be read when the program is an operating system kernel.
Raises
• FaultError -- if the address range is invalid or the type of
address (physical or virtual) is not supported by the program
• ValueError -- if size is negative
read_u8(address: IntegerLike, physical: bool = False) -> int
read_u16(address: IntegerLike, physical: bool = False) -> int
read_u32(address: IntegerLike, physical: bool = False) -> int
read_u64(address: IntegerLike, physical: bool = False) -> int
read_word(address: IntegerLike, physical: bool = False) -> int
Read an unsigned integer from the program's memory in the program's byte
order.
read_u8(), read_u16(), read_u32(), and read_u64() read an 8-, 16-, 32-, or
64-bit unsigned integer, respectively. read_word() reads a program
word-sized unsigned integer.
For signed integers, alternate byte order, or other formats, you can use
read() and int.from_bytes() or the struct module.
Parameters
• address -- Address of the integer.
• physical -- Whether address is a physical memory address; see
read().
Raises FaultError -- if the address is invalid; see read()
add_memory_segment(address: IntegerLike, size: IntegerLike, read_fn: Callable[[int,
int, int, bool], bytes], physical: bool = False) -> None
Define a region of memory in the program.
If it overlaps a previously registered segment, the new segment takes
precedence.
Parameters
• address -- Address of the segment.
• size -- Size of the segment in bytes.
• physical -- Whether to add a physical memory segment. If False,
then this adds a virtual memory segment.
• read_fn -- Callable to call to read memory from the segment. It is
passed the address being read from, the number of bytes to read,
the offset in bytes from the beginning of the segment, and whether
the address is physical: (address, count, offset, physical). It
should return the requested number of bytes as bytes or another
buffer type.
add_type_finder(fn: Callable[[TypeKind, str, Optional[str]], Type]) -> None
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 taking a TypeKind, name, and filename: (kind, name,
filename). The filename should be matched with filename_matches().
This should return a Type.
add_object_finder(fn: Callable[[Program, str, FindObjectFlags, Optional[str]],
Object]) -> None
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 taking a program, name, FindObjectFlags, and filename:
(prog, name, flags, filename). The filename should be matched with
filename_matches(). This should return an Object.
set_core_dump(path: Path) -> None
Set the program to a core dump.
This loads the memory segments from the core dump and determines the mapped
executable and libraries. It does not load any debugging symbols; see
load_default_debug_info().
Parameters
path -- Core dump file path.
set_kernel() -> None
Set the program to the running operating system kernel.
This loads the memory of the running kernel and thus requires root
privileges. It does not load any debugging symbols; see
load_default_debug_info().
set_pid(pid: int) -> None
Set the program to a running process.
This loads the memory of the process and determines the mapped executable
and libraries. It does not load any debugging symbols; see
load_default_debug_info().
Parameters
pid -- Process ID.
load_debug_info(paths: Optional[Iterable[Path]] = None, default: bool = False,
main: bool = False) -> None
Load debugging information for a list of executable or library files.
Note that this is parallelized, so it is usually faster to load multiple
files at once rather than one by one.
Parameters
• paths -- Paths of binary files.
• default --
Also load debugging information which can automatically be
determined from the program.
For the Linux kernel, this tries to load vmlinux and any loaded
kernel modules from a few standard locations.
For userspace programs, this tries to load the executable and any
loaded libraries.
This implies main=True.
• main --
Also load debugging information for the main executable.
For the Linux kernel, this tries to load vmlinux.
This is currently ignored for userspace programs.
Raises MissingDebugInfoError -- if debugging information was not available
for some files; other files with debugging information are still
loaded
load_default_debug_info() -> None
Load debugging information which can automatically be determined from the
program.
This is equivalent to load_debug_info(None, True).
cache: Dict[Any, Any]
Dictionary for caching program metadata.
This isn't used by drgn itself. It is intended to be used by helpers to
cache metadata about the program. For example, if a helper for a program
depends on the program version or an optional feature, the helper can detect
it and cache it for subsequent invocations:
def my_helper(prog):
try:
have_foo = prog.cache['have_foo']
except KeyError:
have_foo = detect_foo_feature(prog)
prog.cache['have_foo'] = have_foo
if have_foo:
return prog['foo']
else:
return prog['bar']
class drgn.ProgramFlags
Bases: enum.Flag
ProgramFlags are flags that can apply to a Program (e.g., about what kind of
program it is).
IS_LINUX_KERNEL
The program is the Linux kernel.
IS_LIVE
The program is currently running (e.g., it is the running operating system
kernel or a running process).
class drgn.FindObjectFlags
Bases: enum.Flag
FindObjectFlags are flags for Program.object(). These can be combined to search for
multiple kinds of objects at once.
CONSTANT
FUNCTION
VARIABLE
ANY
class drgn.Thread
A thread in a program.
tid: Final[int]
Thread ID (as defined by gettid(2)).
object: Final[Object]
If the program is the Linux kernel, the struct task_struct * object for this
thread. Otherwise, not defined.
stack_trace() -> StackTrace
Get the stack trace for this thread.
This is equivalent to prog.stack_trace(thread.tid). See
Program.stack_trace().
Filenames
The Program.type(), Program.object(), Program.variable(), Program.constant(), and
Program.function() methods all take a filename parameter to distinguish between multiple
definitions with the same name. The filename refers to the source code file that contains
the definition. It is matched with filename_matches(). If multiple definitions match, one
is returned arbitrarily.
drgn.filename_matches(haystack: Optional[str], needle: Optional[str]) -> bool
Return whether a filename containing a definition (haystack) matches a filename
being searched for (needle).
The filename is matched from right to left, so 'stdio.h', 'include/stdio.h',
'usr/include/stdio.h', and '/usr/include/stdio.h' would all match a definition in
/usr/include/stdio.h. If needle is None or empty, it matches any definition. If
haystack is None or empty, it only matches if needle is also None or empty.
Parameters
• haystack -- Path of file containing definition.
• needle -- Filename to match.
Program Constructors
The drgn command line interface automatically creates a Program named prog. However, drgn
may also be used as a library without the CLI, in which case a Program must be created
manually.
drgn.program_from_core_dump(path: Path) -> Program
Create a Program from a core dump file. The type of program (e.g., userspace or
kernel) is determined automatically.
Parameters
path -- Core dump file path.
drgn.program_from_kernel() -> Program
Create a Program from the running operating system kernel. This requires root
privileges.
drgn.program_from_pid(pid: int) -> Program
Create a Program from a running program with the given PID. This requires
appropriate permissions (on Linux, ptrace(2) attach permissions).
Parameters
pid -- Process ID of the program to debug.
Platforms
class drgn.Platform
A Platform represents the environment (i.e., architecture and ABI) that a program
runs on.
Platform(arch: Architecture, flags: Optional[PlatformFlags] = None)
Create a Platform.
Parameters
• arch -- Platform.arch
• flags -- Platform.flags; if None, default flags for the
architecture are used.
arch: Final[Architecture]
Instruction set architecture of this platform.
flags: Final[PlatformFlags]
Flags which apply to this platform.
registers: Final[Sequence[Register]]
Processor registers on this platform.
class drgn.Architecture
Bases: enum.Enum
An Architecture represents an instruction set architecture.
X86_64 The x86-64 architecture, a.k.a. AMD64 or Intel 64.
I386 The 32-bit x86 architecture, a.k.a. i386 or IA-32.
AARCH64
The AArch64 architecture, a.k.a. ARM64.
ARM The 32-bit Arm architecture.
PPC64 The 64-bit PowerPC architecture.
RISCV64
The 64-bit RISC-V architecture.
RISCV32
The 32-bit RISC-V architecture.
S390X The s390x architecture, a.k.a. IBM Z or z/Architecture.
S390 The 32-bit s390 architecture, a.k.a. System/390.
UNKNOWN
An architecture which is not known to drgn. Certain features are not
available when the architecture is unknown, but most of drgn will still
work.
class drgn.PlatformFlags
Bases: enum.Flag
PlatformFlags are flags describing a Platform.
IS_64_BIT
Platform is 64-bit.
IS_LITTLE_ENDIAN
Platform is little-endian.
class drgn.Register
A Register represents information about a processor register.
names: Final[Sequence[str]]
Names of this register.
drgn.host_platform: Platform
The platform of the host which is running drgn.
Languages
class drgn.Language
A Language represents a programming language supported by drgn.
This class cannot be constructed; there are singletons for the supported languages.
name: Final[str]
Name of the programming language.
C: ClassVar[Language]
The C programming language.
CPP: ClassVar[Language]
The C++ programming language.
Objects
class drgn.Object
An Object represents a symbol or value in a program. An object may exist in the
memory of the program (a reference), it may be a constant or temporary computed
value (a value), or it may be absent entirely (an absent object).
All instances of this class have two attributes: prog_, the program that the object
is from; and type_, the type of the object. Reference objects also have an
address_ and a bit_offset_. Objects may also have a bit_field_size_.
repr() of an object returns a Python representation of the object:
>>> print(repr(prog['jiffies']))
Object(prog, 'volatile unsigned long', address=0xffffffffbf005000)
str() returns a "pretty" representation of the object in programming language
syntax:
>>> print(prog['jiffies'])
(volatile unsigned long)4326237045
The output format of str() can be modified by using the format_() method instead:
>>> sysname = prog['init_uts_ns'].name.sysname
>>> print(sysname)
(char [65])"Linux"
>>> print(sysname.format_(type_name=False))
"Linux"
>>> print(sysname.format_(string=False))
(char [65]){ 76, 105, 110, 117, 120 }
NOTE:
The drgn CLI is set up so that objects are displayed in the "pretty" format
instead of with repr() (the latter is the default behavior of Python's
interactive mode). Therefore, it's usually not necessary to call print() in the
drgn CLI.
Objects support the following operators:
• Arithmetic operators: +, -, *, /, %
• Bitwise operators: <<, >>, &, |, ^, ~
• Relational operators: ==, !=, <, >, <=, >=
• Subscripting: [] (Python does not have a unary * operator, so pointers are
dereferenced with ptr[0])
• Member access: . (Python does not have a -> operator, so . is also used to access
members of pointers to structures)
• The address-of operator: drgn.Object.address_of_() (this is a method because
Python does not have a & operator)
• Array length: len()
These operators all have the semantics of the program's programming language. For
example, adding two objects from a program written in C results in an object with a
type and value according to the rules of C:
>>> Object(prog, 'unsigned long', 2**64 - 1) + Object(prog, 'int', 1)
Object(prog, 'unsigned long', value=0)
If only one operand to a binary operator is an object, the other operand will be
converted to an object according to the language's rules for literals:
>>> Object(prog, 'char', 0) - 1
Object(prog, 'int', value=-1)
The standard int(), float(), and bool() functions convert an object to that Python
type. Conversion to bool uses the programming language's notion of "truthiness".
Additionally, certain Python functions will automatically coerce an object to the
appropriate Python type (e.g., hex(), round(), and list subscripting).
Object attributes and methods are named with a trailing underscore to avoid
conflicting with structure, union, or class members. The attributes and methods
always take precedence; use member_() if there is a conflict.
Objects are usually obtained directly from a Program, but they can be constructed
manually, as well (for example, if you got a variable address from a log file).
Object(prog: Program, type: Union[str, Type], value: Union[IntegerLike, float,
bool, Mapping[str, Any], Sequence[Any]], *, bit_field_size: Optional[IntegerLike] =
None)
Create a value object given its type and value.
Parameters
• prog -- Program to create the object in.
• type -- Type of the object.
• value -- Value of the object. See value_().
• bit_field_size -- Size in bits of the object if it is a bit field.
The default is None, which means the object is not a bit field.
Object(prog: Program, *, value: Union[int, float, bool])
Create a value object from a "literal".
This is used to emulate a literal number in the source code of the program.
The type is deduced from value according to the language's rules for
literals.
Parameters
value -- Value of the literal.
Object(prog: Program, type: Union[str, Type], *, address: IntegerLike, bit_offset:
IntegerLike = 0, bit_field_size: Optional[IntegerLike] = None)
Create a reference object.
Parameters
• address -- Address of the object in the program.
• bit_offset -- Offset in bits from address to the beginning of the
object.
Object(prog: Program, type: Union[str, Type], *, bit_field_size: Optional[‐
IntegerLike] = None)
Create an absent object.
prog_: Final[Program]
Program that this object is from.
type_: Final[Type]
Type of this object.
absent_: Final[bool]
Whether this object is absent.
This is False for all values and references (even if the reference has an
invalid address).
address_: Final[Optional[int]]
Address of this object if it is a reference, None if it is a value or
absent.
bit_offset_: Final[Optional[int]]
Offset in bits from this object's address to the beginning of the object if
it is a reference, None otherwise. This can only be non-zero for scalars.
bit_field_size_: Final[Optional[int]]
Size in bits of this object if it is a bit field, None if it is not.
__getattribute__(name: str) -> Object
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 -- Attribute name.
__getitem__(idx: IntegerLike) -> Object
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 -- The array index.
Raises TypeError -- if this object is not a pointer or array
__len__() -> int
Implement len(self). Get the number of elements in this object.
>>> len(prog['init_task'].comm)
16
This is only valid for arrays.
Raises TypeError -- if this object is not an array with complete type
value_() -> Any
Get the value of this object as a Python object.
For basic types (integer, floating-point, boolean), this returns an object
of the directly corresponding Python type (int, float, bool). For pointers,
this returns the address value of the pointer. For enums, this returns an
int. For structures and unions, this returns a dict of members. For arrays,
this returns a list of values.
Raises
• FaultError -- if reading the object causes a bad memory access
• TypeError -- if this object has an unreadable type (e.g., void)
string_() -> bytes
Read a null-terminated string pointed to by this object.
This is only valid for pointers and arrays. The element type is ignored;
this operates byte-by-byte.
For pointers and flexible arrays, this stops at the first null byte.
For complete arrays, this stops at the first null byte or at the end of the
array.
Raises
• FaultError -- if reading the string causes a bad memory access
• TypeError -- if this object is not a pointer or array
member_(name: str) -> Object
Get a member of this object.
This is valid for structures, unions, 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 -- Name of the member.
Raises
• TypeError -- if this object is not a structure, union, class, or a
pointer to one of those
• LookupError -- if this object does not have a member with the given
name
address_of_() -> Object
Get a pointer to this object.
This corresponds to the address-of (&) operator in C. It is only possible
for reference objects, as value objects don't have an address in the
program.
As opposed to address_, this returns an Object, not an int.
Raises ValueError -- if this object is a value
read_() -> Object
Read this object (which may be a reference or a value) and return it as a
value object.
This is useful if the object can change in the running program (but of
course nothing stops the program from modifying the object while it is being
read).
As opposed to value_(), this returns an Object, not a standard Python type.
Raises
• FaultError -- if reading this object causes a bad memory access
• TypeError -- if this object has an unreadable type (e.g., void)
to_bytes_() -> bytes
Return the binary representation of this object's value.
classmethod from_bytes_(prog: Program, type: Union[str, Type], bytes: bytes, *,
bit_offset: IntegerLike = 0, bit_field_size: Optional[IntegerLike] = None) ->
Object
Return a value object from its binary representation.
Parameters
• prog -- Program to create the object in.
• type -- Type of the object.
• bytes -- Buffer containing value of the object.
• bit_offset -- Offset in bits from the beginning of bytes to the
beginning of the object.
• bit_field_size -- Size in bits of the object if it is a bit field.
The default is None, which means the object is not a bit field.
format_(*, columns: Optional[IntegerLike] = None, dereference: Optional[bool] =
None, symbolize: Optional[bool] = None, string: Optional[bool] = None, char:
Optional[bool] = None, type_name: Optional[bool] = None, member_type_names:
Optional[bool] = None, element_type_names: Optional[bool] = None,
members_same_line: Optional[bool] = None, elements_same_line: Optional[bool] =
None, member_names: Optional[bool] = None, element_indices: Optional[bool] = None,
implicit_members: Optional[bool] = None, implicit_elements: Optional[bool] = None)
-> str
Format this object in programming language syntax.
Various format options can be passed (as keyword arguments) to control the
output. Options that aren't passed or are passed as None fall back to a
default. Specifically, obj.format_() (i.e., with no passed options) is
equivalent to str(obj).
>>> workqueues = prog['workqueues']
>>> print(workqueues)
(struct list_head){
.next = (struct list_head *)0xffff932ecfc0ae10,
.prev = (struct list_head *)0xffff932e3818fc10,
}
>>> print(workqueues.format_(type_name=False,
... member_type_names=False,
... member_names=False,
... members_same_line=True))
{ 0xffff932ecfc0ae10, 0xffff932e3818fc10 }
Parameters
• columns -- Number of columns to limit output to when the expression
can be reasonably wrapped. Defaults to no limit.
• dereference -- If this object is a pointer, include the
dereferenced value. This does not apply to structure, union, or
class members, or array elements, as dereferencing those could lead
to an infinite loop. Defaults to True.
• symbolize -- Include a symbol name and offset for pointer objects.
Defaults to True.
• string -- Format the values of objects with string type as strings.
For C, this applies to pointers to and arrays of char, signed char,
and unsigned char. Defaults to True.
• char -- Format objects with character type as character literals.
For C, this applies to char, signed char, and unsigned char.
Defaults to False.
• type_name -- Include the type name of this object. Defaults to
True.
• member_type_names -- Include the type names of structure, union,
and class members. Defaults to True.
• element_type_names -- Include the type names of array elements.
Defaults to False.
• members_same_line -- Place multiple structure, union, and class
members on the same line if they fit within the specified number of
columns. Defaults to False.
• elements_same_line -- Place multiple array elements on the same
line if they fit within the specified number of columns. Defaults
to True.
• member_names -- Include the names of structure, union, and class
members. Defaults to True.
• element_indices -- Include the indices of array elements. Defaults
to False.
• implicit_members -- Include structure, union, and class members
which have an implicit value (i.e., for C, zero-initialized).
Defaults to True.
• implicit_elements -- Include array elements which have an implicit
value (i.e., for C, zero-initialized). Defaults to False.
drgn.NULL(prog: Program, type: Union[str, Type]) -> Object
Get an object representing NULL casted to the given type.
This is equivalent to Object(prog, type, 0).
Parameters
• prog -- The program.
• type -- The type.
drgn.cast(type: Union[str, Type], obj: Object) -> Object
Get the value of 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
• type -- The type to cast to.
• obj -- The object to cast.
drgn.reinterpret(type: Union[str, Type], obj: Object) -> Object
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 -- The type to reinterpret as.
• obj -- The object to reinterpret.
drgn.container_of(ptr: Object, type: Union[str, Type], member: str) -> Object
Get the containing object of a pointer object.
This corresponds to the container_of() macro in C.
Parameters
• ptr -- Pointer to member in containing object.
• type -- Type of containing object.
• member -- Name of member in containing object. May include one or more
member references and zero or more array subscripts.
Returns
Pointer to containing object.
Raises
• TypeError -- if ptr is not a pointer or type is not a structure, union, or
class type
• ValueError -- if the member is not byte-aligned (e.g., because it is a bit
field)
• LookupError -- if type does not have a member with the given name
Symbols
class drgn.Symbol
A Symbol represents an entry in the symbol table of a program, i.e., an identifier
along with its corresponding address range in the program.
name: Final[str]
Name of this symbol.
address: Final[int]
Start address of this symbol.
size: Final[int]
Size of this symbol in bytes.
binding: Final[SymbolBinding]
Linkage behavior and visibility of this symbol.
kind: Final[SymbolKind]
Kind of entity represented by this symbol.
class drgn.SymbolBinding
Bases: enum.Enum
A SymbolBinding describes the linkage behavior and visibility of a symbol.
UNKNOWN
Unknown.
LOCAL Not visible outside of the object file containing its definition.
GLOBAL Globally visible.
WEAK Globally visible but may be overridden by a non-weak global symbol.
UNIQUE Globally visible even if dynamic shared object is loaded locally. See GCC's
-fno-gnu-unique option.
class drgn.SymbolKind
Bases: enum.Enum
A SymbolKind describes the kind of entity that a symbol represents.
UNKNOWN
Unknown or not defined.
OBJECT Data object (e.g., variable or array).
FUNC Function or other executable code.
SECTION
Object file section.
FILE Source file.
COMMON Data object in common block.
TLS Thread-local storage entity.
IFUNC Indirect function.
Stack Traces
Stack traces are retrieved with 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.
prog: Final[Program]
Program that this stack trace is from.
class drgn.StackFrame
A StackFrame represents a single frame in a thread's call stack.
str() returns a pretty-printed stack frame:
>>> prog.stack_trace(1)[0]
#0 at 0xffffffffb64ac287 (__schedule+0x227/0x606) in context_switch at kernel/sched/core.c:4339:2 (inlined)
This includes more information than when printing the full stack trace. The format
is subject to change. The drgn CLI is set up so that stack frames are displayed
with str() by default.
The [] operator can look up function parameters, local variables, and global
variables in the scope of the stack frame:
>>> prog.stack_trace(1)[0]['prev'].pid
(pid_t)1
>>> prog.stack_trace(1)[0]['scheduler_running']
(int)1
name: Final[Optional[str]]
Name of the function at this frame, or None if it could not be determined.
The name cannot be determined if debugging information is not available for
the function, e.g., because it is implemented in assembly. It may be
desirable to use the symbol name or program counter as a fallback:
name = frame.name
if name is None:
try:
name = frame.symbol().name
except LookupError:
name = hex(frame.pc)
is_inline: Final[bool]
Whether this frame is for an inlined call.
An inline frame shares the same stack frame in memory as its caller.
Therefore, it has the same registers (including program counter and thus
symbol).
interrupted: Final[bool]
Whether this stack frame was interrupted (for example, by a hardware
interrupt, signal, trap, etc.).
If this is True, then the register values in this frame are the values at
the time that the frame was interrupted.
This is False if the frame is for a function call, in which case the
register values are the values when control returns to this frame. In
particular, the program counter is the return address, which is typically
the instruction after the call instruction.
pc: Final[int]
Program counter at this stack frame.
sp: Final[int]
Stack pointer at this stack frame.
__getitem__(name: str) -> Object
Implement self[name]. Get the object (variable, function parameter,
constant, or function) with the given name in the scope of this frame.
If the object exists but has been optimized out, this returns an absent
object.
Parameters
name -- Object name.
__contains__(name: str) -> bool
Implement name in self. Return whether an object with the given name exists
in the scope of this frame.
Parameters
name -- Object name.
locals() -> List[str]
Get a list of the names of all local objects (local variables, function
parameters, local constants, and nested functions) in the scope of this
frame.
Not all names may have present values, but they can be used with the []
operator to check.
source() -> Tuple[str, int, int]
Get the source code location of this frame.
Returns
Location as a (filename, line, column) triple.
Raises LookupError -- if the source code location is not available
symbol() -> Symbol
Get the function symbol at this stack frame.
This is equivalent to:
prog.symbol(frame.pc - (0 if frame.interrupted else 1))
register(reg: str) -> int
Get the value of the given register at this stack frame.
Parameters
reg -- Register name.
Raises
• ValueError -- if the register name is not recognized
• LookupError -- if the register value is not known
registers() -> Dict[str, int]
Get the values of all available registers at this stack frame as a
dictionary with the register names as keys.
Types
class drgn.Type
A Type object describes a type in a program. Each kind of type (e.g., integer,
structure) has different attributes (e.g., name, size). Types can also have
qualifiers (e.g., constant, atomic). Accessing an attribute which does not apply to
a type raises an AttributeError.
repr() of a Type returns a Python representation of the type:
>>> print(repr(prog.type('sector_t')))
prog.typedef_type(name='sector_t', type=prog.int_type(name='unsigned long', size=8, is_signed=False))
str() returns a representation of the type in programming language syntax:
>>> print(prog.type('sector_t'))
typedef unsigned long sector_t
The drgn CLI is set up so that types are displayed with str() instead of repr() by
default.
This class cannot be constructed directly. Instead, use one of the Type
Constructors.
prog: Final[Program]
Program that this type is from.
kind: Final[TypeKind]
Kind of this type.
primitive: Final[Optional[PrimitiveType]]
If this is a primitive type (e.g., int or double), the kind of primitive
type. Otherwise, None.
qualifiers: Final[Qualifiers]
Bitmask of this type's qualifier.
language: Final[Language]
Programming language of this type.
name: Final[str]
Name of this type. This is present for integer, boolean, floating-point, and
typedef types.
tag: Final[Optional[str]]
Tag of this type, or None if this is an anonymous type. This is present for
structure, union, class, and enumerated types.
size: Final[Optional[int]]
Size of this type in bytes, or None if this is an incomplete type. This is
present for integer, boolean, floating-point, structure, union, class, and
pointer types.
length: Final[Optional[int]]
Number of elements in this type, or None if this is an incomplete type.
This is only present for array types.
is_signed: Final[bool]
Whether this type is signed. This is only present for integer types.
byteorder: Final[str]
Byte order of this type: 'little' if it is little-endian, or 'big' if it is
big-endian. This is present for integer, boolean, floating-point, and
pointer types.
type: Final[Type]
Type underlying this type, defined as follows:
• For typedef types, the aliased type.
• For enumerated types, the compatible integer type, which is None if this
is an incomplete type.
• For pointer types, the referenced type.
• For array types, the element type.
• For function types, the return type.
For other types, this attribute is not present.
members: Final[Optional[Sequence[TypeMember]]]
List of members of this type, or None if this is an incomplete type. This
is present for structure, union, and class types.
enumerators: Final[Optional[Sequence[TypeEnumerator]]]
List of enumeration constants of this type, or None if this is an incomplete
type. This is only present for enumerated types.
parameters: Final[Sequence[TypeParameter]]
List of parameters of this type. This is only present for function types.
is_variadic: Final[bool]
Whether this type takes a variable number of arguments. This is only present
for function types.
template_parameters: Final[Sequence[TypeTemplateParameter]]
List of template parameters of this type. This is present for structure,
union, class, and function types.
type_name() -> str
Get a descriptive full name of this type.
is_complete() -> bool
Get whether this type is complete (i.e., the type definition is known).
This is always False for void types. It may be False for structure, union,
class, enumerated, and array types, as well as typedef types where the
underlying type is one of those. Otherwise, it is always True.
qualified(qualifiers: Qualifiers) -> Type
Get a copy of this type with different qualifiers.
Note that the original qualifiers are replaced, not added to.
Parameters
qualifiers -- New type qualifiers.
unqualified() -> Type
Get a copy of this type with no qualifiers.
member(name: str) -> TypeMember
Look up a member in this type by name.
If this type has any unnamed members, this also matches members of those
unnamed members, recursively. If the member is found in an unnamed member,
TypeMember.bit_offset and TypeMember.offset are adjusted accordingly.
Parameters
name -- Name of the member.
Raises
• TypeError -- if this type is not a structure, union, or class type
• LookupError -- if this type does not have a member with the given
name
has_member(name: str) -> bool
Return whether this type has a member with the given name.
If this type has any unnamed members, this also matches members of those
unnamed members, recursively.
Parameters
name -- Name of the member.
Raises TypeError -- if this type is not a structure, union, or class type
class drgn.TypeMember
A TypeMember represents a member of a structure, union, or class type.
TypeMember(object_or_type: Union[Object, Type, Callable[[], Union[Object, Type]]],
name: Optional[str] = None, bit_offset: int = 0)
Create a TypeMember.
Parameters
• object_or_type --
One of:
1. TypeMember.object as an Object.
2. TypeMember.type as a Type. In this case, object is set to an
absent object with that type.
3. A callable that takes no arguments and returns one of the above.
It is called when object or type is first accessed, and the
result is cached.
• name -- TypeMember.name
• bit_offset -- TypeMember.bit_offset
object: Final[Object]
Member as an Object.
This is the default initializer for the member, or an absent object if the
member has no default initializer. (However, the DWARF specification as of
version 5 does not actually support default member initializers, so this is
usually absent.)
type: Final[Type]
Member type.
This is a shortcut for TypeMember.object.type.
name: Final[Optional[str]]
Member name, or None if the member is unnamed.
bit_offset: Final[int]
Offset of the member from the beginning of the type in bits.
offset: Final[int]
Offset of the member from the beginning of the type in bytes. If the offset
is not byte-aligned, accessing this attribute raises ValueError.
bit_field_size: Final[Optional[int]]
Size in bits of this member if it is a bit field, None if it is not.
This is a shortcut for TypeMember.object.bit_field_size_.
class drgn.TypeEnumerator
A TypeEnumerator represents a constant in an enumerated type.
Its name and value may be accessed as attributes or unpacked:
>>> prog.type('enum pid_type').enumerators[0].name
'PIDTYPE_PID'
>>> name, value = prog.type('enum pid_type').enumerators[0]
>>> value
0
TypeEnumerator(name: str, value: int)
Create a TypeEnumerator.
Parameters
• name -- TypeEnumerator.name
• value -- TypeEnumerator.value
name: Final[str]
Enumerator name.
value: Final[int]
Enumerator value.
class drgn.TypeParameter
A TypeParameter represents a parameter of a function type.
TypeParameter(default_argument_or_type: Union[Object, Type, Callable[[], Union[‐
Object, Type]]], name: Optional[str] = None)
Create a TypeParameter.
Parameters
• default_argument_or_type --
One of:
1. TypeParameter.default_argument as an Object.
2. TypeParameter.type as a Type. In this case, default_argument is
set to an absent object with that type.
3. A callable that takes no arguments and returns one of the above.
It is called when default_argument or type is first accessed,
and the result is cached.
• name -- TypeParameter.name
default_argument: Final[Object]
Default argument for parameter.
If the parameter does not have a default argument, then this is an absent
object.
NOTE:
Neither GCC nor Clang emits debugging information for default arguments
(as of GCC 10 and Clang 11), and drgn does not yet parse it, so this is
usually absent.
type: Final[Type]
Parameter type.
This is the same as TypeParameter.default_argument.type_.
name: Final[Optional[str]]
Parameter name, or None if the parameter is unnamed.
class drgn.TypeTemplateParameter
A TypeTemplateParameter represents a template parameter of a structure, union,
class, or function type.
TypeTemplateParameter(argument: Union[Type, Object, Callable[[], Union[Type,
Object]]], name: Optional[str] = None, is_default: bool = False)
Create a TypeTemplateParameter.
Parameters
• argument --
One of:
1. TypeTemplateParameter.argument as a Type if the parameter is a
type template parameter.
2. TypeTemplateParameter.argument as a non-absent Object if the
parameter is a non-type template parameter.
3. A callable that takes no arguments and returns one of the above.
It is called when argument is first accessed, and the result is
cached.
• name -- TypeTemplateParameter.name
• is_default -- TypeTemplateParameter.is_default
argument: Final[Union[Type, Object]]
Template argument.
If this is a type template parameter, then this is a Type. If this is a
non-type template parameter, then this is an Object.
name: Final[Optional[str]]
Template parameter name, or None if the parameter is unnamed.
is_default: Final[bool]
Whether argument is the default for the template parameter.
NOTE:
There are two ways to interpret this:
1. The argument was omitted entirely and thus defaulted to the
default argument.
2. The (specified or defaulted) argument is the same as the default
argument.
Compilers are inconsistent about which interpretation they use.
GCC added this information in version 4.9. Clang added it in version 11
(and only when emitting DWARF version 5). If the program was compiled by
an older version, this is always false.
class drgn.TypeKind
Bases: enum.Enum
A TypeKind represents a kind of type.
VOID Void type.
INT Integer type.
BOOL Boolean type.
FLOAT Floating-point type.
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: Type, member: str) -> int
Get the offset (in bytes) of a member in a Type.
This corresponds to offsetof() in C.
Parameters
• type -- Structure, union, or class type.
• member -- Name of member. May include one or more member references and
zero or more array subscripts.
Raises
• TypeError -- if type is not a structure, union, or class type
• ValueError -- if the member is not byte-aligned (e.g., because it is a bit
field)
• LookupError -- if type does not have a member with the given name
Type Constructors
Custom drgn types can be created with the following factory functions. These can be used
just like types obtained from Program.type().
Program.void_type(*, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[‐
Language] = None) -> Type
Create a new void type. It has kind TypeKind.VOID.
Parameters
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.int_type(name: str, size: IntegerLike, is_signed: bool, byteorder: Optional[str] =
None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) ->
Type
Create a new integer type. It has kind TypeKind.INT.
Parameters
• name -- Type.name
• size -- Type.size
• is_signed -- Type.is_signed
• byteorder -- Type.byteorder, or None to use the program's default byte
order.
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.bool_type(name: str, size: IntegerLike, byteorder: Optional[str] = None, *,
qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new boolean type. It has kind TypeKind.BOOL.
Parameters
• name -- Type.name
• size -- Type.size
• byteorder -- Type.byteorder, or None to use the program's default byte
order.
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.float_type(name: str, size: IntegerLike, byteorder: Optional[str] = None, *,
qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new floating-point type. It has kind TypeKind.FLOAT.
Parameters
• name -- Type.name
• size -- Type.size
• byteorder -- Type.byteorder, or None to use the program's default byte
order.
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.struct_type(tag: Optional[str], size: IntegerLike, members: Sequence[TypeMember],
*, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new structure type. It has kind TypeKind.STRUCT.
Parameters
• tag -- Type.tag
• size -- Type.size
• members -- Type.members
• template_parameters -- Type.template_parameters
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.struct_type(tag: Optional[str], size: None = None, members: None = None, *,
template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new incomplete structure type.
Program.union_type(tag: Optional[str], size: IntegerLike, members: Sequence[TypeMember],
*, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new union type. It has kind TypeKind.UNION. Otherwise, this is the same as
as struct_type().
Program.union_type(tag: Optional[str], size: None = None, members: None = None, *,
template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new incomplete union type.
Program.class_type(tag: Optional[str], size: IntegerLike, members: Sequence[TypeMember],
*, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new class type. It has kind TypeKind.CLASS. Otherwise, this is the same as
as struct_type().
Program.class_type(tag: Optional[str], size: None = None, members: None = None, *,
template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new incomplete class type.
Program.enum_type(tag: Optional[str], type: Type, enumerators: Sequence[TypeEnumerator],
*, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new enumerated type. It has kind TypeKind.ENUM.
Parameters
• tag -- Type.tag
• type -- The compatible integer type (Type.type)
• enumerators -- Type.enumerators
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.enum_type(tag: Optional[str], type: None = None, enumerators: None = None, *,
qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new incomplete enumerated type.
Program.typedef_type(name: str, type: Type, *, qualifiers: Qualifiers = Qualifiers.NONE,
language: Optional[Language] = None) -> Type
Create a new typedef type. It has kind TypeKind.TYPEDEF.
Parameters
• name -- Type.name
• type -- The aliased type (Type.type)
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.pointer_type(type: Type, size: Optional[int] = None, byteorder: Optional[str] =
None, *, qualifiers: Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) ->
Type
Create a new pointer type. It has kind TypeKind.POINTER,
Parameters
• type -- The referenced type (Type.type)
• size -- Type.size, or None to use the program's default pointer size.
• byteorder -- Type.byteorder, or None to use the program's default byte
order.
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.array_type(type: Type, length: Optional[int] = None, *, qualifiers: Qualifiers =
Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new array type. It has kind TypeKind.ARRAY.
Parameters
• type -- The element type (Type.type)
• length -- Type.length
• qualifiers -- Type.qualifiers
• lang -- Type.language
Program.function_type(type: Type, parameters: Sequence[TypeParameter], is_variadic: bool =
False, *, template_parameters: Sequence[TypeTemplateParameter] = (), qualifiers:
Qualifiers = Qualifiers.NONE, language: Optional[Language] = None) -> Type
Create a new function type. It has kind TypeKind.FUNCTION.
Parameters
• type -- The return type (Type.type)
• parameters -- Type.parameters
• is_variadic -- Type.is_variadic
• template_parameters -- Type.template_parameters
• qualifiers -- Type.qualifiers
• lang -- Type.language
Miscellaneous
drgn.sizeof(type_or_obj: Union[Type, Object]) -> int
Get the size of a Type or Object in bytes.
Parameters
type_or_obj -- Entity to get the size of.
Raises TypeError -- if the type does not have a size (e.g., because it is
incomplete or void)
drgn.execscript(path: str, *args: str) -> None
Execute a script.
The script is executed in the same context as the caller: currently defined globals
are available to the script, and globals defined by the script are added back to
the calling context.
This is most useful for executing scripts from interactive mode. For example, you
could have a script named exe.py:
"""Get all tasks executing a given file."""
import sys
from drgn.helpers.linux.fs import d_path
from drgn.helpers.linux.pid import find_task
def task_exe_path(task):
if task.mm:
return d_path(task.mm.exe_file.f_path).decode()
else:
return None
tasks = [
task for task in for_each_task(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 -- File path of the script.
• args -- Zero or more additional arguments to pass to the script. This is a
variable argument list.
class drgn.IntegerLike
Bases: Protocol
An int or integer-like object.
Parameters annotated with this type expect an integer which may be given as a
Python int or an Object with integer type.
drgn.Path: TypeAlias
Filesystem path.
Parameters annotated with this type accept a filesystem path as str, bytes, or
os.PathLike.
Exceptions
class drgn.FaultError
Bases: Exception
This error is raised when a bad memory access is attempted (i.e., when accessing a
memory address which is not valid in a program).
FaultError(message: str, address: int)
Parameters
• message -- FaultError.message
• address -- FaultError.address
message: str
Error message.
address: int
Address that couldn't be accessed.
class drgn.MissingDebugInfoError
Bases: Exception
This error is raised when one or more files in a program do not have debug
information.
class drgn.ObjectAbsentError
Bases: Exception
This error is raised when attempting to use an absent object.
class drgn.OutOfBoundsError
Bases: Exception
This error is raised when attempting to access beyond the bounds of a value object.
CLI
Functions for embedding the drgn CLI.
drgn.cli.version_header() -> str
Return the version header printed at the beginning of a drgn session.
The run_interactive() function does not include this banner at the beginning of an
interactive session. Use this function to retrieve one line of text to add to the
beginning of the drgn banner, or print it before calling run_interactive().
drgn.cli.run_interactive(prog: drgn.Program, banner_func: Optional[Callable[[str], str]] =
None, globals_func: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None, quiet:
bool = False) -> None
Run drgn's Interactive Mode until the user exits.
This function allows your application to embed the same REPL that drgn provides
when it is run on the command line in interactive mode.
Parameters
• prog -- Pre-configured program to run against. Available as a global named
prog in the CLI.
• banner_func -- Optional function to modify the printed banner. Called with
the default banner, and must return a string to use as the new banner. The
default banner does not include the drgn version, which can be retrieved
via version_header().
• globals_func -- Optional function to modify globals provided to the
session. Called with a dictionary of default globals, and must return a
dictionary to use instead.
• quiet -- Whether to suppress non-fatal warnings.
NOTE:
This function uses readline and modifies some settings. Unfortunately, it is
not possible for it to restore all settings. In particular, it clears the
readline history and resets the TAB keybinding to the default.
Applications using readline should save their history and clear any custom
settings before calling this function. After calling this function, applications
should restore their history and settings before using readline.
Helpers
The drgn.helpers package contains subpackages which provide helpers for working with
particular types of programs. Currently, there are common helpers and helpers for the
Linux kernel. In the future, there may be helpers for, e.g., glibc and libstdc++.
class drgn.helpers.ValidationError
Bases: Exception
Error raised by a validator when an inconsistent or invalid state is detected.
Common
The drgn.helpers.common package provides helpers that can be used with any program. The
helpers are available from the individual modules in which they are defined and from this
top-level package. E.g., the following are both valid:
>>> from drgn.helpers.common.memory import identify_address
>>> from drgn.helpers.common import identify_address
Some of these helpers may have additional program-specific behavior but are otherwise
generic.
Formatting
The drgn.helpers.common.format module provides generic helpers for formatting different
things as text.
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.
Parameters
• c -- Character to escape.
• escape_single_quote -- Whether to escape single quotes to \'.
• escape_double_quote -- Whether to escape double quotes to \".
• escape_backslash -- Whether to escape backslashes to \\.
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().
Parameters
buffer -- Byte array to escape.
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'
Parameters
• value -- Bitmask to decode.
• flags -- List of flag names and their bit numbers or values.
• bit_numbers -- Whether flags specifies the bit numbers (where 0 is the
least significant bit) or values of the flags.
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().
Parameters
• value -- Bitmask to decode.
• type -- Enumerated type with bit numbers for enumerators.
• bit_numbers -- Whether the enumerator values specify the bit numbers or
values of the 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'
Parameters
• n -- Number to format.
• precision -- Number of digits to include in fractional part.
Memory
The drgn.helpers.common.memory module provides helpers for working with memory and
addresses.
drgn.helpers.common.memory.identify_address(addr: drgn.Object) -> Optional[str]
drgn.helpers.common.memory.identify_address(prog: drgn.Program, addr: drgn.IntegerLike) ->
Optional[str]
Try to identify what an address refers to.
For all programs, this will identify addresses as follows:
• Object symbols (e.g., addresses in global variables): object symbol:
{symbol_name}+{hex_offset} (where hex_offset is the offset from the beginning of
the symbol in hexadecimal).
• Function symbols (i.e., addresses in functions): function symbol:
{symbol_name}+{hex_offset}.
• Other symbols: symbol: {symbol_name}+{hex_offset}.
Additionally, for the Linux kernel, this will identify:
• Allocated slab objects: slab object: {slab_cache_name}+{hex_offset} (where
hex_offset is the offset from the beginning of the object in hexadecimal).
• Free slab objects: free slab object: {slab_cache_name}+{hex_offset}.
This may recognize other types of addresses in the future.
The address can be given as an Object or as a Program and an integer.
Parameters
addr -- void *
Returns
Identity as string, or None if the address is unrecognized.
Stack
The drgn.helpers.common.stack module provides helpers for working with stack traces.
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().
>>> print_annotated_stack(prog.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]
...
Parameters
trace -- Stack trace to print.
Types
The drgn.helpers.common.type module provides generic helpers for working with types in
ways that aren't provided by the core drgn library.
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.
Parameters
• type -- Enumerated type to convert.
• name -- Name of the IntEnum type to create.
• exclude -- Container (e.g., list or set) of enumerator names to exclude
from the created IntEnum.
• prefix -- Prefix to strip from the beginning of enumerator names.
Linux Kernel
The drgn.helpers.linux package contains several modules for working with data structures
and subsystems in the Linux kernel. The helpers are available from the individual modules
in which they are defined and from this top-level package. E.g., the following are both
valid:
>>> from drgn.helpers.linux.list import list_for_each_entry
>>> from drgn.helpers.linux import list_for_each_entry
Iterator macros (for_each_foo) are a common idiom in the Linux kernel. The equivalent drgn
helpers are implemented as Python generators. For example, the following code in C:
list_for_each(pos, head)
do_something_with(pos);
Translates to the following code in Python:
for pos in list_for_each(head):
do_something_with(pos)
Bit Operations
The drgn.helpers.linux.bitops module provides helpers for common bit operations in the
Linux kernel.
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.
Parameters
• bitmap -- unsigned long *
• size -- Size of bitmap in bits.
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.
Parameters
• bitmap -- unsigned long *
• size -- Size of bitmap in bits.
drgn.helpers.linux.bitops.test_bit(nr: drgn.IntegerLike, bitmap: drgn.Object) -> bool
Return whether a bit in a bitmap is set.
Parameters
• nr -- Bit number.
• bitmap -- unsigned long *
Block Layer
The drgn.helpers.linux.block module provides helpers for working with the Linux block
layer, including disks (struct gendisk) and partitions.
Since Linux v5.11, partitions are represented by struct block_device. Before that, they
were represented by struct hd_struct.
drgn.helpers.linux.block.disk_devt(disk: drgn.Object) -> drgn.Object
Get a disk's device number.
Parameters
disk -- struct gendisk *
Returns
dev_t
drgn.helpers.linux.block.disk_name(disk: drgn.Object) -> bytes
Get the name of a disk (e.g., sda).
Parameters
disk -- struct gendisk *
drgn.helpers.linux.block.for_each_disk(prog: drgn.Program) -> Iterator[drgn.Object]
Iterate over all disks in the system.
Returns
Iterator of struct gendisk * objects.
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.
Parameters
part -- struct block_device * or struct hd_struct * depending on the kernel
version.
Returns
dev_t
drgn.helpers.linux.block.part_name(part: drgn.Object) -> bytes
Get the name of a partition (e.g., sda1).
Parameters
part -- struct block_device * or struct hd_struct * depending on the kernel
version.
drgn.helpers.linux.block.for_each_partition(prog: drgn.Program) -> Iterator[drgn.Object]
Iterate over all partitions in the system.
Returns
Iterator of struct block_device * or struct hd_struct * objects depending on
the kernel version.
drgn.helpers.linux.block.print_partitions(prog: drgn.Program) -> None
Print all of the partitions in the system.
Boot
The drgn.helpers.linux.boot module provides helpers for inspecting the Linux kernel boot
configuration.
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.
BPF
The drgn.helpers.linux.bpf module provides helpers for working with BPF interface in
include/linux/bpf.h, include/linux/bpf-cgroup.h, etc.
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.
Returns
Iterator of struct btf * objects.
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.
Returns
Iterator of struct bpf_link * objects.
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.
Returns
Iterator of struct bpf_map * objects.
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.
Returns
Iterator of struct bpf_prog * objects.
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.
Parameters
• cgrp -- struct cgroup *
• bpf_attach_type -- enum bpf_attach_type
Returns
Iterator of struct bpf_prog * objects.
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.
Parameters
• cgrp -- struct cgroup *
• bpf_attach_type -- enum bpf_attach_type
Returns
Iterator of struct bpf_prog * objects.
Cgroup
The drgn.helpers.linux.cgroup module provides helpers for working with the cgroup
interface in include/linux/cgroup.h. Only cgroup v2 is supported.
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).
Parameters
skcd -- struct sock_cgroup_data *
Returns
struct cgroup *
drgn.helpers.linux.cgroup.cgroup_parent(cgrp: drgn.Object) -> drgn.Object
Return the parent cgroup of the given cgroup if it exists, NULL otherwise.
Parameters
cgrp -- struct cgroup *
Returns
struct cgroup *
drgn.helpers.linux.cgroup.cgroup_name(cgrp: drgn.Object) -> bytes
Get the name of the given cgroup.
Parameters
cgrp -- struct cgroup *
drgn.helpers.linux.cgroup.cgroup_path(cgrp: drgn.Object) -> bytes
Get the full path of the given cgroup.
Parameters
cgrp -- struct 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 .
Parameters
path -- Path name.
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).
Parameters
• pos -- struct cgroup_subsys_state *
• parent -- struct cgroup_subsys_state *
Returns
struct cgroup_subsys_state *
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).
Parameters
• pos -- struct cgroup_subsys_state *
• root -- struct cgroup_subsys_state *
Returns
struct cgroup_subsys_state *
drgn.helpers.linux.cgroup.css_for_each_child(css: drgn.Object) -> Iterator[drgn.Object]
Iterate through children of the given css.
Parameters
css -- struct cgroup_subsys_state *
Returns
Iterator of struct cgroup_subsys_state * objects.
drgn.helpers.linux.cgroup.css_for_each_descendant_pre(css: drgn.Object) -> Iterator[‐
drgn.Object]
Iterate through the given css's descendants in pre-order.
Parameters
css -- struct cgroup_subsys_state *
Returns
Iterator of struct cgroup_subsys_state * objects.
CPU Masks
The drgn.helpers.linux.cpumask module provides helpers for working with CPU masks from
include/linux/cpumask.h.
drgn.helpers.linux.cpumask.for_each_cpu(mask: drgn.Object) -> Iterator[int]
Iterate over all of the CPUs in the given mask.
Parameters
mask -- struct cpumask
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.
Devices
The drgn.helpers.linux.device module provides helpers for working with Linux devices,
including the kernel encoding of dev_t.
drgn.helpers.linux.device.MAJOR(dev: drgn.IntegerLike) -> int
Return the major ID of a kernel dev_t.
Parameters
dev -- dev_t object or :class:int.
drgn.helpers.linux.device.MINOR(dev: drgn.IntegerLike) -> int
Return the minor ID of a kernel dev_t.
Parameters
dev -- dev_t object or :class:int.
drgn.helpers.linux.device.MKDEV(major: drgn.IntegerLike, minor: drgn.IntegerLike) -> int
Return a kernel dev_t from the major and minor IDs.
Parameters
• major -- Device major ID.
• minor -- Device minor ID.
Virtual Filesystem Layer
The drgn.helpers.linux.fs module provides helpers for working with the Linux virtual
filesystem (VFS) layer, including mounts, dentries, and inodes.
drgn.helpers.linux.fs.path_lookup(prog_or_root: Union[drgn.Program, drgn.Object], path:
drgn.Path, allow_negative: bool = False) -> drgn.Object
Look up the given path name.
Parameters
• prog_or_root -- struct path * object to use as root directory, or Program
to use the initial root filesystem.
• path -- Path to lookup.
• allow_negative -- Whether to allow returning a negative dentry (i.e., a
dentry for a non-existent path).
Returns
struct path
Raises Exception -- if the dentry is negative and allow_negative is False, or if
the path is not present in the dcache. The latter does not necessarily mean
that the path does not exist; it may be uncached. On a live system, you can
make the kernel cache the path by accessing it (e.g., with open() or
os.stat()):
>>> path_lookup(prog, '/usr/include/stdlib.h')
...
Exception: could not find '/usr/include/stdlib.h' in dcache
>>> open('/usr/include/stdlib.h').close()
>>> path_lookup(prog, '/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.
Parameters
path -- struct path or 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.
Parameters
• vfsmnt -- struct vfsmount *
• dentry -- struct dentry *
drgn.helpers.linux.fs.dentry_path(dentry: drgn.Object) -> bytes
Return the path of a dentry from the root of its filesystem.
Parameters
dentry -- struct dentry *
drgn.helpers.linux.fs.inode_path(inode: drgn.Object) -> Optional[bytes]
Return any path of an inode from the root of its filesystem.
Parameters
inode -- struct inode *
Returns
Path, or None if the inode has no aliases.
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.
Parameters
inode -- struct inode *
drgn.helpers.linux.fs.mount_src(mnt: drgn.Object) -> bytes
Get the source device name for a mount.
Parameters
mnt -- struct mount *
drgn.helpers.linux.fs.mount_dst(mnt: drgn.Object) -> bytes
Get the path of a mount point.
Parameters
mnt -- struct mount *
drgn.helpers.linux.fs.mount_fstype(mnt: drgn.Object) -> bytes
Get the filesystem type of a mount.
Parameters
mnt -- struct mount *
drgn.helpers.linux.fs.for_each_mount(prog_or_ns: Union[drgn.Program, drgn.Object], 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.
Parameters
• prog_or_ns -- struct mnt_namespace * to iterate over, or Program to
iterate over initial mount namespace.
• src -- Only include mounts with this source device name.
• dst -- Only include mounts with this destination path.
• fstype -- Only include mounts with this filesystem type.
Returns
Iterator of struct mount * objects.
drgn.helpers.linux.fs.print_mounts(prog_or_ns: Union[drgn.Program, drgn.Object], 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.
Parameters
• task -- struct task_struct *
• fd -- File descriptor.
Returns
struct file *
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.
Parameters
task -- struct task_struct *
Returns
Iterator of (fd, struct file *) tuples.
drgn.helpers.linux.fs.print_files(task: drgn.Object) -> None
Print the open files of a given task.
Parameters
task -- struct task_struct *
IDR
The drgn.helpers.linux.idr module provides helpers for working with the IDR data structure
in include/linux/idr.h. An IDR provides a mapping from an ID to a pointer.
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.
Parameters
• idr -- struct idr *
• id -- Entry ID.
Returns
void * found entry, or NULL if not found.
drgn.helpers.linux.idr.idr_for_each(idr: drgn.Object) -> Iterator[Tuple[int, drgn.Object]]
Iterate over all of the entries in an IDR.
Parameters
idr -- struct idr *
Returns
Iterator of (index, void *) tuples.
Kconfig
The drgn.helpers.linux.kconfig module provides helpers for reading the Linux kernel build
configuration.
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(prog)['CONFIG_SMP']
'y'
>>> get_kconfig(prog)['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.
Kernfs
The drgn.helpers.linux.kernfs module provides helpers for working with the kernfs pseudo
filesystem interface in include/linux/kernfs.h.
drgn.helpers.linux.kernfs.kernfs_name(kn: drgn.Object) -> bytes
Get the name of the given kernfs node.
Parameters
kn -- struct kernfs_node *
drgn.helpers.linux.kernfs.kernfs_path(kn: drgn.Object) -> bytes
Get full path of the given kernfs node.
Parameters
kn -- struct 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.
Parameters
• parent -- struct kernfs_node *
• path -- Path name.
Returns
struct kernfs_node * (NULL if not found)
Linked Lists
The drgn.helpers.linux.list module provides helpers for working with the doubly-linked
list implementations (struct list_head and struct hlist_head) in include/linux/list.h.
drgn.helpers.linux.list.list_empty(head: drgn.Object) -> bool
Return whether a list is empty.
Parameters
head -- struct list_head *
drgn.helpers.linux.list.list_is_singular(head: drgn.Object) -> bool
Return whether a list has only one element.
Parameters
head -- struct list_head *
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().
Parameters
• head -- struct list_head *
• type -- Entry type.
• member -- Name of list node member in entry type.
Returns
type *
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().
Parameters
• head -- struct list_head *
• type -- Entry type.
• member -- Name of list node member in entry type.
Returns
type *
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.
Parameters
• head -- struct list_head *
• type -- Entry type.
• member -- Name of list node member in entry type.
Returns
type *
drgn.helpers.linux.list.list_next_entry(pos: drgn.Object, member: str) -> drgn.Object
Return the next entry in a list.
Parameters
• pos -- type*
• member -- Name of list node member in entry type.
Returns
type *
drgn.helpers.linux.list.list_prev_entry(pos: drgn.Object, member: str) -> drgn.Object
Return the previous entry in a list.
Parameters
• pos -- type*
• member -- Name of list node member in entry type.
Returns
type *
drgn.helpers.linux.list.list_for_each(head: drgn.Object) -> Iterator[drgn.Object]
Iterate over all of the nodes in a list.
Parameters
head -- struct list_head *
Returns
Iterator of struct list_head * objects.
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.
Parameters
head -- struct list_head *
Returns
Iterator of struct list_head * objects.
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.
Parameters
• type -- Entry type.
• head -- struct list_head *
• member -- Name of list node member in entry type.
Returns
Iterator of type * objects.
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.
Parameters
• type -- Entry type.
• head -- struct list_head *
• member -- Name of list node member in entry type.
Returns
Iterator of type * objects.
drgn.helpers.linux.list.validate_list(head: drgn.Object) -> None
Validate that the next and prev pointers in a list are consistent.
Parameters
head -- struct list_head *
Raises ValidationError -- if the list is invalid
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.
Parameters
head -- struct list_head *
Raises ValidationError -- if the list is invalid
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.
Parameters
• type -- Entry type.
• head -- struct list_head *
• member -- Name of list node member in entry type.
Raises ValidationError -- if the list is invalid
drgn.helpers.linux.list.hlist_empty(head: drgn.Object) -> bool
Return whether a hash list is empty.
Parameters
head -- struct hlist_head *
drgn.helpers.linux.list.hlist_for_each(head: drgn.Object) -> Iterator[drgn.Object]
Iterate over all of the nodes in a hash list.
Parameters
head -- struct hlist_head *
Returns
Iterator of struct hlist_node * objects.
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.
Parameters
• type -- Entry type.
• head -- struct hlist_head *
• member -- Name of list node member in entry type.
Returns
Iterator of type * objects.
Nulls Lists
The drgn.helpers.linux.list_nulls module provides helpers for working with the special
version of lists (struct hlist_nulls_head and struct hlist_nulls_node) in
include/linux/list_nulls.h where the end of list is not a NULL pointer, but a "nulls"
marker.
drgn.helpers.linux.list_nulls.is_a_nulls(pos: drgn.Object) -> bool
Return whether a a pointer is a nulls marker.
Parameters
pos -- struct hlist_nulls_node *
drgn.helpers.linux.list_nulls.hlist_nulls_empty(head: drgn.Object) -> bool
Return whether a nulls hash list is empty.
Parameters
head -- struct hlist_nulls_head *
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.
Parameters
• type -- Entry type.
• head -- struct hlist_nulls_head *
• member -- Name of list node member in entry type.
Returns
Iterator of type * objects.
Lockless Lists
The drgn.helpers.linux.llist module provides helpers for working with the lockless,
NULL-terminated, singly-linked list implementation in include/linux/llist.h (struct
llist_head and struct llist_node).
drgn.helpers.linux.llist.llist_empty(head: drgn.Object) -> bool
Return whether an llist is empty.
Parameters
head -- struct llist_head *
drgn.helpers.linux.llist.llist_is_singular(head: drgn.Object) -> bool
Return whether an llist has only one element.
Parameters
head -- struct llist_head *
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().
Parameters
• head -- struct llist_head *
• type -- Entry type.
• member -- Name of struct llist_node member in entry type.
Returns
type *
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().
Parameters
• head -- struct llist_head *
• type -- Entry type.
• member -- Name of struct llist_node member in entry type.
Returns
type *
drgn.helpers.linux.llist.llist_next_entry(pos: drgn.Object, member: str) -> drgn.Object
Return the next entry in an llist.
Parameters
• pos -- type*
• member -- Name of struct llist_node member in entry type.
Returns
type *
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.
Parameters
node -- struct llist_node *
Returns
Iterator of struct llist_node * objects.
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.
Parameters
• type -- Entry type.
• node -- struct llist_node *
• member -- Name of struct llist_node member in entry type.
Returns
Iterator of type * objects.
Memory Management
The drgn.helpers.linux.mm module provides helpers for working with the Linux memory
management (MM) subsystem. Only AArch64, s390x, and x86-64 are currently supported.
drgn.helpers.linux.mm.PageActive(page: drgn.Object) -> bool
Return whether the PG_active flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageChecked(page: drgn.Object) -> bool
Return whether the PG_checked flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageDirty(page: drgn.Object) -> bool
Return whether the PG_dirty flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageDoubleMap(page: drgn.Object) -> bool
Return whether the PG_double_map flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageError(page: drgn.Object) -> bool
Return whether the PG_error flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageForeign(page: drgn.Object) -> bool
Return whether the PG_foreign flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageHWPoison(page: drgn.Object) -> bool
Return whether the PG_hwpoison flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageHasHWPoisoned(page: drgn.Object) -> bool
Return whether the PG_has_hwpoisoned flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageIdle(page: drgn.Object) -> bool
Return whether the PG_idle flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageIsolated(page: drgn.Object) -> bool
Return whether the PG_isolated flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageLRU(page: drgn.Object) -> bool
Return whether the PG_lru flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageLocked(page: drgn.Object) -> bool
Return whether the PG_locked flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageMappedToDisk(page: drgn.Object) -> bool
Return whether the PG_mappedtodisk flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageMlocked(page: drgn.Object) -> bool
Return whether the PG_mlocked flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageOwnerPriv1(page: drgn.Object) -> bool
Return whether the PG_owner_priv_1 flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PagePinned(page: drgn.Object) -> bool
Return whether the PG_pinned flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PagePrivate(page: drgn.Object) -> bool
Return whether the PG_private flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PagePrivate2(page: drgn.Object) -> bool
Return whether the PG_private_2 flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageReadahead(page: drgn.Object) -> bool
Return whether the PG_readahead flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageReclaim(page: drgn.Object) -> bool
Return whether the PG_reclaim flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageReferenced(page: drgn.Object) -> bool
Return whether the PG_referenced flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageReported(page: drgn.Object) -> bool
Return whether the PG_reported flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageReserved(page: drgn.Object) -> bool
Return whether the PG_reserved flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageSavePinned(page: drgn.Object) -> bool
Return whether the PG_savepinned flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageSkipKASanPoison(page: drgn.Object) -> bool
Return whether the PG_skip_kasan_poison flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageSlab(page: drgn.Object) -> bool
Return whether the PG_slab flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageSlobFree(page: drgn.Object) -> bool
Return whether the PG_slob_free flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageSwapBacked(page: drgn.Object) -> bool
Return whether the PG_swapbacked flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageUncached(page: drgn.Object) -> bool
Return whether the PG_uncached flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageUnevictable(page: drgn.Object) -> bool
Return whether the PG_unevictable flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageUptodate(page: drgn.Object) -> bool
Return whether the PG_uptodate flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageVmemmapSelfHosted(page: drgn.Object) -> bool
Return whether the PG_vmemmap_self_hosted flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageWaiters(page: drgn.Object) -> bool
Return whether the PG_waiters flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageWorkingset(page: drgn.Object) -> bool
Return whether the PG_workingset flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageWriteback(page: drgn.Object) -> bool
Return whether the PG_writeback flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageXenRemapped(page: drgn.Object) -> bool
Return whether the PG_xen_remapped flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageYoung(page: drgn.Object) -> bool
Return whether the PG_young flag is set on a page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageCompound(page: drgn.Object) -> bool
Return whether a page is part of a compound page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageHead(page: drgn.Object) -> bool
Return whether a page is a head page in a compound page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.PageTail(page: drgn.Object) -> bool
Return whether a page is a tail page in a compound page.
Parameters
page -- struct page *
drgn.helpers.linux.mm.compound_head(page: drgn.Object) -> drgn.Object
Get the head page associated with a page.
If page is a tail page, this returns the head page of the compound page it belongs
to. Otherwise, it returns page.
Parameters
page -- struct page *
Returns
struct page *
drgn.helpers.linux.mm.compound_order(page: drgn.Object) -> drgn.Object
Return the allocation order of a potentially compound page.
Parameters
page -- struct page *
Returns
unsigned int
drgn.helpers.linux.mm.compound_nr(page: drgn.Object) -> drgn.Object
Return the number of pages in a potentially compound page.
Parameters
page -- struct page *
Returns
unsigned long
drgn.helpers.linux.mm.page_size(page: drgn.Object) -> drgn.Object
Return the number of bytes in a potentially compound page.
Parameters
page -- struct page *
Returns
unsigned long
drgn.helpers.linux.mm.decode_page_flags(page: drgn.Object) -> str
Get a human-readable representation of the flags set on a page.
>>> decode_page_flags(page)
'PG_uptodate|PG_dirty|PG_lru|PG_reclaim|PG_swapbacked|PG_readahead|PG_savepinned|PG_isolated|PG_reported'
Parameters
page -- struct page *
drgn.helpers.linux.mm.for_each_page(prog: drgn.Program) -> Iterator[drgn.Object]
Iterate over every struct page * from the minimum to the maximum page.
NOTE:
This may include offline pages which don't have a valid struct page. Wrap
accesses in a try ... except drgn.FaultError:
>>> for page in for_each_page(prog):
... try:
... if PageLRU(page):
... print(hex(page))
... except drgn.FaultError:
... continue
0xfffffb4a000c0000
0xfffffb4a000c0040
...
This may be fixed in the future.
Returns
Iterator of struct page * objects.
drgn.helpers.linux.mm.PFN_PHYS(pfn: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.PFN_PHYS(prog: drgn.Program, pfn: drgn.IntegerLike) -> drgn.Object
Get the physical address of a page frame number (PFN).
The PFN can be given as an Object or as a Program and an integer.
Parameters
pfn -- unsigned long
Returns
phys_addr_t
drgn.helpers.linux.mm.PHYS_PFN(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.PHYS_PFN(prog: drgn.Program, addr: int) -> drgn.Object
Get the page frame number (PFN) of a physical address.
The address can be given as an Object or as a Program and an integer.
Parameters
addr -- phys_addr_t
Returns
unsigned long
drgn.helpers.linux.mm.page_to_pfn(page: drgn.Object) -> drgn.Object
Get the page frame number (PFN) of a page.
Parameters
page -- struct page *
Returns
unsigned long
drgn.helpers.linux.mm.page_to_phys(page: drgn.Object) -> drgn.Object
Get the physical address of a page.
Parameters
page -- struct page *
Returns
phys_addr_t
drgn.helpers.linux.mm.page_to_virt(page: drgn.Object) -> drgn.Object
Get the directly mapped virtual address of a page.
Parameters
page -- struct page *
Returns
void *
drgn.helpers.linux.mm.pfn_to_page(pfn: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.pfn_to_page(prog: drgn.Program, pfn: drgn.IntegerLike) ->
drgn.Object
Get the page with a page frame number (PFN).
The PFN can be given as an Object or as a Program and an integer.
Parameters
pfn -- unsigned long
Returns
struct page *
drgn.helpers.linux.mm.pfn_to_virt(pfn: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.pfn_to_virt(prog: drgn.Program, pfn: drgn.IntegerLike) ->
drgn.Object
Get the directly mapped virtual address of a page frame number (PFN).
The PFN can be given as an Object or as a Program and an integer.
Parameters
pfn -- unsigned long
Returns
void *
drgn.helpers.linux.mm.phys_to_page(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.phys_to_page(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the page containing a physical address.
The address can be given as an Object or as a Program and an integer.
Parameters
addr -- phys_addr_t
Returns
struct page *
drgn.helpers.linux.mm.phys_to_virt(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.phys_to_virt(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the directly mapped virtual address of a physical address.
The address can be given as an Object or as a Program and an integer.
Parameters
addr -- phys_addr_t
Returns
void *
drgn.helpers.linux.mm.virt_to_page(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.virt_to_page(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the page containing a directly mapped virtual address.
The address can be given as an Object or as a Program and an integer.
NOTE:
This only works for virtual addresses from the "direct map". This includes
address from:
• kmalloc
• Slab allocator
• Page allocator
But not:
• vmalloc
• vmap
• ioremap
• Symbols (function pointers, global variables)
For vmalloc or vmap addresses, use vmalloc_to_page(addr). For arbitrary kernel
addresses, use follow_page(prog["init_mm"].address_of_(), addr).
Parameters
addr -- void *
Returns
struct page *
drgn.helpers.linux.mm.virt_to_pfn(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.virt_to_pfn(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the page frame number (PFN) of a directly mapped virtual address.
The address can be given as an Object or as a Program and an integer.
NOTE:
This only works for virtual addresses from the "direct map". For vmalloc or vmap
addresses, use vmalloc_to_pfn(addr). For arbitrary kernel addresses, use
follow_pfn(prog["init_mm"].address_of_(), addr).
Parameters
addr -- void *
Returns
unsigned long
drgn.helpers.linux.mm.virt_to_phys(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.virt_to_phys(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the physical address of a directly mapped virtual address.
The address can be given as an Object or as a Program and an integer.
NOTE:
This only works for virtual addresses from the "direct map". For arbitrary
kernel addresses, use follow_phys(prog["init_mm"].address_of_(), addr).
Parameters
addr -- void *
Returns
phys_addr_t
drgn.helpers.linux.mm.follow_page(mm: drgn.Object, addr: drgn.IntegerLike) -> drgn.Object
Get the page that a virtual address maps to in a virtual address space.
>>> task = find_task(prog, 113)
>>> follow_page(task.mm, 0x7fffbbb6d4d0)
*(struct page *)0xffffbe4bc0337b80 = {
...
}
Parameters
• mm -- struct mm_struct *
• addr -- void *
Returns
struct page *
drgn.helpers.linux.mm.follow_pfn(mm: drgn.Object, addr: drgn.IntegerLike) -> drgn.Object
Get the page frame number (PFN) that a virtual address maps to in a virtual address
space.
>>> task = find_task(prog, 113)
>>> follow_pfn(task.mm, 0x7fffbbb6d4d0)
(unsigned long)52718
Parameters
• mm -- struct mm_struct *
• addr -- void *
Returns
unsigned long
drgn.helpers.linux.mm.follow_phys(mm: drgn.Object, addr: drgn.IntegerLike) -> drgn.Object
Get the physical address that a virtual address maps to in a virtual address space.
>>> task = find_task(prog, 113)
>>> follow_phys(task.mm, 0x7fffbbb6d4d0)
(phys_addr_t)215934160
Parameters
• mm -- struct mm_struct *
• addr -- void *
Returns
phys_addr_t
drgn.helpers.linux.mm.vmalloc_to_page(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.vmalloc_to_page(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the page containing a vmalloc or vmap address.
The address can be given as an Object or as a Program and an integer.
>>> task = find_task(prog, 113)
>>> vmalloc_to_page(task.stack)
*(struct page *)0xffffbe4bc00a2200 = {
...
}
Parameters
addr -- void *
Returns
struct page *
drgn.helpers.linux.mm.vmalloc_to_pfn(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.mm.vmalloc_to_pfn(prog: drgn.Program, addr: drgn.IntegerLike) ->
drgn.Object
Get the page frame number (PFN) containing a vmalloc or vmap address.
The address can be given as an Object or as a Program and an integer.
>>> task = find_task(prog, 113)
>>> vmalloc_to_pfn(task.stack)
(unsigned long)10376
Parameters
addr -- void *
Returns
unsigned long
drgn.helpers.linux.mm.access_process_vm(task: drgn.Object, address: drgn.IntegerLike,
size: drgn.IntegerLike) -> bytes
Read memory from a task's virtual address space.
>>> task = find_task(prog, 1490152)
>>> access_process_vm(task, 0x7f8a62b56da0, 12)
b'hello, world'
Parameters
• task -- struct task_struct *
• address -- Starting address.
• size -- Number of bytes to read.
drgn.helpers.linux.mm.access_remote_vm(mm: drgn.Object, address: drgn.IntegerLike, size:
drgn.IntegerLike) -> bytes
Read memory from a virtual address space. This is similar to access_process_vm(),
but it takes a struct mm_struct * instead of a struct task_struct *.
>>> task = find_task(prog, 1490152)
>>> access_remote_vm(task.mm, 0x7f8a62b56da0, 12)
b'hello, world'
Parameters
• mm -- struct mm_struct *
• address -- Starting address.
• size -- Number of bytes to read.
drgn.helpers.linux.mm.cmdline(task: drgn.Object) -> List[bytes]
Get the list of command line arguments of a task.
>>> cmdline(find_task(prog, 1495216))
[b'vim', b'drgn/helpers/linux/mm.py']
$ tr '\0' ' ' < /proc/1495216/cmdline
vim drgn/helpers/linux/mm.py
Parameters
task -- struct task_struct *
drgn.helpers.linux.mm.environ(task: drgn.Object) -> List[bytes]
Get the list of environment variables of a task.
>>> environ(find_task(prog, 1497797))
[b'HOME=/root', b'PATH=/usr/local/sbin:/usr/local/bin:/usr/bin', b'LOGNAME=root']
$ tr '\0' '\n' < /proc/1497797/environ
HOME=/root
PATH=/usr/local/sbin:/usr/local/bin:/usr/bin
LOGNAME=root
Parameters
task -- struct task_struct *
drgn.helpers.linux.mm.totalram_pages(prog: drgn.Program) -> int
Return the total number of RAM memory pages.
Networking
The drgn.helpers.linux.net module provides helpers for working with the Linux kernel
networking subsystem.
drgn.helpers.linux.net.SOCKET_I(inode: drgn.Object) -> drgn.Object
Get a socket from an inode referring to the socket.
Parameters
inode -- struct inode *
Returns
struct socket *
Raises ValueError -- If inode does not refer to a socket
drgn.helpers.linux.net.SOCK_INODE(sock: drgn.Object) -> drgn.Object
Get the inode of a socket.
Parameters
sock -- struct socket *
Returns
struct inode *
drgn.helpers.linux.net.for_each_net(prog: drgn.Program) -> Iterator[drgn.Object]
Iterate over all network namespaces in the system.
Returns
Iterator of struct net * objects.
drgn.helpers.linux.net.get_net_ns_by_inode(inode: drgn.Object) -> drgn.Object
Get a network namespace from a network namespace NSFS inode, e.g.
/proc/$PID/ns/net or /var/run/netns/$NAME.
Parameters
inode -- struct inode *
Returns
struct net *
Raises ValueError -- if inode is not a network namespace inode
drgn.helpers.linux.net.get_net_ns_by_fd(task: drgn.Object, fd: drgn.IntegerLike) ->
drgn.Object
Get a network namespace from a task and a file descriptor referring to a network
namespace NSFS inode, e.g. /proc/$PID/ns/net or /var/run/netns/$NAME.
Parameters
• task -- struct task_struct *
• fd -- File descriptor.
Returns
struct net *
Raises ValueError -- If fd does not refer to a network namespace inode
drgn.helpers.linux.net.netdev_for_each_tx_queue(dev: drgn.Object) -> Iterator[drgn.Object]
Iterate over all TX queues for a network device.
Parameters
dev -- struct net_device *
Returns
Iterator of struct netdev_queue * objects.
drgn.helpers.linux.net.netdev_get_by_index(prog_or_net: Union[drgn.Program, drgn.Object],
ifindex: drgn.IntegerLike) -> drgn.Object
Get the network device with the given interface index number.
Parameters
• prog_or_net -- struct net * containing the device, or Program to use the
initial network namespace.
• ifindex -- Network interface index number.
Returns
struct net_device * (NULL if not found)
drgn.helpers.linux.net.netdev_get_by_name(prog_or_net: Union[drgn.Program, drgn.Object],
name: Union[str, bytes]) -> drgn.Object
Get the network device with the given interface name.
Parameters
• prog_or_net -- struct net * containing the device, or Program to use the
initial network namespace.
• name -- Network interface name.
Returns
struct net_device * (NULL if not found)
drgn.helpers.linux.net.sk_fullsock(sk: drgn.Object) -> bool
Check whether a socket is a full socket, i.e., not a time-wait or request socket.
Parameters
sk -- struct sock *
drgn.helpers.linux.net.sk_nulls_for_each(head: drgn.Object) -> Iterator[drgn.Object]
Iterate over all the entries in a nulls hash list of sockets specified by struct
hlist_nulls_head head.
Parameters
head -- struct hlist_nulls_head *
Returns
Iterator of struct sock * objects.
NUMA Node Masks
The drgn.helpers.linux.nodemask module provides helpers for working with NUMA node masks
from include/linux/nodemask.h.
drgn.helpers.linux.nodemask.for_each_node_mask(mask: drgn.Object) -> Iterator[int]
Iterate over all of the NUMA nodes in the given mask.
Parameters
mask -- nodemask_t
drgn.helpers.linux.nodemask.for_each_node_state(prog: drgn.Program, state:
drgn.IntegerLike) -> Iterator[int]
Iterate over all NUMA nodes in the given state.
Parameters
state -- enum node_states (e.g., N_NORMAL_MEMORY)
drgn.helpers.linux.nodemask.for_each_node(prog: drgn.Program) -> Iterator[int]
Iterate over all possible NUMA nodes.
drgn.helpers.linux.nodemask.for_each_online_node(prog: drgn.Program) -> Iterator[int]
Iterate over all online NUMA nodes.
drgn.helpers.linux.nodemask.node_state(node: drgn.IntegerLike, state: drgn.Object) -> bool
Return whether the given NUMA node has the given state.
Parameters
• node -- NUMA node number.
• state -- enum node_states (e.g., N_NORMAL_MEMORY)
Per-CPU
The drgn.helpers.linux.percpu module provides helpers for working with per-CPU allocations
from include/linux/percpu.h and per-CPU counters from include/linux/percpu_counter.h.
drgn.helpers.linux.percpu.per_cpu_ptr(ptr: drgn.Object, cpu: drgn.IntegerLike) ->
drgn.Object
Return the per-CPU pointer for a given CPU.
>>> prog["init_net"].loopback_dev.pcpu_refcnt
(int *)0x2c980
>>> per_cpu_ptr(prog["init_net"].loopback_dev.pcpu_refcnt, 7)
*(int *)0xffff925e3ddec980 = 4
Parameters
• ptr -- Per-CPU pointer, i.e., type __percpu *. For global variables, it's
usually easier to use per_cpu().
• cpu -- CPU number.
Returns
type * object.
drgn.helpers.linux.percpu.per_cpu(var: drgn.Object, cpu: drgn.IntegerLike) -> drgn.Object
Return the per-CPU variable for a given CPU.
>>> print(repr(prog["runqueues"]))
Object(prog, 'struct rq', address=0x278c0)
>>> per_cpu(prog["runqueues"], 6).curr.comm
(char [16])"python3"
Parameters
• var -- Per-CPU variable, i.e., type __percpu (not a pointer; use
per_cpu_ptr() for that).
• cpu -- CPU number.
Returns
type object.
drgn.helpers.linux.percpu.percpu_counter_sum(fbc: drgn.Object) -> int
Return the sum of a per-CPU counter.
Parameters
fbc -- struct percpu_counter *
Process IDS
The drgn.helpers.linux.pid module provides helpers for looking up process IDs and
processes.
drgn.helpers.linux.pid.find_pid(prog_or_ns: Union[drgn.Program, drgn.Object], pid:
drgn.IntegerLike) -> drgn.Object
Return the struct pid * for the given PID number.
Parameters
prog_or_ns -- struct pid_namespace * object, or Program to use initial PID
namespace.
Returns
struct pid *
drgn.helpers.linux.pid.find_task(prog_or_ns: Union[drgn.Program, drgn.Object], pid:
drgn.IntegerLike) -> drgn.Object
Return the task with the given PID.
Parameters
prog_or_ns -- struct pid_namespace * object, or Program to use initial PID
namespace.
Returns
struct task_struct *
drgn.helpers.linux.pid.pid_task(pid: drgn.Object, pid_type: drgn.IntegerLike) ->
drgn.Object
Return the struct task_struct * containing the given struct pid * of the given
type.
Parameters
• pid -- struct pid *
• pid_type -- enum pid_type
Returns
struct task_struct *
drgn.helpers.linux.pid.for_each_pid(prog_or_ns: Union[drgn.Program, drgn.Object]) ->
Iterator[drgn.Object]
Iterate over all PIDs in a namespace.
Parameters
prog_or_ns -- struct pid_namespace * to iterate over, or Program to iterate
over initial PID namespace.
Returns
Iterator of struct pid * objects.
drgn.helpers.linux.pid.for_each_task(prog_or_ns: Union[drgn.Program, drgn.Object]) ->
Iterator[drgn.Object]
Iterate over all of the tasks visible in a namespace.
Parameters
prog_or_ns -- struct pid_namespace * to iterate over, or Program to iterate
over initial PID namespace.
Returns
Iterator of struct task_struct * objects.
Log Buffer
The drgn.helpers.linux.printk module provides helpers for reading the Linux kernel log
buffer.
class drgn.helpers.linux.printk.PrintkRecord
Bases: NamedTuple
Kernel log record.
text: bytes
Message text.
facility: int
syslog(3) facility.
level: int
Log level.
seq: int
Sequence number.
timestamp: int
Timestamp in nanoseconds.
caller_tid: Optional[int]
Thread ID of thread that logged this record, if available.
This is available if the message was logged from task context and if the
kernel saves the printk() caller ID.
As of Linux 5.10, the kernel always saves the caller ID. From Linux 5.1
through 5.9, it is saved only if the kernel was compiled with
CONFIG_PRINTK_CALLER. Before that, it is never saved.
caller_cpu: Optional[int]
Processor ID of CPU that logged this record, if available.
This is available only if the message was logged when not in task context
(e.g., in an interrupt handler) and if the kernel saves the printk() caller
ID.
See caller_tid for when the kernel saves the caller ID.
continuation: bool
Whether this record is a continuation of a previous record.
context: Dict[bytes, bytes]
Additional metadata for the message.
See the /dev/kmsg documentation for an explanation of the keys and values.
drgn.helpers.linux.printk.get_printk_records(prog: drgn.Program) -> List[PrintkRecord]
Get a list of records in the kernel log buffer.
drgn.helpers.linux.printk.get_dmesg(prog: drgn.Program) -> bytes
Get the contents of the kernel log buffer formatted like dmesg(1).
The format of each line is:
[ timestamp] message
If you need to format the log buffer differently, use get_printk_records() and
format it yourself.
Radix Trees
The drgn.helpers.linux.radixtree module provides helpers for working with radix trees from
include/linux/radix-tree.h.
SEE ALSO:
XArrays, which were introduced in Linux 4.20 as a replacement for radix trees.
drgn.helpers.linux.radixtree.radix_tree_lookup(root: drgn.Object, index: drgn.IntegerLike)
-> drgn.Object
Look up the entry at a given index in a radix tree.
Parameters
• root -- struct radix_tree_root *
• index -- Entry index.
Returns
void * found entry, or NULL if not found.
drgn.helpers.linux.radixtree.radix_tree_for_each(root: drgn.Object) -> Iterator[Tuple[int,
drgn.Object]]
Iterate over all of the entries in a radix tree.
Parameters
root -- struct radix_tree_root *
Returns
Iterator of (index, void *) tuples.
Red-Black Trees
The drgn.helpers.linux.rbtree module provides helpers for working with red-black trees
from include/linux/rbtree.h.
drgn.helpers.linux.rbtree.RB_EMPTY_ROOT(root: drgn.Object) -> bool
Return whether a red-black tree is empty.
Parameters
node -- struct rb_root *
drgn.helpers.linux.rbtree.RB_EMPTY_NODE(node: drgn.Object) -> bool
Return whether a red-black tree node is empty, i.e., not inserted in a tree.
Parameters
node -- struct rb_node *
drgn.helpers.linux.rbtree.rb_parent(node: drgn.Object) -> drgn.Object
Return the parent node of a red-black tree node.
Parameters
node -- struct rb_node *
Returns
struct rb_node *
drgn.helpers.linux.rbtree.rb_first(root: drgn.Object) -> drgn.Object
Return the first node (in sort order) in a red-black tree, or NULL if the tree is
empty.
Parameters
root -- struct rb_root *
Returns
struct rb_node *
drgn.helpers.linux.rbtree.rb_last(root: drgn.Object) -> drgn.Object
Return the last node (in sort order) in a red-black tree, or NULL if the tree is
empty.
Parameters
root -- struct rb_root *
Returns
struct rb_node *
drgn.helpers.linux.rbtree.rb_next(node: drgn.Object) -> drgn.Object
Return the next node (in sort order) after a red-black node, or NULL if the node is
the last node in the tree or is empty.
Parameters
node -- struct rb_node *
Returns
struct rb_node *
drgn.helpers.linux.rbtree.rb_prev(node: drgn.Object) -> drgn.Object
Return the previous node (in sort order) before a red-black node, or NULL if the
node is the first node in the tree or is empty.
Parameters
node -- struct rb_node *
Returns
struct rb_node *
drgn.helpers.linux.rbtree.rbtree_inorder_for_each(root: drgn.Object) -> Iterator[‐
drgn.Object]
Iterate over all of the nodes in a red-black tree, in sort order.
Parameters
root -- struct rb_root *
Returns
Iterator of struct rb_node * objects.
drgn.helpers.linux.rbtree.rbtree_inorder_for_each_entry(type: Union[str, drgn.Type], root:
drgn.Object, member: str) -> Iterator[drgn.Object]
Iterate over all of the entries in a red-black tree in sorted order.
Parameters
• type -- Entry type.
• root -- struct rb_root *
• member -- Name of struct rb_node member in entry type.
Returns
Iterator of type * objects.
drgn.helpers.linux.rbtree.rb_find(type: Union[str, drgn.Type], root: drgn.Object, member:
str, key: KeyType, cmp: Callable[[KeyType, drgn.Object], int]) -> drgn.Object
Find an entry in a red-black tree given a key and a comparator function.
Note that this function does not have an analogue in the Linux kernel source code,
as tree searches are all open-coded.
Parameters
• type -- Entry type.
• root -- struct rb_root *
• member -- Name of struct rb_node member in entry type.
• key -- Key to find.
• cmp -- Callback taking key and entry that returns < 0 if the key is less
than the entry, > 0 if the key is greater than the entry, and 0 if the key
matches the entry.
Returns
type * found entry, or NULL if not found.
drgn.helpers.linux.rbtree.validate_rbtree(type: Union[str, drgn.Type], root: drgn.Object,
member: str, cmp: Callable[[drgn.Object, drgn.Object], int], allow_equal: bool) -> None
Validate a red-black tree.
This checks that:
1. The tree is a valid binary search tree ordered according to cmp.
2. If allow_equal is False, there are no nodes that compare equal according to cmp.
3. The rb_parent pointers are consistent.
4. The red-black tree requirements are satisfied: the root node is black, no red
node has a red child, and every path from any node to any of its descendant leaf
nodes goes through the same number of black nodes.
Parameters
• type -- Entry type.
• root -- struct rb_root *
• member -- Name of struct rb_node member in entry type.
• cmp -- Callback taking two type * entry objects that returns < 0 if the
first entry is less than the second entry, > 0 if the first entry is
greater than the second entry, and 0 if they are equal.
• allow_equal -- Whether the tree may contain entries that compare equal to
each other.
Raises ValidationError -- if the tree is invalid
drgn.helpers.linux.rbtree.validate_rbtree_inorder_for_each_entry(type: Union[str,
drgn.Type], root: drgn.Object, member: str, cmp: Callable[[drgn.Object, drgn.Object],
int], allow_equal: bool) -> Iterator[drgn.Object]
Like rbtree_inorder_for_each_entry(), but validates the red-black tree like
validate_rbtree() while iterating.
Parameters
• type -- Entry type.
• root -- struct rb_root *
• member -- Name of struct rb_node member in entry type.
• cmp -- Callback taking two type * entry objects that returns < 0 if the
first entry is less than the second entry, > 0 if the first entry is
greater than the second entry, and 0 if they are equal.
• allow_equal -- Whether the tree may contain entries that compare equal to
each other.
Raises ValidationError -- if the tree is invalid
CPU Scheduler
The drgn.helpers.linux.sched module provides helpers for working with the Linux CPU
scheduler.
drgn.helpers.linux.sched.idle_task(prog: drgn.Program, cpu: drgn.IntegerLike) ->
drgn.Object
Return the idle thread (PID 0, a.k.a swapper) for the given CPU.
>>> idle_task(prog, 1).comm
(char [16])"swapper/1"
Parameters
cpu -- CPU number.
Returns
struct task_struct *
drgn.helpers.linux.sched.task_cpu(task: drgn.Object) -> int
Return the CPU number that the given task last ran on.
Parameters
task -- struct task_struct *
drgn.helpers.linux.sched.task_state_to_char(task: drgn.Object) -> str
Get the state of the task as a character (e.g., 'R' for running). See ps(1) for a
description of the process state codes.
Parameters
task -- struct task_struct *
drgn.helpers.linux.sched.loadavg(prog: drgn.Program) -> Tuple[float, float, float]
Return system load averaged over 1, 5 and 15 minutes as tuple of three float
values.
>>> loadavg(prog)
(2.34, 0.442, 1.33)
Slab Allocator
The drgn.helpers.linux.slab module provides helpers for working with the Linux slab
allocator.
WARNING:
Beware of slab merging when using these helpers. See slab_cache_is_merged().
drgn.helpers.linux.slab.slab_cache_is_merged(slab_cache: drgn.Object) -> bool
Return whether a slab cache has been merged with any other slab caches.
Unless configured otherwise, the kernel may merge slab caches of similar sizes
together. See the SLUB users guide and slab_merge/slab_nomerge in the kernel
parameters documentation.
This can cause confusion, as only the name of the first cache will be found, and
objects of different types will be mixed in the same slab cache.
For example, suppose that we have two types, struct foo and struct bar, which have
the same size but are otherwise unrelated. If the kernel creates a slab cache named
foo for struct foo, then another slab cache named bar for struct bar, then slab
cache foo will be reused instead of creating another cache for bar. So the
following will fail:
find_slab_cache(prog, "bar")
And the following will also return struct bar * objects errantly casted to struct
foo *:
slab_cache_for_each_allocated_object(
find_slab_cache(prog, "foo"), "struct foo"
)
Unfortunately, these issues are difficult to work around generally, so one must be
prepared to handle them on a case-by-case basis (e.g., by looking up the slab cache
by its variable name and by checking that members of the structure make sense for
the expected type).
Parameters
slab_cache -- struct kmem_cache *
drgn.helpers.linux.slab.get_slab_cache_aliases(prog: drgn.Program) -> Dict[str, str]
Return a dict mapping slab cache name to the cache it was merged with.
The SLAB and SLUB subsystems can merge caches with similar settings and object
sizes, as described in the documentation of slab_cache_is_merged(). In some cases,
the information about which caches were merged is lost, but in other cases, we can
reconstruct the info. This function reconstructs the mapping, but requires that
the kernel is configured with CONFIG_SLUB and CONFIG_SYSFS.
The returned dict maps from original cache name, to merged cache name. You can use
this mapping to discover the correct cache to lookup via find_slab_cache(). The
dict contains an entry only for caches which were merged into a cache of a
different name.
>>> cache_to_merged = get_slab_cache_aliases(prog)
>>> cache_to_merged["dnotify_struct"]
'avc_xperms_data'
>>> "avc_xperms_data" in cache_to_merged
False
>>> find_slab_cache(prog, "dnotify_struct") is None
True
>>> find_slab_cache(prog, "avc_xperms_data") is None
False
Warning
This function will only work on kernels which are built with CONFIG_SLUB and
CONFIG_SYSFS enabled.
Parameters
prog -- Program to search
Returns
Mapping of slab cache name to final merged name
Raises LookupError -- If the helper fails because the debugged kernel doesn't have
the required configuration
drgn.helpers.linux.slab.for_each_slab_cache(prog: drgn.Program) -> Iterator[drgn.Object]
Iterate over all slab caches.
Returns
Iterator of struct kmem_cache * objects.
drgn.helpers.linux.slab.find_slab_cache(prog: drgn.Program, name: Union[str, bytes]) ->
Optional[drgn.Object]
Return the slab cache with the given name.
Parameters
name -- Slab cache name.
Returns
struct kmem_cache *
drgn.helpers.linux.slab.print_slab_caches(prog: drgn.Program) -> None
Print the name and struct kmem_cache * value of all slab caches.
drgn.helpers.linux.slab.slab_cache_for_each_allocated_object(slab_cache: drgn.Object,
type: Union[str, drgn.Type]) -> Iterator[drgn.Object]
Iterate over all allocated objects in a given slab cache.
Only the SLUB and SLAB allocators are supported; SLOB does not store enough
information to identify objects in a slab cache.
>>> dentry_cache = find_slab_cache(prog, "dentry")
>>> next(slab_cache_for_each_allocated_object(dentry_cache, "struct dentry"))
*(struct dentry *)0xffff905e41404000 = {
...
}
Parameters
• slab_cache -- struct kmem_cache *
• type -- Type of object in the slab cache.
Returns
Iterator of type * objects.
drgn.helpers.linux.slab.slab_object_info(addr: drgn.Object) -> Optional['SlabObjectInfo']
drgn.helpers.linux.slab.slab_object_info(prog: drgn.Program, addr: drgn.IntegerLike) ->
Optional[SlabObjectInfo]
Get information about an address if it is in a slab object.
>>> ptr = find_task(prog, 1).comm.address_of_()
>>> info = slab_object_info(ptr)
>>> info
SlabObjectInfo(slab_cache=Object(prog, 'struct kmem_cache *', address=0xffffdb93c0045e18), slab=Object(prog, 'struct slab *', value=0xffffdb93c0045e00), address=0xffffa2bf81178000, allocated=True)
Note that SlabObjectInfo.address is the start address of the object, which may be
less than addr if addr points to a member inside of the object:
>>> ptr.value_() - info.address
1496
>>> offsetof(prog.type("struct task_struct"), "comm")
1496
The address can be given as an Object or as a Program and an integer.
Note that SLOB does not store enough information to identify slab objects, so if
the kernel is configured to use SLOB, this will always return None.
Parameters
addr -- void *
Returns
SlabObjectInfo if addr is in a slab object, or None if not.
class drgn.helpers.linux.slab.SlabObjectInfo
Information about an object in the slab allocator.
slab_cache: drgn.Object
struct kmem_cache * that the slab object is from.
slab: drgn.Object
Slab containing the slab object.
Since Linux v5.17, this is a struct slab *. Before that, it is a struct page
*.
address: int
Address of the slab object.
allocated: bool
True if the object is allocated, False if it is free.
drgn.helpers.linux.slab.find_containing_slab_cache(addr: drgn.Object) -> drgn.Object
drgn.helpers.linux.slab.find_containing_slab_cache(prog: drgn.Program, addr:
drgn.IntegerLike) -> drgn.Object
Get the slab cache that an address was allocated from, if any.
The address can be given as an Object or as a Program and an integer.
Note that SLOB does not store enough information to identify objects in a slab
cache, so if the kernel is configured to use SLOB, this will always return NULL.
Parameters
addr -- void *
Returns
struct kmem_cache * containing addr, or NULL if addr is not from a slab
cache.
Traffic Control (TC)
The drgn.helpers.linux.tc module provides helpers for working with the Linux kernel
Traffic Control (TC) subsystem.
drgn.helpers.linux.tc.qdisc_lookup(dev: drgn.Object, major: drgn.IntegerLike) ->
drgn.Object
Get a Qdisc from a device and a major handle number. It is worth noting that
conventionally handles are hexadecimal, e.g. 10: in a tc command means major handle
0x10.
Parameters
• dev -- struct net_device *
• major -- Qdisc major handle number.
Returns
struct Qdisc * (NULL if not found)
TCP
The drgn.helpers.linux.tcp module provides helpers for working with the TCP protocol in
the Linux kernel.
drgn.helpers.linux.tcp.sk_tcpstate(sk: drgn.Object) -> drgn.Object
Return the TCP protocol state of a socket.
Parameters
sk -- struct sock *
Returns
TCP state enum value.
Users
The drgn.helpers.linux.user module provides helpers for working with users in the Linux
kernel.
drgn.helpers.linux.user.find_user(prog: drgn.Program, uid: Union[drgn.Object,
drgn.IntegerLike]) -> drgn.Object
Return the user structure with the given UID.
Parameters
uid -- kuid_t object or integer.
Returns
struct user_struct * (NULL if not found)
drgn.helpers.linux.user.for_each_user(prog: drgn.Program) -> Iterator[drgn.Object]
Iterate over all users in the system.
Returns
Iterator of struct user_struct * objects.
XArrays
The drgn.helpers.linux.xarray module provides helpers for working with the XArray data
structure from include/linux/xarray.h.
NOTE:
XArrays were introduced in Linux 4.20 as a replacement for radix trees. To make it
easier to work with data structures that were changed from a radix tree to an XArray
(like struct address_space::i_pages), drgn treats XArrays and radix trees
interchangeably in some cases.
Specifically, xa_load() is equivalent to radix_tree_lookup(), and xa_for_each() is
equivalent to radix_tree_for_each(), except that the radix tree helpers assume
advanced=False. (Therefore, xa_load() and xa_for_each() also accept a struct
radix_tree_root *, and radix_tree_lookup() and radix_tree_for_each() also accept a
struct xarray *.)
drgn.helpers.linux.xarray.xa_load(xa: drgn.Object, index: drgn.IntegerLike, *, advanced:
bool = False) -> drgn.Object
Look up the entry at a given index in an XArray.
>>> entry = xa_load(inode.i_mapping.i_pages.address_of_(), 2)
>>> cast("struct page *", entry)
*(struct page *)0xffffed6980306f40 = {
...
}
Parameters
• xa -- struct xarray *
• index -- Entry index.
• advanced -- Whether to return nodes only visible to the XArray advanced
API. If False, zero entries (see xa_is_zero()) will be returned as NULL.
Returns
void * found entry, or NULL if not found.
drgn.helpers.linux.xarray.xa_for_each(xa: drgn.Object, *, advanced: bool = False) ->
Iterator[Tuple[int, drgn.Object]]
Iterate over all of the entries in an XArray.
>>> for index, entry in xa_for_each(inode.i_mapping.i_pages.address_of_()):
... print(index, entry)
...
0 (void *)0xffffed6980356140
1 (void *)0xffffed6980306f80
2 (void *)0xffffed6980306f40
3 (void *)0xffffed6980355b40
Parameters
• xa -- struct xarray *
• advanced -- Whether to return nodes only visible to the XArray advanced
API. If False, zero entries (see xa_is_zero()) will be skipped.
Returns
Iterator of (index, void *) tuples.
drgn.helpers.linux.xarray.xa_is_value(entry: drgn.Object) -> bool
Return whether an XArray entry is a value.
See xa_to_value().
Parameters
entry -- void *
drgn.helpers.linux.xarray.xa_to_value(entry: drgn.Object) -> drgn.Object
Return the value in an XArray entry.
In addition to pointers, XArrays can store integers between 0 and LONG_MAX. If
xa_is_value() returns True, use this to get the stored integer.
>>> entry = xa_load(xa, 9)
>>> entry
(void *)0xc9
>>> xa_is_value(entry)
True
>>> xa_to_value(entry)
(unsigned long)100
Parameters
entry -- void *
Returns
unsigned long
drgn.helpers.linux.xarray.xa_is_zero(entry: drgn.Object) -> bool
Return whether an XArray entry is a "zero" entry.
A zero entry is an entry that was reserved but is not present. These are only
visible to the XArray advanced API, so they are only returned by xa_load() and
xa_for_each() when advanced = True.
>>> entry = xa_load(xa, 10, advanced=True)
>>> entry
(void *)0x406
>>> xa_is_zero(entry)
True
>>> xa_load(xa, 10)
(void *)0
Parameters
entry -- void *
Case Studies
These are writeups of real-world problems solved with drgn.
Using Stack Trace Variables to Find a Kyber Bug
Author: Omar Sandoval
Date: June 9th, 2021
Jakub Kicinski reported a crash in the Kyber I/O scheduler when he was testing Linux 5.12.
He captured a core dump and asked me to debug it. This is a quick writeup of that
investigation.
First, we can get the task that crashed:
>>> task = per_cpu(prog["runqueues"], prog["crashing_cpu"]).curr
Then, we can get its stack trace:
>>> trace = prog.stack_trace(task)
>>> trace
#0 queued_spin_lock_slowpath (../kernel/locking/qspinlock.c:471:3)
#1 queued_spin_lock (../include/asm-generic/qspinlock.h:85:2)
#2 do_raw_spin_lock (../kernel/locking/spinlock_debug.c:113:2)
#3 spin_lock (../include/linux/spinlock.h:354:2)
#4 kyber_bio_merge (../block/kyber-iosched.c:573:2)
#5 blk_mq_sched_bio_merge (../block/blk-mq-sched.h:37:9)
#6 blk_mq_submit_bio (../block/blk-mq.c:2182:6)
#7 __submit_bio_noacct_mq (../block/blk-core.c:1015:9)
#8 submit_bio_noacct (../block/blk-core.c:1048:10)
#9 submit_bio (../block/blk-core.c:1125:9)
#10 submit_stripe_bio (../fs/btrfs/volumes.c:6553:2)
#11 btrfs_map_bio (../fs/btrfs/volumes.c:6642:3)
#12 btrfs_submit_data_bio (../fs/btrfs/inode.c:2440:8)
#13 submit_one_bio (../fs/btrfs/extent_io.c:175:9)
#14 submit_extent_page (../fs/btrfs/extent_io.c:3229:10)
#15 __extent_writepage_io (../fs/btrfs/extent_io.c:3793:9)
#16 __extent_writepage (../fs/btrfs/extent_io.c:3872:8)
#17 extent_write_cache_pages (../fs/btrfs/extent_io.c:4514:10)
#18 extent_writepages (../fs/btrfs/extent_io.c:4635:8)
#19 do_writepages (../mm/page-writeback.c:2352:10)
#20 __writeback_single_inode (../fs/fs-writeback.c:1467:8)
#21 writeback_sb_inodes (../fs/fs-writeback.c:1732:3)
#22 __writeback_inodes_wb (../fs/fs-writeback.c:1801:12)
#23 wb_writeback (../fs/fs-writeback.c:1907:15)
#24 wb_check_background_flush (../fs/fs-writeback.c:1975:10)
#25 wb_do_writeback (../fs/fs-writeback.c:2063:11)
#26 wb_workfn (../fs/fs-writeback.c:2091:20)
#27 process_one_work (../kernel/workqueue.c:2275:2)
#28 worker_thread (../kernel/workqueue.c:2421:4)
#29 kthread (../kernel/kthread.c:292:9)
#30 ret_from_fork+0x1f/0x2a (../arch/x86/entry/entry_64.S:294)
It looks like kyber_bio_merge() tried to lock an invalid spinlock. For reference, this is
the source code of kyber_bio_merge():
static bool kyber_bio_merge(struct blk_mq_hw_ctx *hctx, struct bio *bio,
unsigned int nr_segs)
{
struct kyber_hctx_data *khd = hctx->sched_data;
struct blk_mq_ctx *ctx = blk_mq_get_ctx(hctx->queue);
struct kyber_ctx_queue *kcq = &khd->kcqs[ctx->index_hw[hctx->type]];
unsigned int sched_domain = kyber_sched_domain(bio->bi_opf);
struct list_head *rq_list = &kcq->rq_list[sched_domain];
bool merged;
spin_lock(&kcq->lock);
merged = blk_bio_list_merge(hctx->queue, rq_list, bio, nr_segs);
spin_unlock(&kcq->lock);
return merged;
}
When printed, the kcq structure containing the spinlock indeed looks like garbage (omitted
for brevity).
A crash course on the Linux kernel block layer: for each block device, there is a
"software queue" (struct blk_mq_ctx *ctx) for each CPU and a "hardware queue" (struct
blk_mq_hw_ctx *hctx) for each I/O queue provided by the device. Each hardware queue has
one or more software queues assigned to it. Kyber keeps additional data per hardware
queue (struct kyber_hctx_data *khd) and per software queue (struct kyber_ctx_queue *kcq).
Let's try to figure out where the bad kcq came from. It should be an element of the
khd->kcqs array (khd is optimized out, but we can recover it from hctx->sched_data):
>>> trace[4]["khd"]
(struct kyber_hctx_data *)<absent>
>>> hctx = trace[4]["hctx"]
>>> khd = cast("struct kyber_hctx_data *", hctx.sched_data)
>>> trace[4]["kcq"] - khd.kcqs
(ptrdiff_t)1
>>> hctx.nr_ctx
(unsigned short)1
So the kcq is for the second software queue, but the hardware queue is only supposed to
have one software queue. Let's see which CPU was assigned to the hardware queue:
>>> hctx.ctxs[0].cpu
(unsigned int)6
Here's the problem: we're not running on CPU 6, we're running on CPU 19:
>>> prog["crashing_cpu"]
(int)19
And CPU 19 is assigned to a different hardware queue that actually does have two software
queues:
>>> ctx = per_cpu_ptr(hctx.queue.queue_ctx, 19)
>>> other_hctx = ctx.hctxs[hctx.type]
>>> other_hctx == hctx
False
>>> other_hctx.nr_ctx
(unsigned short)2
The bug is that the caller gets the hctx for the current CPU, then kyber_bio_merge() gets
the ctx for the current CPU, and if the thread is migrated to another CPU in between, they
won't match. The fix is to get a consistent view of the hctx and ctx. The commit that
fixes this is here.
Getting Debugging Symbols
Most Linux distributions don't install debugging symbols for installed packages by
default. This page documents how to install debugging symbols on common distributions. If
drgn prints an error like:
$ sudo drgn
could not get debugging information for:
kernel (could not find vmlinux for 5.14.14-200.fc34.x86_64)
...
Then you need to install debugging symbols.
Fedora
Fedora makes it very easy to install debugging symbols with the DNF debuginfo-install
plugin, which is installed by default. Simply run sudo dnf debuginfo-install $package:
$ sudo dnf debuginfo-install python3
To find out what package owns a binary, use rpm -qf:
$ rpm -qf $(which python3)
python3-3.9.7-1.fc34.x86_64
To install symbols for the running kernel:
$ sudo dnf debuginfo-install kernel-$(uname -r)
Also see the Fedora documentation.
Debian
Debian requires you to manually add the debugging symbol repositories:
$ sudo tee /etc/apt/sources.list.d/debug.list << EOF
deb http://deb.debian.org/debian-debug/ $(lsb_release -cs)-debug main
deb http://deb.debian.org/debian-debug/ $(lsb_release -cs)-proposed-updates-debug main
EOF
$ sudo apt update
Then, debugging symbol packages can be installed with sudo apt install. Some debugging
symbol packages are named with a -dbg suffix:
$ sudo apt install python3-dbg
And some are named with a -dbgsym suffix:
$ sudo apt install coreutils-dbgsym
You can use the find-dbgsym-packages command from the debian-goodies package to find the
correct name:
$ sudo apt install debian-goodies
$ find-dbgsym-packages $(which python3)
libc6-dbg libexpat1-dbgsym python3.9-dbg zlib1g-dbgsym
$ find-dbgsym-packages $(which cat)
coreutils-dbgsym libc6-dbg
To install symbols for the running kernel:
$ sudo apt install linux-image-$(uname -r)-dbg
Also see the Debian documentation.
Ubuntu
On Ubuntu, you must install the debugging symbol archive signing key and manually add the
debugging symbol repositories:
$ sudo apt update
$ sudo apt install ubuntu-dbgsym-keyring
$ sudo tee /etc/apt/sources.list.d/debug.list << EOF
deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse
deb http://ddebs.ubuntu.com $(lsb_release -cs)-updates main restricted universe multiverse
deb http://ddebs.ubuntu.com $(lsb_release -cs)-proposed main restricted universe multiverse
EOF
$ sudo apt update
Like Debian, some debugging symbol packages are named with a -dbg suffix and some are
named with a -dbgsym suffix:
$ sudo apt install python3-dbg
$ sudo apt install coreutils-dbgsym
You can use the find-dbgsym-packages command from the debian-goodies package to find the
correct name:
$ sudo apt install debian-goodies
$ find-dbgsym-packages $(which python3)
libc6-dbg libexpat1-dbgsym python3.9-dbg zlib1g-dbgsym
$ find-dbgsym-packages $(which cat)
coreutils-dbgsym libc6-dbg
To install symbols for the running kernel:
$ sudo apt install linux-image-$(uname -r)-dbgsym
Also see the Ubuntu documentation.
Arch Linux
Arch Linux unfortunately does not make debugging symbols available. Packages must be
manually rebuilt with debugging symbols enabled. See the ArchWiki and the feature request.
Release Highlights
These are highlights of each release of drgn focusing on a few exciting items from the
full release notes.
0.0.23 (Released June 28th, 2023)
These are some of the highlights of drgn 0.0.23. See the GitHub release for the full
release notes, including more improvements and bug fixes.
Virtual Address Translation Helpers
This release added several Linux kernel helpers for translating virtual addresses.
follow_phys() translates a virtual address to a physical address in a given address space.
For example, to get the physical address that virtual address 0x7f7fe46a4270 maps to in
process 115:
>>> task = find_task(prog, 115)
>>> address = 0x7f7fe46a4270
>>> print(hex(follow_phys(task.mm, address)))
0x4090270
follow_page() translates a virtual address to the struct page * that it maps to:
>>> follow_page(task.mm, address)
*(struct page *)0xffffd20ac0102400 = {
...
}
follow_pfn() translates a virtual address to the page frame number (PFN) of the page that
it maps to:
>>> follow_pfn(task.mm, address)
(unsigned long)16528
These can be used to translate arbitrary kernel virtual addresses by passing
prog["init_mm"].address_of_():
>>> print(hex(follow_phys(prog["init_mm"].address_of_(), 0xffffffffc0483000)))
0x2e4b000
Vmalloc/Vmap Address Translation Helpers
vmalloc_to_page() is a special case of follow_page() for vmalloc and vmap addresses:
>>> vmalloc_to_page(prog, 0xffffffffc0477000)
*(struct page *)0xffffc902400b8980 = {
...
}
Likewise, vmalloc_to_pfn() is a special case of follow_pfn() for vmalloc and vmap
addresses:
>>> vmalloc_to_pfn(prog, 0xffffffffc0477000)
(unsigned long)11814
contrib Directory
Martin Liška, Boris Burkov, and Johannes Thumshirn added lots of new scripts to the
contrib directory:
• btrfs_tree.py: work-in-progress helpers for Btrfs B-trees
• btrfs_tree_mod_log.py: simulator for the Btrfs tree modification log
• dump_btrfs_bgs.py: print block groups in a Btrfs filesystem
• kcore_list.py: print memory regions from /proc/kcore
• kernel_sys.py: print system information (similar to crash's sys command)
• mount.py: print a filesystem mount table
• platform_drivers.py: print registered platform drivers
• vmmap.py: print memory mappings in a process (similar to /proc/$pid/maps)
• vmstat.py: print information about kernel memory usage
Embedding Interactive Mode
drgn.cli.run_interactive() runs drgn's interactive mode. It can be used to embed drgn in
another application. For example, you could use it for a custom drgn.Program that the
standard drgn CLI can't set up:
import drgn
import drgn.cli
prog = drgn.Program()
prog.add_type_finder(...)
prog.add_object_finder(...)
prog.add_memory_segment(...)
drgn.cli.run_interactive(prog)
Full s390x Support
Sven Schnelle contributed s390x virtual address translation support. This is the state of
architecture support in this release:
drgn 0.0.23 Architecture Support
┌─────────────┬─────────────────────┬──────────────┬─────────────────────┐
│Architecture │ Linux Kernel │ Stack Traces │ Virtual Address │
│ │ Modules │ │ Translation │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│x86-64 │ ✓ │ ✓ │ ✓ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│AArch64 │ ✓ │ ✓ │ ✓ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│ppc64 │ ✓ │ ✓ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│s390x │ ✓ │ ✓ │ ✓ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│i386 │ ✓ │ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│Arm │ ✓ │ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│RISC-V │ ✓ │ │ │
└─────────────┴─────────────────────┴──────────────┴─────────────────────┘
Linux 6.3 & 6.4 Support
Linux 6.3 and 6.4 had an unusual number of breaking changes for drgn. Here are some errors
you might see with older versions of drgn that are fixed in this release.
On startup (fixed by Ido Schimmel):
warning: could not get debugging information for:
kernel modules (could not find loaded kernel modules: 'struct module' has no member 'core_size')
From drgn.Program.stack_trace() and drgn.Thread.stack_trace():
Exception: unknown ORC entry type 3
From compound_order() and compound_nr():
AttributeError: 'struct page' has no member 'compound_order'
From for_each_disk() and for_each_partition():
AttributeError: 'struct class' has no member 'p'
Python 3.12 Support
Python 3.12, currently in beta, changed an implementation detail that drgn depended on,
which caused crashes like:
Py_SIZE: Assertion `ob->ob_type != &PyLong_Type' failed.
Stephen Brennan fixed this.
0.0.22 (Released January 5th, 2023)
These are some of the highlights of drgn 0.0.22. See the GitHub release for the full
release notes, including more improvements and bug fixes.
Listing Stack Frame Locals
drgn.StackFrame.locals() returns the names of all arguments and local variables in the
scope of a stack frame. This allows you to get a quick idea of what's going on in a
function without needing to read the source code right away.
Let's use the __schedule stack frame from the following trace as an example:
>>> trace = prog.stack_trace(1)
>>> trace
#0 context_switch (./kernel/sched/core.c:5209:2)
#1 __schedule (./kernel/sched/core.c:6521:8)
#2 schedule (./kernel/sched/core.c:6597:3)
#3 do_wait (./kernel/exit.c:1562:4)
#4 kernel_wait4 (./kernel/exit.c:1706:8)
#5 __do_sys_wait4 (./kernel/exit.c:1734:13)
#6 do_syscall_x64 (./arch/x86/entry/common.c:50:14)
#7 do_syscall_64 (./arch/x86/entry/common.c:80:7)
#8 entry_SYSCALL_64+0x9b/0x197 (./arch/x86/entry/entry_64.S:120)
#9 0x7f6a34a00057
>>> trace[1].locals()
['sched_mode', 'prev', 'next', 'switch_count', 'prev_state', 'rf', 'rq', 'cpu']
>>> for name in trace[1].locals():
... print(name, trace[1][name].format_(dereference=False))
...
sched_mode (unsigned int)0
prev (struct task_struct *)0xffffa3b601178000
next (struct task_struct *)0xffffa3b6026db800
switch_count (unsigned long *)0xffffa3b601178528
prev_state (unsigned long)<absent>
rf (struct rq_flags){
.flags = (unsigned long)1,
.cookie = (struct pin_cookie){},
.clock_update_flags = (unsigned int)4,
}
rq (struct rq *)0xffffa3b67fda9640
cpu (int)<absent>
Compare this to the kernel source code. Note that some of the variables have been
optimized out by the compiler.
This feature was contributed by Stephen Brennan.
Merged Slab Caches
The Linux kernel slab allocator merges "similar" slab caches as an optimization, which
often causes confusion. slab_cache_is_merged() (added back in 0.0.20) returns whether or
not a slab cache has been merged, but not what it was merged with. In this release,
Stephen Brennan added get_slab_cache_aliases(), which provides a mapping from a slab cache
name to the name of the cache it was merged into:
>>> get_slab_cache_aliases(prog)
{'io_kiocb': 'maple_node', 'ip_dst_cache': 'uid_cache', 'aio_kiocb': 'uid_cache', 'ip_fib_alias': 'Acpi-Parse', 'pid_namespace': 'pid', 'iommu_iova': 'vmap_area', 'fasync_cache': 'ftrace_event_field', 'dnotify_mark': 'Acpi-State', 'tcp_bind2_bucket': 'vmap_area', 'nsproxy': 'Acpi-Operand', 'shared_policy_node': 'ftrace_event_field', 'eventpoll_epi': 'pid', 'fib6_nodes': 'vmap_area', 'Acpi-Namespace': 'ftrace_event_field', 'posix_timers_cache': 'maple_node', 'inotify_inode_mark': 'Acpi-State', 'kernfs_iattrs_cache': 'trace_event_file', 'fs_cache': 'vmap_area', 'UDP-Lite': 'UDP', 'anon_vma_chain': 'vmap_area', 'ip6_dst_cache': 'maple_node', 'eventpoll_pwq': 'vmap_area', 'inet_peer_cache': 'uid_cache', 'fsnotify_mark_connector': 'numa_policy', 'ip_fib_trie': 'ftrace_event_field', 'filp': 'maple_node', 'dnotify_struct': 'numa_policy', 'UDPLITEv6': 'UDPv6', 'biovec-16': 'maple_node', 'PING': 'signal_cache', 'ep_head': 'blkdev_ioc', 'tcp_bind_bucket': 'pid', 'Acpi-ParseExt': 'Acpi-State', 'cred_jar': 'pid', 'ovl_aio_req': 'pid', 'pool_workqueue': 'maple_node', 'sigqueue': 'Acpi-State', 'file_lock_ctx': 'Acpi-Parse', 'kernfs_node_cache': 'pid'}
This means that if you're looking for io_kiocb allocations, you actually need to look at
the maple_node slab cache. Conversely, if you're looking at the maple_node slab cache, you
need to be aware that it also contains allocations from all of the following slab caches:
>>> [merged for merged, canonical in get_slab_cache_aliases(prog).items() if canonical == "maple_node"]
['io_kiocb', 'posix_timers_cache', 'ip6_dst_cache', 'filp', 'biovec-16', 'pool_workqueue']
Slab Address Information
This release extended identify_address() to show additional information about slab
allocations:
>>> ptr1 = 0xffffa3b601178438
>>> ptr2 = 0xffffa3b601176cc0
>>> identify_address(prog, ptr1)
'slab object: task_struct+0x438'
>>> identify_address(prog, ptr2)
'free slab object: mm_struct+0x0'
This means that ptr1 is an address 0x438 bytes into an allocated object from the
task_struct slab cache, and ptr2 is a free object from the mm_struct slab cache.
slab_object_info() provides the same information programmatically:
>>> slab_object_info(prog, ptr1)
SlabObjectInfo(slab_cache=Object(prog, 'struct kmem_cache *', value=0xffffa3b601045500), slab=Object(prog, 'struct slab *', value=0xffffe80840045e00), address=0xffffa3b601178000, allocated=True)
>>> slab_object_info(prog, ptr2)
SlabObjectInfo(slab_cache=Object(prog, 'struct kmem_cache *', value=0xffffa3b601045900), slab=Object(prog, 'struct slab *', value=0xffffe80840045c00), address=0xffffa3b601176cc0, allocated=False)
Annotated Stack Memory
print_annotated_stack() prints a stack trace and all of its memory, identifying anything
that it can:
>>> print_annotated_stack(prog.stack_trace(1))
STACK POINTER VALUE
[stack frame #0 at 0xffffffffaf8a68e9 (__schedule+0x429/0x488) in context_switch at ./kernel/sched/core.c:5209:2 (inlined)]
[stack frame #1 at 0xffffffffaf8a68e9 (__schedule+0x429/0x488) in __schedule at ./kernel/sched/core.c:6521:8]
ffffbb1ac0013d28: ffffffffaf4498f5 [function symbol: __flush_tlb_one_user+0x5]
ffffbb1ac0013d30: 00000000af449feb
ffffbb1ac0013d38: 0000000000000001
ffffbb1ac0013d40: 0000000000000004
ffffbb1ac0013d48: 25c5ff9539edc200
ffffbb1ac0013d50: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d58: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d60: ffffbb1ac0013e10
ffffbb1ac0013d68: ffffa3b601177ff0 [slab object: mm_struct+0x70]
ffffbb1ac0013d70: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d78: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d80: ffffffffaf8a69d1 [function symbol: schedule+0x89]
[stack frame #2 at 0xffffffffaf8a69d1 (schedule+0x89/0xc7) in schedule at ./kernel/sched/core.c:6597:3]
ffffbb1ac0013d88: ffffbb1ac0013de8
ffffbb1ac0013d90: 0000000000000000
ffffbb1ac0013d98: ffffffffaf4595ee [function symbol: do_wait+0x231]
[stack frame #3 at 0xffffffffaf4595ee (do_wait+0x231/0x2e3) in do_wait at ./kernel/exit.c:1562:4]
ffffbb1ac0013da0: ffffa3b601178450 [slab object: task_struct+0x450]
ffffbb1ac0013da8: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013db0: 0000000000000004
ffffbb1ac0013db8: 0000000000000000
ffffbb1ac0013dc0: 00007ffe0984a170
ffffbb1ac0013dc8: 0000000000000000
ffffbb1ac0013dd0: fffffffffffffffd
ffffbb1ac0013dd8: 0000000000000004
ffffbb1ac0013de0: ffffffffaf45a42f [function symbol: kernel_wait4+0xc2]
[stack frame #4 at 0xffffffffaf45a42f (kernel_wait4+0xc2/0x11b) in kernel_wait4 at ./kernel/exit.c:1706:8]
ffffbb1ac0013de8: 0000000400000004
ffffbb1ac0013df0: 0000000000000000
ffffbb1ac0013df8: 0000000000000000
ffffbb1ac0013e00: 0000000000000000
ffffbb1ac0013e08: 0000000000000000
ffffbb1ac0013e10: ffffffff00000000
ffffbb1ac0013e18: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013e20: ffffffffaf45890c [function symbol: child_wait_callback+0x0]
ffffbb1ac0013e28: ffffa3b601188028 [slab object: signal_cache+0x28]
ffffbb1ac0013e30: ffffa3b601188028 [slab object: signal_cache+0x28]
ffffbb1ac0013e38: 000055d500000000
ffffbb1ac0013e40: 25c5ff9539edc200
ffffbb1ac0013e48: 0000000000000000
ffffbb1ac0013e50: ffffbb1ac0013f30
ffffbb1ac0013e58: ffffbb1ac0013f58
ffffbb1ac0013e60: 0000000000000000
ffffbb1ac0013e68: 0000000000000000
ffffbb1ac0013e70: 0000000000000000
ffffbb1ac0013e78: ffffffffaf45a4c0 [function symbol: __do_sys_wait4+0x38]
[stack frame #5 at 0xffffffffaf45a4c0 (__do_sys_wait4+0x38/0x8c) in __do_sys_wait4 at ./kernel/exit.c:1734:13]
ffffbb1ac0013e80: ffffffffaf8aaa21 [function symbol: _raw_spin_unlock_irq+0x10]
ffffbb1ac0013e88: ffffffffaf46460c [function symbol: do_sigaction+0xf8]
ffffbb1ac0013e90: ffffa3b601180020 [slab object: sighand_cache+0x20]
ffffbb1ac0013e98: ffffa3b6028d02d0 [slab object: vm_area_struct+0x0]
ffffbb1ac0013ea0: 25c5ff9539edc200
ffffbb1ac0013ea8: 0000000000000002
ffffbb1ac0013eb0: 00007ffe09849fb0
ffffbb1ac0013eb8: ffffbb1ac0013f58
ffffbb1ac0013ec0: 0000000000000000
ffffbb1ac0013ec8: 0000000000000000
ffffbb1ac0013ed0: 0000000000000046
ffffbb1ac0013ed8: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013ee0: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013ee8: ffffbb1ac0013f58
ffffbb1ac0013ef0: 0000000000000000
ffffbb1ac0013ef8: ffffffffaf426def [function symbol: fpregs_assert_state_consistent+0x1b]
ffffbb1ac0013f00: 0000000000000000
ffffbb1ac0013f08: ffffffffaf4b2f53 [function symbol: exit_to_user_mode_prepare+0xa6]
ffffbb1ac0013f10: 0000000000000000
ffffbb1ac0013f18: 25c5ff9539edc200
ffffbb1ac0013f20: ffffbb1ac0013f58
ffffbb1ac0013f28: 0000000000000000
ffffbb1ac0013f30: ffffbb1ac0013f48
ffffbb1ac0013f38: ffffffffaf8a1573 [function symbol: do_syscall_64+0x70]
[stack frame #6 at 0xffffffffaf8a1573 (do_syscall_64+0x70/0x8a) in do_syscall_x64 at ./arch/x86/entry/common.c:50:14 (inlined)]
[stack frame #7 at 0xffffffffaf8a1573 (do_syscall_64+0x70/0x8a) in do_syscall_64 at ./arch/x86/entry/common.c:80:7]
ffffbb1ac0013f40: 0000000000000000
ffffbb1ac0013f48: 0000000000000000
ffffbb1ac0013f50: ffffffffafa0009b [symbol: entry_SYSCALL_64+0x9b]
[stack frame #8 at 0xffffffffafa0009b (entry_SYSCALL_64+0x9b/0x197) at ./arch/x86/entry/entry_64.S:120]
ffffbb1ac0013f58: 0000000000000000
[stack frame #9 at 0x7f6a34a00057]
Like drgn.StackFrame.locals(), this provides a nice overview of everything happening in a
function, which might include useful hints. Keep in mind that it may identify "stale"
addresses for anything that a function hasn't reinitialized yet, and as always, be careful
of slab cache merging.
This was inspired by the crash bt -FF command. It was contributed by Nhat Pham.
XArray Helpers
XArrays were introduced in Linux 4.20 as a replacement for radix trees. drgn's radix tree
helpers also support XArrays in some cases, but this is awkward, not obvious, and doesn't
work for new, XArray-only functionality.
This release added dedicated XArray helpers like xa_load() and xa_for_each().
s390x Support
Sven Schnelle contributed s390x support for Linux kernel modules and stack traces. This is
the state of architecture support in this release:
drgn 0.0.22 Architecture Support
┌─────────────┬─────────────────────┬──────────────┬─────────────────────┐
│Architecture │ Linux Kernel │ Stack Traces │ Virtual Address │
│ │ Modules │ │ Translation │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│x86-64 │ ✓ │ ✓ │ ✓ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│AArch64 │ ✓ │ ✓ │ ✓ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│ppc64 │ ✓ │ ✓ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│s390x │ ✓ │ ✓ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│i386 │ ✓ │ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│Arm │ ✓ │ │ │
├─────────────┼─────────────────────┼──────────────┼─────────────────────┤
│RISC-V │ ✓ │ │ │
└─────────────┴─────────────────────┴──────────────┴─────────────────────┘
Relicensing to LGPL
drgn was originally licensed as GPLv3+. In this release, it was changed to LGPLv2.1+. The
motivation for this change was to enable the long term vision for drgn that more projects
can use it as a library providing programmatic interfaces for debugger functionality. For
example, Object Introspection, a userspace memory profiler recently open sourced by Meta,
uses drgn to parse debugging information.
AUTHOR
Omar Sandoval
COPYRIGHT
Omar Sandoval