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