DWARF_GET_RANGES(3)

NAME
dwarf_get_ranges - retrieve non-contiguous address ranges

LIBRARY
libdwarf

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 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.
    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 libdwarf. 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.

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.

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

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

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.

SEE ALSO
dwarf(3), dwarf_ranges_dealloc(3)