DWARF_SRCLINES(3)

✨ DWARF_SRCLINES(3) ✨

okay so bestie, you know how we found the Library Functions Manual the other day? this is one of those pages 💅 it lives in libdwarf and it's genuinely iconic if you're into debug info (iykyk).

---

🎀 NAME 🎀

dwarf_srclines — go get the line number info for a debugging information entry. literally its whole job 🫶

---

📚 LIBRARY 📚

DWARF Access Library (libdwarf, -ldwarf) — that's the one, no cap.

---

🌸 SYNOPSIS 🌸

#include <libdwarf.h>

int
dwarf_srclines(Dwarf_Die die, Dwarf_Line **lines, Dwarf_Signed *nlines,
    Dwarf_Error *err);

---

💖 DESCRIPTION 💖

Function dwarf_srclines() hands you back the line number information that's associated with a compilation unit. and like, it comes back as an array of Dwarf_Line descriptors. a whole squad of them. 💅

the die argument should reference a DWARF debugging information entry descriptor that has line number information — peek dwarf(3) if you need the lore. the lines argument should point to a location that's gonna hold a pointer to the returned array of Dwarf_Line descriptors. the nlines argument should point to a location that's gonna hold the number of descriptors returned (yes, you get a count, we love a count). and if the err argument is not NULL, it gets used to store error information in case something goes wrong. 🫶

the Dwarf_Line descriptors you get back are meant to be passed along to the other line number functions in the API set, so you can pull specific info about each source line. it's giving teamwork. ✨

🦋 Memory Management 🦋

okay this part matters, listen up 🙈 the memory area used for that array of Dwarf_Line descriptors returned in the lines argument is owned by the DWARF Access Library (libdwarf, -ldwarf). so the application should not attempt to free this pointer. like, don't. portable code should instead use dwarf_srclines_dealloc() to indicate that the memory may be freed. periodt. 💀

---

🔥 RETURN VALUES 🔥

Function dwarf_srclines() returns DW_DLV_OK when it succeeds — slay. in case of an error, it returns DW_DLV_ERROR and sets the err argument. so check it, bestie. ⭐

---

🌈 EXAMPLES 🌈

to obtain an array of Dwarf_Line descriptors and to retrieve the source file, line number, and virtual address associated with each descriptor:

      int n;
      Dwarf_Die die;
      Dwarf_Error de;
      char *filename;
      Dwarf_Line *lines;
      Dwarf_Signed nlines;
      Dwarf_Addr lineaddr;
      Dwarf_Unsigned lineno;

      /* variable "die" should reference a DIE for a compilation unit */

      if (dwarf_srclines(die, &lines, &nlines, &de) != DW_DLV_OK)
              errx(EXIT_FAILURE, "dwarf_srclines: %s", dwarf_errmsg(de));

      for (n = 0; n < nlines; n++) {
              /* Retrieve the file name for this descriptor. */
              if (dwarf_linesrc(lines[n], &filename, &de))
                      errx(EXIT_FAILURE, "dwarf_linesrc: %s",
                          dwarf_errmsg(de));

              /* Retrieve the line number in the source file. */
              if (dwarf_lineno(lines[n], &lineno, &de))
                      errx(EXIT_FAILURE, "dwarf_lineno: %s",
                          dwarf_errmsg(de));
              /* Retrieve the virtual address for this line. */
              if (dwarf_lineaddr(lines[n], &lineaddr, &de))
                      errx(EXIT_FAILURE, "dwarf_lineaddr: %s",
                          dwarf_errmsg(de));
              }

---

💀 ERRORS 💀

Function dwarf_srclines() can fail with:

• [DW_DLE_ARGUMENT] — one of the arguments die, lines or nlines was NULL. (girl. come on. 🙈)
• [DW_DLE_NO_ENTRY] — the compilation unit referenced by argument die does not have associated line number information. it's giving empty vibes.
• [DW_DLE_MEMORY] — an out of memory condition was encountered during the execution of this function. 😭

---

👑 SEE ALSO 👑

dwarf(3), dwarf_line_srcfileno(3), dwarf_lineaddr(3), dwarf_linebeginstatement(3), dwarf_lineblock(3), dwarf_lineendsequence(3), dwarf_lineno(3), dwarf_lineoff(3), dwarf_linesrc(3), dwarf_srcfiles(3), dwarf_srclines_dealloc(3)

---

and that's the page, bestie 🧚 this one's from Debian, dated November 9, 2011 — oldie but a goodie, fr fr. mwah 💋 go read your line tables. 🌸