1.\" $NetBSD: dwarf_get_fde_list.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_fde_list.3 2122 2011-11-09 15:35:14Z jkoshy 28.\" 29.Dd November 9, 2011 30.Os 31.Dt DWARF_GET_FDE_LIST 3 32.Sh NAME 33.Nm dwarf_get_fde_list 34.Nd retrieve frame information 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft int 40.Fo dwarf_get_fde_list 41.Fa "Dwarf_Debug dbg" 42.Fa "Dwarf_Cie **cie_list" 43.Fa "Dwarf_Signed *cie_count" 44.Fa "Dwarf_Fde **fde_list" 45.Fa "Dwarf_Signed *fde_count" 46.Fa "Dwarf_Error *err" 47.Fc 48.Ft int 49.Fo dwarf_get_fde_list_eh 50.Fa "Dwarf_Debug dbg" 51.Fa "Dwarf_Cie **cie_list" 52.Fa "Dwarf_Signed *cie_count" 53.Fa "Dwarf_Fde **fde_list" 54.Fa "Dwarf_Signed *fde_count" 55.Fa "Dwarf_Error *err" 56.Fc 57.Sh DESCRIPTION 58These functions retrieve frame related information for the specified 59DWARF debug context. 60.Pp 61Function 62.Fn dwarf_get_fde_list 63retrieves frame information from the DWARF section named 64.Dq ".debug_frame" . 65For objects containing GNU style C++ exception handling 66information, the function 67.Fn dwarf_get_fde_list_eh 68retrieves frame information from the section named 69.Dq ".eh_frame" . 70.Pp 71Frame information is returned using opaque descriptors 72of type 73.Vt Dwarf_Cie 74and 75.Vt Dwarf_Fde . 76Applications need to use the other frame related functions in the 77DWARF(3) API set to retrieve the information contained in these 78descriptors. 79.Pp 80Argument 81.Ar dbg 82should reference a DWARF debug context allocated using 83.Xr dwarf_init 3 . 84.Pp 85Argument 86.Ar cie_list 87should point to a location that will be set to a pointer to an array 88of 89.Vt Dwarf_Cie 90descriptors. 91.Pp 92Argument 93.Ar cie_count 94should point to a location that will be set to the number of 95.Vt Dwarf_Cie 96descriptors returned. 97.Pp 98Argument 99.Ar fde_list 100should point to a location that will be set to a pointer to an array 101of 102.Vt Dwarf_Fde 103descriptors. 104.Pp 105Argument 106.Ar fde_count 107should point to a location that will be set to the number of 108.Vt Dwarf_Fde 109descriptors returned. 110.Pp 111If argument 112.Ar err 113is not NULL, it will be used to store error information in case of an 114error. 115.Ss Memory Management 116The memory areas used for the arrays returned in arguments 117.Ar cie_list 118and 119.Ar fde_list 120are owned by the 121.Lb libdwarf . 122Application code should not attempt to directly free these areas. 123Portable applications should instead use the 124.Xr dwarf_fde_cie_list_dealloc 3 125function to indicate that these memory areas may be freed. 126.Sh RETURN VALUES 127On success, these functions returns 128.Dv DW_DLV_OK . 129They return 130.Dv DW_DLV_NO_ENTRY 131if there is no frame information associated with the given DWARF 132debug context. 133In case of an error, they return 134.Dv DW_DLV_ERROR 135and set the argument 136.Ar err . 137.Sh ERRORS 138These functions may fail with the following errors: 139.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 140.It Bq Er DW_DLE_ARGUMENT 141One of the arguments 142.Va dbg , 143.Va cie_list , 144.Va cie_count , 145.Va fde_list 146or 147.Va fde_count 148was NULL. 149.It Bq Er DW_DLE_NO_ENTRY 150There is no frame information associated with the giving DWARF debug 151context. 152.El 153.Sh EXAMPLE 154To obtain frame information from the 155.Dq ".debug_frame" 156section, use: 157.Bd -literal -offset indent 158Dwarf_Debug dbg; 159Dwarf_Cie *cie_list, cie; 160Dwarf_Fde *fde_list, fde; 161Dwarf_Off fde_offset, cie_offset; 162Dwarf_Unsigned func_len, fde_length, fde_instlen; 163Dwarf_Signed cie_count, fde_count, cie_index; 164Dwarf_Addr low_pc; 165Dwarf_Ptr fde_addr, fde_inst, cie_inst; 166Dwarf_Error de; 167int i; 168 169if (dwarf_get_fde_list(dbg, &cie_list, &cie_count, 170 &fde_list, &fde_count, &de) != DW_DLV_OK) { 171 errx(EXIT_FAILURE, "dwarf_get_fde_list failed: %s", 172 dwarf_errmsg(de)); 173} 174 175for (i = 0; i < fde_count; i++) { 176 if (dwarf_get_fde_n(fde_list, i, &fde, &de) != DW_DLV_OK) { 177 warnx("dwarf_get_fde_n failed: %s", 178 dwarf_errmsg(de)); 179 continue; 180 } 181 if (dwarf_get_cie_of_fde(fde, &cie, &de) != DW_DLV_OK) { 182 warnx("dwarf_get_fde_n failed: %s", 183 dwarf_errmsg(de)); 184 continue; 185 } 186 if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr, 187 &fde_length, &cie_offset, &cie_index, &fde_offset, 188 &de) != DW_DLV_OK) { 189 warnx("dwarf_get_fde_range failed: %s", 190 dwarf_errmsg(de)); 191 continue; 192 } 193 if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, 194 &de) != DW_DLV_OK) { 195 warnx("dwarf_get_fde_instr_bytes failed: %s", 196 dwarf_errmsg(de)); 197 continue; 198 } 199 200 /* ... Use the retrieved frame information ... */ 201} 202 203/* Indicate that the returned arrays may be freed. */ 204dwarf_fde_cie_list_dealloc(dbg, cie_list, cie_count, fde_list, 205 fde_count); 206.Ed 207.Sh SEE ALSO 208.Xr dwarf 3 , 209.Xr dwarf_get_cie_index 3 , 210.Xr dwarf_get_cie_of_fde 3 , 211.Xr dwarf_get_fde_at_pc 3 , 212.Xr dwarf_get_fde_instr_bytes 3 , 213.Xr dwarf_get_fde_n 3 , 214.Xr dwarf_get_fde_range 3 , 215.Xr dwarf_fde_cie_list_dealloc 3 , 216.Xr dwarf_set_frame_cfa_value 3 , 217.Xr dwarf_set_frame_rule_table_size 3 , 218.Xr dwarf_set_frame_rule_initial_value 3 , 219.Xr dwarf_set_frame_same_value 3 , 220.Xr dwarf_set_frame_undefined_value 3 221