DWARF_ADD_FRAME_CIE(3)

💅 DWARF_ADD_FRAME_CIE(3) — the libdwarf glow-up, bestie edition

okay so real talk, this is page DWARF_ADD_FRAME_CIE(3) from the Library Functions Manual, and it's about making one (1) call frame CIE. that's it. that's the post. let's get into it 🎀

---

✨ NAME ✨

dwarf_add_frame_cie — adds a call frame common information entry to a DWARF producer instance. literally what it says on the tin, no plot twist 🦋

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf). link it, love it, don't forget the -ldwarf 💅

🫶 SYNOPSIS 🫶

#include <libdwarf.h>

Dwarf_Unsigned
dwarf_add_frame_cie(Dwarf_P_Debug dbg, char *augmenter, Dwarf_Small caf,
    Dwarf_Small daf, Dwarf_Small ra, Dwarf_Ptr initinst,
    Dwarf_Unsigned initlen, Dwarf_Error *err);

like, look at that signature. seven args. she's high maintenance and she's worth it 👑

🌸 DESCRIPTION 🌸

so dwarf_add_frame_cie() adds a DWARF call frame common information entry (CIE — yes, the acronym, we're being fancy) to a producer instance. main character energy, honestly. ✨

here's the tea on every single argument, no skips:

• Argument dbg should reference a DWARF producer instance allocated using dwarf_producer_init(3) or dwarf_producer_init_b(3). don't just vibe in with a random pointer, she needs to be initialized first 💀
• Argument augmenter should point to a NUL-terminated augmentation string for the common information entry. yes, NUL-terminated. yes, that matters. 🔥
• Argument caf specifies the code alignment factor.
• Argument daf specifies the data alignment factor.
• Argument ra specifies the column number used for the return address register.
• Argument initinst should point to a byte stream containing the initial instructions for the common information entry. it's giving raw bytes, it's giving ✨artistry✨
• Argument initlen should hold the length in bytes of the byte stream pointed to by argument initinst. so like, initinst and initlen are a package deal, bestie. you don't bring one to the party without the other 🙈
• If argument err is not NULL, it will be used to store error information in case of an error. so if you do want the drama delivered directly to you, hand her an err pointer. if not, NULL is fine 🫶

ngl the alignment factors and return-address column feel like tiny details but they are NOT — they're exactly the details the CIE exists to hold, so get them right the first time, fr fr.

👑 RETURN VALUES 👑

On success, function dwarf_add_frame_cie() returns the index value of the created common information entry. yay! a number! she ate 💅

In case of an error, function dwarf_add_frame_cie() returns DW_DLV_NOCOUNT and sets the argument err. so like… if you see DW_DLV_NOCOUNT, that's your cue, the vibe check failed, go read err 😭

💀 ERRORS 💀

Function dwarf_add_frame_cie() can fail with:

• [DW_DLE_ARGUMENT] — Argument dbg was NULL. iconic mistake. tragic outcome. 🍓
• [DW_DLE_MEMORY] — An out of memory condition was encountered during the execution of the function. not her fault, the machine is just going through it 💀

🌈 SEE ALSO 🌈

the whole friend group, go say hi:

dwarf(3), dwarf_add_fde_inst(3), dwarf_add_frame_fde(3), dwarf_add_frame_fde_b(3), dwarf_fde_cfa_offset(3), dwarf_new_fde(3), dwarf_producer_init(3), dwarf_producer_init_b(3)

iykyk 🧚

---

and that's the page!! this one ships from Debian, dated September 26, 2011 — yes she's been serving CIE content since 2011 and she has not lost a step 💜 mwah, go build some call frames, bestie 🎀