--- documentID: "56fb1685892b85202d6c176a1e22d939201f0c0a79f93e53993ff05aeeb82c35" docname: "extended/debug_info/index" title: "Debug Information - LIEF Documentation" description: "Load DWARF and PDB debug information, attach matching debug files to binaries, and navigate the shared Python, C++, and Rust APIs." canonical: "https://lief.re/doc/latest/extended/debug_info/index.html" markdownURL: "https://lief.re/doc/latest/extended/debug_info/index.md" documentationVersion: "2.0.0" documentationChannel: "latest" language: "en" contentHash: "df58ab23032cad6658ee4e6ef7397e2cdcf48631bf38e4d0beaf4a239f2fd348" --- # [Debug Information]() Debug information connects machine code with source-level names, types, functions, variables, and locations. [LIEF Extended]() reads [DWARF]() and [PDB]() through format-specific APIs and the common interfaces documented below. ## [Choose how to load debug information]() | Input | Starting point | | --- | --- | | A binary containing DWARF sections | Parse the binary and access `lief.Binary.debug_info()` ( [`lief::elf::Binary::debug_info`]() ; [`lief.Binary.debug_info`]() ; [`LIEF::Binary::debug_info()`]() ) | | A separate DWARF file or a Mach-O debug companion | Load it with `lief.dwarf.load()` ( [`lief::dwarf::load`]() ; [`lief.dwarf.load()`]() ; [`LIEF::dwarf::load()`]() ) | | A PDB file | Load it with `lief.pdb.load()` ( [`lief::pdb::load`]() ; [`lief.pdb.load()`]() ; [`LIEF::pdb::load()`]() ) | | A parsed binary and its matching external debug file | Attach the file with `lief.abstract.Binary.load_debug_info()` ( [`lief::generic::Binary::load_debug_info`]() ; [`lief.Binary.load_debug_info()`]() ; [`LIEF::Binary::load_debug_info()`]() ) | Attaching an external file makes its information available to the parsed binary. The `lief.Binary.disassemble()` ( [`lief::generic::Binary::disassemble`]() ; [`lief::generic::Binary::disassemble_symbol`]() ; [`lief::generic::Binary::disassemble_address`]() ; [`lief::generic::Binary::disassemble_slice`]() ; [`LIEF::Binary::disassemble()`]() ; [`lief.Binary.disassemble()`]() ; [`lief.Binary.disassemble_from_bytes()`]() ) API can then disassemble functions by name. Attaching the file does not embed it into the executable. Use the debug file from the same build: `lief.abstract.Binary.load_debug_info()` ( [`lief::generic::Binary::load_debug_info`]() ; [`lief.Binary.load_debug_info()`]() ; [`LIEF::Binary::load_debug_info()`]() ) does not verify build IDs or PDB identifiers for you. The [DWARF]() and [PDB]() guides show how to iterate over compilation units, find functions and types, and generate C/C++ declarations. ## [Shared API reference]() ### [C++]() #### [DebugInfo]() ##### [` DebugInfo `]() class DebugInfo This class provides a generic interface for accessing debug information from different formats such as DWARF and PDB. Users can use this interface to access high-level debug features like resolving function addresses. > **See also** > > [LIEF::pdb::DebugInfo](), [LIEF::dwarf::DebugInfo]() Subclassed by [LIEF::dwarf::DebugInfo](), [LIEF::pdb::DebugInfo]() Public Types ###### [` FORMAT `]() enum class FORMAT *Values:* ###### [` UNKNOWN `]() enumerator UNKNOWN = 0 ###### [` DWARF `]() enumerator DWARF ###### [` PDB `]() enumerator PDB Public Functions ###### [` DebugInfo `]() DebugInfo(std::unique\_ptr<details::DebugInfo> impl) ###### [` ~DebugInfo `]() virtual ~DebugInfo() ###### [` format `]() inline virtual [FORMAT]( "LIEF::DebugInfo::FORMAT") format() const ###### [` Tas `]() template<class T> inline const [T]( "LIEF::DebugInfo::as::T") \*as() const This function can be used to **down cast** a [DebugInfo]() instance: ```cpp std::unique_ptr dbg = bin->debug_info(); if (const auto* dwarf = inst->as()) { dwarf->find_function("main"); } ``` ###### [` find_function_address `]() virtual std::optional<uint64\_t> find\_function\_address(const std::string &name) const = 0 Attempt to resolve the address of the function specified by `name`. Friends **friend class Binary** #### [debug\_location\_t]() ##### [` debug_location_t `]() struct debug\_location\_t This structure holds a debug location (source filename & line). Public Members ###### [` file `]() std::string file ###### [` line `]() uint64\_t line = 0 #### [DeclOpt]() ##### [` DeclOpt `]() class DeclOpt Configuration options for generated code from debug info. This structure configures how the debug information (DWARF/PDB) translated into an AST is generated. You can use it to configure the indentation, and the information to generate when translating DWARF/PDB into C++-like definitions Public Types ###### [` type_aliases_t `]() using type\_aliases\_t = std::unordered\_map<std::string, std::string> Mapping between a type name and a user-friendly aliases. (e.g. `std::basic_string,std::allocator>` -> `std::string`). Public Functions ###### [` DeclOpt `]() DeclOpt() ###### [` DeclOpt `]() DeclOpt(const [DeclOpt]( "LIEF::DeclOpt::DeclOpt") &other) ###### [` operator= `]() [DeclOpt]( "LIEF::DeclOpt") &operator=(const [DeclOpt]( "LIEF::DeclOpt") &other) ###### [` DeclOpt `]() DeclOpt([DeclOpt]( "LIEF::DeclOpt::DeclOpt") &&other) noexcept ###### [` operator= `]() [DeclOpt]( "LIEF::DeclOpt") &operator=([DeclOpt]( "LIEF::DeclOpt") &&other) noexcept ###### [` ~DeclOpt `]() ~DeclOpt() ###### [` indentation `]() uint32\_t indentation() const The number of spaces for indentation. ###### [` indentation `]() [DeclOpt]( "LIEF::DeclOpt") &indentation(uint32\_t value) ###### [` is_cpp `]() bool is\_cpp() const Prefer C++ syntax over C syntax. If true, the output will use C++ features (e.g. `bool` keyword) ###### [` is_cpp `]() [DeclOpt]( "LIEF::DeclOpt") &is\_cpp(bool value) ###### [` show_extended_annotations `]() bool show\_extended\_annotations() const Enable extended comments and annotations. If true, the generated code will include comments containing low-level details such as memory addresses, offsets, type sizes, and original source locations. ###### [` show_extended_annotations `]() [DeclOpt]( "LIEF::DeclOpt") &show\_extended\_annotations(bool value) ###### [` include_types `]() bool include\_types() const Include full type definitions. If true, the output will contain the full definition of types (structs, enums, unions). ###### [` include_types `]() [DeclOpt]( "LIEF::DeclOpt") &include\_types(bool value) ###### [` include_locals `]() bool include\_locals() const Emit a function body listing its local / stack variables. ###### [` include_locals `]() [DeclOpt]( "LIEF::DeclOpt") &include\_locals(bool value) ###### [` desugar `]() bool desugar() const Resolve type aliases (sugar). If true, typedef and type aliases are replaced by their underlying canonical types (e.g., `uint32_t` might become `unsigned int`). ###### [` desugar `]() [DeclOpt]( "LIEF::DeclOpt") &desugar(bool value) ###### [` show_field_offsets `]() bool show\_field\_offsets() const Show the relative offset of each field/attribute in structures. If true, every member of a structure is prefixed with its byte offset, ```cpp struct Foo { /* 0x00 *‍/ int A; /* 0x04 *‍/ int B; }; ``` ###### [` show_field_offsets `]() [DeclOpt]( "LIEF::DeclOpt") &show\_field\_offsets(bool value) ###### [` type_aliases `]() const [type\_aliases\_t]( "LIEF::DeclOpt::type_aliases_t") &type\_aliases() const Mapping of type names to user-friendly aliases. ###### [` type_aliases `]() [DeclOpt]( "LIEF::DeclOpt") &type\_aliases([type\_aliases\_t]( "LIEF::DeclOpt::type_aliases_t") aliases) ###### [` add_type_alias `]() [DeclOpt]( "LIEF::DeclOpt") &add\_type\_alias(std::string name, std::string alias) Register a single type alias. --- ### [Python]() #### [DebugInfo]() ##### [` lief.DebugInfo `]() class lief.DebugInfo Bases: `object` This class provides a generic interface for accessing debug information from different formats such as DWARF and PDB. Users can use this interface to access high-level debug features like resolving function addresses. See: [`DebugInfo`]( "lief.pdb.DebugInfo"), [`lief.dwarf.DebugInfo`]( "lief.dwarf.DebugInfo") ###### [` FORMAT `]() class FORMAT(*\*values*) Bases: `Enum` ###### [` DWARF `]() DWARF = 1 ###### [` PDB `]() PDB = 2 ###### [` UNKNOWN `]() UNKNOWN = 0 ###### [` from_value `]() from\_value(*arg: int*) → [lief.DebugInfo.FORMAT]( "lief.DebugInfo.FORMAT") = <nanobind.nb\_func object> ###### [` find_function_address `]() find\_function\_address(*self*, *name: str*) → int | None Attempt to resolve the address of the function specified by `name`. ###### [` format `]() property format → [lief.DebugInfo.FORMAT]( "lief.DebugInfo.FORMAT") The actual debug format (PDB/DWARF) #### [debug\_location\_t]() ##### [` lief.debug_location_t `]() class lief.debug\_location\_t Bases: `object` ###### [` file `]() property file → str ###### [` line `]() property line → int #### [DeclOpt]() ##### [` lief.DeclOpt `]() class lief.DeclOpt(*self*) Bases: `object` Configuration options for generated code from debug info. This structure configures how the debug information (DWARF/PDB) translated into an AST is generated. You can use it to configure the indentation, and the information to generate when translating DWARF/PDB into C++-like definitions ###### [` add_type_alias `]() add\_type\_alias(*self*, *name: str*, *alias: str*) → [lief.\_lief.DeclOpt]( "lief._lief.DeclOpt") Register a single type alias (see [`type_aliases`]( "lief.DeclOpt.type_aliases")). ###### [` desugar `]() property desugar → bool Resolve type aliases (sugar). If true, typedef and type aliases are replaced by their underlying canonical types (e.g., `uint32_t` might become `unsigned int`). ###### [` include_locals `]() property include\_locals → bool Emit a function body listing its local / stack variables. ###### [` include_types `]() property include\_types → bool Include full type definitions. If true, the output will contain the full definition of types (structs, enums, unions). ###### [` indentation `]() property indentation → int The number of spaces for indentation. ###### [` is_cpp `]() property is\_cpp → bool Prefer C++ syntax over C syntax. If true, the output will use C++ features (e.g., `bool` keyword) ###### [` show_extended_annotations `]() property show\_extended\_annotations → bool Enable extended comments and annotations. If true, the generated code will include comments containing low-level details such as memory addresses, offsets, type sizes, and original source locations. ###### [` show_field_offsets `]() property show\_field\_offsets → bool Show the relative offset of each field/attribute in structures. If true, every member of a structure is prefixed with its byte offset (e.g. `/* 0x04 */`). ###### [` type_aliases `]() property type\_aliases → dict[str, str] Mapping of type names to user-friendly aliases used while rendering types (e.g. `std::basic_string` -> `std::string`). --- ### [Rust]() - [`lief::generic::DebugInfo`]() - [`lief::DebugLocation`]() - [`lief::DeclOpt`]()