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 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd November 9, 2011
  28 .Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3
  29 .Os
  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 EXAMPLES
 108 To retrieve and expand the frame instructions for a given FDE
 109 descriptor, use:
 110 .Bd -literal -offset indent
 111 Dwarf_Dbg dbg;
 112 Dwarf_Cie cie;
 113 Dwarf_Fde fde;
 114 Dwarf_Ptr fde_inst;
 115 Dwarf_Unsigned fde_instlen;
 116 Dwarf_Frame_Op *ops;
 117 Dwarf_Signed opcnt;
 118 Dwarf_Error de;
 119
 120 /* ... assuming `dbg` references a valid DWARF debugging context,
 121   `fde` references a valid FDE descriptor and `cie` holds the CIE
 122   descriptor associated with the FDE descriptor ... */
 123
 124 if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen,
 125     &de) != DW_DLV_OK)
 126         errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s",
 127             dwarf_errmsg(de));
 128
 129 if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen,
 130     &ops, &opcnt, &de) != DW_DLV_OK)
 131         errx(EXIT_FAILURE,
 132             "dwarf_expand_frame_instructions failed: %s",
 133             dwarf_errmsg(de));
 134
 135 for (i = 0; i < opcnt; i++) {
 136         /* ... use ops[i] ... */
 137 }
 138
 139 /* Free the memory area when no longer needed. */
 140 dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK);
 141 .Ed
 142 .Sh ERRORS
 143 Function
 144 .Fn dwarf_expand_frame_instructions
 145 can fail with:
 146 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 147 .It Bq Er DW_DLE_ARGUMENT
 148 One of the arguments
 149 .Ar cie ,
 150 .Ar instructions ,
 151 .Ar ret_ops
 152 or
 153 .Ar ret_opcnt
 154 was NULL.
 155 .It Bq Er DW_DLE_ARGUMENT
 156 Argument
 157 .Ar len
 158 was 0.
 159 .It Bq Er DW_DLE_MEMORY
 160 An out of memory condition was encountered during the execution of
 161 this function.
 162 .It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR
 163 An unknown instruction was found in the instruction bytes provided
 164 in argument
 165 .Ar instructions .
 166 .El
 167 .Sh SEE ALSO
 168 .Xr dwarf 3 ,
 169 .Xr dwarf_frame_instructions_dealloc 3 ,
 170 .Xr dwarf_get_cie_index 3 ,
 171 .Xr dwarf_get_cie_info 3 ,
 172 .Xr dwarf_get_cie_of_fde 3 ,
 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