API Reference¶
Programs¶
-
class
drgn.
Program
¶ A
Program
represents a crashed or running program. It can be used to lookup type definitions, access variables, and read arbitrary memory.The main functionality of a
Program
is looking up objects (i.e., variables, constants, or functions). This is usually done with the[]
operator.-
Program
(platform=None) Create a
Program
with no target program. It is usually more convenient to use one of the Program Constructors.
-
flags
¶ Flags which apply to this program.
- Vartype
-
platform
¶ Platform that this program runs on, or
None
if it has not been determined yet.
-
language
¶ Default programming language of the program.
This is used for interpreting the type name given to
type()
and when creating anObject
without an explicit type.For the Linux kernel, this is
Language.C
. For userspace programs, this is determined from the language ofmain
in the program, falling back toLanguage.C
. This heuristic may change in the future.- Vartype
-
__getitem__
(name)¶ Implement
self[name]
. Get the object (variable, constant, or function) with the given name.This is equivalent to
prog.object(name)
except that this raisesKeyError
instead ofLookupError
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()
, orobject()
methods can be used instead.>>> prog['jiffies'] Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
-
variable
(name, filename=None)¶ Get the variable with the given name.
>>> prog.variable('jiffies') Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
This is equivalent to
prog.object(name, FindObjectFlags.VARIABLE, filename)
.
-
constant
(name, filename=None)¶ Get the constant (e.g., enumeration constant) with the given name.
Note that support for macro constants is not yet implemented for DWARF files, and most compilers don’t generate macro debugging information by default anyways.
>>> prog.constant('PIDTYPE_MAX') Object(prog, 'enum pid_type', value=4)
This is equivalent to
prog.object(name, FindObjectFlags.CONSTANT, filename)
.
-
function
(name, filename=None)¶ Get the function with the given name.
>>> prog.function('schedule') Object(prog, 'void (void)', address=0xffffffff94392370)
This is equivalent to
prog.object(name, FindObjectFlags.FUNCTION, filename)
.
-
object
(name, flags=FindObjectFlags.ANY, filename=None)¶ Get the object (variable, constant, or function) with the given name.
- Parameters
name (
str
) – The object name.flags (
FindObjectFlags
) – Flags indicating what kind of object to look for.filename (
Optional
[str
]) – The source code file that contains the definition. See Filenames.
- Raises
LookupError – if no objects with the given name are found in the given file
- Return type
-
symbol
(address_or_name)¶ Get the symbol containing the given address, or the global symbol with the given name.
- Parameters
address_or_name (
Union
[IntegerLike
,str
]) – The address or name.- Raises
LookupError – if no symbol contains the given address or matches the given name
- Return type
-
stack_trace
(thread)¶ Get the stack trace for the given thread in the program.
thread
may be a thread ID (as defined by gettid(2)), in which case this will unwind the stack for the thread with that ID. The ID may be a Pythonint
or an integerObject
thread
may also be astruct pt_regs
orstruct 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 astruct task_struct *
object, in which case this will unwind the stack for that task. Seedrgn.helpers.linux.pid.find_task()
.This is implemented for the Linux kernel (both live and core dumps) as well as userspace core dumps; it is not yet implemented for live userspace processes.
- Parameters
thread (
Union
[Object
,IntegerLike
]) – Thread ID,struct pt_regs
object, orstruct task_struct *
object.- Return type
-
type
(name, filename=None)¶ Get the type with the given name.
>>> prog.type('long') int_type(name='long', size=8, is_signed=True)
-
read
(address, size, physical=False)¶ Read size bytes of memory starting at address in the program. The address may be virtual (the default) or physical if the program supports it.
>>> prog.read(0xffffffffbe012b40, 16) b'swapper/0'
- Parameters
address (
IntegerLike
) – The starting address.size (
IntegerLike
) – The number of bytes to read.physical (
bool
) – Whether address is a physical memory address. IfFalse
, then it is a virtual memory address. Physical memory can usually only be read when the program is an operating system kernel.
- Raises
FaultError – if the address range is invalid or the type of address (physical or virtual) is not supported by the program
ValueError – if size is negative
- Return type
-
read_word
(address, physical=False)¶ Read an unsigned integer from the program’s memory in the program’s byte order.
read_u8()
,read_u16()
,read_u32()
, andread_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()
andint.from_bytes()
or thestruct
module.- Parameters
address (
IntegerLike
) – Address of the integer.physical (
bool
) – Whether address is a physical memory address; seeread()
.
- Raises
FaultError – if the address is invalid; see
read()
- Return type
-
add_memory_segment
(address, size, read_fn, physical=False)¶ Define a region of memory in the program.
If it overlaps a previously registered segment, the new segment takes precedence.
- Parameters
address (
IntegerLike
) – Address of the segment.size (
IntegerLike
) – Size of the segment in bytes.physical (
bool
) – Whether to add a physical memory segment. IfFalse
, then this adds a virtual memory segment.read_fn (
Callable
[[int
,int
,int
,bool
],bytes
]) – Callable to call to read memory from the segment. It is passed the address being read from, the number of bytes to read, the offset in bytes from the beginning of the segment, and whether the address is physical:(address, count, offset, physical)
. It should return the requested number of bytes asbytes
or another buffer type.
- Return type
-
add_type_finder
(fn)¶ Register a callback for finding types in the program.
Callbacks are called in reverse order of the order they were added until the type is found. So, more recently added callbacks take precedence.
-
add_object_finder
(fn)¶ Register a callback for finding objects in the program.
Callbacks are called in reverse order of the order they were added until the object is found. So, more recently added callbacks take precedence.
- Parameters
fn (
Callable
[[Program
,str
,FindObjectFlags
,Optional
[str
]],Object
]) – Callable taking a program, name,FindObjectFlags
, and filename:(prog, name, flags, filename)
. The filename should be matched withfilename_matches()
. This should return anObject
.- Return type
-
set_core_dump
(path)¶ Set the program to a core dump.
This loads the memory segments from the core dump and determines the mapped executable and libraries. It does not load any debugging symbols; see
load_default_debug_info()
.
-
set_kernel
()¶ Set the program to the running operating system kernel.
This loads the memory of the running kernel and thus requires root privileges. It does not load any debugging symbols; see
load_default_debug_info()
.- Return type
-
set_pid
(pid)¶ Set the program to a running process.
This loads the memory of the process and determines the mapped executable and libraries. It does not load any debugging symbols; see
load_default_debug_info()
.
-
load_debug_info
(paths=None, default=False, main=False)¶ Load debugging information for a list of executable or library files.
Note that this is parallelized, so it is usually faster to load multiple files at once rather than one by one.
- Parameters
default (
bool
) –Also load debugging information which can automatically be determined from the program.
For the Linux kernel, this tries to load
vmlinux
and any loaded kernel modules from a few standard locations.For userspace programs, this tries to load the executable and any loaded libraries.
This implies
main=True
.main (
bool
) –Also load debugging information for the main executable.
For the Linux kernel, this tries to load
vmlinux
.This is currently ignored for userspace programs.
- Raises
MissingDebugInfoError – if debugging information was not available for some files; other files with debugging information are still loaded
- Return type
-
load_default_debug_info
()¶ Load debugging information which can automatically be determined from the program.
This is equivalent to
load_debug_info(None, True)
.- Return type
-
cache
¶ Dictionary for caching program metadata.
This isn’t used by drgn itself. It is intended to be used by helpers to cache metadata about the program. For example, if a helper for a program depends on the program version or an optional feature, the helper can detect it and cache it for subsequent invocations:
def my_helper(prog): try: have_foo = prog.cache['have_foo'] except KeyError: have_foo = detect_foo_feature(prog) prog.cache['have_foo'] = have_foo if have_foo: return prog['foo'] else: return prog['bar']
-
-
class
drgn.
ProgramFlags
¶ Bases:
enum.Flag
ProgramFlags
are flags that can apply to aProgram
(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 forProgram.object()
. These can be combined to search for multiple kinds of objects at once.-
CONSTANT
¶
-
FUNCTION
¶
-
VARIABLE
¶
-
ANY
¶
-
Filenames¶
The Program.type()
, Program.object()
,
Program.variable()
, Program.constant()
, and
Program.function()
methods all take a filename parameter to
distinguish between multiple definitions with the same name. The filename
refers to the source code file that contains the definition. It is matched with
filename_matches()
. If multiple definitions match, one is returned
arbitrarily.
-
drgn.
filename_matches
(haystack, needle)¶ Return whether a filename containing a definition (haystack) matches a filename being searched for (needle).
The filename is matched from right to left, so
'stdio.h'
,'include/stdio.h'
,'usr/include/stdio.h'
, and'/usr/include/stdio.h'
would all match a definition in/usr/include/stdio.h
. If needle isNone
or empty, it matches any definition. If haystack isNone
or empty, it only matches if needle is alsoNone
or empty.
Program Constructors¶
The drgn command line interface automatically creates a Program
named
prog
. However, drgn may also be used as a library without the CLI, in which
case a Program
must be created manually.
-
drgn.
program_from_core_dump
(path)¶ Create a
Program
from a core dump file. The type of program (e.g., userspace or kernel) is determined automatically.
Platforms¶
-
class
drgn.
Platform
¶ A
Platform
represents the environment (i.e., architecture and ABI) that a program runs on.-
Platform
(arch, flags=None) Create a
Platform
.- Parameters
arch (
Architecture
) –Platform.arch
flags (
Optional
[PlatformFlags
]) –Platform.flags
; ifNone
, default flags for the architecture are used.
-
arch
¶ Instruction set architecture of this platform.
- Vartype
-
flags
¶ Flags which apply to this platform.
- Vartype
-
-
class
drgn.
Architecture
¶ Bases:
enum.Enum
An
Architecture
represents an instruction set architecture.-
X86_64
¶ The x86-64 architecture, a.k.a. AMD64.
-
PPC64
¶ The 64-bit PowerPC architecture.
-
UNKNOWN
¶ An architecture which is not known to drgn. Certain features are not available when the architecture is unknown, but most of drgn will still work.
-
-
class
drgn.
PlatformFlags
¶ Bases:
enum.Flag
PlatformFlags
are flags describing aPlatform
.-
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.
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; andtype_
, the type of the object. Reference objects also have anaddress_
and abit_offset_
. Objects may also have abit_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 theformat_()
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 callprint()
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 withptr[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()
, andbool()
functions convert an object to that Python type. Conversion tobool
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()
, andlist subscripting
).Object attributes and methods are named with a trailing underscore to avoid conflicting with structure, union, or class members. The attributes and methods always take precedence; use
member_()
if there is a conflict.Objects are usually obtained directly from a
Program
, but they can be constructed manually, as well (for example, if you got a variable address from a log file).-
Object
(prog, type, value, *, bit_field_size=None) Create a value object given its type and value.
- Parameters
prog (
Program
) – Program to create the object in.value (
Union
[IntegerLike
,float
,bool
,Mapping
[str
,Any
],Sequence
[Any
]]) – Value of the object. Seevalue_()
.bit_field_size (
Optional
[IntegerLike
]) – Size in bits of the object if it is a bit field. The default isNone
, which means the object is not a bit field.
-
Object
(prog, *, value) Create a value object from a “literal”.
This is used to emulate a literal number in the source code of the program. The type is deduced from value according to the language’s rules for literals.
-
Object
(prog, type, *, address, bit_offset=0, bit_field_size=None) Create a reference object.
- Parameters
address (
IntegerLike
) – Address of the object in the program.bit_offset (
IntegerLike
) – Offset in bits from address to the beginning of the object.
-
Object
(prog, type, *, bit_field_size=None) Create an absent object.
-
absent_
¶ Whether this object is absent.
This is
False
for all values and references (even if the reference has an invalid address).- Vartype
-
address_
¶ Address of this object if it is a reference,
None
if it is a value or absent.
-
bit_offset_
¶ Offset in bits from this object’s address to the beginning of the object if it is a reference,
None
otherwise. This can only be non-zero for scalars.
-
bit_field_size_
¶ Size in bits of this object if it is a bit field,
None
if it is not.
-
__getattribute__
(name)¶ Implement
self.name
.If name is an attribute of the
Object
class, then this returns that attribute. Otherwise, it is equivalent tomember_()
.>>> print(prog['init_task'].pid) (pid_t)0
-
__getitem__
(idx)¶ Implement
self[idx]
. Get the array element at the given index.>>> print(prog['init_task'].comm[0]) (char)115
This is only valid for pointers and arrays.
Note
Negative indices behave as they would in the object’s language (as opposed to the Python semantics of indexing from the end of the array).
- Parameters
idx (
IntegerLike
) – The array index.- Raises
TypeError – if this object is not a pointer or array
- Return type
-
__len__
()¶ Implement
len(self)
. Get the number of elements in this object.>>> len(prog['init_task'].comm) 16
This is only valid for arrays.
-
value_
()¶ Get the value of this object as a Python object.
For basic types (integer, floating-point, boolean), this returns an object of the directly corresponding Python type (
int
,float
,bool
). For pointers, this returns the address value of the pointer. For enums, this returns anint
. For structures and unions, this returns adict
of members. For arrays, this returns alist
of values.- Raises
FaultError – if reading the object causes a bad memory access
TypeError – if this object has an unreadable type (e.g.,
void
)
- Return type
-
string_
()¶ Read a null-terminated string pointed to by this object.
This is only valid for pointers and arrays. The element type is ignored; this operates byte-by-byte.
For pointers and flexible arrays, this stops at the first null byte.
For complete arrays, this stops at the first null byte or at the end of the array.
- Raises
FaultError – if reading the string causes a bad memory access
TypeError – if this object is not a pointer or array
- Return type
-
member_
(name)¶ Get a member of this object.
This is valid for structures, unions, and pointers to either.
Normally the dot operator (
.
) can be used to accomplish the same thing, but this method can be used if there is a name conflict with an Object member or method.- Parameters
name (
str
) – Name of the member.- Raises
TypeError – if this object is not a structure, union, class, or a pointer to one of those
LookupError – if this object does not have a member with the given name
- Return type
-
address_of_
()¶ Get a pointer to this object.
This corresponds to the address-of (
&
) operator in C. It is only possible for reference objects, as value objects don’t have an address in the program.As opposed to
address_
, this returns anObject
, not anint
.- Raises
ValueError – if this object is a value
- Return type
-
read_
()¶ Read this object (which may be a reference or a value) and return it as a value object.
This is useful if the object can change in the running program (but of course nothing stops the program from modifying the object while it is being read).
As opposed to
value_()
, this returns anObject
, not a standard Python type.- Raises
FaultError – if reading this object causes a bad memory access
TypeError – if this object has an unreadable type (e.g.,
void
)
- Return type
-
format_
(*, columns=None, dereference=None, symbolize=None, string=None, char=None, type_name=None, member_type_names=None, element_type_names=None, members_same_line=None, elements_same_line=None, member_names=None, element_indices=None, implicit_members=None, implicit_elements=None)¶ Format this object in programming language syntax.
Various format options can be passed (as keyword arguments) to control the output. Options that aren’t passed or are passed as
None
fall back to a default. Specifically,obj.format_()
(i.e., with no passed options) is equivalent tostr(obj)
.>>> workqueues = prog['workqueues'] >>> print(workqueues) (struct list_head){ .next = (struct list_head *)0xffff932ecfc0ae10, .prev = (struct list_head *)0xffff932e3818fc10, } >>> print(workqueues.format_(type_name=False, ... member_type_names=False, ... member_names=False, ... members_same_line=True)) { 0xffff932ecfc0ae10, 0xffff932e3818fc10 }
- Parameters
columns (
Optional
[IntegerLike
]) – Number of columns to limit output to when the expression can be reasonably wrapped. Defaults to no limit.dereference (
Optional
[bool
]) – If this object is a pointer, include the dereferenced value. This does not apply to structure, union, or class members, or array elements, as dereferencing those could lead to an infinite loop. Defaults toTrue
.symbolize (
Optional
[bool
]) – Include a symbol name and offset for pointer objects. Defaults toTrue
.string (
Optional
[bool
]) – Format the values of objects with string type as strings. For C, this applies to pointers to and arrays ofchar
,signed char
, andunsigned char
. Defaults toTrue
.char (
Optional
[bool
]) – Format objects with character type as character literals. For C, this applies tochar
,signed char
, andunsigned char
. Defaults toFalse
.type_name (
Optional
[bool
]) – Include the type name of this object. Defaults toTrue
.member_type_names (
Optional
[bool
]) – Include the type names of structure, union, and class members. Defaults toTrue
.element_type_names (
Optional
[bool
]) – Include the type names of array elements. Defaults toFalse
.members_same_line (
Optional
[bool
]) – Place multiple structure, union, and class members on the same line if they fit within the specified number ofcolumns
. Defaults toFalse
.elements_same_line (
Optional
[bool
]) – Place multiple array elements on the same line if they fit within the specified number ofcolumns
. Defaults toTrue
.member_names (
Optional
[bool
]) – Include the names of structure, union, and class members. Defaults toTrue
.element_indices (
Optional
[bool
]) – Include the indices of array elements. Defaults toFalse
.implicit_members (
Optional
[bool
]) – Include structure, union, and class members which have an implicit value (i.e., for C, zero-initialized). Defaults toTrue
.implicit_elements (
Optional
[bool
]) – Include array elements which have an implicit value (i.e., for C, zero-initialized). Defaults toFalse
.
- Return type
-
drgn.
NULL
(prog, type)¶ Get an object representing
NULL
casted to the given type.This is equivalent to
Object(prog, type, 0)
.
-
drgn.
cast
(type, obj)¶ Get the value of the given object casted to another type.
Objects with a scalar type (integer, boolean, enumerated, floating-point, or pointer) can be casted to a different scalar type. Other objects can only be casted to the same type. This always results in a value object. See also
drgn.reinterpret()
.
-
drgn.
reinterpret
(type, obj)¶ Get a copy of the given object reinterpreted as another type and/or byte order.
This reinterprets the raw memory of the object, so an object can be reinterpreted as any other type. However, value objects with a scalar type cannot be reinterpreted, as their memory layout in the program is not known. Reinterpreting a reference results in a reference, and reinterpreting a value results in a value. See also
drgn.cast()
.
-
drgn.
container_of
(ptr, type, member)¶ Get the containing object of a pointer object.
This corresponds to the
container_of()
macro in C.- Parameters
- Returns
Pointer to containing object.
- Raises
TypeError – if ptr is not a pointer or type is not a structure, union, or class type
ValueError – if the member is not byte-aligned (e.g., because it is a bit field)
LookupError – if type does not have a member with the given name
- Return type
Symbols¶
Stack Traces¶
Stack traces are retrieved with Program.stack_trace()
.
-
class
drgn.
StackTrace
¶ A
StackTrace
is a sequence ofStackFrame
.len(trace)
is the number of stack frames in the trace.trace[0]
is the innermost stack frame,trace[1]
is its caller, andtrace[len(trace) - 1]
is the outermost frame. Negative indexing also works:trace[-1]
is the outermost frame andtrace[-len(trace)]
is the innermost frame. It is also iterable:for frame in trace: if frame.symbol().name == 'io_schedule': print('Thread is doing I/O')
str()
returns a pretty-printed stack trace:>>> print(prog.stack_trace(1)) #0 __schedule+0x25c/0x8ba #1 schedule+0x3c/0x7e #2 schedule_hrtimeout_range_clock+0x10c/0x118 #3 ep_poll+0x3ca/0x40a #4 do_epoll_wait+0xb0/0xc6 #5 __x64_sys_epoll_wait+0x1a/0x1d #6 do_syscall_64+0x55/0x17c #7 entry_SYSCALL_64+0x7c/0x156
The drgn CLI is set up so that stack traces are displayed with
str()
by default.
-
class
drgn.
StackFrame
¶ A
StackFrame
represents a single frame in a thread’s call stack.-
interrupted
¶ Whether this stack frame was interrupted (for example, by a hardware interrupt, signal, trap, etc.).
If this is
True
, then the register values in this frame are the values at the time that the frame was interrupted.This is
False
if the frame is for a function call, in which case the register values are the values when control returns to this frame. In particular, the program counter is the return address, which is typically the instruction after the call instruction.- Vartype
-
symbol
()¶ Get the function symbol at this stack frame.
This is equivalent to:
prog.symbol(frame.pc - (0 if frame.interrupted else 1))
- Return type
-
register
(reg)¶ Get the value of the given register at this stack frame.
- Parameters
reg (
str
) – Register name.- Raises
ValueError – if the register name is not recognized
LookupError – if the register value is not known
- Return type
-
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 anAttributeError
.repr()
of aType
returns a Python representation of the type:>>> print(repr(prog.type('sector_t'))) typedef_type(name='sector_t', type=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 ofrepr()
by default.This class cannot be constructed directly. Instead, use one of the Type Constructors.
-
primitive
¶ If this is a primitive type (e.g.,
int
ordouble
), the kind of primitive type. Otherwise,None
.- Vartype
-
qualifiers
¶ Bitmask of this type’s qualifier.
- Vartype
-
name
¶ Name of this type. This is present for integer, boolean, floating-point, and typedef types.
- Vartype
-
tag
¶ Tag of this type, or
None
if this is an anonymous type. This is present for structure, union, class, and enumerated types.
-
size
¶ Size of this type in bytes, or
None
if this is an incomplete type. This is present for integer, boolean, floating-point, structure, union, class, and pointer types.
-
length
¶ Number of elements in this type, or
None
if this is an incomplete type. This is only present for array types.
-
byteorder
¶ Byte order of this type:
'little'
if it is little-endian, or'big'
if it is big-endian. This is present for integer, boolean, floating-point, and pointer types.- Vartype
-
type
¶ Type underlying this type, defined as follows:
For typedef types, the aliased type.
For enumerated types, the compatible integer type, which is
None
if this is an incomplete type.For pointer types, the referenced type.
For array types, the element type.
For function types, the return type.
For other types, this attribute is not present.
- Vartype
-
members
¶ List of members of this type, or
None
if this is an incomplete type. This is present for structure, union, and class types.- Vartype
-
enumerators
¶ List of enumeration constants of this type, or
None
if this is an incomplete type. This is only present for enumerated types.- Vartype
-
parameters
¶ List of parameters of this type. This is only present for function types.
- Vartype
-
is_variadic
¶ Whether this type takes a variable number of arguments. This is only present for function types.
- Vartype
-
template_parameters
¶ List of template parameters of this type. This is present for structure, union, class, and function types.
- Vartype
-
is_complete
()¶ Get whether this type is complete (i.e., the type definition is known). This is always
False
for void types. It may beFalse
for structure, union, class, enumerated, and array types, as well as typedef types where the underlying type is one of those. Otherwise, it is alwaysTrue
.- Return type
-
qualified
(qualifiers)¶ Get a copy of this type with different qualifiers.
Note that the original qualifiers are replaced, not added to.
- Parameters
qualifiers (
Qualifiers
) – New type qualifiers.- Return type
-
member
(name)¶ Look up a member in this type by name.
If this type has any unnamed members, this also matches members of those unnamed members, recursively. If the member is found in an unnamed member,
TypeMember.bit_offset
andTypeMember.offset
are adjusted accordingly.- Parameters
name (
str
) – Name of the member.- Raises
TypeError – if this type is not a structure, union, or class type
LookupError – if this type does not have a member with the given name
- Return type
-
has_member
(name)¶ Return whether this type has a member with the given name.
If this type has any unnamed members, this also matches members of those unnamed members, recursively.
-
-
class
drgn.
TypeMember
¶ A
TypeMember
represents a member of a structure, union, or class type.-
TypeMember
(object_or_type, name=None, bit_offset=0) Create a
TypeMember
.- Parameters
object_or_type (
Union
[Object
,Type
,Callable
[[],Union
[Object
,Type
]]]) –One of:
TypeMember.object
as anObject
.TypeMember.type
as aType
. In this case,object
is set to an absent object with that type.A callable that takes no arguments and returns one of the above. It is called when
object
ortype
is first accessed, and the result is cached.
name (
Optional
[str
]) –TypeMember.name
bit_offset (
int
) –TypeMember.bit_offset
-
object
¶ Member as an
Object
.This is the default initializer for the member, or an absent object if the member has no default initializer. (However, the DWARF specification as of version 5 does not actually support default member initializers, so this is usually absent.)
- Vartype
-
offset
¶ Offset of the member from the beginning of the type in bytes. If the offset is not byte-aligned, accessing this attribute raises
ValueError
.- Vartype
-
-
class
drgn.
TypeEnumerator
¶ A
TypeEnumerator
represents a constant in an enumerated type.Its name and value may be accessed as attributes or unpacked:
>>> prog.type('enum pid_type').enumerators[0].name 'PIDTYPE_PID' >>> name, value = prog.type('enum pid_type').enumerators[0] >>> value 0
-
TypeEnumerator
(name, value) Create a
TypeEnumerator
.- Parameters
name (
str
) –TypeEnumerator.name
value (
int
) –TypeEnumerator.value
-
-
class
drgn.
TypeParameter
¶ A
TypeParameter
represents a parameter of a function type.-
TypeParameter
(default_argument_or_type, name=None) Create a
TypeParameter
.- Parameters
default_argument_or_type (
Union
[Object
,Type
,Callable
[[],Union
[Object
,Type
]]]) –One of:
TypeParameter.type
as aType
. In this case,default_argument
is set to an absent object with that type.A callable that takes no arguments and returns one of the above. It is called when
default_argument
ortype
is first accessed, and the result is cached.
name (
Optional
[str
]) –TypeParameter.name
-
default_argument
¶ Default argument for parameter.
If the parameter does not have a default argument, then this is an absent object.
Note
Neither GCC nor Clang emits debugging information for default arguments (as of GCC 10 and Clang 11), and drgn does not yet parse it, so this is usually absent.
- Vartype
-
-
class
drgn.
TypeTemplateParameter
¶ A
TypeTemplateParameter
represents a template parameter of a structure, union, class, or function type.-
TypeTemplateParameter
(argument, name=None, is_default=False) Create a
TypeTemplateParameter
.- Parameters
argument (
Union
[Type
,Object
,Callable
[[],Union
[Type
,Object
]]]) –One of:
TypeTemplateParameter.argument
as aType
if the parameter is a type template parameter.TypeTemplateParameter.argument
as a non-absentObject
if the parameter is a non-type template parameter.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 (
Optional
[str
]) –TypeTemplateParameter.name
is_default (
bool
) –TypeTemplateParameter.is_default
-
argument
¶ Template argument.
If this is a type template parameter, then this is a
Type
. If this is a non-type template parameter, then this is anObject
.
-
is_default
¶ Whether
argument
is the default for the template parameter.Note
There are two ways to interpret this:
The argument was omitted entirely and thus defaulted to the default argument.
The (specified or defaulted) argument is the same as the default argument.
Compilers are inconsistent about which interpretation they use.
GCC added this information in version 4.9. Clang added it in version 11 (and only when emitting DWARF version 5). If the program was compiled by an older version, this is always false.
- Vartype
-
-
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.
-
ATOMIC
¶ Atomic type.
-
-
drgn.
offsetof
(type, member)¶ Get the offset (in bytes) of a member in a
Type
.This corresponds to
offsetof()
in C.- Parameters
- Raises
TypeError – if type is not a structure, union, or class type
ValueError – if the member is not byte-aligned (e.g., because it is a bit field)
LookupError – if type does not have a member with the given name
- Return type
Type Constructors¶
Custom drgn types can be created with the following factory functions. These
can be used just like types obtained from Program.type()
.
-
Program.
void_type
(*, qualifiers=Qualifiers.NONE, language=None)¶ Create a new void type. It has kind
TypeKind.VOID
.- Parameters
qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
int_type
(name, size, is_signed, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new integer type. It has kind
TypeKind.INT
.- Parameters
size (
IntegerLike
) –Type.size
is_signed (
bool
) –Type.is_signed
byteorder (
Optional
[str
]) –Type.byteorder
, orNone
to use the program’s default byte order.qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
bool_type
(name, size, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new boolean type. It has kind
TypeKind.BOOL
.- Parameters
size (
IntegerLike
) –Type.size
byteorder (
Optional
[str
]) –Type.byteorder
, orNone
to use the program’s default byte order.qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
float_type
(name, size, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new floating-point type. It has kind
TypeKind.FLOAT
.- Parameters
size (
IntegerLike
) –Type.size
byteorder (
Optional
[str
]) –Type.byteorder
, orNone
to use the program’s default byte order.qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
struct_type
(tag, size, members, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)¶ Create a new structure type. It has kind
TypeKind.STRUCT
.- Parameters
size (
IntegerLike
) –Type.size
members (
Sequence
[TypeMember
]) –Type.members
template_parameters (
Sequence
[TypeTemplateParameter
]) –Type.template_parameters
qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
struct_type
(tag, size=None, members=None, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None) Create a new incomplete structure type.
- Return type
-
Program.
union_type
(tag, size, members, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)¶ Create a new union type. It has kind
TypeKind.UNION
. Otherwise, this is the same as asstruct_type()
.- Return type
-
Program.
union_type
(tag, size=None, members=None, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None) Create a new incomplete union type.
- Return type
-
Program.
class_type
(tag, size, members, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)¶ Create a new class type. It has kind
TypeKind.CLASS
. Otherwise, this is the same as asstruct_type()
.- Return type
-
Program.
class_type
(tag, size=None, members=None, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None) Create a new incomplete class type.
- Return type
-
Program.
enum_type
(tag, type, enumerators, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new enumerated type. It has kind
TypeKind.ENUM
.- Parameters
enumerators (
Sequence
[TypeEnumerator
]) –Type.enumerators
qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
enum_type
(tag, type=None, enumerators=None, *, qualifiers=Qualifiers.NONE, language=None) Create a new incomplete enumerated type.
- Return type
-
Program.
typedef_type
(name, type, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new typedef type. It has kind
TypeKind.TYPEDEF
.- Parameters
qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
pointer_type
(type, size=None, byteorder=None, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new pointer type. It has kind
TypeKind.POINTER
,- Parameters
size (
Optional
[int
]) –Type.size
, orNone
to use the program’s default pointer size.byteorder (
Optional
[str
]) –Type.byteorder
, orNone
to use the program’s default byte order.qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
array_type
(type, length=None, *, qualifiers=Qualifiers.NONE, language=None)¶ Create a new array type. It has kind
TypeKind.ARRAY
.- Parameters
length (
Optional
[int
]) –Type.length
qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
-
Program.
function_type
(type, parameters, is_variadic=False, *, template_parameters=(), qualifiers=Qualifiers.NONE, language=None)¶ Create a new function type. It has kind
TypeKind.FUNCTION
.- Parameters
parameters (
Sequence
[TypeParameter
]) –Type.parameters
is_variadic (
bool
) –Type.is_variadic
template_parameters (
Sequence
[TypeTemplateParameter
]) –Type.template_parameters
qualifiers (
Qualifiers
) –Type.qualifiers
lang –
Type.language
- Return type
Miscellaneous¶
-
drgn.
sizeof
(type_or_obj)¶
-
drgn.
execscript
(path, *args)¶ Execute a script.
The script is executed in the same context as the caller: currently defined globals are available to the script, and globals defined by the script are added back to the calling context.
This is most useful for executing scripts from interactive mode. For example, you could have a script named
exe.py
:"""Get all tasks executing a given file.""" import sys from drgn.helpers.linux.fs import d_path from drgn.helpers.linux.pid import find_task def task_exe_path(task): if task.mm: return d_path(task.mm.exe_file.f_path).decode() else: return None tasks = [ task for task in for_each_task(prog) if task_exe_path(task) == sys.argv[1] ]
Then, you could execute it and use the defined variables and functions:
>>> execscript('exe.py', '/usr/bin/bash') >>> tasks[0].pid (pid_t)358442 >>> task_exe_path(find_task(prog, 357954)) '/usr/bin/vim'
- Parameters
path (
str
) – File path of the script.args (
str
) – Zero or more additional arguments to pass to the script. This is a variable argument list.
- Return type
-
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 anObject
with integer type.
-
drgn.
Path
¶ Filesystem path.
Parameters annotated with this type accept a filesystem path as
str
,bytes
, oros.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
(address) - Parameters
address (
int
) –FaultError.address
-
-
class
drgn.
MissingDebugInfoError
¶ Bases:
Exception
This error is raised when one or more files in a program do not have debug information.