contrib/elftoolchain/libdwarf/dwarf_get_fde_list.3

   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
  56 These functions retrieve frame related information for the specified
  57 DWARF debug context.
  58 .Pp
  59 Function
  60 .Fn dwarf_get_fde_list
  61 retrieves frame information from the DWARF section named
  62 .Dq ".debug_frame" .
  63 For objects containing GNU style C++ exception handling
  64 information, the function
  65 .Fn dwarf_get_fde_list_eh
  66 retrieves frame information from the section named
  67 .Dq ".eh_frame" .
  68 .Pp
  69 Frame information is returned using opaque descriptors
  70 of type
  71 .Vt Dwarf_Cie
  72 and
  73 .Vt Dwarf_Fde .
  74 Applications need to use the other frame related functions in the
  75 DWARF(3) API set to retrieve the information contained in these
  76 descriptors.
  77 .Pp
  78 Argument
  79 .Ar dbg
  80 should reference a DWARF debug context allocated using
  81 .Xr dwarf_init 3 .
  82 .Pp
  83 Argument
  84 .Ar cie_list
  85 should point to a location that will be set to a pointer to an array
  86 of
  87 .Vt Dwarf_Cie
  88 descriptors.
  89 .Pp
  90 Argument
  91 .Ar cie_count
  92 should point to a location that will be set to the number of
  93 .Vt Dwarf_Cie
  94 descriptors returned.
  95 .Pp
  96 Argument
  97 .Ar fde_list
  98 should point to a location that will be set to a pointer to an array
  99 of
 100 .Vt Dwarf_Fde
 101 descriptors.
 102 .Pp
 103 Argument
 104 .Ar fde_count
 105 should point to a location that will be set to the number of
 106 .Vt Dwarf_Fde
 107 descriptors returned.
 108 .Pp
 109 If argument
 110 .Ar err
 111 is not NULL, it will be used to store error information in case of an
 112 error.
 113 .Ss Memory Management
 114 The memory areas used for the arrays returned in arguments
 115 .Ar cie_list
 116 and
 117 .Ar fde_list
 118 are owned by the
 119 .Lb libdwarf .
 120 Application code should not attempt to directly free these areas.
 121 Portable applications should instead use the
 122 .Xr dwarf_fde_cie_list_dealloc 3
 123 function to indicate that these memory areas may be freed.
 124 .Sh RETURN VALUES
 125 On success, these functions returns
 126 .Dv DW_DLV_OK .
 127 They return
 128 .Dv DW_DLV_NO_ENTRY
 129 if there is no frame information associated with the given DWARF
 130 debug context.
 131 In case of an error, they return
 132 .Dv DW_DLV_ERROR
 133 and set the argument
 134 .Ar err .
 135 .Sh EXAMPLES
 136 To obtain frame information from the
 137 .Dq ".debug_frame"
 138 section, use:
 139 .Bd -literal -offset indent
 140 Dwarf_Debug dbg;
 141 Dwarf_Cie *cie_list, cie;
 142 Dwarf_Fde *fde_list, fde;
 143 Dwarf_Off fde_offset, cie_offset;
 144 Dwarf_Unsigned func_len, fde_length, fde_instlen;
 145 Dwarf_Signed cie_count, fde_count, cie_index;
 146 Dwarf_Addr low_pc;
 147 Dwarf_Ptr fde_addr, fde_inst, cie_inst;
 148 Dwarf_Error de;
 149 int i;
 150
 151 if (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
 157 for (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. */
 186 dwarf_fde_cie_list_dealloc(dbg, cie_list, cie_count, fde_list,
 187     fde_count);
 188 .Ed
 189 .Sh ERRORS
 190 These functions may fail with the following errors:
 191 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 192 .It Bq Er DW_DLE_ARGUMENT
 193 One of the arguments
 194 .Va dbg ,
 195 .Va cie_list ,
 196 .Va cie_count ,
 197 .Va fde_list
 198 or
 199 .Va fde_count
 200 was NULL.
 201 .It Bq Er DW_DLE_NO_ENTRY
 202 There is no frame information associated with the giving DWARF debug
 203 context.
 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