1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $Id: dwarf_get_ranges.3 3644 2018-10-15 19:55:01Z jkoshy $
28 .Dt DWARF_GET_RANGES 3
32 .Nd retrieve non-contiguous address ranges
40 .Fa "Dwarf_Off offset"
41 .Fa "Dwarf_Ranges **ranges"
42 .Fa "Dwarf_Signed *cnt"
43 .Fa "Dwarf_Unsigned *byte_cnt"
44 .Fa "Dwarf_Error *err"
47 .Fo dwarf_get_ranges_a
49 .Fa "Dwarf_Off offset"
51 .Fa "Dwarf_Ranges **ranges"
52 .Fa "Dwarf_Signed *cnt"
53 .Fa "Dwarf_Unsigned *byte_cnt"
54 .Fa "Dwarf_Error *err"
59 retrieves information about the non-contiguous address ranges associated
60 with a DWARF debugging information entry.
61 Information about address ranges is returned as an array of
66 descriptor describing one address range entry.
70 should reference a DWARF debug context allocated using
75 is an offset, relative to the
77 section, to the start of the desired list of address ranges.
78 The offset of an address ranges list is indicated by the
80 attribute of a debugging information entry.
85 .Fn dwarf_get_ranges_a
86 only) is ignored in this implementation; see the section
87 .Sx "Compatibility Notes"
92 should point to a location that will be set to a pointer to an array
99 should point to a location that will be set to the number of entries
103 is not NULL, it will be set to the number of bytes occupied by the
104 returned entries in the
110 is not NULL, it will be used to store error information in case
114 descriptors are defined in the header file
116 and consists of the following fields:
117 .Bl -tag -width ".Va dwr_addr1"
119 The first address offset, whose meaning depends on the type of the
122 The second address offset, whose meaning depends on the type of the
125 The type of this address range entry:
126 .Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact
127 .It Dv DW_RANGES_ENTRY
129 For this type of entry, the fields
133 hold the beginning and ending offsets of the address range, respectively.
134 .It Dv DW_RANGES_ADDRESS_SELECTION
135 A base address selection entry.
136 For this type of entry, the field
138 is the value of the largest representable address offset, and
140 is a base address for the beginning and ending address offsets of
141 subsequent address range entries in the list.
151 .Ss Memory Management
152 The memory area used for the array of
154 descriptors returned in argument
158 The application should not attempt to directly free this pointer.
159 Portable code should instead use
160 .Fn dwarf_ranges_dealloc
161 to indicate that the memory may be freed.
169 if there is no address range list at the specified offset
171 In case of an error, they return
176 To retrieve the address range list associated with a debugging
177 information entry, use:
178 .Bd -literal -offset indent
183 Dwarf_Attribute *attr_list;
184 Dwarf_Ranges *ranges;
186 Dwarf_Unsigned off, attr_count, bytecnt;
189 if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
191 errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
194 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
195 if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
196 warnx("dwarf_whatattr failed: %s",
200 if (attr != DW_AT_ranges)
202 if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
203 warnx("dwarf_formudata failed: %s",
207 if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
208 &bytecnt, &de) != DW_DLV_OK)
210 for (j = 0; j < cnt; j++) {
211 if (ranges[j].dwr_type == DW_RANGES_END)
213 else if (ranges[j].dwr_type ==
214 DW_RANGES_ADDRESS_SELECTION)
215 base = ranges[j].dwr_addr2;
218 * DW_RANGES_ENTRY entry.
219 * .. Use dwr_addr1 and dwr_addr2 ..
227 .Fn dwarf_get_ranges_a
229 .Fn dwarf_get_ranges ,
230 except that it requires one additional argument
232 denoting the debugging information entry associated with
233 the address range list.
234 In this implementation of the
238 is ignored, and function
239 .Fn dwarf_get_ranges_a
240 is only provided for compatibility with other implementations of the
243 These function can fail with:
244 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
245 .It Bq Er DW_DLE_ARGUMENT
252 .It Bq Er DW_DLE_NO_ENTRY
253 There is no address range list at the specified offset
258 .Xr dwarf_ranges_dealloc 3