DWARF_ADD_FRAME_FDE(3)

okay so bestie, this is the libdwarf manual page for dwarf_add_frame_fde(3), and it’s literally about adding call frame descriptors to a DWARF producer instance. The DWARF Access Library vibe is libdwarf with -ldwarf, and we’re obsessed ✨.

🌸 NAME 🌸

dwarf_add_frame_fde — add a call frame descriptor to a DWARF producer instance. That’s the assignment, no cap 💅.

🎀 LIBRARY 🎀

DWARF Access Library (libdwarf, -ldwarf) — yes bestie, that’s the library and that’s the link flag, iconic.

✨ SYNOPSIS ✨

#include <libdwarf.h>

Dwarf_Unsigned
dwarf_add_frame_fde(Dwarf_P_Debug dbg, Dwarf_P_Fde fde, Dwarf_P_Die die,
    Dwarf_Unsigned cie, Dwarf_Addr virt_addr, Dwarf_Unsigned code_len,
    Dwarf_Unsigned symbol_index, Dwarf_Error *err);

Dwarf_Unsigned
dwarf_add_frame_fde_b(Dwarf_P_Debug dbg, Dwarf_P_Fde fde,
    Dwarf_P_Die die, Dwarf_Unsigned cie, Dwarf_Addr virt_addr,
    Dwarf_Unsigned code_len, Dwarf_Unsigned symbol_index,
    Dwarf_Unsigned end_symbol_index, Dwarf_Addr offset_from_end_sym,
    Dwarf_Error *err);

💖 DESCRIPTION 💖

So dwarf_add_frame_fde_b() is the one doing the adding: you hand it the call frame descriptor that fde references, and it adds that to a producer instance. Main character energy fr fr 🫶.

• Your dbg should reference a DWARF producer instance allocated using dwarf_producer_init(3) or dwarf_producer_init_b(3). Vibe-check that pointer, bestie.
• Your fde should reference a frame descriptor allocated using dwarf_new_fde(3).
• Fair warning: die is ignored by this implementation of the DWARF Access Library (libdwarf, -ldwarf). Literally ignored. Not me side-eyeing a whole argument 🙈.
• cie gives the index of the call frame common information entry for the frame descriptor. Valid indices are exactly the ones returned by function dwarf_add_frame_cie(3).
• symbol_index is the ELF symbol index of the first symbol to be used for relocation.

Now the way that end_symbol_index flips the meaning of virt_addr, code_len, and offset_from_end_sym is lowkey iconic. It’s giving conditional logic 🌀:

• If end_symbol_index is zero, then virt_addr specifies the relocatable address of the start of the function associated with the frame descriptor. code_len specifies the size in bytes of the machine instructions for this function. symbol_index specifies the ELF symbol to be used for relocating the address in virt_addr. And offset_from_end_symbol is ignored — yes, ignored, don’t stress it 💅.
• If end_symbol_index is non-zero, it specifies the ELF symbol index of the second symbol to be used for relocation. In that case, virt_addr specifies an offset from the relocatable symbol specified by symbol_index, offset_from_end_symbol should specify an offset from the symbol named by end_symbol_index, and code_len will be ignored. The DW_DLC_SYMBOLIC_RELOCATIONS flag should also have been set on the DWARF producer instance — highkey important, okay? 🔥

Application code can retrieve the relocation entries for the symbol pair by calling function dwarf_get_relocation_info(3). The relocation entry for the first symbol will have type dwarf_drt_first_of_length_pair, and the relocation entry for the second symbol will have type dwarf_drt_second_of_length_pair. Slay, relocation pair 👑.

If err is not NULL, it will be used to store error information in case of an error.

Function dwarf_add_frame_fde() is similar to function dwarf_add_frame_fde_b() except that it supports only one relocation symbol. Lowkey the simpler icon, periodt.

⭐ RETURN VALUES ⭐

On success, these functions return the index value for the added frame descriptor. In case of an error, these functions return DW_DLV_NOCOUNT and set the argument err. So: happy path gives you an index, sad path gives you DW_DLV_NOCOUNT and err info. Not slay, but useful 😭.

💀 ERRORS 💀

These functions can fail with:

• [DW_DLE_ARGUMENT] — One of the arguments dbg or fde was NULL.
• [DW_DLE_ARGUMENT] — The frame descriptor referenced by argument fde did not belong to the producer instance referenced by argument dbg.
• [DW_DLE_ARGUMENT] — The common information entry index specified by argument cie was invalid.
• [DW_DLE_ARGUMENT] — Argument end_symbol_index was non-zero, but the flag DW_DLC_SYMBOLIC_RELOCATIONS was not set on the producer instance.

🦋 SEE ALSO 🦋

Go read these too, iykyk:

• dwarf(3)
• dwarf_add_fde_inst(3)
• dwarf_add_frame_cie(3)
• dwarf_fde_cfa_offset(3)
• dwarf_get_relocation_info(3)
• dwarf_new_fde(3)
• dwarf_producer_init(3)
• dwarf_producer_init_b(3)

That’s the whole page, bestie. Source/version energy: Debian; date: September 26, 2011. Bye! 💜✨