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