Python

lief.dwarf.load(path: str) lief.dwarf.DebugInfo | None

Load the DWARF from the given path

DebugInfo

class lief.dwarf.DebugInfo

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.


CompilationUnit

class lief.dwarf.CompilationUnit

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

Bases: object

C = lief._lief.dwarf.LANG.C
CPP = lief._lief.dwarf.LANG.CPP
DART = lief._lief.dwarf.LANG.DART
RUST = lief._lief.dwarf.LANG.RUST
UNKNOWN = lief._lief.dwarf.LANG.UNKNOWN
from_value(arg: int) lief.dwarf.CompilationUnit.Language.LANG = <nanobind.nb_func object>
property value int

The underlying integer value

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 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;
}

Function

class lief.dwarf.Function

Bases: object

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

class Parameter

Bases: object

This class represents a DWARF function’s parameter.

property name str

The name of the parameter

property type lief.dwarf.Type | None

Type of the parameter

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 is_artificial bool

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

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.Function.Parameter]

Return the list of parameters used by this function.

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


Scope

class lief.dwarf.Scope

Bases: object

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

class TYPE

Bases: object

CLASS = lief._lief.dwarf.TYPE.CLASS
COMPILATION_UNIT = lief._lief.dwarf.TYPE.COMPILATION_UNIT
FUNCTION = lief._lief.dwarf.TYPE.FUNCTION
NAMESPACE = lief._lief.dwarf.TYPE.NAMESPACE
STRUCT = lief._lief.dwarf.TYPE.STRUCT
UNION = lief._lief.dwarf.TYPE.UNION
UNKNOWN = lief._lief.dwarf.TYPE.UNKNOWN
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.


Variable

class lief.dwarf.Variable

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.


Type

Inheritance diagram of lief._lief.dwarf.types.Base, lief._lief.dwarf.types.Union, lief._lief.dwarf.types.Class, lief._lief.dwarf.types.ClassLike, lief._lief.dwarf.types.Structure, lief._lief.dwarf.types.Array, lief._lief.dwarf.types.Pointer, lief._lief.dwarf.types.Const, lief._lief.dwarf.Type
class lief.dwarf.Type

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

class KIND

Bases: object

ARRAY = lief._lief.dwarf.KIND.ARRAY
BASE = lief._lief.dwarf.KIND.BASE
CLASS = lief._lief.dwarf.KIND.CLASS
CONST = lief._lief.dwarf.KIND.CONST
POINTER = lief._lief.dwarf.KIND.POINTER
STRUCT = lief._lief.dwarf.KIND.STRUCT
UNION = lief._lief.dwarf.KIND.UNION
UNKNOWN = lief._lief.dwarf.KIND.UNKNOWN
UNSPECIFIED = lief._lief.dwarf.KIND.UNSPECIFIED
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.

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


Array

Inheritance diagram of lief._lief.dwarf.types.Array
class lief.dwarf.types.Array

Bases: Type

This class represents a DW_TAG_array_type

property underlying_type lief.dwarf.Type

The underlying type of this array.


Base

Inheritance diagram of lief._lief.dwarf.types.Base
class lief.dwarf.types.Base

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

Bases: object

ADDRESS = lief._lief.dwarf.types.ENCODING.ADDRESS
BOOLEAN = lief._lief.dwarf.types.ENCODING.BOOLEAN
FLOAT = lief._lief.dwarf.types.ENCODING.FLOAT
NONE = lief._lief.dwarf.types.ENCODING.NONE
SIGNED = lief._lief.dwarf.types.ENCODING.SIGNED
SIGNED_CHAR = lief._lief.dwarf.types.ENCODING.SIGNED_CHAR
UNSIGNED = lief._lief.dwarf.types.ENCODING.UNSIGNED
UNSIGNED_CHAR = lief._lief.dwarf.types.ENCODING.UNSIGNED_CHAR
property encoding lief.dwarf.types.Base.ENCODING

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


ClassLike

Inheritance diagram of lief._lief.dwarf.types.Class, lief._lief.dwarf.types.ClassLike, lief._lief.dwarf.types.Union, lief._lief.dwarf.types.Structure
class lief.dwarf.types.ClassLike

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 members list[lief.dwarf.types.ClassLike.Member]

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


Structure

Inheritance diagram of lief._lief.dwarf.types.Structure
class lief.dwarf.types.Structure

Bases: ClassLike

This class represents a DWARF struct type (DW_TAG_structure_type)


Class

Inheritance diagram of lief._lief.dwarf.types.Class
class lief.dwarf.types.Class

Bases: ClassLike

This class represents a DWARF class type (DW_TAG_class_type)


Union

Inheritance diagram of lief._lief.dwarf.types.Union
class lief.dwarf.types.Union

Bases: ClassLike

This class represents a DWARF union type (DW_TAG_union_type)


Const

Inheritance diagram of lief._lief.dwarf.types.Const
class lief.dwarf.types.Const

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.


Pointer

Inheritance diagram of lief._lief.dwarf.types.Pointer
class lief.dwarf.types.Pointer

Bases: Type

This class represents a DW_TAG_pointer_type DWARF type.

property underlying_type lief.dwarf.Type

The type pointed by this pointer


debug_location_t

class lief.debug_location_t

Bases: object

property file str
property line int