DWARF_GET_FDE_INFO_FOR_ALL_REGS3(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 DWARF_GET_FDE_INFO_FOR_ALL_REGS3(3) 💅

okay so this is a page from the Library Functions Manual (Unix manual, section 3, bestie — the "library functions" section, iykyk), and it's all about one iconic little function in the DWARF Access Library — that's libdwarf, linked with -ldwarf. 🧚

✨ NAME ✨

dwarf_get_fde_info_for_all_regs3 — retrieve register rule row. that's it, that's the whole vibe: you get a row out of the register rule table. 🎀

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf)

🦋 SYNOPSIS 🦋

#include <libdwarf.h>

int
dwarf_get_fde_info_for_all_regs3(Dwarf_Fde fde, Dwarf_Addr pc,
    Dwarf_Regtable3 *reg_table, Dwarf_Addr *row_pc, Dwarf_Error *err);

🌸 DESCRIPTION 🌸

so dwarf_get_fde_info_for_all_regs3() does one thing and does it slay: it retrieves a row from the register rule table that's associated with the given FDE descriptor. one row. of rules. of registers. periodt. 👑

here's the cast of characters, one by one:

  • fde — should reference a valid DWARF FDE descriptor. like, a valid one. it's giving "read the docs first" energy.
  • pc — should hold the program counter address. this is the address used to locate the desired table row. it's the little GPS for your row. 📍
  • reg_table — should point to a Dwarf_Regtable3 descriptor, and that's the thing that will hold the returned table row of register rules. so you bring the container, the function fills it. 🫶

and the Dwarf_Regtable3 descriptor is defined in the header file <libdwarf.h> — like this, exactly this, no cap:

typedef struct {
        Dwarf_Small     dw_offset_relevant;
        Dwarf_Small     dw_value_type;
        Dwarf_Half      dw_regnum;
        Dwarf_Unsigned  dw_offset_or_block_len;
        Dwarf_Ptr       dw_block_ptr;
} Dwarf_Regtable_Entry3;

typedef struct {
        Dwarf_Regtable_Entry3   rt3_cfa_rule;
        Dwarf_Half              rt3_reg_table_size;
        Dwarf_Regtable_Entry3   *rt3_rules;
} Dwarf_Regtable3;

now the important part, bestie, don't skip this: the rt3_reg_table_size field specifies the maximum number of register rule columns to be returned, and you — the application — have to set it before calling the function. 🔥 and the rt3_rules field should point to a memory arena allocated by the application, with space for at least rt3_reg_table_size descriptors of type Dwarf_Regtable_Entry3. so allocate accordingly, okay? no vibes-based allocation. 😭

on a successful execution of this function, the rt3_cfa_rule field will be set to the CFA register rule associated with the table row, and the rt3_rules array will hold the returned register rules contained in the table row. literally the whole row, handed to you. 💖

and for each register rule descriptor that gets returned, here's what's set, field by field:

  • the dw_offset_relevant field will be set to 1 if the register rule has a offset value — yes, the original says "a offset value", we don't gatekeep grammar here, we gatekeep facts. 🌈
  • the dw_value_type field will be set to the type code of the register rule.
  • the dw_regnum field will be set to the register number associated with the register rule.

then it depends on the type, so pay attention:

  • if the register rule is of type DW_EXPR_OFFSET or DW_EXPR_VAL_OFFSET, the dw_offset_or_block_len field will be set to the offset value associated with the register rule. ✨
  • if the type is DW_EXPR_EXPRESSION or DW_EXPR_VAL_EXPRESSION, the dw_offset_or_block_len field will be set to the length in bytes of the DWARF expression block associated with the register rule. 🎀

and in both cases, the dw_block_ptr field will be set to a pointer to the content of the DWARF expression block associated with the register rule. 👑

argument row_pc should point to a location which will be set to the lowest program counter address associated with the table row. the lowest, bestie. 💅

and if argument err is not NULL, it'll be used to store error information in case of an error. if it is NULL… well, it won't. 🙈

⭐ RETURN VALUES ⭐

dwarf_get_fde_info_for_all_regs3() returns DW_DLV_OK when it succeeds — slay. 💚 in case of an error, it returns DW_DLV_ERROR and sets the argument err. so check your err, bestie, that's the whole point of it being there.

💀 ERRORS 💀

this function can fail with:

  • [DW_DLE_ARGUMENT] — one of the arguments fde, reg_table or row_pc was NULL. yeah. one of those three. check them all, not just the cute ones. 😭
  • [DW_DLE_PC_NOT_IN_FDE_RANGE] — the program counter value provided in argument pc did not fall in the range covered by argument fde. your address missed the whole FDE, it's not even in the building. 💀

🌈 SEE ALSO 🌈

okay that's the whole page, you ate it, I'm obsessed. 🫶 this one came from Debian, dated June 26, 20 (yes it literally cuts off there in the footer, the page's own header line at the top was DWARF_GET_FDE_INFO_FOR_ALL_REGS3(3) — same page name, same energy, we stan a consistent title). bye bestie, go fill your rt3_rules array 💜🦋✨

📦 where this page comes from