external/bsd/elftoolchain/dist/libdwarf/dwarf_get_fde_list.3

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