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 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd November 9, 2011 28.Dt DWARF_GET_FDE_LIST 3 29.Os 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 EXAMPLES 136To obtain frame information from the 137.Dq ".debug_frame" 138section, use: 139.Bd -literal -offset indent 140Dwarf_Debug dbg; 141Dwarf_Cie *cie_list, cie; 142Dwarf_Fde *fde_list, fde; 143Dwarf_Off fde_offset, cie_offset; 144Dwarf_Unsigned func_len, fde_length, fde_instlen; 145Dwarf_Signed cie_count, fde_count, cie_index; 146Dwarf_Addr low_pc; 147Dwarf_Ptr fde_addr, fde_inst, cie_inst; 148Dwarf_Error de; 149int i; 150 151if (dwarf_get_fde_list(dbg, &cie_list, &cie_count, 152 &fde_list, &fde_count, &de) != DW_DLV_OK) { 153 errx(EXIT_FAILURE, "dwarf_get_fde_list failed: %s", 154 dwarf_errmsg(de)); 155} 156 157for (i = 0; i < fde_count; i++) { 158 if (dwarf_get_fde_n(fde_list, i, &fde, &de) != DW_DLV_OK) { 159 warnx("dwarf_get_fde_n failed: %s", 160 dwarf_errmsg(de)); 161 continue; 162 } 163 if (dwarf_get_cie_of_fde(fde, &cie, &de) != DW_DLV_OK) { 164 warnx("dwarf_get_fde_n failed: %s", 165 dwarf_errmsg(de)); 166 continue; 167 } 168 if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr, 169 &fde_length, &cie_offset, &cie_index, &fde_offset, 170 &de) != DW_DLV_OK) { 171 warnx("dwarf_get_fde_range failed: %s", 172 dwarf_errmsg(de)); 173 continue; 174 } 175 if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, 176 &de) != DW_DLV_OK) { 177 warnx("dwarf_get_fde_instr_bytes failed: %s", 178 dwarf_errmsg(de)); 179 continue; 180 } 181 182 /* ... Use the retrieved frame information ... */ 183} 184 185/* Indicate that the returned arrays may be freed. */ 186dwarf_fde_cie_list_dealloc(dbg, cie_list, cie_count, fde_list, 187 fde_count); 188.Ed 189.Sh ERRORS 190These functions may fail with the following errors: 191.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 192.It Bq Er DW_DLE_ARGUMENT 193One of the arguments 194.Va dbg , 195.Va cie_list , 196.Va cie_count , 197.Va fde_list 198or 199.Va fde_count 200was NULL. 201.It Bq Er DW_DLE_NO_ENTRY 202There is no frame information associated with the giving DWARF debug 203context. 204.El 205.Sh SEE ALSO 206.Xr dwarf 3 , 207.Xr dwarf_fde_cie_list_dealloc 3 , 208.Xr dwarf_get_cie_index 3 , 209.Xr dwarf_get_cie_of_fde 3 , 210.Xr dwarf_get_fde_at_pc 3 , 211.Xr dwarf_get_fde_instr_bytes 3 , 212.Xr dwarf_get_fde_n 3 , 213.Xr dwarf_get_fde_range 3 , 214.Xr dwarf_set_frame_cfa_value 3 , 215.Xr dwarf_set_frame_rule_initial_value 3 , 216.Xr dwarf_set_frame_rule_table_size 3 , 217.Xr dwarf_set_frame_same_value 3 , 218.Xr dwarf_set_frame_undefined_value 3 219