1.\" Copyright (c) 2011 Kai Wang
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.\" $Id: dwarf_get_aranges.3 3644 2018-10-15 19:55:01Z jkoshy $
26.\"
27.Dd November 9, 2011
28.Dt DWARF_GET_ARANGES 3
29.Os
30.Sh NAME
31.Nm dwarf_get_aranges
32.Nd retrieve program address space mappings
33.Sh LIBRARY
34.Lb libdwarf
35.Sh SYNOPSIS
36.In libdwarf.h
37.Ft int
38.Fo dwarf_get_aranges
39.Fa "Dwarf_Debug dbg"
40.Fa "Dwarf_Arange **ar_list"
41.Fa "Dwarf_Signed *ar_cnt"
42.Fa "Dwarf_Error *err"
43.Fc
44.Sh DESCRIPTION
45The function
46.Fn dwarf_get_aranges
47retrieves address range information from the
48.Dq ".debug_aranges"
49DWARF section.
50Information about address ranges is returned using opaque descriptors
51of type
52.Vt Dwarf_Arange ,
53.Pp
54Argument
55.Ar dbg
56should reference a DWARF debug context allocated using
57.Xr dwarf_init 3 .
58.Pp
59Argument
60.Ar ar_list
61should point to a location which will be set to a pointer to an array
62of
63.Vt Dwarf_Arange
64descriptors.
65.Pp
66Argument
67.Ar ar_cnt
68should point to a location which will be set to the number of
69descriptors returned.
70.Pp
71If argument
72.Ar err
73is not NULL, it will be used to store error information in case of an
74error.
75.Ss Memory Management
76The memory area used for the array returned in argument
77.Ar ar_list
78is owned by
79.Lb libdwarf .
80Application code should not attempt to directly free this area.
81Portable applications should instead use
82.Xr dwarf_dealloc 3
83to indicate that the memory area may be freed.
84.Sh RETURN VALUES
85Function
86.Fn dwarf_get_aranges
87returns
88.Dv DW_DLV_OK
89when it succeeds.
90It returns
91.Dv DW_DLV_NO_ENTRY
92if there is no
93.Dq ".debug_aranges"
94section associated with the specified debugging context.
95In case of an error, it returns
96.Dv DW_DLV_ERROR
97and sets the argument
98.Ar err .
99.Sh EXAMPLES
100To loop through all the address lookup table entries, use:
101.Bd -literal -offset indent
102Dwarf_Debug dbg;
103Dwarf_Addr start;
104Dwarf_Arange *aranges;
105Dwarf_Off die_off;
106Dwarf_Signed i, cnt;
107Dwarf_Unsigned length;
108Dwarf_Error de;
109
110if (dwarf_get_aranges(dbg, &aranges, &cnt, &de) != DW_DLV_OK)
111	errx(EXIT_FAILURE, "dwarf_get_aranges: %s",
112	    dwarf_errmsg(de));
113
114for (i = 0; i < cnt; i++) {
115	if (dwarf_get_arange_info(aranges[i], &start, &length,
116	    &die_off, &de) != DW_DLV_OK) {
117		warnx("dwarf_get_arange_info: %s",
118		    dwarf_errmsg(de));
119		continue;
120	}
121	/* Do something with the returned information. */
122}
123.Ed
124.Sh ERRORS
125Function
126.Fn dwarf_get_aranges
127can fail with:
128.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
129.It Bq Er DW_DLE_ARGUMENT
130One of the arguments
131.Ar dbg ,
132.Ar ar_list
133or
134.Ar ar_cnt
135was NULL.
136.It Bq Er DW_DLE_NO_ENTRY
137The debugging context
138.Ar dbg
139did not contain a
140.Dq ".debug_aranges"
141string section.
142.El
143.Sh SEE ALSO
144.Xr dwarf 3 ,
145.Xr dwarf_get_arange 3 ,
146.Xr dwarf_get_arange_cu_header_offset 3 ,
147.Xr dwarf_get_arange_info 3 ,
148.Xr dwarf_get_cu_die_offset 3
149