GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
DWARF_GET_RANGES(3) FreeBSD Library Functions Manual DWARF_GET_RANGES(3)

dwarf_get_ranges
retrieve non-contiguous address ranges

DWARF Access Library (libdwarf, -ldwarf)

#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);

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:
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.
A base address selection entry. For this type of entry, the field dwr_addr1 is the value of the largest representable address offset, and dwr_addr2 is a base address for the beginning and ending address offsets of subsequent address range entries in the list.
An end of list mark. Both dwr_addr1 and dwr_addr2 are set to 0.

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.

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.

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 ..
			 */
		}
	}
}

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 argument die is ignored, and function dwarf_get_ranges_a() is only provided for compatibility with other implementations of the DWARF(3) API.

These function can fail with:
[]
One of the arguments dbg, ranges or cnt was NULL.
[]
There is no address range list at the specified offset offset.

dwarf(3), dwarf_ranges_dealloc(3)
November 9, 2011 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.