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 2122 2011-11-09 15:35:14Z jkoshy $ 26.\" 27.Dd November 9, 2011 28.Os 29.Dt DWARF_GET_ARANGES 3 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 ERRORS 100Function 101.Fn dwarf_get_aranges 102can fail with: 103.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 104.It Bq Er DW_DLE_ARGUMENT 105One of the arguments 106.Ar dbg , 107.Ar ar_list 108or 109.Ar ar_cnt 110was NULL. 111.It Bq Er DW_DLE_NO_ENTRY 112The debugging context 113.Ar dbg 114did not contain a 115.Dq ".debug_aranges" 116string section. 117.El 118.Sh EXAMPLE 119To loop through all the address lookup table entries, use: 120.Bd -literal -offset indent 121Dwarf_Debug dbg; 122Dwarf_Addr start; 123Dwarf_Arange *aranges; 124Dwarf_Off die_off; 125Dwarf_Signed i, cnt; 126Dwarf_Unsigned length; 127Dwarf_Error de; 128 129if (dwarf_get_aranges(dbg, &aranges, &cnt, &de) != DW_DLV_OK) 130 errx(EXIT_FAILURE, "dwarf_get_aranges: %s", 131 dwarf_errmsg(de)); 132 133for (i = 0; i < cnt; i++) { 134 if (dwarf_get_arange_info(aranges[i], &start, &length, 135 &die_off, &de) != DW_DLV_OK) { 136 warnx("dwarf_get_arange_info: %s", 137 dwarf_errmsg(de)); 138 continue; 139 } 140 /* Do something with the returned information. */ 141} 142.Ed 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