1.\"	$NetBSD: dwarf_get_arange_info.3,v 1.2 2014/03/09 16:58:04 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_arange_info.3 2134 2011-11-10 08:40:14Z jkoshy
28.\"
29.Dd April 16, 2011
30.Os
31.Dt DWARF_GET_ARANGE_INFO 3
32.Sh NAME
33.Nm dwarf_get_arange_info
34.Nd extract address range information from a descriptor
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft int
40.Fo dwarf_get_arange_info
41.Fa "Dwarf_Arange ar"
42.Fa "Dwarf_Addr *start"
43.Fa "Dwarf_Unsigned *length"
44.Fa "Dwarf_Off *cu_die_offset"
45.Fa "Dwarf_Error *err"
46.Fc
47.Sh DESCRIPTION
48Function
49.Fn dwarf_get_arange_info
50extracts address range information from a
51.Vt Dwarf_Arange
52descriptor.
53.Pp
54Argument
55.Ar ar
56should reference a valid
57.Vt Dwarf_Arange
58descriptor returned by function
59.Xr dwarf_get_aranges 3 .
60.Pp
61Argument
62.Ar start
63should point to a location which will hold the start value of the
64address range associated with the descriptor.
65.Pp
66Argument
67.Ar length
68should point to a location which will hold the length in bytes of the
69address range associated with the descriptor.
70.Pp
71Argument
72.Ar cu_die_offset
73should point to a location which will be set to an offset, relative to
74the
75.Dq ".debug_info"
76section, of the first debugging information entry in the compilation
77unit associated with argument
78.Ar ar .
79.Pp
80If argument
81.Ar err
82is not NULL, it will be used to store error information in case of an
83error.
84.Sh RETURN VALUES
85Function
86.Fn dwarf_get_arange_info
87returns
88.Dv DW_DLV_OK
89when it succeeds.
90In case of an error, it returns
91.Dv DW_DLV_ERROR
92and sets the argument
93.Ar err .
94.Sh ERRORS
95Function
96.Fn dwarf_get_arange_info
97can fail with:
98.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
99.It Bq Er DW_DLE_ARGUMENT
100One of the arguments
101.Ar ar ,
102.Ar start ,
103.Ar length
104or
105.Ar cu_die_offset
106was NULL.
107.Sh EXAMPLE
108To loop through all the address lookup table entries, use:
109.Bd -literal -offset indent
110Dwarf_Debug dbg;
111Dwarf_Addr start;
112Dwarf_Arange *aranges;
113Dwarf_Off die_off;
114Dwarf_Signed i, cnt;
115Dwarf_Unsigned length;
116Dwarf_Error de;
117
118if (dwarf_get_aranges(dbg, &aranges, &cnt, &de) != DW_DLV_OK)
119	errx(EXIT_FAILURE, "dwarf_get_aranges: %s",
120	    dwarf_errmsg(de));
121for (i = 0; i < cnt; i++) {
122	if (dwarf_get_arange_info(aranges[i], &start, &length,
123	    &die_off, &de) != DW_DLV_OK) {
124		warnx("dwarf_get_arange_info: %s",
125		    dwarf_errmsg(de));
126		continue;
127	}
128	/* Do something with the returned information. */
129}
130.Ed
131.Sh SEE ALSO
132.Xr dwarf 3 ,
133.Xr dwarf_get_arange 3 ,
134.Xr dwarf_get_aranges 3 ,
135.Xr dwarf_get_arange_cu_header_offset 3 ,
136.Xr dwarf_get_cu_die_offset 3
137