Python¶

Bases: DebugInfo

This class represents a DWARF debug information. It can embed different compilation units which can be accessed through compilation_units.

This class can be instantiated from lief.Binary.debug_info

property compilation_units → Iterator[lief.dwarf.CompilationUnit | None]¶

Iterator on the CompilationUnit embedded in this dwarf

find_function(*args) → lief.dwarf.Function | None¶

Overloaded function.

1. find_function(self, name: str) -> Optional[lief._lief.dwarf.Function]

   Try to find the function with the given name (mangled or not)

   info: lief.dwarf.DebugInfo = ...
   if func := info.find_function("_ZNSt6localeD1Ev"):
       print("Found")
   if func := info.find_function("std::locale::~locale()"):
       print("Found")
   

2. find_function(self, addr: int) -> Optional[lief._lief.dwarf.Function]

   Try to find the function at the given virtual address.

find_type(self, name: str) → lief.dwarf.Type | None¶

Try to find the type with the given name.

find_variable(*args) → lief.dwarf.Variable | None¶

Overloaded function.

1. find_variable(self, addr: int) -> Optional[lief._lief.dwarf.Variable]

   Try to find the (static) variable at the given virtual address.

2. find_variable(self, name: str) -> Optional[lief._lief.dwarf.Variable]

   Try to find the variable with the given name. This name can be mangled or not.

Bases: object

This class represents a DWARF compilation unit

class Language¶

Bases: object

Languages supported by the DWARF (v5) format. See: https://dwarfstd.org/languages.html

Some languages (like C++11, C++17, ..) have a version (11, 17, …) which is stored in a dedicated attribute: version

class LANG(value)¶

Bases: Enum

C = 1¶

COBOL = 10¶

CPP = 2¶

D = 8¶

DART = 4¶

FORTRAN = 6¶

JAVA = 9¶

MODULA = 5¶

RUST = 3¶

SWIFT = 7¶

UNKNOWN = 0¶

from_value(arg: int) → lief.dwarf.CompilationUnit.Language.LANG = <nanobind.nb_func object>¶

property lang → lief.dwarf.CompilationUnit.Language.LANG¶

The language itself

property version → int¶

Version of the language (e.g. 17 for C++17)

property compilation_dir → str¶

Return the path to the directory in which the compilation took place for compiling this compilation unit (e.g. /workdir/build)

It returns an empty string if the entry is not present or can’t be resolved.

This value matches the DW_AT_comp_dir attribute.

find_function(*args) → lief.dwarf.Function | None¶

Overloaded function.

1. find_function(self, name: str) -> Optional[lief._lief.dwarf.Function]

   Try to find the function whose name is given in parameter.

   The provided name can be demangled.

2. find_function(self, addr: int) -> Optional[lief._lief.dwarf.Function]

   Try to find the function at the given address

find_variable(*args) → lief.dwarf.Variable | None¶

Overloaded function.

1. find_variable(self, addr: int) -> Optional[lief._lief.dwarf.Variable]

   Try to find the variable at the given address

2. find_variable(self, name: str) -> Optional[lief._lief.dwarf.Variable]

   Try to find the variable with the given name (mangled or not)

property functions → Iterator[lief.dwarf.Function | None]¶

Return an iterator over the functions implemented in this compilation unit.

Note that this iterator only iterates over the functions that have a concrete implementation in the compilation unit.

For instance with this code:

inline const char* get_secret_env() {
  return getenv("MY_SECRET_ENV");
}

int main() {
  printf("%s", get_secret_env());
  return 0;
}

The iterator will only return one function for main since get_secret_env is inlined and thus, its implementation is located in main.

property high_address → int¶

Return the highest virtual address owned by this compilation unit

property imported_functions → Iterator[lief.dwarf.Function | None]¶

Return an iterator over the functions imported in this compilation unit but not implemented.

For instance with this code:

#include <cstdio>
int main() {
  printf("Hello\n");
  return 0;
}

printf is imported from the standard libc so the function is returned by the iterator. On the other hand, main() is implemented in this compilation unit so it is not returned by imported_function but functions.

property language → lief.dwarf.CompilationUnit.Language¶

Original language of this compilation unit.

This value matches the DW_AT_language attribute.

property low_address → int¶

Return the lowest virtual address owned by this compilation unit.

property name → str¶

Name of the file associated with this compilation unit (e.g. test.cpp) Return an empty string if the name is not found or can’t be resolved

This value matches the DW_AT_name attribute.

property producer → str¶

Information about the program (or library) that generated this compilation unit. For instance, it can output: Debian clang version 17.0.6.

It returns an empty string if the producer is not present or can’t be resolved.

This value matches the DW_AT_producer attribute.

property ranges → list[lief.range_t]¶

Return a list of address ranges owned by this compilation unit.

If the compilation unit owns a contiguous range, it returns a single range.

property size → int¶

Return the size of the compilation unit according to its range of address.

If the compilation is fragmented (i.e. there are some address ranges between the lowest address and the highest that are not owned by the CU), then it returns the sum of all the address ranges owned by this CU.

If the compilation unit is not fragmented, then it basically returns high_address - low_address.

property types → Iterator[lief.dwarf.Type | None]¶

Return an iterator over the different types defined in this compilation unit.

property variables → Iterator[lief.dwarf.Variable | None]¶

Return an iterator over the variables defined in the any scope of this compilation unit:

static int A = 1; // Returned by the iterator
static const char* B = "Hello"; // Returned by the iterator

int get() {
  static int C = 2; // Returned by the iterator
  return C;
}

Bases: object

This class represents a DWARF function which can be associated with either: DW_TAG_subprogram or DW_TAG_inlined_subroutine.

property address → int | None¶

Return the address of the function (DW_AT_entry_pc or DW_AT_low_pc) or None if it’s not available.

property debug_location → lief.debug_location_t¶

Original source code location.

property instructions → Iterator[lief.assembly.Instruction | None]¶

Disassemble the current function by returning an iterator over the lief.assembly.Instruction.

property is_artificial → bool¶

Whether this function is created by the compiler and not present in the original source code.

property is_external → bool¶

Whether the function is defined outside the current compilation unit (DW_AT_external).

property linkage_name → str¶

The name of the function which is used for linking (DW_AT_linkage_name).

This name differs from name as it is usually mangled. The function return an empty string if the linkage name is not available.

property name → str¶

The name of the function (DW_AT_name)

property parameters → list[lief.dwarf.Parameter | None]¶

Return the list of parameters used by this function (including template parameters)

property ranges → list[lief.range_t]¶

Ranges of virtual addresses owned by this function.

property scope → lief.dwarf.Scope | None¶

Scope in which this function is defined

property size → int¶

Return the size taken by this function in the binary.

property thrown_types → list[lief.dwarf.Type | None]¶

List of exceptions (types) that can be thrown by the function. For instance, given this Swift code:

func summarize(_ ratings: [Int]) throws(StatisticsError) {
  // ...
}

thrown_types returns one element associated with the Type: StatisticsError.

property type → lief.dwarf.Type | None¶

Return the Type associated with the return type of this function

property variables → Iterator[lief.dwarf.Variable | None]¶

Return an iterator over the variables (DW_TAG_variable) defined within the scope of this function. This includes regular stack-based variables as well as static ones.

Bases: object

This class represents a DWARF parameter which can be either: - A regular function parameter (see: parameters.Formal) - A template type parameter (see: parameters.TemplateType) - A template value parameter (see: parameters.TemplateValue)

property name → str¶

Name of the parameter

property type → lief.dwarf.Type | None¶

Type of this parameter

Bases: Parameter

This class represents a regular function parameter.

For instance, given this prototype:

int main(int argc, const char** argv);

The function main has two Formal parameters:

1. argc (lief.dwarf.Parameter.name) typed as int

   (Base from lief.dwarf.Parameter.type)

2. argv (lief.dwarf.Parameter.name) typed as const char**

   (Const)

property type → lief.dwarf.Type | None¶

Bases: Parameter

This class represents a template value parameter.

For instance, given this prototype:

template<int X = 5>
void generic();

The function generic has one TemplateValue parameter: X

Bases: Parameter

This class represents a template type parameter.

For instance, given this prototype:

template<class Y>
void generic();

The function generic has one TemplateType parameter: Y

Bases: object

This class materializes a scope in which Function, Variable, Type, … can be defined.

class TYPE(value)¶

Bases: Enum

CLASS = 2¶

COMPILATION_UNIT = 6¶

FUNCTION = 5¶

NAMESPACE = 4¶

STRUCT = 3¶

UNION = 1¶

UNKNOWN = 0¶

chained(self, sep: str) → str¶

Represent the whole chain of all (parent) scopes using the provided separator. E.g. ns1::ns2::Class1::Struct2::Type.

property name → str¶

Name of the scope. For instance namespace’s name or function’s name.

property parent → lief.dwarf.Scope | None¶

Parent scope (if any).

property type → lief.dwarf.Scope.TYPE¶

The current scope type.

Bases: object

This class represents a DWARF variable which can be owned by a Function or a CompilationUnit.

property address → int | None¶

Address of the variable.

If the variable is static, it returns the virtual address where it is defined. If the variable is stack-based, it returns the relative offset from the frame-base register.

If the address can’t be resolved, it returns None.

property debug_location → lief.debug_location_t¶

The original source location where the variable is defined.

property is_constexpr → bool¶

Whether it’s a constexpr variable.

property linkage_name → str¶

The name of the variable which is used for linking (DW_AT_linkage_name).

This name differs from name as it is usually mangled. The function return an empty string if the linkage name is not available.

property name → str¶

Name of the variable (usually demangled)

property scope → lief.dwarf.Scope | None¶

Scope in which this variable is defined

property size → int | None¶

Return the size of the variable (or a lief_errors if it can’t be resolved).

This size is defined by the type of the variable.

property type → lief.dwarf.Type | None¶

Return the type of this variable.

Bases: object

This class represents a DWARF Type which includes:

• DW_TAG_array_type

• DW_TAG_const_type

• DW_TAG_pointer_type

• DW_TAG_structure_type

• DW_TAG_base_type

• DW_TAG_class_type

• DW_TAG_enumeration_type

• DW_TAG_string_type

• DW_TAG_union_type

• DW_TAG_volatile_type

• DW_TAG_unspecified_type

• DW_TAG_typedef

• DW_TAG_reference_type

• DW_TAG_subroutine_type

• DW_TAG_ptr_to_member_type

• DW_TAG_set_type

• DW_TAG_packed_type

• DW_TAG_file_type

• DW_TAG_thrown_type

• DW_TAG_restrict_type

• DW_TAG_interface_type

• DW_TAG_shared_type

• DW_TAG_rvalue_reference_type

• DW_TAG_template_alias

• DW_TAG_coarray_type

• DW_TAG_dynamic_type

• DW_TAG_atomic_type

• DW_TAG_immutable_type

class KIND(value)¶

Bases: Enum

ARRAY = 5¶

ATOMIC = 26¶

BASE = 2¶

CLASS = 4¶

COARRAY = 24¶

CONST_KIND = 3¶

DYNAMIC = 25¶

ENUM = 28¶

FILE = 16¶

IMMUTABLE = 27¶

INTERFACE = 20¶

PACKED = 15¶

POINTER = 6¶

POINTER_MEMBER = 14¶

REF = 10¶

RESTRICT = 19¶

RVALREF = 22¶

SET_TYPE = 11¶

SHARED = 21¶

STRING = 12¶

STRUCT = 7¶

SUBROUTINE = 13¶

TEMPLATE_ALIAS = 23¶

THROWN = 17¶

TYPEDEF = 9¶

UNION = 8¶

UNKNOWN = 0¶

UNSPECIFIED = 1¶

VOLATILE = 18¶

property is_unspecified → bool¶

Whether this type is a DW_TAG_unspecified_type

property kind → lief.dwarf.Type.KIND¶

Discriminator for the type’s subclasses

property location → lief.debug_location_t¶

Return the debug location where this type is defined.

property name → str | None¶

Return the type’s name or None if it can’t be resolved.

The name is resolved using either DW_AT_name or DW_AT_picture_string.

property scope → lief.dwarf.Scope | None¶

Scope in which this type is defined

property size → int | None¶

Return the size of the type or None if it can’t be computed.

This size should match the equivalent of sizeof(Type).

Bases: Type

This class represents a DW_TAG_array_type

property size_info → lief.dwarf.types.Array.size_info_t¶

Return information about the size of this array.

This size info is usually embedded in a DW_TAG_subrange_type DIE which is represented by the Array.size_info_t class.

class size_info_t¶

Bases: object

Class that wraps information about the dimension of this array

property name → str¶

Name of the index (usually not relevant like __ARRAY_SIZE_TYPE__)

property size → int¶

Size of the array. For instance in uint8_t[3], it returns 3.

property type → lief.dwarf.Type¶

Type of the index for this array.

For instance in uint8_t[3] the index type could be set to a size_t.

property underlying_type → lief.dwarf.Type¶

The underlying type of this array.

Bases: Type

This class wraps the DW_TAG_base_type type which can be used – for instance – to represent integers or primitive types.

class ENCODING(value)¶

Bases: Enum

ADDRESS = 7¶

BOOLEAN = 6¶

FLOAT = 5¶

NONE = 0¶

SIGNED = 1¶

SIGNED_CHAR = 2¶

UNSIGNED = 3¶

UNSIGNED_CHAR = 4¶

property encoding → lief.dwarf.types.Base.ENCODING¶

Describe how the base type is encoded and should be interpreted.

Bases: Type

This class abstracts a DWARF aggregate (DW_TAG_structure_type, DW_TAG_class_type, DW_TAG_union_type).

class Member¶

Bases: object

This class represents a class/struct/union attribute.

property bit_offset → int | None¶

Offset of the current member in bits in the current struct/union/class

This function differs from offset for aggregates using bit-field declaration:

struct S {
  int flag : 4;
  int opt : 1
};

Usually, offset * 8 == bit_offset

If the offset can’t be resolved it returns None

property is_declaration → bool¶

property is_external → bool¶

property name → str¶

Name of the member

property offset → int | None¶

Offset of the current member in the struct/union/class

If the offset can’t be resolved it returns None

property type → lief.dwarf.Type | None¶

Type of the current member

find_member(self, offset: int) → lief.dwarf.types.ClassLike.Member | None¶

Try to find the attribute at the given offset

property functions → Iterator[lief.dwarf.Function | None]¶

Iterator over the functions defined by the class-like.

property members → list[lief.dwarf.types.ClassLike.Member]¶

Return a list of all the members defined in this class-like type.

Bases: ClassLike

This class represents a DWARF struct type (DW_TAG_structure_type)

Bases: ClassLike

This class represents a DWARF class type (DW_TAG_class_type)

Bases: ClassLike

This class represents a DWARF union type (DW_TAG_union_type)

Bases: ClassLike

This class represents a DWARF packed type (DW_TAG_packed_type)

Bases: Type

This class represents a DW_TAG_const_type modifier

property underlying_type → lief.dwarf.Type¶

The underlying type being const-ed by this type.

Bases: Type

This class represents a DW_TAG_pointer_type DWARF type.

property underlying_type → lief.dwarf.Type¶

The type pointed by this pointer

Bases: Type

This class represents a DW_TAG_typedef type

property underlying_type → lief.dwarf.Type¶

The type aliased by this typedef

Bases: Type

This class represents the DW_TAG_atomic_type type

property underlying_type → lief.dwarf.Type¶

The underlying type being atomized by this type.

Bases: Type

This class represents the DW_TAG_coarray_type type

Bases: Type

This class represents the DW_TAG_dynamic_type type

Bases: Type

This class represents the DW_TAG_enumeration_type type

Bases: Type

This class represents the DW_TAG_file_type type

Bases: Type

This class represents the DW_TAG_immutable_type type

property underlying_type → lief.dwarf.Type¶

The underlying type.

Bases: Type

This class represents the DW_TAG_interface_type type

Bases: Type

This class represents the DW_TAG_ptr_to_member_type type

property containing_type → lief.dwarf.Type | None¶

The type that embeds this member.

property underlying_type → lief.dwarf.Type¶

The type of the member referenced by this pointer.

Bases: Type

This class represents the DW_TAG_rvalue_reference_type type

property underlying_type → lief.dwarf.Type¶

The underlying type referenced by this rvalue-type.

Bases: Type

This class represents the DW_TAG_reference_type type

property underlying_type → lief.dwarf.Type¶

The underlying type referenced by this ref-type.

Bases: Type

This class represents the DW_TAG_restrict_type type

property underlying_type → lief.dwarf.Type¶

The underlying type referenced by this restrict-type.

Bases: Type

This class represents the DW_TAG_set_type type

property underlying_type → lief.dwarf.Type¶

The underlying type referenced by this set-type.

Bases: Type

This class represents the DW_TAG_shared_type type

property underlying_type → lief.dwarf.Type¶

The underlying type referenced by this shared-type.

Bases: Type

This class represents the DW_TAG_string_type type

Bases: Type

This class represents the DW_TAG_subroutine_type type

property parameters → list[lief.dwarf.Parameter | None]¶

Parameters of this subroutine

Bases: Type

This class represents the DW_TAG_template_alias type

property parameters → list[lief.dwarf.Parameter | None]¶

Parameters associated with the underlying template

property underlying_type → lief.dwarf.Type¶

The underlying type aliased by this type.

Bases: Type

This class represents a DW_TAG_thrown_type

property underlying_type → lief.dwarf.Type¶

The underlying type being thrown

Bases: Type

This class represents a DW_TAG_volatile_type

property underlying_type → lief.dwarf.Type¶

The underlying type.

Bases: object

This class exposes the main API to create DWARF information

create_compilation_unit(self) → lief.dwarf.editor.CompilationUnit | None¶

Create a new compilation unit

from_binary(bin: lief.Binary) → lief.dwarf.Editor | None = <nanobind.nb_func object>¶

write(self, output: str) → None¶

Write the DWARF file to the specified output

Bases: object

This class represents an editable DWARF compilation unit

create_array(self, name: str, ty: lief.dwarf.editor.Type, count: int) → lief.dwarf.editor.ArrayType | None¶

Create an array type with the given name, type and size.

create_base_type(self, name: str, size: int, encoding: lief.dwarf.editor.BaseType.ENCODING) → lief.dwarf.editor.BaseType | None¶

Create a primitive type with the given name and size.

create_enum(self, name: str) → lief.dwarf.editor.EnumType | None¶

Create an enum type (DW_TAG_enumeration_type)

create_function(self, name: str) → lief.dwarf.editor.Function | None¶

Create a new function owned by this compilation unit

create_function_type(self, name: str) → lief.dwarf.editor.FunctionType | None¶

Create a function type with the given name.

create_generic_type(self, name: str) → lief.dwarf.editor.Type | None¶

Create a DW_TAG_unspecified_type type with the given name

create_pointer_type(self, ty: lief.dwarf.editor.Type) → lief.dwarf.editor.PointerType | None¶

Create a pointer on the provided type.

create_structure(self, name: str, kind: lief.dwarf.editor.StructType.TYPE) → lief.dwarf.editor.StructType | None¶

Create a struct-like type (struct, class, union) with the given name

create_typedef(self, name: str, ty: lief.dwarf.editor.Type) → lief.dwarf.editor.TypeDef | None¶

Create a typdef with the name provided in the first parameter which aliases the type provided in the second parameter

create_variable(self, name: str) → lief.dwarf.editor.Variable | None¶

Create a new global variable owned by this compilation unit

create_void_type(self) → lief.dwarf.editor.Type | None¶

Create a void type

set_producer(self, arg: str) → lief.dwarf.editor.CompilationUnit¶

Set the DW_AT_producer producer attribute.

This attribute aims to inform about the program that generated this compilation unit (e.g. LIEF Extended)

Bases: object

This class represents an editable DWARF function (DW_TAG_subprogram)

class Label¶

Bases: object

This class mirrors the DW_TAG_label DWARF tag

class LexicalBlock¶

Bases: object

This class mirrors the DW_TAG_lexical_block DWARF tag

class Parameter¶

Bases: object

This class represents a parameter of the current function (DW_TAG_formal_parameter)

add_label(self, addr: int, label: str) → lief.dwarf.editor.Function.Label | None¶

Add a label at the given address

add_lexical_block(self, start: int, end: int) → lief.dwarf.editor.Function.LexicalBlock | None¶

Add a lexical block with the given range

add_parameter(self, name: str, type: lief.dwarf.editor.Type) → lief.dwarf.editor.Function.Parameter | None¶

Add a parameter to the current function

create_stack_variable(self, name: str) → lief.dwarf.editor.Variable | None¶

Create a stack-based variable owned by the current function

class range_t(self)¶

class range_t(self, start: int, end: int)

Bases: object

property end → int¶

property start → int¶

set_address(self, addr: int) → lief.dwarf.editor.Function¶

Set the address of this function by defining DW_AT_entry_pc

set_external(self) → lief.dwarf.editor.Function¶

Set the function as external by defining DW_AT_external to true. This means that the function is imported by the current compilation unit.

set_low_high(self, low: int, high: int) → lief.dwarf.editor.Function¶

Set the upper and lower bound addresses for this function. This assumes that the function is contiguous between low and high.

Underneath, the function defines DW_AT_low_pc and DW_AT_high_pc

set_ranges(self, ranges: collections.abc.Sequence[lief.dwarf.editor.Function.range_t]) → lief.dwarf.editor.Function¶

Set the ranges of addresses owned by the implementation of this function by setting the DW_AT_ranges attribute.

This setter should be used for non-contiguous function.

set_return_type(self, type: lief.dwarf.editor.Type) → lief.dwarf.editor.Function¶

Set the return type of this function

Bases: object

This class represents an editable DWARF variable which can be scoped by a function or a compilation unit (DW_TAG_variable)

set_addr(self, addr: int) → lief.dwarf.editor.Variable¶

Set the global address of this variable. Setting this address is only revelant in the case of a static global variable. For stack variable, you should use set_stack_offset().

This function set the DW_AT_location attribute

set_external(self) → lief.dwarf.editor.Variable¶

Mark this variable as imported

set_stack_offset(self, offset: int) → lief.dwarf.editor.Variable¶

Set the stack offset of this variable.

This function set the DW_AT_location attribute

set_type(self, type: lief.dwarf.editor.Type) → lief.dwarf.editor.Variable¶

Set the type of the current variable

Bases: object

This class is the base class for any types created when editing DWARF debug info.

A type is owned by a lief.dwarf.editor.CompilationUnit and should be created from this class.

pointer_to(self) → lief.dwarf.editor.PointerType | None¶

Create a pointer type pointing to this type

Bases: Type

This class represents a pointer to another type.

Bases: Type

This class represents an editable enum type (DW_TAG_enumeration_type)

class Value¶

Bases: object

This class represents an enum value

add_value(self, name: str, value: int) → lief.dwarf.editor.EnumType.Value | None¶

Add an enum value by specifying its name and its integer value.

set_size(self, size: int) → lief.dwarf.editor.EnumType¶

Define the number of bytes required to hold an instance of the enumeration (DW_AT_byte_size).

Bases: Type

This class represents a primitive type like int, char.

class ENCODING(value)¶

Bases: Enum

ADDRESS = 1¶

BOOLEAN = 6¶

FLOAT = 7¶

NONE = 0¶

SIGNED = 2¶

SIGNED_CHAR = 3¶

UNSIGNED = 4¶

UNSIGNED_CHAR = 5¶

Bases: Type

This class represents an array type.

Bases: Type

This class represents a function type (DW_TAG_subroutine_type)

class Parameter¶

Bases: object

This class represents a function’s parameter

add_parameter(self, type: lief.dwarf.editor.Type) → lief.dwarf.editor.FunctionType.Parameter | None¶

Add a parameter

set_return_type(self, type: lief.dwarf.editor.Type) → lief.dwarf.editor.FunctionType¶

Set the return type of this function

Bases: Type

This class represents a typedef (DW_TAG_typedef).

Bases: Type

This class represents a struct-like type which can be:

• DW_TAG_class_type

• DW_TAG_structure_type

• DW_TAG_union_type

class Member¶

Bases: object

This class represents a member of the struct-like

class TYPE(value)¶

Bases: Enum

CLASS = 0¶

STRUCT = 1¶

UNION = 2¶

add_member(self, name: str, type: lief.dwarf.editor.Type, offset: int) → lief.dwarf.editor.StructType.Member | None¶

mber to the current struct-like

set_size(self, size: int) → lief.dwarf.editor.StructType¶

Define the overall size which is equivalent to the sizeof of the current type.

This function defines the DW_AT_byte_size attribute