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 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
  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 ERRORS
 136 These functions may fail with the following errors:
 137 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 138 .It Bq Er DW_DLE_ARGUMENT
 139 One of the arguments
 140 .Va dbg ,
 141 .Va cie_list ,
 142 .Va cie_count ,
 143 .Va fde_list
 144 or
 145 .Va fde_count
 146 was NULL.
 147 .It Bq Er DW_DLE_NO_ENTRY
 148 There is no frame information associated with the giving DWARF debug
 149 context.
 150 .El
 151 .Sh EXAMPLE
 152 To obtain frame information from the
 153 .Dq ".debug_frame"
 154 section, use:
 155 .Bd -literal -offset indent
 156 Dwarf_Debug dbg;
 157 Dwarf_Cie *cie_list, cie;
 158 Dwarf_Fde *fde_list, fde;
 159 Dwarf_Off fde_offset, cie_offset;
 160 Dwarf_Unsigned func_len, fde_length, fde_instlen;
 161 Dwarf_Signed cie_count, fde_count, cie_index;
 162 Dwarf_Addr low_pc;
 163 Dwarf_Ptr fde_addr, fde_inst, cie_inst;
 164 Dwarf_Error de;
 165 int i;
 166
 167 if (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
 173 for (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. */
 202 dwarf_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