dwarf_get_arange_info(3) [freebsd man page]

DWARF_GET_ARANGE_INFO(3)				   BSD Library Functions Manual 				  DWARF_GET_ARANGE_INFO(3)

NAME

     dwarf_get_arange_info -- extract address range information from a descriptor

LIBRARY

     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS

     #include <libdwarf.h>

     int
     dwarf_get_arange_info(Dwarf_Arange ar, Dwarf_Addr *start, Dwarf_Unsigned *length, Dwarf_Off *cu_die_offset, Dwarf_Error *err);

DESCRIPTION

     Function dwarf_get_arange_info() extracts address range information from a Dwarf_Arange descriptor.

     Argument ar should reference a valid Dwarf_Arange descriptor returned by function dwarf_get_aranges(3).

     Argument start should point to a location which will hold the start value of the address range associated with the descriptor.

     Argument length should point to a location which will hold the length in bytes of the address range associated with the descriptor.

     Argument cu_die_offset should point to a location which will be set to an offset, relative to the ``.debug_info'' section, of the first
     debugging information entry in the compilation unit associated with argument ar.

     If argument err is not NULL, it will be used to store error information in case of an error.

RETURN VALUES

     Function dwarf_get_arange_info() 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_get_arange_info() can fail with:

     [DW_DLE_ARGUMENT]	One of the arguments ar, start, length or cu_die_offset was NULL.

EXAMPLE

     To loop through all the address lookup table entries, use:

	   Dwarf_Debug dbg;
	   Dwarf_Addr start;
	   Dwarf_Arange *aranges;
	   Dwarf_Off die_off;
	   Dwarf_Signed i, cnt;
	   Dwarf_Unsigned length;
	   Dwarf_Error de;

	   if (dwarf_get_aranges(dbg, &aranges, &cnt, &de) != DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_get_aranges: %s",
		       dwarf_errmsg(de));
	   for (i = 0; i < cnt; i++) {
		   if (dwarf_get_arange_info(aranges[i], &start, &length,
		       &die_off, &de) != DW_DLV_OK) {
			   warnx("dwarf_get_arange_info: %s",
			       dwarf_errmsg(de));
			   continue;
		   }
		   /* Do something with the returned information. */
	   }

SEE ALSO

     dwarf(3), dwarf_get_arange(3), dwarf_get_aranges(3), dwarf_get_arange_cu_header_offset(3), dwarf_get_cu_die_offset(3)

BSD
								  April 16, 2011							       BSD

DWARF_GET_RANGES(3)					   BSD Library Functions Manual 				       DWARF_GET_RANGES(3)

NAME

     dwarf_get_ranges -- retrieve non-contiguous address ranges

LIBRARY

     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS

     #include <libdwarf.h>

     int
     dwarf_get_ranges(Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Ranges **ranges, Dwarf_Signed *cnt, Dwarf_Unsigned *byte_cnt, Dwarf_Error *err);

     int
     dwarf_get_ranges_a(Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Die die, Dwarf_Ranges **ranges, Dwarf_Signed *cnt, Dwarf_Unsigned *byte_cnt,
	 Dwarf_Error *err);

DESCRIPTION

     Function dwarf_get_ranges() retrieves information about the non-contiguous address ranges associated with a DWARF debugging information
     entry.  Information about address ranges is returned as an array of descriptors of type Dwarf_Ranges, with each Dwarf_Ranges descriptor
     describing one address range entry.

     Argument dbg should reference a DWARF debug context allocated using dwarf_init(3).

     Argument offset is an offset, relative to the ``.debug_ranges'' section, to the start of the desired list of address ranges.  The offset of
     an address ranges list is indicated by the DW_AT_ranges attribute of a debugging information entry.

     Argument die (function dwarf_get_ranges_a() only) is ignored in this implementation; see the section Compatibility Notes below.

     Argument ranges should point to a location that will be set to a pointer to an array of Dwarf_Ranges descriptors.

     Argument cnt should point to a location that will be set to the number of entries returned.  If argument byte_cnt is not NULL, it will be set
     to the number of bytes occupied by the returned entries in the ``.debug_ranges'' section.

     If argument err is not NULL, it will be used to store error information in case of an error.

     Dwarf_Ranges descriptors are defined in the header file <libdwarf.h>, and consists of the following fields:

     dwr_addr1	The first address offset, whose meaning depends on the type of the entry.

     dwr_addr2	The second address offset, whose meaning depends on the type of the entry.

     dwr_type	The type of this address range entry:
		DW_RANGES_ENTRY  A range list entry.  For this type of entry, the fields dwr_addr1 and dwr_addr2 hold the beginning and ending
				 offsets of the address range, respectively.
		DW_RANGES_ADDRESS_SELECTION
				 A base address selection entry.  For this type of entry, the field dwr_addr1 is the value of the largest repre-
				 sentable address offset, and dwr_addr2 is a base address for the begining and ending address offsets of subse-
				 quent address range entries in the list.
		DW_RANGES_END	 An end of list mark.  Both dwr_addr1 and dwr_addr2 are set to 0.

   Memory Management
     The memory area used for the array of Dwarf_Ranges descriptors returned in argument ranges is owned by the DWARF Access Library (libdwarf,
     -ldwarf).	The application should not attempt to directly free this pointer.  Portable code should instead use dwarf_ranges_dealloc() to
     indicate that the memory may be freed.

COMPATIBILITY

     Function dwarf_get_ranges_a() is identical to dwarf_get_ranges(), except that it requires one additional argument die denoting the debugging
     information entry associated with the address range list.	In this implementation of the DWARF Access Library (libdwarf, -ldwarf), the argu-
     ment die is ignored, and function dwarf_get_ranges_a() is only provided for compatibility with other implementations of the DWARF(3) API.

RETURN VALUES

     These functions return DW_DLV_OK when they succeed.  They return DW_DLV_NO_ENTRY if there is no address range list at the specified offset
     offset.  In case of an error, they return DW_DLV_ERROR and set the argument err.

ERRORS

     These function can fail with:

     [DW_DLE_ARGUMENT]	One of the arguments dbg, ranges or cnt was NULL.

     [DW_DLE_NO_ENTRY]	There is no address range list at the specified offset offset.

EXAMPLE

     To retrieve the address range list associated with a debugging information entry, use:

	   Dwarf_Debug dbg;
	   Dwarf_Die die;
	   Dwarf_Error de;
	   Dwarf_Addr base;
	   Dwarf_Attribute *attr_list;
	   Dwarf_Ranges *ranges;
	   Dwarf_Signed cnt;
	   Dwarf_Unsigned off, attr_count, bytecnt;
	   int i, j;

	   if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
	       DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
		       dwarf_errmsg(de));

	   for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
		   if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
			   warnx("dwarf_whatattr failed: %s",
			       dwarf_errmsg(de));
			   continue;
		   }
		   if (attr != DW_AT_ranges)
			   continue;
		   if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
			   warnx("dwarf_formudata failed: %s",
			       dwarf_errmsg(de));
			   continue;
		   }
		   if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
		       &bytecnt, &de) != DW_DLV_OK)
			   continue;
		   for (j = 0; j < cnt; j++) {
			   if (ranges[j].dwr_type == DW_RANGES_END)
				   break;
			   else if (ranges[j].dwr_type ==
			       DW_RANGES_ADDRESS_SELECTION)
				   base = ranges[j].dwr_addr2;
			   else {
				   /*
				    * DW_RANGES_ENTRY entry.
				    * .. Use dwr_addr1 and dwr_addr2 ..
				    */
			   }
		   }
	   }

SEE ALSO

     dwarf(3), dwarf_ranges_dealloc(3)

BSD
								 November 9, 2011							       BSD