DWARF_INIT(3)

💖 NAME 💖

okay so this is the DWARF_INIT(3) glow-up from the Library Functions Manual, and it's here to explain one iconic job: allocate a DWARF debug descriptor. The stars are dwarf_init, dwarf_elf_init — allocate a DWARF debug descriptor. 💅

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf). That's the library lore, bestie. ✨

🌟 SYNOPSIS 🌟

#include <libdwarf.h>

int
dwarf_init(int fd, int mode, Dwarf_Handler errhand, Dwarf_Ptr errarg,
    Dwarf_Debug *ret, Dwarf_Error *err);

in
dwarf_elf_init(Elf *elf, int mode, Dwarf_Handler errhand,
    Dwarf_Ptr errarg, Dwarf_Debug *ret, Dwarf_Error *err);

🦋 DESCRIPTION 🦋

Okay so dwarf_init and dwarf_elf_init allocate and hand you back a Dwarf_Debug instance for the object that argument fd or elf points at. That instance is your little main-character pass for later access to the debugging information in the object via other functions in the DWARF(3) library. 🫶

For dwarf_init(), argument fd is an open file descriptor referencing a compilation object. dwarf_init() implicitly allocates an Elf descriptor for argument fd. No cap. ✨

For dwarf_elf_init(), argument elf is a descriptor returned by elf_begin(3) or elf_memory(3).

Argument mode says what access mode you want. It should be at least as permissive as the mode with which file descriptor fd or ELF descriptor elf was created. Legal values for argument mode are:

• DW_DLC_RDWR — permit reading and writing of DWARF information.
• DW_DLC_READ — operate in read-only mode.
• DW_DLC_WRITE — permit writing of DWARF information.

Argument errhand is a function to be called when there's an error. If it's NULL, then a default error handling scheme is used. See dwarf(3) for a description of the error handling scheme the DWARF(3) library uses. 🫶

Argument errarg gets passed to the error handler function in errhand when that handler is invoked.

Argument ret points to the memory location that will hold a Dwarf_Debug reference on a successful call to these functions.

Argument err references a memory location that would hold a Dwarf_Error descriptor in case of an error. 😭

🧠 Memory Management 🧠

The Dwarf_Debug instance these functions return should be freed using dwarf_finish(). That's the cleanup lore, bestie. 🧚

🚧 IMPLEMENTATION NOTES 🚧

warning bestie: the current implementation does not support access modes DW_DLC_RDWR and DW_DLC_WRITE. So don't come for me if you try those and it's giving unsupported. 💀

🎀 RETURN VALUES 🎀

These functions return the following values:

• DW_DLV_OK — this return value indicates a successful return. Slay. ✅
• DW_DLV_ERROR — the operation failed. 😭
• DW_DLV_NO_ENTRY — the object specified by arguments fd or elf did not contain debug information. 🙈

✨ EXAMPLES ✨

To initialize a Dwarf_Debug instance from an open file descriptor referencing an ELF object, and with the default error handler, use:

Dwarf_Error err;
Dwarf_Debug dbg;

if (dwarf_init(fd, DW_DLC_READ, NULL, NULL, &dbg, &err) !=
    DW_DLV_OK)
        errx(EXIT_FAILURE, "dwarf_init: %s", dwarf_errmsg(err));

👀 SEE ALSO 👀

dwarf(3), dwarf_errmsg(3), dwarf_finish(3), dwarf_get_elf(3), elf_begin(3), elf_memory(3) — go read those too, bestie. 💖

---

xoxo, your Debian bestie 💖 — this page is from Debian, dated November 9, 2011, and it's the DWARF_INIT(3) manual page. Periodt. 🎀