Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DWARF_SRCLINES(3)	 BSD Library Functions Manual	     DWARF_SRCLINES(3)

NAME
     dwarf_srclines -- retrieve	line number information	for a debugging	infor-
     mation 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 de-
     scriptor 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 num-
     ber 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)

BSD			       November	9, 2011				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dwarf_srclines&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help