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

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