mirror of
https://github.com/JakeHillion/drgn.git
synced 2024-12-26 18:45:37 +00:00
393a1f3149
drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
893 lines
28 KiB
ReStructuredText
893 lines
28 KiB
ReStructuredText
API Reference
|
|
=============
|
|
|
|
.. module:: drgn
|
|
|
|
Programs
|
|
--------
|
|
|
|
.. class:: 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
|
|
:meth:`[] <__getitem__>` operator.
|
|
|
|
This class cannot be constructed directly. Instead, use one of the
|
|
:ref:`api-program-constructors`.
|
|
|
|
.. attribute:: flags
|
|
|
|
Flags which apply to this program.
|
|
|
|
:vartype: ProgramFlags
|
|
|
|
.. attribute:: word_size
|
|
|
|
Size of a word in this program in bytes.
|
|
|
|
:vartype: int
|
|
|
|
.. attribute:: byteorder
|
|
|
|
Byte order (a.k.a. endianness) in this program (either ``'little'``
|
|
or ``'big'``).
|
|
|
|
:vartype: str
|
|
|
|
.. attribute:: __getitem__(name)
|
|
|
|
Implement ``self[name]``. Get the object (variable, constant, or
|
|
function) with the given name.
|
|
|
|
If there are multiple objects with the same name, one is returned
|
|
arbitrarily. In this case, the :meth:`variable()`, :meth:`constant()`,
|
|
or :meth:`function()` methods can be used instead.
|
|
|
|
>>> prog['jiffies']
|
|
Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
|
|
|
|
:param str name: The object name.
|
|
:rtype: Object
|
|
|
|
.. attribute:: variable(name, filename=None)
|
|
|
|
Get the variable with the given name.
|
|
|
|
>>> prog.variable('jiffies')
|
|
Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
|
|
|
|
:param str name: The variable name.
|
|
:param filename: The source code file that contains the definition. See
|
|
:ref:`api-filenames`.
|
|
:type filename: str or None
|
|
:rtype: Object
|
|
:raises LookupError: if no variables with the given name are found in
|
|
the given file
|
|
|
|
.. attribute:: 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)
|
|
|
|
:param str name: The constant name.
|
|
:param filename: The source code file that contains the definition. See
|
|
:ref:`api-filenames`.
|
|
:type filename: str or None
|
|
:rtype: Object
|
|
:raises LookupError: if no constants with the given name are found in
|
|
the given file
|
|
|
|
.. attribute:: function(name, filename=None)
|
|
|
|
Get the function with the given name.
|
|
|
|
>>> prog.function('schedule')
|
|
Object(prog, 'void (void)', address=0xffffffff94392370)
|
|
|
|
:param str name: The function name.
|
|
:param filename: The source code file that contains the definition. See
|
|
:ref:`api-filenames`.
|
|
:type filename: str or None
|
|
:rtype: Object
|
|
:raises LookupError: if no functions with the given name are found in
|
|
the given file
|
|
|
|
.. attribute:: type(name, filename=None)
|
|
|
|
Get the type with the given name.
|
|
|
|
>>> prog.type('long')
|
|
int_type(name='long', size=8, is_signed=True)
|
|
|
|
:param str name: The type name.
|
|
:param filename: The source code file that contains the definition. See
|
|
:ref:`api-filenames`.
|
|
:type filename: str or None
|
|
:rtype: Type
|
|
:raises LookupError: if no types with the given name are found in
|
|
the given file
|
|
|
|
.. attribute:: 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\x00\x00\x00\x00\x00\x00\x00'
|
|
|
|
:param int address: The starting address.
|
|
:param int size: The number of bytes to read.
|
|
:param bool 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.
|
|
:rtype: bytes
|
|
:raises FaultError: if the address range is invalid or the type of
|
|
address (physical or virtual) is not supported by the program
|
|
:raises ValueError: if *size* is negative
|
|
|
|
.. class:: ProgramFlags
|
|
|
|
``ProgramFlags`` is an :class:`enum.IntFlag` of flags that can apply to a
|
|
:class:`Program` (e.g., about what kind of program it is).
|
|
|
|
.. attribute:: IS_LINUX_KERNEL
|
|
|
|
The program is the Linux kernel.
|
|
|
|
.. _api-filenames:
|
|
|
|
Filenames
|
|
^^^^^^^^^
|
|
|
|
The :meth:`Program.type()`, :meth:`Program.variable()`,
|
|
:meth:`Program.constant()`, and :meth:`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.
|
|
``None`` matches any definition. Otherwise, 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 multiple definitions match, one is returned
|
|
arbitrarily.
|
|
|
|
.. _api-program-constructors:
|
|
|
|
Program Constructors
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The drgn command line interface automatically creates a :class:`Program` named
|
|
``prog``. However, drgn may also be used as a library without the CLI, in which
|
|
case a ``Program`` must be created manually.
|
|
|
|
.. function:: program_from_core_dump(path, verbose=False)
|
|
|
|
Create a :class:`Program` from a core dump file. The type of program (e.g.,
|
|
userspace or kernel) is determined automatically.
|
|
|
|
:param str path: Core dump file path.
|
|
:param bool verbose: Whether to print non-fatal errors to stderr (e.g.,
|
|
about not being able to find debugging symbols).
|
|
:rtype: Program
|
|
|
|
.. function:: program_from_kernel(verbose=False)
|
|
|
|
Create a :class:`Program` from the running operating system kernel. This
|
|
requires root privileges.
|
|
|
|
:param bool verbose: Whether to print non-fatal errors to stderr (e.g.,
|
|
about not being able to find kernel modules or debugging symbols).
|
|
:rtype: Program
|
|
|
|
.. function:: program_from_pid(pid)
|
|
|
|
Create a :class:`Program` from a running program with the given PID. This
|
|
requires appropriate permissions (on Linux, :manpage:`ptrace(2)` attach
|
|
permissions).
|
|
|
|
:param int pid: Process ID of the program to debug.
|
|
:rtype: Program
|
|
|
|
Objects
|
|
-------
|
|
|
|
.. class:: Object(prog, type=None, *, address=None, value=None, byteorder=None, bit_offset=None, bit_field_size=None)
|
|
|
|
An ``Object`` represents a symbol or value in a program. An object may
|
|
exist in the memory of the program (a *reference*), or it may be a
|
|
temporary computed value (a *value*).
|
|
|
|
All instances of this class have two attributes: :attr:`prog_`, the program
|
|
that the object is from; and :attr:`type_`, the type of the object.
|
|
Reference objects also have an :attr:`address_` attribute. Objects may also
|
|
have a :attr:`byteorder_`, :attr:`bit_offset_`, and
|
|
:attr:`bit_field_size_`.
|
|
|
|
:func:`repr()` of an object returns a Python representation of the object:
|
|
|
|
>>> print(repr(prog['jiffies']))
|
|
Object(prog, 'volatile long unsigned int', address=0xffffffffbf005000)
|
|
|
|
:class:`str() <str>` returns a representation of the object in programming
|
|
language syntax:
|
|
|
|
>>> print(prog['jiffies'])
|
|
(volatile long unsigned int)4326237045
|
|
|
|
Note that the drgn CLI is set up so that objects are displayed with
|
|
``str()`` instead of ``repr()`` (the latter is the default behavior of
|
|
Python's interactive mode). This means that in the drgn CLI, the call to
|
|
``print()`` in the second example above is not necessary.
|
|
|
|
Objects support the following operators:
|
|
|
|
* Arithmetic operators: ``+``, ``-``, ``*``, ``/``, ``%``
|
|
* Bitwise operators: ``<<``, ``>>``, ``&``, ``|``, ``^``, ``~``
|
|
* Relational operators: ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``
|
|
* Subscripting: :meth:`[] <__getitem__>` (Python does not have a unary
|
|
``*`` operator, so pointers are dereferenced with ``ptr[0]``)
|
|
* Member access: :meth:`. <__getattribute__>` (Python does not have a
|
|
``->`` operator, so ``.`` is also used to access members of pointers to
|
|
structures)
|
|
* The address-of operator: :meth:`drgn.Object.address_of_()` (this is a
|
|
method because Python does not have a ``&`` operator)
|
|
* Array length: :meth:`len() <__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', value=2**64 - 1) + Object(prog, 'int', value=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', value=0) - 1
|
|
Object(prog, 'int', value=-1)
|
|
|
|
The standard :class:`int() <int>`, :class:`float() <float>`, and
|
|
:class:`bool() <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., :func:`hex()`,
|
|
:func:`round()`, and :meth:`list subscripting <object.__getitem__>`).
|
|
|
|
Object attributes and methods are named with a trailing underscore to avoid
|
|
conflicting with structure or union members. The attributes and methods
|
|
always take precedence; use :meth:`member_()` if there is a conflict.
|
|
|
|
Objects are usually obtained directly from a :class:`Program`, but they can
|
|
be constructed manually, as well (for example, if you got a variable
|
|
address from a log file).
|
|
|
|
:param Program prog: The program to create this object in.
|
|
:param type: The type of the object. If omitted, this is deduced from
|
|
*value* according to the language's rules for literals.
|
|
:type type: str or Type
|
|
:param int address: The address of this object in the program. Either this
|
|
or *value* must be given, but not both.
|
|
:param value: The value of this object. See :meth:`value_()`.
|
|
:param byteorder: Byte order of the object. This should be ``'little'`` or
|
|
``'big'``. The default is ``None``, which indicates the program byte
|
|
order. This must be ``None`` for primitive values.
|
|
:type byteorder: str or None
|
|
:param bit_offset: Offset in bits from the object's address to the
|
|
beginning of the object. The default is ``None``, which means no
|
|
offset. This must be ``None`` for primitive values.
|
|
:type bit_offset: int or None
|
|
:param bit_field_size: Size in bits of this object if it is a bit field.
|
|
The default is ``None``, which means the object is not a bit field.
|
|
:type bit_field_size: int or None
|
|
|
|
.. attribute:: prog_
|
|
|
|
Program that this object is from.
|
|
|
|
:vartype: Program
|
|
|
|
.. attribute:: type_
|
|
|
|
Type of this object.
|
|
|
|
:vartype: Type
|
|
|
|
.. attribute:: address_
|
|
|
|
Address of this object if it is a reference, ``None`` if it is a value.
|
|
|
|
:vartype: int or None
|
|
|
|
.. attribute:: byteorder_
|
|
|
|
Byte order of this object (either ``'little'`` or ``'big'``) if it is a
|
|
reference or a non-primitive value, ``None`` otherwise.
|
|
|
|
:vartype: str or None
|
|
|
|
.. attribute:: bit_offset_
|
|
|
|
Offset in bits from this object's address to the beginning of the
|
|
object if it is a reference or a non-primitive value, ``None``
|
|
otherwise.
|
|
|
|
:vartype: int or None
|
|
|
|
.. attribute:: bit_field_size_
|
|
|
|
Size in bits of this object if it is a bit field, ``None`` if it is
|
|
not.
|
|
|
|
:vartype: int or None
|
|
|
|
.. method:: __getattribute__(name)
|
|
|
|
Implement ``self.name``.
|
|
|
|
If *name* is an attribute of the :class:`Object` class, then this
|
|
returns that attribute. Otherwise, it is equivalent to
|
|
:meth:`member_()`.
|
|
|
|
>>> print(prog['init_task'].pid)
|
|
(pid_t)0
|
|
|
|
:param str name: Attribute name.
|
|
|
|
.. method:: __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.
|
|
|
|
:param int idx: The array index.
|
|
:rtype: Object
|
|
:raises TypeError: if this object is not a pointer or array
|
|
|
|
.. method:: __len__()
|
|
|
|
Implement ``len(self)``. Get the number of elements in this object.
|
|
|
|
>>> len(prog['init_task'].comm)
|
|
16
|
|
|
|
This is only valid for arrays.
|
|
|
|
:rtype: int
|
|
:raises TypeError: if this object is not an array with complete type
|
|
|
|
.. method:: value_()
|
|
|
|
Get the value of this object as a Python object.
|
|
|
|
For basic types (integer, floating-point, boolean), this returns an
|
|
object of the directly corresponding Python type (``int``, ``float``,
|
|
``bool``). For pointers, this returns the address value of the pointer.
|
|
For enums, this returns an ``int``. For structures and unions, this
|
|
returns a ``dict`` of members. For arrays, this returns a ``list`` of
|
|
values.
|
|
|
|
:raises FaultError: if reading the object causes a bad memory access
|
|
:raises TypeError: if this object has an unreadable type (e.g.,
|
|
``void``)
|
|
|
|
.. method:: 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.
|
|
|
|
:rtype: bytes
|
|
:raises FaultError: if reading the string causes a bad memory access
|
|
:raises TypeError: if this object is not a pointer or array
|
|
|
|
.. method:: 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.
|
|
|
|
:param str name: Name of the member.
|
|
:rtype: Object
|
|
:raises TypeError: if this object is not a structure, union, or a
|
|
pointer to either
|
|
:raises LookupError: if this object does not have a member with the
|
|
given name
|
|
|
|
.. method:: 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 :attr:`address_`, this returns an ``Object``, not an
|
|
``int``.
|
|
|
|
:rtype: Object
|
|
:raises ValueError: if this object is a value
|
|
|
|
.. method:: 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 :meth:`value_()`, this returns an ``Object``, not a
|
|
standard Python type.
|
|
|
|
:rtype: Object
|
|
:raises FaultError: if reading this object causes a bad memory access
|
|
:raises TypeError: if this object has an unreadable type (e.g.,
|
|
``void``)
|
|
|
|
.. function:: NULL(prog, type)
|
|
|
|
Get an object representing ``NULL`` casted to the given type.
|
|
|
|
This is equivalent to ``Object(prog, type, value=0)``.
|
|
|
|
:param Program prog: The program.
|
|
:param type: The type.
|
|
:type type: str or Type
|
|
:rtype: Object
|
|
|
|
.. function:: 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 :func:`drgn.reinterpret()`.
|
|
|
|
:param type: The type to cast to.
|
|
:type type: str or Type
|
|
:param Object obj: The object to cast.
|
|
:rtype: Object
|
|
|
|
.. function:: reinterpret(type, obj, byteorder=None)
|
|
|
|
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 :func:`drgn.cast()`.
|
|
|
|
:param type: The type to reinterpret as.
|
|
:type type: str or Type
|
|
:param Object obj: The object to reinterpret.
|
|
:param byteorder: The byte order to reinterpret as. This should be
|
|
``'little'`` or ``'big'``. The default is ``None``, which indicates the
|
|
program byte order.
|
|
:type byteorder: str or None
|
|
:rtype: Object
|
|
|
|
.. function:: container_of(ptr, type, member)
|
|
|
|
Get the containing object of a pointer object.
|
|
|
|
This corresponds to the ``container_of()`` macro in C.
|
|
|
|
:param Object ptr: The pointer.
|
|
:param type: The type of the containing object.
|
|
:type type: str or Type
|
|
:param str member: The name of the member in ``type``.
|
|
:raises TypeError: if the object is not a pointer or the type is not a
|
|
structure or union type
|
|
:raises LookupError: If the type does not have a member with the given name
|
|
|
|
.. _api-reference-types:
|
|
|
|
Types
|
|
-----
|
|
|
|
.. class:: 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 :exc:`AttributeError`.
|
|
|
|
:func:`repr()` of a Type 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))
|
|
|
|
:class:`str() <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
|
|
:ref:`api-type-constructors`.
|
|
|
|
.. attribute:: kind
|
|
|
|
Kind of this type.
|
|
|
|
:vartype: TypeKind
|
|
|
|
.. attribute:: qualifiers
|
|
|
|
Bitmask of this type's qualifier.
|
|
|
|
:vartype: Qualifiers
|
|
|
|
.. attribute:: name
|
|
|
|
Name of this type. This is present for integer, boolean,
|
|
floating-point, complex, and typedef types.
|
|
|
|
:vartype: str
|
|
|
|
.. attribute:: tag
|
|
|
|
Tag of this type, or ``None`` if this is an anonymous type. This is
|
|
present for structure, union, and enumerated types.
|
|
|
|
:vartype: str or None
|
|
|
|
.. attribute:: size
|
|
|
|
Size of this type in bytes, or ``None`` if this is an incomplete type.
|
|
This is present for integer, boolean, floating-point, complex,
|
|
structure, union, and pointer types.
|
|
|
|
:vartype: int or None
|
|
|
|
.. attribute:: length
|
|
|
|
Number of elements in this type, or ``None`` if this is an incomplete
|
|
type. This is only present for array types.
|
|
|
|
:vartype: int or None
|
|
|
|
.. attribute:: is_signed
|
|
|
|
Whether this type is signed. This is only present for integer types.
|
|
|
|
:vartype: bool
|
|
|
|
.. attribute:: type
|
|
|
|
Type underlying this type, defined as follows:
|
|
|
|
* For complex types, the corresponding the real type.
|
|
* For typedef types, the aliased type.
|
|
* For enumerated types, the compatible integer type, which is ``None``
|
|
if this is an incomplete type.
|
|
* For pointer types, the referenced type.
|
|
* For array types, the element type.
|
|
* For function types, the return type.
|
|
|
|
For other types, this attribute is not present.
|
|
|
|
:vartype: Type
|
|
|
|
.. attribute:: members
|
|
|
|
List of members of this type, or ``None`` if this is an incomplete
|
|
type. This is present for structure and union types.
|
|
|
|
Each member is a (type, name, bit offset, bit field size) tuple. The
|
|
name is ``None`` if the member is unnamed; the bit field size is zero
|
|
if the member is not a bit field.
|
|
|
|
:vartype: list[tuple(Type, str or None, int, int)]
|
|
|
|
.. attribute:: enumerators
|
|
|
|
List of enumeration constants of this type, or ``None`` if this is an
|
|
incomplete type. This is only present for enumerated types.
|
|
|
|
Each enumeration constant is a (name, value) tuple.
|
|
|
|
:vartype: list[tuple(str, int)] or None
|
|
|
|
.. attribute:: parameters
|
|
|
|
List of parameters of this type. This is only present for function
|
|
types.
|
|
|
|
Each parameter is a (type, name) tuple. The name is ``None`` if the
|
|
parameter is unnamed.
|
|
|
|
:vartype: list[tuple(Type, str or None)]
|
|
|
|
.. attribute:: is_variadic
|
|
|
|
Whether this type takes a variable number of arguments. This is only
|
|
present for function types.
|
|
|
|
:vartype: bool
|
|
|
|
.. method:: type_name()
|
|
|
|
Get a descriptive full name of this type.
|
|
|
|
:rtype: str
|
|
|
|
.. method:: is_complete()
|
|
|
|
Get whether this type is complete (i.e., the type definition is known).
|
|
This is always ``False`` for void types. It may be ``False`` for
|
|
structure, union, enumerated, and array types, as well as typedef types
|
|
where the underlying type is one of those. Otherwise, it is always
|
|
``True``.
|
|
|
|
:rtype: bool
|
|
|
|
.. method:: qualified(qualifiers)
|
|
|
|
Get a copy of this type with different qualifiers.
|
|
|
|
Note that the original qualifiers are replaced, not added to.
|
|
|
|
:param qualifiers: New type qualifiers.
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. method:: unqualified()
|
|
|
|
Get a copy of this type with no qualifiers.
|
|
|
|
:rtype: Type
|
|
|
|
.. class:: TypeKind
|
|
|
|
``TypeKind`` is an :class:`enum.Enum` of the different kinds of types.
|
|
|
|
.. attribute:: VOID
|
|
|
|
Void type.
|
|
|
|
.. attribute:: INT
|
|
|
|
Integer type.
|
|
|
|
.. attribute:: BOOL
|
|
|
|
Boolean type.
|
|
|
|
.. attribute:: FLOAT
|
|
|
|
Floating-point type.
|
|
|
|
.. attribute:: COMPLEX
|
|
|
|
Complex type.
|
|
|
|
.. attribute:: STRUCT
|
|
|
|
Structure type.
|
|
|
|
.. attribute:: UNION
|
|
|
|
Union type.
|
|
|
|
.. attribute:: ENUM
|
|
|
|
Enumerated type.
|
|
|
|
.. attribute:: TYPEDEF
|
|
|
|
Type definition (a.k.a. alias) type.
|
|
|
|
.. attribute:: POINTER
|
|
|
|
Pointer type.
|
|
|
|
.. attribute:: ARRAY
|
|
|
|
Array type.
|
|
|
|
.. attribute:: FUNCTION
|
|
|
|
Function type.
|
|
|
|
.. class:: Qualifiers
|
|
|
|
``Qualifiers`` is an :class:`enum.IntFlag` of type qualifiers.
|
|
|
|
.. attribute:: CONST
|
|
|
|
Constant type.
|
|
|
|
.. attribute:: VOLATILE
|
|
|
|
Volatile type.
|
|
|
|
.. attribute:: RESTRICT
|
|
|
|
`Restrict <https://en.cppreference.com/w/c/language/restrict>`_ type.
|
|
|
|
.. attribute:: ATOMIC
|
|
|
|
Atomic type.
|
|
|
|
.. _api-type-constructors:
|
|
|
|
Type Constructors
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Custom drgn types can be created with the following factory functions. These
|
|
can be used just like types obtained from :meth:`Program.type()`.
|
|
|
|
.. function:: void_type(qualifiers=None)
|
|
|
|
Create a new void type. It has kind :attr:`TypeKind.VOID`.
|
|
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: int_type(name, size, is_signed, qualifiers=None)
|
|
|
|
Create a new integer type. It has kind :attr:`TypeKind.INT`.
|
|
|
|
:param str name: :attr:`Type.name`
|
|
:param int size: :attr:`Type.size`
|
|
:param bool is_signed: :attr:`Type.is_signed`
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: bool_type(name, size, qualifiers=None)
|
|
|
|
Create a new boolean type. It has kind :attr:`TypeKind.BOOL`.
|
|
|
|
:param str name: :attr:`Type.name`
|
|
:param int size: :attr:`Type.size`
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: float_type(name, size, qualifiers=None)
|
|
|
|
Create a new floating-point type. It has kind :attr:`TypeKind.FLOAT`.
|
|
|
|
:param str name: :attr:`Type.name`
|
|
:param int size: :attr:`Type.size`
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: complex_type(name, size, type, qualifiers=None)
|
|
|
|
Create a new complex type. It has kind :attr:`TypeKind.COMPLEX`.
|
|
|
|
:param str name: :attr:`Type.name`
|
|
:param int size: :attr:`Type.size`
|
|
:param Type type: The corresponding real type (:attr:`Type.type`)
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: struct_type(tag, size, members, qualifiers=None)
|
|
|
|
Create a new structure type. It has kind :attr:`TypeKind.STRUCT`.
|
|
|
|
:param tag: :attr:`Type.tag`
|
|
:type tag: str or None
|
|
:param int size: :attr:`Type.size`
|
|
:param list[tuple] members: :attr:`Type.members`. The type of a member may
|
|
be given as a callable returning a ``Type``; it will be called the
|
|
first time that the member is accessed. The name, bit offset, and bit
|
|
field size may be omitted; they default to ``None``, 0, and 0,
|
|
respectively.
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: union_type(tag, size, members, qualifiers=None)
|
|
|
|
Create a new union type. It has kind :attr:`TypeKind.UNION`. Otherwise,
|
|
this is the same as :func:`struct_type()`.
|
|
|
|
.. function:: enum_type(tag, type, enumerators, qualifiers=None)
|
|
|
|
Create a new enumerated type. It has kind :attr:`TypeKind.ENUM`.
|
|
|
|
:param tag: :attr:`Type.tag`
|
|
:type tag: str or None
|
|
:param type: The compatible integer type (:attr:`Type.type`)
|
|
:type param Type or None:
|
|
:param enumerators: :attr:`Type.enumerators`
|
|
:type enumerators: list[tuple] or None
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: typedef_type(name, type, qualifiers=None)
|
|
|
|
Create a new typedef type. It has kind :attr:`TypeKind.TYPEDEF`.
|
|
|
|
:param str name: :attr:`Type.name`
|
|
:param Type type: The aliased type (:attr:`Type.type`)
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: pointer_type(size, type, qualifiers=None)
|
|
|
|
Create a new pointer type. It has kind :attr:`TypeKind.POINTER`,
|
|
|
|
:param int size: :attr:`Type.size`
|
|
:param Type type: The referenced type (:attr:`Type.type`)
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: array_type(length, type, qualifiers=None)
|
|
|
|
Create a new array type. It has kind :attr:`TypeKind.ARRAY`.
|
|
|
|
:param length: :attr:`Type.length`
|
|
:type length: int or None
|
|
:param Type type: The element type (:attr:`Type.type`)
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
.. function:: function_type(type, parameters, is_variadic=False, qualifiers=None)
|
|
|
|
Create a new function type. It has kind :attr:`TypeKind.FUNCTION`.
|
|
|
|
:param Type type: The return type (:attr:`Type.type`)
|
|
:param list[tuple] parameters: :attr:`Type.parameters`. The type of a
|
|
parameter may be given as a callable returning a ``Type``; it will be
|
|
called the first time that the parameter is accessed. The name may be
|
|
omitted and defaults to ``None``.
|
|
:param bool is_variadic: :attr:`Type.is_variadic`
|
|
:param qualifiers: :attr:`Type.qualifiers`
|
|
:type qualifiers: Qualifiers or None
|
|
:rtype: Type
|
|
|
|
Exceptions
|
|
----------
|
|
|
|
.. exception:: FaultError
|
|
|
|
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, or when
|
|
accessing out of bounds of a value object).
|
|
|
|
.. exception:: FileFormatError
|
|
|
|
This is error raised when a file cannot be parsed according to its expected
|
|
format (e.g., ELF or DWARF).
|