xref: /netbsd-src/external/bsd/elftoolchain/dist/libdwarf/dwarf_get_ranges.3 (revision 5ac3bc719ce6e70593039505b491894133237d12)
1.\"	$NetBSD: dwarf_get_ranges.3,v 1.6 2024/03/03 17:37:31 christos Exp $
2.\"
3.\" Copyright (c) 2011 Kai Wang
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" Id: dwarf_get_ranges.3 3963 2022-03-12 16:07:32Z jkoshy
28.\"
29.Dd November 9, 2011
30.Dt DWARF_GET_RANGES 3
31.Os
32.Sh NAME
33.Nm dwarf_get_ranges
34.Nd retrieve non-contiguous address ranges
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft int
40.Fo dwarf_get_ranges
41.Fa "Dwarf_Debug dbg"
42.Fa "Dwarf_Off offset"
43.Fa "Dwarf_Ranges **ranges"
44.Fa "Dwarf_Signed *cnt"
45.Fa "Dwarf_Unsigned *byte_cnt"
46.Fa "Dwarf_Error *err"
47.Fc
48.Ft int
49.Fo dwarf_get_ranges_a
50.Fa "Dwarf_Debug dbg"
51.Fa "Dwarf_Off offset"
52.Fa "Dwarf_Die die"
53.Fa "Dwarf_Ranges **ranges"
54.Fa "Dwarf_Signed *cnt"
55.Fa "Dwarf_Unsigned *byte_cnt"
56.Fa "Dwarf_Error *err"
57.Fc
58.Sh DESCRIPTION
59Function
60.Fn dwarf_get_ranges
61retrieves information about the non-contiguous address ranges associated
62with a DWARF debugging information entry.
63Information about address ranges is returned as an array of
64descriptors of type
65.Vt Dwarf_Ranges ,
66with each
67.Vt Dwarf_Ranges
68descriptor describing one address range entry.
69.Pp
70Argument
71.Fa dbg
72should reference a DWARF debug context allocated using
73.Xr dwarf_init 3 .
74.Pp
75Argument
76.Fa offset
77is an offset, relative to the
78.Dq ".debug_ranges"
79section, to the start of the desired list of address ranges.
80The offset of an address ranges list is indicated by the
81.Dv DW_AT_ranges
82attribute of a debugging information entry.
83.Pp
84Argument
85.Fa die
86(function
87.Fn dwarf_get_ranges_a
88only) is ignored in this implementation; see the section
89.Sx "Compatibility Notes"
90below.
91.Pp
92Argument
93.Fa ranges
94should point to a location that will be set to a pointer to an array
95of
96.Vt Dwarf_Ranges
97descriptors.
98.Pp
99Argument
100.Fa cnt
101should point to a location that will be set to the number of entries
102returned.
103If argument
104.Fa byte_cnt
105is not
106.Dv NULL ,
107it will be set to the number of bytes occupied by the
108returned entries in the
109.Dq ".debug_ranges"
110section.
111.Pp
112If argument
113.Fa err
114is not
115.Dv NULL ,
116it will be used to store error information in case of an error.
117.Pp
118.Vt Dwarf_Ranges
119descriptors are defined in the header file
120.In libdwarf.h ,
121and consists of the following fields:
122.Bl -tag -width ".Va dwr_addr1"
123.It Va dwr_addr1
124The first address offset, whose meaning depends on the type of the
125entry.
126.It Va dwr_addr2
127The second address offset, whose meaning depends on the type of the
128entry.
129.It Va dwr_type
130The type of this address range entry:
131.Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact
132.It Dv DW_RANGES_ENTRY
133A range list entry.
134For this type of entry, the fields
135.Va dwr_addr1
136and
137.Va dwr_addr2
138hold the beginning and ending offsets of the address range, respectively.
139.It Dv DW_RANGES_ADDRESS_SELECTION
140A base address selection entry.
141For this type of entry, the field
142.Va dwr_addr1
143is the value of the largest representable address offset, and
144.Va dwr_addr2
145is a base address for the beginning and ending address offsets of
146subsequent address range entries in the list.
147.It Dv DW_RANGES_END
148An end of list mark.
149Both
150.Va dwr_addr1
151and
152.Va dwr_addr2
153are set to 0.
154.El
155.El
156.Ss Memory Management
157The memory area used for the array of
158.Vt Dwarf_Ranges
159descriptors returned in argument
160.Fa ranges
161is owned by the
162.Lb libdwarf .
163The application should not attempt to directly free this pointer.
164Portable code should instead use
165.Fn dwarf_ranges_dealloc
166to indicate that the memory may be freed.
167.Sh RETURN VALUES
168These functions
169return
170.Dv DW_DLV_OK
171when they succeed.
172They return
173.Dv DW_DLV_NO_ENTRY
174if there is no address range list at the specified offset
175.Fa offset .
176In case of an error, they return
177.Dv DW_DLV_ERROR
178and set the argument
179.Fa err .
180.Sh EXAMPLES
181To retrieve the address range list associated with a debugging
182information entry, use:
183.Bd -literal -offset indent
184Dwarf_Debug dbg;
185Dwarf_Die die;
186Dwarf_Error de;
187Dwarf_Addr base;
188Dwarf_Attribute *attr_list;
189Dwarf_Ranges *ranges;
190Dwarf_Signed cnt;
191Dwarf_Unsigned off, attr_count, bytecnt;
192int i, j;
193
194if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
195    DW_DLV_OK)
196	errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
197	    dwarf_errmsg(de));
198
199for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
200	if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
201		warnx("dwarf_whatattr failed: %s",
202		    dwarf_errmsg(de));
203		continue;
204	}
205	if (attr != DW_AT_ranges)
206		continue;
207	if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
208		warnx("dwarf_formudata failed: %s",
209		    dwarf_errmsg(de));
210		continue;
211	}
212	if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
213	    &bytecnt, &de) != DW_DLV_OK)
214		continue;
215	for (j = 0; j < cnt; j++) {
216		if (ranges[j].dwr_type == DW_RANGES_END)
217			break;
218		else if (ranges[j].dwr_type ==
219		    DW_RANGES_ADDRESS_SELECTION)
220			base = ranges[j].dwr_addr2;
221		else {
222			/*
223			 * DW_RANGES_ENTRY entry.
224			 * .. Use dwr_addr1 and dwr_addr2 ..
225			 */
226		}
227	}
228}
229.Ed
230.Sh COMPATIBILITY
231Function
232.Fn dwarf_get_ranges_a
233is identical to
234.Fn dwarf_get_ranges ,
235except that it requires one additional argument
236.Fa die
237denoting the debugging information entry associated with
238the address range list.
239In this implementation of the
240.Lb libdwarf ,
241the argument
242.Fa die
243is ignored, and function
244.Fn dwarf_get_ranges_a
245is only provided for compatibility with other implementations of the
246DWARF(3) API.
247.Sh ERRORS
248These function can fail with:
249.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
250.It Bq Er DW_DLE_ARGUMENT
251One of the arguments
252.Fa dbg ,
253.Fa ranges
254or
255.Fa cnt
256was
257.Dv NULL .
258.It Bq Er DW_DLE_NO_ENTRY
259There is no address range list at the specified offset
260.Fa offset .
261.El
262.Sh SEE ALSO
263.Xr dwarf 3 ,
264.Xr dwarf_ranges_dealloc 3
265