NAME
dwarf_srclines —
retrieve line number
information for a debugging information entry
LIBRARY
DWARF Access Library (libdwarf, -ldwarf)
SYNOPSIS
#include <libdwarf.h>
int
dwarf_srclines(
Dwarf_Die die,
Dwarf_Line **lines,
Dwarf_Signed
*nlines,
Dwarf_Error *err);
DESCRIPTION
Function
dwarf_srclines() returns line number information
associated with a compilation unit. Line number information is returned as an
array of
Dwarf_Line descriptors.
Argument
die should reference a DWARF debugging
information entry descriptor with line number information, see
dwarf(3). Argument
lines should point to a location that will hold a
pointer to the returned array of
Dwarf_Line descriptors.
Argument
nlines should point to a location that will
hold the number of descriptors returned. If argument
err
is not NULL, it will be used to store error information in case of an error.
The returned
Dwarf_Line descriptors may be passed to the
other line number functions in the API set to retrieve specific information
about each source line.
Memory Management
The memory area used for the array of
Dwarf_Line
descriptors returned in argument
lines is owned by the
DWARF Access Library (libdwarf, -ldwarf). The
application should not attempt to free this pointer. Portable code should
instead use
dwarf_srclines_dealloc() to indicate that the
memory may be freed.
RETURN VALUES
Function
dwarf_srclines() returns
DW_DLV_OK
when it succeeds. In case of an error, it
returns
DW_DLV_ERROR
and sets the argument
err.
ERRORS
Function
dwarf_srclines() can fail with:
-
-
- [
DW_DLE_ARGUMENT
]
- One of the arguments die,
lines or nlines was NULL.
-
-
- [
DW_DLE_NO_ENTRY
]
- The compilation unit referenced by argument
die does not have associated line number
information.
-
-
- [
DW_DLE_MEMORY
]
- An out of memory condition was encountered during the
execution of this function.
EXAMPLE
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));
}
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)