DWARF_CHILD(3)

🦋 DWARF_CHILD(3) 🦋

okay so bestie, welcome to the DWARF_CHILD(3) page from the Library Functions Manual 💖 (folding that manual name in right here like a lil intro, because we're cute like that). This is the one about grabbing and walking DWARF Debugging Information Entry descriptors — DIE energy, literally. 🧚

🌸 NAME 🌸

dwarf_child, dwarf_offdie, dwarf_offdie_b, dwarf_siblingof, dwarf_siblingof_b — retrieve DWARF Debugging Information Entry descriptors. 🎀

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf) 🫶

✨ SYNOPSIS ✨

The exact spellings, no cap:

#include <libdwarf.h>

int
dwarf_child(Dwarf_Die die, Dwarf_Die *ret_die, Dwarf_Error *err);

int
dwarf_offdie(Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Die *ret_die,
    Dwarf_Error *err);

int
dwarf_offdie_b(Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Bool is_info,
    Dwarf_Die *ret_die, Dwarf_Error *err);

int
dwarf_siblingof(Dwarf_Debug dbg, Dwarf_Die die, Dwarf_Die *ret_die,
    Dwarf_Error *err);

int
dwarf_siblingof_b(Dwarf_Debug dbg, Dwarf_Die die, Dwarf_Die *ret_die,
    Dwarf_Bool is_info, Dwarf_Error *err);

💅 DESCRIPTION 💅

These functions are your little DIE-wranglers: they retrieve and traverse DWARF Debugging Information Entry (DIE) descriptors that belong to a compilation unit. 🌀 These descriptors are arranged in the form of a tree, and you traverse that tree using “child” and “sibling” links; peep dwarf(3) for more information. The Dwarf_Die opaque type is how we represent a DWARF Debugging Information Entry descriptor — mysterious, iconic, opaque. 👑

• dwarf_child() — retrieves the child of the descriptor denoted by argument die, and stores it in the location pointed to by argument ret_die. 🍼
• dwarf_siblingof() — retrieves the sibling of the descriptor denoted by argument die, and stores it in the location pointed to by argument ret_die. If argument die is NULL, the first debugging information entry descriptor for the current compilation unit will be returned. This function and dwarf_child() may be used together to traverse the tree of debugging information entry descriptors for a compilation unit. 👯
• dwarf_siblingof_b() — identical to dwarf_siblingof() except that it can retrieve the sibling descriptor from either the current compilation unit or type unit. If argument is_info is non-zero, the function behaves identically to dwarf_siblingof(). If argument is_info is zero, the descriptor referred by argument die should be associated with a debugging information entry in the type unit. The function will store the sibling of the descriptor in the location pointed to by argument ret_die. If argument is_info is zero and argument die is NULL, the first debugging information entry descriptor for the current type unit will be returned. 🦋
• dwarf_offdie() — retrieves the debugging information entry descriptor at global offset offset in the .debug_info section of the object associated with argument dbg. The returned descriptor is written to the location pointed to by argument ret_die. 📍
• dwarf_offdie_b() — identical to dwarf_offdie() except that it can retrieve the debugging information entry descriptor at global offset offset from either of the .debug_info and .debug_types sections of the object associated with argument dbg. If argument is_info is non-zero, the function will retrieve the debugging information entry from the .debug_info section, otherwise the function will retrieve the debugging information entry from the .debug_types section. The returned descriptor is written to the location pointed to by argument ret_die. 🗂️

🧠 Memory Management 🧠

The memory area used for the Dwarf_Die descriptor returned in argument ret_die is allocated by the DWARF Access Library (libdwarf, -ldwarf). Application code should use function dwarf_dealloc() with the allocation type DW_DLA_DIE to free the memory area when the Dwarf_Die descriptor is no longer needed. Don't ghost it, free it bestie 💖

🎀 RETURN VALUES 🎀

These functions return the following values, and yes, each one has a vibe:

• [DW_DLV_OK] — the call succeeded. ✅
• [DW_DLV_ERROR] — the requested operation failed. Additional information about the error encountered will be recorded in argument err, if it is not NULL. 😭
• [DW_DLV_NO_ENTRY] — for functions dwarf_child(), dwarf_siblingof() and dwarf_siblingof_b(), the descriptor denoted by argument die did not have a child or sibling. For functions dwarf_offdie() and dwarf_offdie_b(), there was no debugging information entry at the offset specified by argument offset. 🙈

🌈 EXAMPLES 🌈

Wanna retrieve the first DWARF Debugging Information Entry descriptor for the first compilation unit associated with a Dwarf_Debug instance, and traverse all its children? Say less, bestie. Do this, exactly:

             Dwarf_Debug dbg;
             Dwarf_Die die, die0;
             Dwarf_Error de;

             ... allocate dbg using dwarf_init() etc ...

             if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) !=
                 DW_DLV_OK)
                     errx(EXIT_FAILURE, "dwarf_next_cu_header: %s",
                         dwarf_errmsg(de));

             /* Get the first DIE for the current compilation unit. */
             die = NULL;
             if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK)
                     errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de));

             /* Get the first child of this DIE. */
             die = die0;
             if (dwarf_child(die, &die0, &de) != DW_DLV_OK)
                     errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de));

             /* Get the rest of children. */
             do {
                     die = die0;
                     if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR)
                             errx(EXIT_FAILURE, "dwarf_siblingof: %s",
                                 dwarf_errmsg(de));
             } while (die0 != NULL);

💀 ERRORS 💀

These functions may fail with the following errors, and they are not cute:

• [DW_DLE_ARGUMENT] — arguments dbg, die or ret_die were NULL. 🚫
• [DW_DLE_DIE_NO_CU_CONTEXT] — argument dbg was not associated with a compilation unit. 😵
• [DW_DLE_NO_ENTRY] — the descriptor denoted by argument die had no child or sibling, or there was no DWARF debugging information entry at the offset specified by argument offset. 🫥

👀 SEE ALSO 👀

dwarf(3), dwarf_errmsg(3), dwarf_get_die_infotypes_flag(3), dwarf_next_cu_header(3) ✨

---

xoxo, your Debian bestie 💅 — this one is from Debian, dated December 21, 2014, and it's the DWARF_CHILD(3) page. periodt. 🎀✨