1.\" $NetBSD: dwarf_get_fde_list.3,v 1.6 2024/03/03 17:37:31 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 3962 2022-03-12 15:56:10Z jkoshy 28.\" 29.Dd November 9, 2011 30.Dt DWARF_GET_FDE_LIST 3 31.Os 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.Fa dbg 82should reference a DWARF debug context allocated using 83.Xr dwarf_init 3 . 84.Pp 85Argument 86.Fa 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.Fa 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.Fa 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.Fa 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.Fa err 113is not 114.Dv NULL , 115it will be used to store error information in case of an error. 116.Ss Memory Management 117The memory areas used for the arrays returned in arguments 118.Fa cie_list 119and 120.Fa fde_list 121are owned by the 122.Lb libdwarf . 123Application code should not attempt to directly free these areas. 124Portable applications should instead use the 125.Xr dwarf_fde_cie_list_dealloc 3 126function to indicate that these memory areas may be freed. 127.Sh RETURN VALUES 128On success, these functions returns 129.Dv DW_DLV_OK . 130They return 131.Dv DW_DLV_NO_ENTRY 132if there is no frame information associated with the given DWARF 133debug context. 134In case of an error, they return 135.Dv DW_DLV_ERROR 136and set the argument 137.Fa err . 138.Sh EXAMPLES 139To obtain frame information from the 140.Dq ".debug_frame" 141section, use: 142.Bd -literal -offset indent 143Dwarf_Debug dbg; 144Dwarf_Cie *cie_list, cie; 145Dwarf_Fde *fde_list, fde; 146Dwarf_Off fde_offset, cie_offset; 147Dwarf_Unsigned func_len, fde_length, fde_instlen; 148Dwarf_Signed cie_count, fde_count, cie_index; 149Dwarf_Addr low_pc; 150Dwarf_Ptr fde_addr, fde_inst, cie_inst; 151Dwarf_Error de; 152int i; 153 154if (dwarf_get_fde_list(dbg, &cie_list, &cie_count, 155 &fde_list, &fde_count, &de) != DW_DLV_OK) { 156 errx(EXIT_FAILURE, "dwarf_get_fde_list failed: %s", 157 dwarf_errmsg(de)); 158} 159 160for (i = 0; i < fde_count; i++) { 161 if (dwarf_get_fde_n(fde_list, i, &fde, &de) != DW_DLV_OK) { 162 warnx("dwarf_get_fde_n failed: %s", 163 dwarf_errmsg(de)); 164 continue; 165 } 166 if (dwarf_get_cie_of_fde(fde, &cie, &de) != DW_DLV_OK) { 167 warnx("dwarf_get_fde_n failed: %s", 168 dwarf_errmsg(de)); 169 continue; 170 } 171 if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr, 172 &fde_length, &cie_offset, &cie_index, &fde_offset, 173 &de) != DW_DLV_OK) { 174 warnx("dwarf_get_fde_range failed: %s", 175 dwarf_errmsg(de)); 176 continue; 177 } 178 if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, 179 &de) != DW_DLV_OK) { 180 warnx("dwarf_get_fde_instr_bytes failed: %s", 181 dwarf_errmsg(de)); 182 continue; 183 } 184 185 /* ... Use the retrieved frame information ... */ 186} 187 188/* Indicate that the returned arrays may be freed. */ 189dwarf_fde_cie_list_dealloc(dbg, cie_list, cie_count, fde_list, 190 fde_count); 191.Ed 192.Sh ERRORS 193These functions may fail with the following errors: 194.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 195.It Bq Er DW_DLE_ARGUMENT 196One of the arguments 197.Va dbg , 198.Va cie_list , 199.Va cie_count , 200.Va fde_list 201or 202.Va fde_count 203was 204.Dv NULL . 205.It Bq Er DW_DLE_NO_ENTRY 206There is no frame information associated with the giving DWARF debug 207context. 208.El 209.Sh SEE ALSO 210.Xr dwarf 3 , 211.Xr dwarf_fde_cie_list_dealloc 3 , 212.Xr dwarf_get_cie_index 3 , 213.Xr dwarf_get_cie_of_fde 3 , 214.Xr dwarf_get_fde_at_pc 3 , 215.Xr dwarf_get_fde_instr_bytes 3 , 216.Xr dwarf_get_fde_n 3 , 217.Xr dwarf_get_fde_range 3 , 218.Xr dwarf_set_frame_cfa_value 3 , 219.Xr dwarf_set_frame_rule_initial_value 3 , 220.Xr dwarf_set_frame_rule_table_size 3 , 221.Xr dwarf_set_frame_same_value 3 , 222.Xr dwarf_set_frame_undefined_value 3 223