DWARF(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💖 NAME 💖

okay so this is the DWARF(3) page from the Library Functions Manual, and it's literally all about how libdwarf lets you access debugging information in object files. bestie, that's the whole vibe. 🫶

🎀 LIBRARY 🎀

DWARF Access Library (libdwarf, -ldwarf) — yes, that's the glow-up name and the link line, keep both in your notes. ✨

🦋 SYNOPSIS 🦋

#include <libdwarf.h>

🌸 DESCRIPTION 🌸

so the DWARF Access Library (libdwarf, -ldwarf) gives applications functions that let them read and write debugging information in object files. the format of the debugging information you can get at through this API is defined by the DWARF standard — peep dwarf(4) for that. 👑

the DWARF(3) API has two parts, and yes both are main-character energy:

  • a consumer API set that lets applications read existing debug information in a program object. the functions that make up the DWARF consumer API are described in the section “DWARF Consumer API” below.
  • a producer API set that lets applications add debug information to a program object. the functions that make up the DWARF producer API are described in the section “DWARF Producer API” below.

each function referenced below is further described in its own manual page. no cap, every single one has its own little moment. 💅

✨ Namespace use ✨

the DWARF library uses these prefixes, and they are not interchangeable, okay?

  • DWARF_* — used for error numbers and constants.
  • DW_* — used for constants.
  • Dwarf_* — used for types.
  • dwarf_* — used for functions and macros that make up the API.

🧚 Data Types 🧚

the DWARF(3) API uses these data types, and honestly they're giving very specific little descriptors:

  • Dwarf_Abbrev — describes DWARF abbreviations.
  • Dwarf_Addr — a program address in the target object.
  • Dwarf_Arange — describes address ranges.
  • Dwarf_Attribute, Dwarf_P_Attribute — describes attributes of debugging information entries.
  • Dwarf_Bool — used for boolean states.
  • Dwarf_Cie, Dwarf_P_Cie — describes call information that is common to several frames.
  • Dwarf_Debug, Dwarf_P_Debug — an opaque type describing a debug context.
  • Dwarf_Die, Dwarf_P_Die — a debugging information entry.
  • Dwarf_Fde, Dwarf_P_Fde — a frame descriptor.
  • Dwarf_Func — a descriptor representing a function.
  • Dwarf_Global — a descriptor representing a global name.
  • Dwarf_Half — a 16-bit wide unsigned numeric type.
  • Dwarf_Handler — a pointer to an error handling function.
  • Dwarf_Line — a descriptor for a source line.
  • Dwarf_Off — an unsigned file offset.
  • Dwarf_P_Expr — a descriptor for a location expression.
  • Dwarf_Ptr — a virtual address used by an application.
  • Dwarf_Signed — a 64-bit wide signed numeric type.
  • Dwarf_Small — an 8-bit wide unsigned numeric type.
  • Dwarf_Type — a descriptor representing a user-specified type.
  • Dwarf_Unsigned — a 64-bit wide unsigned numeric type.
  • Dwarf_Var — a descriptor representing a static variable.
  • Dwarf_Weak — a descriptor representing a weak name.

💀 Error Handling 💀

library functions that encounter an error will return with a value other than DW_DLV_OK. that's the signal, bestie. 🚨

the DWARF Access Library (libdwarf, -ldwarf) allows applications to specify three levels of error handling:

  1. most library functions take a parameter of type Dwarf_Error that specifies a location to store an error descriptor in case of an error. if an error occurs during the execution of an API, and if this parameter is non-NULL, then an error descriptor is written to the location specified.
  2. otherwise, if the error parameter was NULL, but if an error handler was defined for the debug context in use using dwarf_init(3) or dwarf_seterrhand(3), then the library will invoke the specified error handler with an error descriptor as argument.
  3. otherwise, if a library wide error handler was specified using dwarf_seterrhand(3), it is called.

error descriptors may be used with dwarf_errmsg(3) or dwarf_errno(3). 🎀

👑 The DWARF Consumer API 👑

the DWARF consumer API permits applications to read DWARF information in an object file. literally its whole thing. 🦋

the major functional groups of functions in the consumer API are listed below.

Abbreviations

okay so first up, the abbrev squad — they’re giving “let me look up that abbreviation real quick” energy 💅

  • dwarf_get_abbrev() — Retrieve abbreviation information at a given offset. lowkey essential.
  • dwarf_get_abbrev_children_flag() — Check if an abbreviation has child elements. yes, we’re asking if it has kids 😭
  • dwarf_get_abbrev_code() — Retrieve the abbreviation code for an abbreviation entry descriptor.
  • dwarf_get_abbrev_entry() — Retrieve abbreviation information for an abbreviation entry descriptor.
  • dwarf_get_abbrev_tag() — Retrieve the tag for an abbreviation entry. iconic.

Addresses

address stuff!! we love a good memory map moment 🗺️✨

  • dwarf_get_address_size() — Return the number of bytes needed to represent an address.
  • dwarf_get_arange() — Search for an address range descriptor covering an address.
  • dwarf_get_arange_cu_header_offset() — Retrieve the offsets associated with an address range descriptor.
  • dwarf_get_arange_info() — Extract address range information from a descriptor.
  • dwarf_get_aranges() — Retrieve program address space mappings.
  • dwarf_get_cu_die_offset() — Retrieve the offset associated with a compilation unit for an address range descriptor.
  • dwarf_get_ranges(), dwarf_get_ranges_a() — Retrieve information about non-contiguous address ranges for a debugging information entry.

Attributes

the attribute girlies are here and they have so many forms 💖

  • dwarf_arrayorder() — Retrieve the value of a DW_AT_ordering attribute.
  • dwarf_attr() — Retrieve an attribute descriptor.
  • dwarf_attrlist() — Retrieve attribute descriptors for a debugging information entry.
  • dwarf_attroffset() — Retrieve the section-relative offset of an attribute descriptor.
  • dwarf_attrval_flag() — Retrieve a DW_AT_FORM_flag value.
  • dwarf_attrval_signed() — Retrieve an attribute's value as a signed integral quantity.
  • dwarf_attrval_string() — Retrieve an attribute's value as a NUL-terminated string.
  • dwarf_attrval_unsigned() — Retrieve an attribute's value as an unsigned integral quantity.
  • dwarf_bitoffset() — Retrieve the value of a DW_AT_bit_offset attribute.
  • dwarf_bitsize() — Retrieve the value of a DW_AT_bit_size attribute.
  • dwarf_bytesize() — Retrieve the value of a DW_AT_byte_size attribute.
  • dwarf_formaddr() — Return the value of an ADDRESS-class attribute.
  • dwarf_formblock() — Return the value of a BLOCK-class attribute. (yes that’s the whole description, no notes 💀)
  • dwarf_formexprloc() — Return information about a location expression.
  • dwarf_formflag() — Retrieve information about a BOOLEAN-class attribute.
  • dwarf_formref(), dwarf_global_formref() — Retrieve offsets for REFERENCE-class attributes.
  • dwarf_formsdata(), dwarf_formudata() — Retrieve the value of a CONSTANT-class attribute.
  • dwarf_formsig8() — Return the type signature for a DWARF type.
  • dwarf_formstring() — Retrieve information about a STRING-class attribute.
  • dwarf_get_form_class() — Retrieve the form class for an attribute.
  • dwarf_hasattr() — Check for the presence of an attribute.
  • dwarf_hasform() — Check if an attribute has the given form.
  • dwarf_whatattr() — Retrieve the attribute code for an attribute.
  • dwarf_whatform(), dwarf_whatform_direct() — Retrieve the form of an attribute.

Call Information Entries and Frame Descriptor Entries

CIE and FDE besties!! frame info is literally the backbone of stack unwinding, no cap 🫶

  • dwarf_get_cie_index() — Retrieve the index for a CIE descriptor.
  • dwarf_get_cie_info() — Retrieve information from a CIE descriptor.
  • dwarf_get_cie_of_fde() — Retrieve a CIE descriptor.
  • dwarf_get_fde_at_pc() — Retrieve an FDE descriptor for an address.
  • dwarf_get_fde_info_for_all_regs() — Retrieve register rule row.
  • dwarf_get_fde_info_for_all_regs3() — Retrieve register rule row (revised API).
  • dwarf_get_fde_info_for_cfa_reg3() — Retrieve a CFA register rule.
  • dwarf_get_fde_info_for_reg() — Retrieve a register rule.
  • dwarf_get_fde_info_for_reg3() — Retrieve a register rule (revised API).
  • dwarf_get_fde_instr_bytes() — Retrieve instructions from an FDE descriptor.
  • dwarf_get_fde_list(), dwarf_get_fde_list_eh() — Retrieve frame information.
  • dwarf_get_fde_n() — Retrieve an FDE descriptor.
  • dwarf_get_fde_range() — Retrieve range information from an FDE descriptor.

Compilation Units

compilation units are the main characters of debug info, periodt 🎀

  • dwarf_get_cu_die_offset_given_cu_header_offset(), dwarf_get_cu_die_offset_given_cu_header_offset_b() — Retrieve the offset of the debugging information entry for a compilation or type unit.
  • dwarf_next_cu_header(), dwarf_next_cu_header_b(), dwarf_next_cu_header_c() — Step through compilation units in a debug context.

Debugging Information Entries

DIEs!! (debugging information entries, not the other thing 😭) they’re everywhere and we love them 💜

  • dwarf_child() — Returns the child of a debugging information entry.
  • dwarf_die_abbrev_code() — Returns the abbreviation code for a debugging information entry.
  • dwarf_die_CU_offset(), dwarf_die_CU_offset_range() — Retrieve offsets and lengths for a compilation unit.
  • dwarf_diename() — Returns the DW_AT_name attribute for a debugging information entry.
  • dwarf_dieoffset() — Retrieves the offset for a debugging information entry.
  • dwarf_get_die_infotypes_flag() — Indicate the originating section for a debugging information entry.
  • dwarf_highpc(), dwarf_highpc_b() — Return the highest PC value for a debugging information entry.
  • dwarf_lowpc() — Return the lowest PC value for a debugging information entry.
  • dwarf_offdie(), dwarf_offdie_b() — Retrieve a debugging information entry given an offset.
  • dwarf_siblingof(), dwarf_siblingof_b() — Retrieve the sibling descriptor for a debugging information entry.
  • dwarf_srclang() — Retrieve the source language attribute for a debugging information entry.
  • dwarf_tag() — Retrieve the tag for a debugging information entry.

Functions

function girlies rise!! we’re getting names and offsets and all the good stuff ✨

  • dwarf_func_cu_offset() — Retrieves the offset for the compilation unit for a function.
  • dwarf_func_die_offset() — Retrieves the offset for the debugging information entry for a function.
  • dwarf_funcname() — Retrieves the name of a function.
  • dwarf_func_name_offsets() — Retrieve both the name and offsets for a function.
  • dwarf_get_funcs() — Retrieve information about static functions.

Globals

global variables said “notice me” and honestly? valid 💅

  • dwarf_get_globals() — Retrieve a list of globals.
  • dwarf_global_cu_offset() — Return the offset for compilation unit for a global.
  • dwarf_global_die_offset() — Return the offset for the debugging information entry for a global.
  • dwarf_global_name_offsets() — Return the name and offsets for a global.
  • dwarf_globname() — Return the name for a global.

Initialization and Finalization

okay so before you do literally anything, you gotta init. Functions dwarf_elf_init() and dwarf_init() may be used for initialization. And when you’re done and you wanna release resources? The function dwarf_finish() may be used to release resources. clean up after yourself bestie 🧹💖

The functions dwarf_object_init() and dwarf_object_finish() are the ✨vibe✨ — they let an app plug in its own alternate low-level file access routines instead of the default ones. Slay, honestly.

Line Numbers 🎀

All the line-info girlies, gather round:

  • dwarf_lineaddr() — pulls the program address that belongs to a source line.
  • dwarf_linebeginstatement() — checks whether a source line lands right at the beginning of a statement.
  • dwarf_lineblock() — checks whether a source line sits at the start of a basic block.
  • dwarf_lineendsequence() — checks if this source line is the end of a sequence of instructions.
  • dwarf_lineno() — grabs the line number off a line descriptor.
  • dwarf_lineoff() — grabs the column number off a line descriptor.
  • dwarf_linesrc() — gets the source file for a line descriptor.
  • dwarf_line_srcfileno() — gets the index of the source file for a line descriptor.
  • dwarf_srcfiles() — returns the source files for a compilation unit.
  • dwarf_srclines() — returns the line number information for a compilation unit.

Location Lists 📍

  • dwarf_get_loclist_entry() — retrieves a location list entry.
  • dwarf_loclist(), dwarf_loclist_n() — retrieve location expressions.
  • dwarf_loclist_from_expr(), dwarf_loclist_from_expr_a(), dwarf_loclist_from_expr_b() — translate a location expression into a location descriptor.

Error Handling 😭

  • dwarf_errmsg() — retrieves a human-readable error message (finally, words instead of vibes).
  • dwarf_errno() — retrieves an error number from an error descriptor.
  • dwarf_seterrarg() — sets the argument that gets passed to a callback error handler.
  • dwarf_seterrhand() — sets the callback handler that gets called in case of an error.

Frame Handling 🦋

  • dwarf_expand_frame_instructions() — translates frame instruction bytes.
  • dwarf_set_frame_cfa_value() — sets the CFA parameter for the internal register rule table.
  • dwarf_set_frame_rule_initial_value() — sets the initial value of the register rules in that internal register rule table.
  • dwarf_set_frame_rule_table_size() — sets the max number of columns in the register rule table.
  • dwarf_set_frame_same_value() — sets the register number that represents the “same value” rule.
  • dwarf_set_frame_undefined_value() — sets the register number that represents the “undefined” rule.

Macros 💅

  • dwarf_find_macro_value_start() — returns the macro value part of a macro string.
  • dwarf_get_macro_details() — retrieves macro information.

Memory Management 🧹

okay so this one's important bestie, listen up 👑 — in the DWARF consumer API, the memory management rules are not one-size-fits-all. They differ between functions.

Sometimes the memory areas the library hands back to your application get freed by calling specific API functions. Other times, the deallocation function dwarf_dealloc() is enough. The individual manual pages for the API's functions document the specific memory management rules you're supposed to follow — so like, read those, no cap.

The function dwarf_dealloc() is used to mark memory arenas as unused. And on top of that, these functions release specific types of DWARF resources: dwarf_fde_cie_list_dealloc(), dwarf_funcs_dealloc(), dwarf_globals_dealloc(), dwarf_pubtypes_dealloc(), dwarf_ranges_dealloc(), dwarf_srclines_dealloc(), dwarf_types_dealloc(), dwarf_vars_dealloc(), and dwarf_weaks_dealloc().

Symbol Constants 🔤

Want symbolic names for DWARF constants? These functions ate:

dwarf_get_ACCESS_name(), dwarf_get_AT_name(), dwarf_get_ATE_name(), dwarf_get_CC_name(), dwarf_get_CFA_name(), dwarf_get_CHILDREN_name(), dwarf_get_DS_name(), dwarf_get_DSC_name(), dwarf_get_EH_name(), dwarf_get_END_name(), dwarf_get_FORM_name(), dwarf_get_ID_name(), dwarf_get_INL_name(), dwarf_get_LANG_name(), dwarf_get_LNE_name(), dwarf_get_LNS_name(), dwarf_get_MACINFO_name(), dwarf_get_OP_name(), dwarf_get_ORD_name(), dwarf_get_TAG_name(), dwarf_get_VIRTUALITY_name(), and dwarf_get_VIS_name().

Types 🌸

  • dwarf_get_pubtypes(), dwarf_get_types() — retrieve descriptors for user-defined types.
  • dwarf_next_types_section() — steps through “.debug_types” sections in a debug context.
  • dwarf_pubtype_cu_offset(), dwarf_type_cu_offset() — return the offset for the compilation unit for a type.
  • dwarf_pubtype_die_offset(), dwarf_type_die_offset() — return the offset for the debugging information entry for a type.
  • dwarf_pubtypename(), dwarf_typename() — retrieve the name of a type.
  • dwarf_pubtype_name_offsets(), dwarf_type_name_offsets() — retrieve the name and offsets for a type.

Variables 🍓

  • dwarf_get_vars() — retrieve descriptors for static variables.
  • dwarf_var_cu_offset() — return the offset for the compilation unit for a variable.
  • dwarf_var_die_offset() — return the offset for the debugging information entry for a variable.
  • dwarf_varname() — retrieve the name of a variable.
  • dwarf_var_name_offsets() — retrieve the name and offsets for a variable.

Weak Symbols 🫶

  • dwarf_get_weaks() — retrieve information about weak symbols.
  • dwarf_weak_cu_offset() — return the offset for the compilation unit for a weak symbol.
  • dwarf_weak_die_offset() — return the offset for the debugging information entry for a weak symbol.
  • dwarf_weakname() — retrieve the name of a weak symbol.
  • dwarf_weak_name_offsets() — retrieve the name and offsets for a weak symbol.

Miscellaneous 🌈

  • dwarf_get_elf() — retrieves the ELF descriptor for a debug context — see elf(3).
  • dwarf_get_str() — retrieves a NUL-terminated string from the DWARF string section.
  • dwarf_set_reloc_application() — controls whether relocations are handled by the DWARF Access Library (libdwarf, -ldwarf).

✨ The DWARF Producer API ✨

okay so the DWARF producer API is the whole era where your app gets to add DWARF information to an object file 💅. It’s giving “I’m the one writing the debug tea,” and honestly? iconic.

The major functional groups of functions in the producer API are listed below, bestie:

🎀 Attribute Management 🎀

The following functions are used to attach attributes to a debugging information entry — yes, all of them, collect them like little debug Pokémon:

  • dwarf_add_AT_comp_dir()
  • dwarf_add_AT_const_value_signedint()
  • dwarf_add_AT_const_value_string()
  • dwarf_add_AT_const_value_unsignedint()
  • dwarf_add_AT_dataref()
  • dwarf_add_AT_flag()
  • dwarf_add_AT_location_expr()
  • dwarf_add_AT_name()
  • dwarf_add_AT_producer()
  • dwarf_add_AT_ref_address()
  • dwarf_add_AT_reference()
  • dwarf_add_AT_signed_const()
  • dwarf_add_AT_string()
  • dwarf_add_AT_targ_address()
  • dwarf_add_AT_targ_address_b()
  • dwarf_add_AT_unsigned_const()

🦋 Debugging Information Entry Management 🦋

DIE management, because DWARF loves an acronym and we love a main character:

  • dwarf_add_die_to_debug() — Set the root debugging information entry for a DWARF producer instance.
  • dwarf_die_link() — Links debugging information entries.
  • dwarf_new_die() — Allocate a new debugging information entry.

🌸 Initialization and Finalization 🌸

The functions dwarf_producer_init() and dwarf_producer_init_b() are used to initialize a producer instance. That’s the setup era, the “get ready with me” of the producer API.

When done, applications release resources using the function dwarf_producer_finish(). Clean up after yourself, bestie — no cap.

💜 Relocations and Sections 💜

  • dwarf_get_relocation_info() — Retrieve a relocation array from a producer instance.
  • dwarf_get_relocation_info_count() — Return the number of relocation arrays for a producer instance.
  • dwarf_get_section_bytes() — Retrieve the ELF byte stream for a section.
  • dwarf_reset_section_bytes() — Reset internal state for a producer instance.
  • dwarf_transform_to_disk_form() — Prepare byte streams for writing out.

🍓 Macros 🍓

  • dwarf_def_macro() — Add a macro definition.
  • dwarf_end_macro_file(), dwarf_start_macro_file() — Record macro file related information.
  • dwarf_undef_macro() — Note the removal of a macro definition.
  • dwarf_vendor_ext() — Enables storing macro information as specified in the DWARF standard.

🧚 Symbols, Expressions, Addresses and Offsets 🧚

This is the big group-chat of producer functions, and every single one is here:

  • dwarf_add_arange(), dwarf_add_arange_b() — Add address range information.
  • dwarf_add_directory_decl() — Add information about an include directory to a producer instance.
  • dwarf_add_fde_inst() — Add an operation to a frame descriptor entry.
  • dwarf_add_file_decl() — Add information about a source file to a producer instance.
  • dwarf_add_frame_cie() — Add call information to a frame descriptor.
  • dwarf_add_frame_fde(), dwarf_add_frame_fde_b() — Link a frame descriptor to a producer instance.
  • dwarf_add_funcname() — Add information about a function to a producer instance.
  • dwarf_add_line_entry() — Record mapping information between machine addresses and a source line.
  • dwarf_add_expr_addr(), dwarf_add_expr_addr_b() — Add a DW_OP_addr opcode to a location expression.
  • dwarf_add_expr_gen() — Add an operator to a location expression.
  • dwarf_add_pubname() — Add information about a global name to a producer instance.
  • dwarf_add_typename() — Add information about a type to a producer instance.
  • dwarf_add_varname() — Add information about a static variable to a producer instance.
  • dwarf_add_weakname() — Add information about a weak symbol to a producer instance.
  • dwarf_expr_current_offset() — Retrieve the current size of a location expression.
  • dwarf_expr_into_block() — Convert a location expression into a byte stream.
  • dwarf_fde_cfa_offset() — Append a DW_CFA_offset operation to a frame descriptor.
  • dwarf_lne_end_sequence(), dwarf_lne_set_address() — Note address ranges for source lines.
  • dwarf_new_expr() — Allocate a location expression descriptor.
  • dwarf_new_fde() — Allocate a frame descriptor.

⭐ Miscellaneous ⭐

The function dwarf_producer_set_isa() sets the instruction set architecture for the producer instance. That’s the little “what ISA are we in?” button, and it’s slaying.

💖 COMPATIBILITY 💖

This implementation is believed to be source compatible with the SGI/GNU DWARF(3) library, version 20110113.

Known differences with the SGI/GNU library include:

  • The memory management scheme used differs, in a backward-compatible way. See “Memory Management” above, for coding guidelines for portable applications.
  • There is provision for setting a library-wide error handler in addition to the per-debug context handlers supported by the SGI/GNU API, see the subsection “Error Handling” above.

🌈 Extensions 🌈

The following APIs are extensions specific to this implementation:

  • dwarf_attroffset()
  • dwarf_next_types_section()
  • dwarf_producer_set_isa()

🫶 SEE ALSO 🫶

👑 STANDARDS 👑

The DWARF standard is defined by The DWARF Debugging Information Format, Version 4, http://www.dwarfstd.org/.

🎀 HISTORY 🎀

The DWARF(3) API originated at Silicon Graphics Inc.

A BSD-licensed implementation of a subset of the API was written by John Birrell (<jb@FreeBSD.org>) for the FreeBSD project. The implementation was subsequently revised and completed by Kai Wang (<kaiwang27@users.sourceforge.net>).

Manual pages for this implementation were written by Joseph Koshy (<jkoshy@users.sourceforge.net>) and Kai Wang (<kaiwang27@users.sourceforge.net>).

💖 okay that’s the whole DWARF(3) tea — source/version: Debian; date: December 21, 2014; page: DWARF(3) 🫶✨

📦 where this page comes from