contrib/elftoolchain/libdwarf/dwarf_expand_frame_instructions.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_expand_frame_instructions.3 2122 2011-11-09 15:35:14Z jkoshy $
  26 .\"
  27 .Dd November 9, 2011
  28 .Os
  29 .Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3
  30 .Sh NAME
  31 .Nm dwarf_expand_frame_instructions
  32 .Nd expand frame instructions
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_expand_frame_instructions
  39 .Fa "Dwarf_Cie cie"
  40 .Fa "Dwarf_Ptr instructions"
  41 .Fa "Dwarf_Unsigned len"
  42 .Fa "Dwarf_Frame_Op **ret_ops"
  43 .Fa "Dwarf_Signed *ret_opcnt"
  44 .Fa "Dwarf_Error *error"
  45 .Fc
  46 .Sh DESCRIPTION
  47 Function
  48 .Fn dwarf_expand_frame_instructions
  49 translates DWARF frame instruction bytes into an array of
  50 .Vt Dwarf_Frame_Op
  51 descriptors.
  52 .Pp
  53 Argument
  54 .Ar cie
  55 should reference the CIE descriptor associated with the instructions
  56 to be translated.
  57 .Pp
  58 Arugment
  59 .Ar instructions
  60 should point to an array of frame instruction bytes, as
  61 returned by the functions
  62 .Xr dwarf_get_cie_info 3
  63 or
  64 .Xr dwarf_get_fde_instr_bytes 3 .
  65 .Pp
  66 Argument
  67 .Ar len
  68 should specify the number of the frame instruction bytes to be
  69 translated.
  70 .Pp
  71 Argument
  72 .Ar ret_ops
  73 should point to a location that will be set to a pointer to
  74 an array of translated
  75 .Vt Dwarf_Frame_Op
  76 descriptors.
  77 .Pp
  78 Argument
  79 .Ar ret_opcnt
  80 should point to a location that will hold the total number of the
  81 returned descriptors.
  82 .Pp
  83 If argument
  84 .Ar err
  85 is not NULL, it will be used to store error information in case of an
  86 error.
  87 .Ss Memory Management
  88 The memory area used for the descriptor array returned in argument
  89 .Ar ret_ops
  90 is allocated by
  91 .Lb libdwarf .
  92 Application code should use function
  93 .Xr dwarf_dealloc 3
  94 with type
  95 .Dv DW_DLA_FRAME_BLOCK
  96 to free the memory area when the descriptor array is no longer needed.
  97 .Sh RETURN VALUES
  98 Function
  99 .Fn dwarf_expand_frame_instructions
 100 returns
 101 .Dv DW_DLV_OK
 102 when it succeeds.
 103 In case of an error, it returns
 104 .Dv DW_DLV_ERROR
 105 and sets the argument
 106 .Ar err .
 107 .Sh ERRORS
 108 Function
 109 .Fn dwarf_expand_frame_instructions
 110 can fail with:
 111 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 112 .It Bq Er DW_DLE_ARGUMENT
 113 One of the arguments
 114 .Ar cie ,
 115 .Ar instructions ,
 116 .Ar ret_ops
 117 or
 118 .Ar ret_opcnt
 119 was NULL.
 120 .It Bq Er DW_DLE_ARGUMENT
 121 Argument
 122 .Ar len
 123 was 0.
 124 .It Bq Er DW_DLE_MEMORY
 125 An out of memory condition was encountered during the execution of
 126 this function.
 127 .It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR
 128 An unknown instruction was found in the instruction bytes provided
 129 in argument
 130 .Ar instructions .
 131 .El
 132 .Sh EXAMPLE
 133 To retrieve and expand the frame instructions for a given FDE
 134 descriptor, use:
 135 .Bd -literal -offset indent
 136 Dwarf_Dbg dbg;
 137 Dwarf_Cie cie;
 138 Dwarf_Fde fde;
 139 Dwarf_Ptr fde_inst;
 140 Dwarf_Unsigned fde_instlen;
 141 Dwarf_Frame_Op *ops;
 142 Dwarf_Signed opcnt;
 143 Dwarf_Error de;
 144
 145 /* ... assuming `dbg` references a valid DWARF debugging context,
 146   `fde` references a valid FDE descriptor and `cie` holds the CIE
 147   descriptor associated with the FDE descriptor ... */
 148
 149 if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen,
 150     &de) != DW_DLV_OK)
 151         errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s",
 152             dwarf_errmsg(de));
 153
 154 if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen,
 155     &ops, &opcnt, &de) != DW_DLV_OK)
 156         errx(EXIT_FAILURE,
 157             "dwarf_expand_frame_instructions failed: %s",
 158             dwarf_errmsg(de));
 159
 160 for (i = 0; i < opcnt; i++) {
 161         /* ... use ops[i] ... */
 162 }
 163
 164 /* Free the memory area when no longer needed. */
 165 dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK);
 166 .Ed
 167 .Sh SEE ALSO
 168 .Xr dwarf 3 ,
 169 .Xr dwarf_frame_instructions_dealloc 3 ,
 170 .Xr dwarf_get_cie_info 3 ,
 171 .Xr dwarf_get_cie_index 3 ,
 172 .Xr dwarf_get_cie_of_fde ,
 173 .Xr dwarf_get_fde_at_pc 3 ,
 174 .Xr dwarf_get_fde_info_for_all_regs 3 ,
 175 .Xr dwarf_get_fde_info_for_all_regs3 3 ,
 176 .Xr dwarf_get_fde_info_for_cfa_reg3 3 ,
 177 .Xr dwarf_get_fde_info_for_reg 3 ,
 178 .Xr dwarf_get_fde_info_for_reg3 3 ,
 179 .Xr dwarf_get_fde_instr_bytes 3 ,
 180 .Xr dwarf_get_fde_list 3 ,
 181 .Xr dwarf_get_fde_list_eh 3 ,
 182 .Xr dwarf_get_fde_n 3