DWARF_ADD_FILE_DECL(3)

💖 DWARF_ADD_FILE_DECL 💖

okay so bestie, this is a libdwarf page — the DWARF Access Library, aka libdwarf, linked with -ldwarf. It's the one that lets you tell a debug-info producer "hey, there's a source file, here's its info" 🎀

---

✨ NAME ✨

dwarf_add_file_decl — add a source file entry to a producer instance 🗂️

---

🌸 LIBRARY 🌸

DWARF Access Library (libdwarf, -ldwarf)

---

🦋 SYNOPSIS 🦋

#include <libdwarf.h>

Dwarf_Unsigned
dwarf_add_file_decl(Dwarf_P_Debug dbg, char *name,
    Dwarf_Unsigned dirndx, Dwarf_Unsigned mtime, Dwarf_Unsigned size,
    Dwarf_Error *err);

---

💅 DESCRIPTION 💅

So dwarf_add_file_decl() does exactly what it says on the tin — it adds a source file entry to a producer instance. iconic behavior, no notes 🔥

The dbg argument should reference a DWARF producer instance that you allocated using dwarf_producer_init(3) or dwarf_producer_init_b(3). Like, that's the whole vibe — you need the producer first, iykyk.

The name argument should point to a NUL-terminated string containing the name of the source file. literally just the filename, bestie 🍓

Now here's the part where you gotta pay attention 👀 If the file name in name is not a fully qualified pathname, then dirndx should specify the index of the directory where the source file resides. Otherwise — if it is fully qualified — dirndx should be 0. And like, valid directory indices are the ones returned by dwarf_add_directory_decl(3). so don't just make up numbers pls 🙈

The mtime argument specifies the time when the file was last modified ⏰

The size argument specifies the size of the file in bytes 📏

And if err is not NULL, it'll be used to store error information in case of an error. (if it is NULL, then no error info for you, bestie — that's the trade.)

---

🌈 RETURN VALUES 🌈

On success, dwarf_add_file_decl() returns the index value generated for the source file. cute, useful, slay ✨

In case of an error, it returns DW_DLV_NOCOUNT and sets the argument err. sad but honest 😭

---

💀 ERRORS 💀

dwarf_add_file_decl() can fail with:

• [DW_DLE_ARGUMENT] — Either arguments dbg or name was NULL. yeah, one of them was just... not there 🫠
• [DW_DLE_ARGUMENT] — The length of the NUL-teminated string pointed to by argument name was 0. empty string energy, and not the fun kind 💀
• [DW_DLE_MEMORY] — An out of memory condition was encountered during the execution of the function. the classic 😮‍💨

heads up: those first two are both [DW_DLE_ARGUMENT], so don't go thinking they're one error — they're two separate ways to be wrong 🙈

---

👑 SEE ALSO 👑

dwarf(3), dwarf_add_directory_decl(3), dwarf_add_line_entry(3), dwarf_lne_end_sequence(3), dwarf_lne_set_address(3), dwarf_producer_init(3), dwarf_producer_init_b(3)

---

okay and that's the whole page, bestie — go forth and declare your files 🧚💜

Debian · September 17, 2011 · DWARF_ADD_FILE_DECL(3) — mwah, that's the sign-off, dated and sourced and everything 🎀💖