DWARF_ADD_ARANGE(3)

💅 DWARF_ADD_ARANGE(3) — the libdwarf producer page bestie

okay so this is a page from the Library Functions Manual for DWARF_ADD_ARANGE(3), and it lives in the DWARF Access Library — so when you link it, you link libdwarf, like -ldwarf. that's it, that's the library. 🎀

---

✨ NAME ✨

dwarf_add_arange, dwarf_add_arange_b — besties, these two literally add address range information to a DWARF producer instance. that's the whole job. 💖

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf) — yep, that's where they live, no cap.

🧚 SYNOPSIS 🧚

#include <libdwarf.h>

Dwarf_Unsigned
dwarf_add_arange(Dwarf_P_Debug dbg, Dwarf_Addr start,
    Dwarf_Unsigned length, Dwarf_Signed symbol_index, Dwarf_Error *err);

Dwarf_Unsigned
dwarf_add_arange_b(Dwarf_P_Debug dbg, Dwarf_Addr start,
    Dwarf_Unsigned length, Dwarf_Unsigned symbol_index,
    Dwarf_Unsigned end_symbol_index, Dwarf_Addr offset_from_end_symbol,
    Dwarf_Error *err);

like, copy these signatures exactly, okay? the Dwarf_Signed vs Dwarf_Unsigned thing on symbol_index is not a typo and it's not me being sloppy, it's giving deprecated-function energy (more on that below 👀).

🌸 DESCRIPTION 🌸

so dwarf_add_arange_b() adds an address range entry to a producer instance. that's the main character here. 💫

Argument dbg — this should reference a DWARF producer instance that you allocated using dwarf_producer_init(3) or dwarf_producer_init_b(3). no random pointers, bestie, i'm begging.

Argument start — this specifies the relocatable start address of the address range.

Argument length — this specifies the length of the address range. yes, it does what it says. iconic. ✨

Argument symbol_index — this specifies the ELF symbol index of the first symbol to be used for relocation.

Argument end_symbol_index — this specifies the ELF symbol index of the second symbol to be used for relocation.

and here's where the ✨vibes✨ split, so pay attention:

• if argument end_symbol_index is not 0, then the DW_DLC_SYMBOLIC_RELOCATIONS flag should have been set on the DWARF producer instance — like, this is the expectation, okay? 🫶 the address value specified by argument start will be treated as an offset value from the first symbol, and argument offset_from_end_symbol should hold an offset value from the second symbol. your application code can retrieve the relocation entries for the symbol pair by calling function dwarf_get_relocation_info(3). and the receipts: 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. iykyk. 🔥
• if argument end_symbol_index is 0, then argument offset_from_end_symbol will be ignored 🙈 and only one symbol is used for relocation. simple as that.

Argument err — if it's not NULL, it will be used to store error information in case of an error. so like, pass a pointer if you want the tea when things go wrong.

⚠️ okay so listen: function dwarf_add_arange() is deprecated. 💀 it's similar to function dwarf_add_arange_b() except that it cannot handle all possible symbol index values and supports only one relocation symbol. so it's lowkey the older sibling that didn't get the upgrade. use the _b version if you can, bestie.

🦋 RETURN VALUES 🦋

On success, these functions return a non-zero value. 🎉 in case of an error, these functions return 0 and set the argument err. so zero is the bad-vibes number here, don't get it twisted.

💀 ERRORS 💀

These functions can fail with:

• [DW_DLE_ARGUMENT] — Argument dbg was NULL. 😭 like bestie no, you have to actually give it a producer instance.
• [DW_DLE_ARGUMENT] — Argument end_symbol_index was non-zero, but the flag DW_DLC_SYMBOLIC_RELOCATIONS was not set on the producer instance. 🚩 you skipped the flag, didn't you.
• [DW_DLE_MEMORY] — An out of memory condition was encountered during the execution of the function. 💀 the classic.

🌈 SEE ALSO 🌈

dwarf(3), dwarf_get_relocation_info(3), dwarf_producer_init(3), dwarf_producer_init_b(3)

go read those, they're all part of the same friend group fr fr. 🫶

---

and that's the whole page, bestie! 🧚💜 this cutie dropped from Debian on September 18, 2011, so yeah, it's been serving these exact facts since before some of us could even read. respect the icon. 👑🎀✨