DWARF_GET_MACRO_DETAILS(3)

🌸 NAME 🌸

dwarf_get_macro_details — retrieve macro information 💖

Okay so this is the manual page for dwarf_get_macro_details(3) from the Library Functions Manual, bestie, and it's serving DWARF Access Library realness. No cap.

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf) ✨

🧾 SYNOPSIS 🧾

#include <libdwarf.h>

int
dwarf_get_macro_details(Dwarf_Debug dbg, Dwarf_Off offset,
    Dwarf_Unsigned max_count, Dwarf_Signed *entry_cnt,
    Dwarf_Macro_Details **details, Dwarf_Error *err);

💅 DESCRIPTION 💅

Function dwarf_get_macro_details() retrieves info about macros associated with a DWARF debug context. Information about macro entries is returned as an array of descriptors of type Dwarf_Macro_Details, with each Dwarf_Macro_Details descriptor describing one macro information entry. Iconic. 👑

Argument dbg should reference a DWARF debug context allocated using dwarf_init(3). Argument offset is an offset, relative to the “.debug_macinfo” section, to the start of the desired macro information. Argument max_count specifies the maximum number of macro information entries to be returned, or 0 if all entries are to be returned. Argument entry_cnt should point to a location that will be set to the number of entries actually returned. Argument details should point to a location that will be set to a pointer to an array of Dwarf_Macro_Details descriptors. If argument err is not NULL, it will be used to store error information in case of an error.

Dwarf_Macro_Details descriptors are defined in the header file <libdwarf.h>, and consist of the following fields:

• dmd_offset — The section-relative offset within the “.debug_macinfo” section of the macro information entry being described.
• dmd_type — The type code of this macro information entry; one of the DW_MACINFO_* constants defined by the DWARF specification.
• dmd_lineno — The line number associated with the macro information entry, or 0 if there is no applicable line number.
• dmd_fileindex — The source file index for the macro information entry. This field is only meaningful when the dmd_type field is set to DW_MACINFO_start_file.
• dmd_macro — The contents of this field is a pointer to a NUL-terminated string whose meaning depends on the value of the dmd_type field:
  • DW_MACINFO_define — The returned string contains the macro name and value.
  • DW_MACINFO_undef — The string holds the macro name.
  • DW_MACINFO_vendor_ext — The dmd_macro field points to a vendor defined string.
  • The field is NULL for other values of dmd_type.

🧠 Memory Management 🧠

The memory area used for the array of Dwarf_Macro_Details descriptors returned in argument details is owned by the DWARF Access Library (libdwarf, -ldwarf). The application should not attempt to directly free this pointer. Portable code should instead use dwarf_dealloc() with the allocation type DW_DLA_STRING to indicate that the memory may be freed. Don't be out here directly freeing that library-owned pointer, bestie — that's not the vibe. 💀

🔁 RETURN VALUES 🔁

Function dwarf_get_macro_details() returns DW_DLV_OK when it succeeds. It returns DW_DLV_NO_ENTRY if there is no more macro information at the specified offset offset. In case of an error, it returns DW_DLV_ERROR and sets the argument err.

🧪 EXAMPLES 🧪

To loop through all the macro information entries associated with a DWARF debug context:

             Dwarf_Debug dbg;
             Dwarf_Unsigned offset;
             Dwarf_Signed cnt;
             Dwarf_Macro_Details *md;
             Dwarf_Error de;

             offset = 0;
             while (dwarf_get_macro_details(dbg, offset, 0,
                 &cnt, &md, &de) == DW_DLV_OK) {
                     for (i = 0; i < cnt; i++) {
                             /* Access fields of md[i] ... */
                     }
                     offset = md[cnt - 1].dmd_offset + 1;
             }

🚨 ERRORS 🚨

Function dwarf_get_macro_details() can fail with:

• [DW_DLE_ARGUMENT] — One of the arguments dbg, entry_cnt or details was NULL.
• [DW_DLE_NO_ENTRY] — There is no more macro information at the specified offset offset.

👀 SEE ALSO 👀

dwarf(3), dwarf_dealloc(3), dwarf_find_macro_value_start(3), dwarf_init(3)

---

xoxo bestie 💖 this one is from Debian, dated March 20, 2011, and it is the DWARF_GET_MACRO_DETAILS(3) page — slay and stay curious ✨🫶