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 3182 2015-04-10 16:08:10Z emaste $
29 .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.
164 .Fn dwarf_get_ranges_a
166 .Fn dwarf_get_ranges ,
167 except that it requires one additional argument
169 denoting the debugging information entry associated with
170 the address range list.
171 In this implementation of the
175 is ignored, and function
176 .Fn dwarf_get_ranges_a
177 is only provided for compatibility with other implementations of the
186 if there is no address range list at the specified offset
188 In case of an error, they return
193 These function can fail with:
194 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
195 .It Bq Er DW_DLE_ARGUMENT
202 .It Bq Er DW_DLE_NO_ENTRY
203 There is no address range list at the specified offset
207 To retrieve the address range list associated with a debugging
208 information entry, use:
209 .Bd -literal -offset indent
214 Dwarf_Attribute *attr_list;
215 Dwarf_Ranges *ranges;
217 Dwarf_Unsigned off, attr_count, bytecnt;
220 if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
222 errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
225 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
226 if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
227 warnx("dwarf_whatattr failed: %s",
231 if (attr != DW_AT_ranges)
233 if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
234 warnx("dwarf_formudata failed: %s",
238 if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
239 &bytecnt, &de) != DW_DLV_OK)
241 for (j = 0; j < cnt; j++) {
242 if (ranges[j].dwr_type == DW_RANGES_END)
244 else if (ranges[j].dwr_type ==
245 DW_RANGES_ADDRESS_SELECTION)
246 base = ranges[j].dwr_addr2;
249 * DW_RANGES_ENTRY entry.
250 * .. Use dwr_addr1 and dwr_addr2 ..
258 .Xr dwarf_ranges_dealloc 3