DWARF_GET_PUBTYPES(3)

💖 DWARF_GET_PUBTYPES 💖

okay so bestie, this one's from the Library Functions Manual and it's literally all about the libdwarf girlies who fetch info about your user-defined types. stay with me, it's actually so good 🎀

---

✨ LIBRARY ✨

DWARF Access Library (libdwarf, -ldwarf) 🫶

---

🌸 SYNOPSIS 🌸

#include <libdwarf.h>

int
dwarf_get_pubtypes(Dwarf_Debug dbg, Dwarf_Type **types,
    Dwarf_Signed *ntypes, Dwarf_Error *err);

int
dwarf_pubtype_cu_offset(Dwarf_Type type, Dwarf_Off *cu_offset,
    Dwarf_Error *err);

int
dwarf_pubtype_die_offset(Dwarf_Type type, Dwarf_Off *die_offset,
    Dwarf_Error *err);

int
dwarf_pubtype_name_offsets(Dwarf_Type type, char **name,
    Dwarf_Off *die_offset, Dwarf_Off *cu_die_offset, Dwarf_Error *err);

int
dwarf_pubtypename(Dwarf_Type type, char **name, Dwarf_Error *err);

---

🦋 DESCRIPTION 🦋

So these functions pull info about file-scope, user-defined types that are recorded in lookup tables inside the .debug_pubtypes DWARF section. The info comes back to you in opaque descriptors of type Dwarf_Type — and bestie, opaque means you can't just peek inside them yourself, you have to use the functions below to get the name and offset info out of them. iykyk 💅

dwarf_get_pubtypes() grabs descriptors for all the user-defined types hanging out with the DWARF debug context you passed as dbg. The types argument should point to a spot that'll get set to a pointer to an array of Dwarf_Type descriptors, and ntypes should point to a spot that'll get set to the number of descriptors you got back. slay ✨

dwarf_pubtype_cu_offset() hands you the offset — relative to the .debug_info section — of the compilation unit that contains the debugging information entry associated with type. Point cu_offset at a location and it'll hold the returned offset for you.

dwarf_pubtype_die_offset() gets the offset — again, relative to .debug_info — of the debugging information entry associated with type, and stashes it in the location die_offset points to. 🎀

dwarf_pubtype_name_offsets() is the triple threat: it gets the name and the offsets for the debugging information entry of type. Here's the breakdown:

• name should point to a location that gets set to a pointer to a NUL-terminated string with the name of the associated debugging information entry.
• die_offset should point to a location that gets set to the offset — relative to .debug_info — of the associated debugging information entry.
• cu_die_offset should point to a location that gets set to the offset — relative to .debug_info — of the first debugging information entry in the compilation unit associated with type.

dwarf_pubtypename() sets the location name points to to a pointer to a NUL-terminated string holding the name of the debugging information entry associated with type. short n sweet fr fr 💖

🧚 Memory Management 🧚

The memory area for the array of Dwarf_Type descriptors you get back in types from dwarf_get_pubtypes() is owned by the DWARF Access Library (libdwarf, -ldwarf). Do not try to free that pointer directly, bestie — that's not your bag. Portable code should instead call dwarf_types_dealloc(3) to say "yeah this memory area can be freed now". 🙈

Same energy for the string that comes back in the name argument of dwarf_pubtype_name_offsets() and dwarf_pubtypename() — that memory area is owned by the DWARF Access Library (libdwarf, -ldwarf) too. Portable code should flag that it can be freed with dwarf_dealloc(3). 🫶

💀 Error Returns 💀

If err isn't NULL, these functions will use it to store error info whenever something goes wrong. very considerate of them honestly.

---

⭐ RETURN VALUES ⭐

On success, these functions return DW_DLV_OK. In case of an error, they return DW_DLV_ERROR and set the err argument. periodt. 👑

---

🌈 EXAMPLES 🌈

Wanna grab the list of file-scope user-defined types and print their names? say less:

Dwarf_Debug dbg;
Dwarf_Signed ntypes;
Dwarf_Type *types;
Dwarf_Error err;
int n, result;
char *typename;

/* Initialize dbg etc. */;
result = dwarf_get_pubtypes(dbg, &types, &ntypes, &err);
if (result != DW_DLV_OK) /* Handle the error. */
        ;

/* Iterate over the returned array of descriptors. */
for (n = 0; n < ntypes; n++) {
        result = dwarf_pubtypename(types[n], &typename, &err);
        if (result != DW_DLV_OK) /* Handle the error. */
                ;
        printf("%s\n", typename);
}

/* Deallocate the returned array. */
dwarf_types_dealloc(dbg, types, ntypes);

---

🔥 ERRORS 🔥

These functions may fail with the following errors:

• [DW_DLE_ARGUMENT] — one of the arguments cu_die_offset, cu_offset, dbg, die_offset, type, types, name, or ntypes was NULL. (yes, all of those. the whole squad.)
• [DW_DLE_NO_ENTRY] — the DWARF debugging context referenced by dbg just did not contain information about user-defined types. it's giving empty. 😭

---

👑 SEE ALSO 👑

dwarf(3), dwarf_dealloc(3), dwarf_get_cu_die_offset_given_cu_header_offset(3), dwarf_pubtypes_dealloc(3)

---

ngl the vibes here are immaculate — go read the whole dwarf family, they're iconic 💜

okay that's the whole page bestie, go forth and fetch those pubtypes ✨💅🍓

Debian 🌸 April 4, 2011 — mwah, that's the source, the version and the date, and this page is officially a wrap 🎀🦋💖