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_ranges.3 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd November 9, 2011 28.Dt DWARF_GET_RANGES 3 29.Os 30.Sh NAME 31.Nm dwarf_get_ranges 32.Nd retrieve non-contiguous address ranges 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_ranges 39.Fa "Dwarf_Debug dbg" 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" 45.Fc 46.Ft int 47.Fo dwarf_get_ranges_a 48.Fa "Dwarf_Debug dbg" 49.Fa "Dwarf_Off offset" 50.Fa "Dwarf_Die die" 51.Fa "Dwarf_Ranges **ranges" 52.Fa "Dwarf_Signed *cnt" 53.Fa "Dwarf_Unsigned *byte_cnt" 54.Fa "Dwarf_Error *err" 55.Fc 56.Sh DESCRIPTION 57Function 58.Fn dwarf_get_ranges 59retrieves information about the non-contiguous address ranges associated 60with a DWARF debugging information entry. 61Information about address ranges is returned as an array of 62descriptors of type 63.Vt Dwarf_Ranges , 64with each 65.Vt Dwarf_Ranges 66descriptor describing one address range entry. 67.Pp 68Argument 69.Ar dbg 70should reference a DWARF debug context allocated using 71.Xr dwarf_init 3 . 72.Pp 73Argument 74.Ar offset 75is an offset, relative to the 76.Dq ".debug_ranges" 77section, to the start of the desired list of address ranges. 78The offset of an address ranges list is indicated by the 79.Dv DW_AT_ranges 80attribute of a debugging information entry. 81.Pp 82Argument 83.Ar die 84(function 85.Fn dwarf_get_ranges_a 86only) is ignored in this implementation; see the section 87.Sx "Compatibility Notes" 88below. 89.Pp 90Argument 91.Ar ranges 92should point to a location that will be set to a pointer to an array 93of 94.Vt Dwarf_Ranges 95descriptors. 96.Pp 97Argument 98.Ar cnt 99should point to a location that will be set to the number of entries 100returned. 101If argument 102.Ar byte_cnt 103is not NULL, it will be set to the number of bytes occupied by the 104returned entries in the 105.Dq ".debug_ranges" 106section. 107.Pp 108If argument 109.Ar err 110is not NULL, it will be used to store error information in case 111of an error. 112.Pp 113.Vt Dwarf_Ranges 114descriptors are defined in the header file 115.In libdwarf.h , 116and consists of the following fields: 117.Bl -tag -width ".Va dwr_addr1" 118.It Va dwr_addr1 119The first address offset, whose meaning depends on the type of the 120entry. 121.It Va dwr_addr2 122The second address offset, whose meaning depends on the type of the 123entry. 124.It Va dwr_type 125The type of this address range entry: 126.Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact 127.It Dv DW_RANGES_ENTRY 128A range list entry. 129For this type of entry, the fields 130.Va dwr_addr1 131and 132.Va dwr_addr2 133hold the beginning and ending offsets of the address range, respectively. 134.It Dv DW_RANGES_ADDRESS_SELECTION 135A base address selection entry. 136For this type of entry, the field 137.Va dwr_addr1 138is the value of the largest representable address offset, and 139.Va dwr_addr2 140is a base address for the beginning and ending address offsets of 141subsequent address range entries in the list. 142.It Dv DW_RANGES_END 143An end of list mark. 144Both 145.Va dwr_addr1 146and 147.Va dwr_addr2 148are set to 0. 149.El 150.El 151.Ss Memory Management 152The memory area used for the array of 153.Vt Dwarf_Ranges 154descriptors returned in argument 155.Ar ranges 156is owned by the 157.Lb libdwarf . 158The application should not attempt to directly free this pointer. 159Portable code should instead use 160.Fn dwarf_ranges_dealloc 161to indicate that the memory may be freed. 162.Sh RETURN VALUES 163These functions 164return 165.Dv DW_DLV_OK 166when they succeed. 167They return 168.Dv DW_DLV_NO_ENTRY 169if there is no address range list at the specified offset 170.Ar offset . 171In case of an error, they return 172.Dv DW_DLV_ERROR 173and set the argument 174.Ar err . 175.Sh EXAMPLES 176To retrieve the address range list associated with a debugging 177information entry, use: 178.Bd -literal -offset indent 179Dwarf_Debug dbg; 180Dwarf_Die die; 181Dwarf_Error de; 182Dwarf_Addr base; 183Dwarf_Attribute *attr_list; 184Dwarf_Ranges *ranges; 185Dwarf_Signed cnt; 186Dwarf_Unsigned off, attr_count, bytecnt; 187int i, j; 188 189if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) != 190 DW_DLV_OK) 191 errx(EXIT_FAILURE, "dwarf_attrlist failed: %s", 192 dwarf_errmsg(de)); 193 194for (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", 197 dwarf_errmsg(de)); 198 continue; 199 } 200 if (attr != DW_AT_ranges) 201 continue; 202 if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) { 203 warnx("dwarf_formudata failed: %s", 204 dwarf_errmsg(de)); 205 continue; 206 } 207 if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt, 208 &bytecnt, &de) != DW_DLV_OK) 209 continue; 210 for (j = 0; j < cnt; j++) { 211 if (ranges[j].dwr_type == DW_RANGES_END) 212 break; 213 else if (ranges[j].dwr_type == 214 DW_RANGES_ADDRESS_SELECTION) 215 base = ranges[j].dwr_addr2; 216 else { 217 /* 218 * DW_RANGES_ENTRY entry. 219 * .. Use dwr_addr1 and dwr_addr2 .. 220 */ 221 } 222 } 223} 224.Ed 225.Sh COMPATIBILITY 226Function 227.Fn dwarf_get_ranges_a 228is identical to 229.Fn dwarf_get_ranges , 230except that it requires one additional argument 231.Ar die 232denoting the debugging information entry associated with 233the address range list. 234In this implementation of the 235.Lb libdwarf , 236the argument 237.Ar die 238is ignored, and function 239.Fn dwarf_get_ranges_a 240is only provided for compatibility with other implementations of the 241DWARF(3) API. 242.Sh ERRORS 243These function can fail with: 244.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 245.It Bq Er DW_DLE_ARGUMENT 246One of the arguments 247.Ar dbg , 248.Ar ranges 249or 250.Ar cnt 251was NULL. 252.It Bq Er DW_DLE_NO_ENTRY 253There is no address range list at the specified offset 254.Ar offset . 255.El 256.Sh SEE ALSO 257.Xr dwarf 3 , 258.Xr dwarf_ranges_dealloc 3 259