DWARF_LOCLIST_FROM_EXPR(3)

✨ DWARF_LOCLIST_FROM_EXPR — bestie's guide to translating DWARF location expression bytes ✨

okay so this is a libdwarf page — the manual is Library Functions Manual, and it's all about turning raw DWARF location expression bytes into something your program can actually read. three functions, one job family. let's go 🫶

---

🌸 NAME

• dwarf_loclist_from_expr
• dwarf_loclist_from_expr_a
• dwarf_loclist_from_expr_b

all three translate DWARF location expression bytes. that's the whole vibe. 💅

🎀 LIBRARY

DWARF Access Library (libdwarf, -ldwarf)

⭐ SYNOPSIS

#include <libdwarf.h>

int
dwarf_loclist_from_expr(Dwarf_Debug dbg, Dwarf_Ptr bytes_in,
    Dwarf_Unsigned bytes_len, Dwarf_Locdesc **llbuf,
    Dwarf_Signed *listlen, Dwarf_Error *err);

int
dwarf_loclist_from_expr_a(Dwarf_Debug dbg, Dwarf_Ptr bytes_in,
    Dwarf_Unsigned bytes_len, Dwarf_Half addr_size,
    Dwarf_Locdesc **llbuf, Dwarf_Signed *listlen, Dwarf_Error *err);

int
dwarf_loclist_from_expr_b(Dwarf_Debug dbg, Dwarf_Ptr bytes_in,
    Dwarf_Unsigned bytes_len, Dwarf_Half addr_size,
    Dwarf_Half offset_size, Dwarf_Small version, Dwarf_Locdesc **llbuf,
    Dwarf_Signed *listlen, Dwarf_Error *error);

---

💖 DESCRIPTION

So. Function dwarf_loclist_from_expr() translates DWARF location expression bytes into a Dwarf_Locdesc descriptor. that's the whole point of it. the size used for address-related data is taken to be the default address size for the object being read — no cap, that's just how it's wired.

• Argument dbg should reference a DWARF debug context allocated using dwarf_init(3). like, it literally has to come from there, bestie. 🙈
• Argument bytes_in should point to an array of DWARF location expression bytes.
• Argument bytes_len should specify the number of the location expression bytes to be translated. this is you telling it how much to read, so don't be weird about it.
• Argument llbuf should point to a location which will be set to a pointer to a returned Dwarf_Locdesc descriptor. it gets filled in for you, iconic. ✨
• Argument listlen should point to a location which will hold the number of the Dwarf_Locdesc descriptors returned. and in this case? it is always set to 1. one and done, periodt.
• If argument err is not NULL, it will be used to store error information in case of an error.

Function dwarf_loclist_from_expr_a() is identical to function dwarf_loclist_from_expr(), except that it requires one additional argument addr_size, which specifies the address size to use when translating the location expression bytes. same girl, one extra parameter. 💁

Function dwarf_loclist_from_expr_b() is identical to function dwarf_loclist_from_expr_a() except that it requires two additional arguments for translating the location expression bytes. Argument offset_size specifies the offset size, and argument version specifies the DWARF version. these values are required to correctly translate the DW_OP_GNU_implicit_pointer opcode — like, that one opcode literally cannot be done right without them. iykyk. 🔥

🦋 Memory Management

the memory area used for the descriptor returned in argument llbuf is allocated by DWARF Access Library (libdwarf, -ldwarf). so when the descriptor is no longer needed, application code should use function dwarf_dealloc(3) to free the memory area in two steps:

1. First, the array of Dwarf_Loc descriptors pointed to by the ld_s field of the Dwarf_Locdesc descriptor should be deallocated using the allocation type DW_DLA_LOC_BLOCK.
2. Next, the application should free the llbuf pointer using the allocation type DW_DLA_LOCDESC.

please don't skip a step, bestie 😭 two steps, in that order, or the memory vibe check fails. also i'm just telling you what the page says — do not come for me.

---

🌈 RETURN VALUES

On success, these functions returns DW_DLV_OK. in case of an error, they return DW_DLV_ERROR and set the argument err. that's it, that's the whole mood. 💜

🍓 ERRORS

These functions may fail with the following errors — screenshot this for later:

• [DW_DLE_ARGUMENT] — one of the arguments dbg, bytes_in, llbuf or listlen was NULL. (yes, all four are checked, no hiding)
• [DW_DLE_ARGUMENT] — argument bytes_len was 0. zero bytes is not a translation, it's a nap.
• [DW_DLE_ARGUMENT] — the value of argument addr_size was invalid.
• [DW_DLE_LOC_EXPR_BAD] — an unknown or invalid operation was found in the location expression bytes provided in argument bytes_in. the bytes said something cursed, basically. 💀
• [DW_DLE_MEMORY] — an out of memory condition was encountered during the execution of this function.

🧚 SEE ALSO

dwarf(3), dwarf_dealloc(3), dwarf_get_fde_info_for_all_regs3(3), dwarf_get_fde_info_for_cfa_reg3(3), dwarf_get_fde_info_for_reg3(3), dwarf_get_loclist_entry(3), dwarf_loclist_n(3)

go read those too, they're the friend group. 👑

---

and that's the page!! this version came out of Debian, dated December 21, 2014, and it belongs to the DWARF_LOCLIST_FROM_EXPR(3) manual. mwah, slay, go free your descriptors responsibly 💅🎀🫶