---
name: "dwarf_get_ranges"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/dwarf_get_ranges"
---

# dwarf\_get\_ranges(3)

retrieve non-contiguous address ranges

## NAME

**dwarf\_get\_ranges** – retrieve non-contiguous address ranges

## LIBRARY

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)](/dwarf_init/3.md).

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 library “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 library “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/3.md), [dwarf\_ranges\_dealloc(3)](/dwarf_ranges_dealloc/3.md)