contrib/elftoolchain/libdwarf/dwarf_get_fde_info_for_cfa_reg3.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_info_for_cfa_reg3.3 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd June 12, 2011
  28 .Dt DWARF_GET_FDE_INFO_FOR_CFA_REGS3 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_get_fde_info_for_cfa_regs3
  32 .Nd retrieve a CFA register rule
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_get_fde_info_for_cfa_regs3
  39 .Fa "Dwarf_Fde fde"
  40 .Fa "Dwarf_Addr pc"
  41 .Fa "Dwarf_Small *type"
  42 .Fa "Dwarf_Signed *offset_relevant"
  43 .Fa "Dwarf_Signed *register_num"
  44 .Fa "Dwarf_Signed *offset_or_block_len"
  45 .Fa "Dwarf_Ptr *block_ptr"
  46 .Fa "Dwarf_Addr *row_pc"
  47 .Fa "Dwarf_Error *err"
  48 .Fc
  49 .Sh DESCRIPTION
  50 Function
  51 .Fn dwarf_get_fde_info_for_cfa_reg3
  52 retrieves the CFA register rule for a given program counter address
  53 from the register rule table associated with an FDE descriptor.
  54 .Pp
  55 Argument
  56 .Ar fde
  57 should reference a valid DWARF FDE descriptor.
  58 .Pp
  59 Argument
  60 .Ar pc
  61 should hold the program counter address to be used to locate the
  62 desired register rule row.
  63 .Pp
  64 On successful execution,
  65 .Fn dwarf_get_fde_info_for_cfa_reg3
  66 stores information about the CFA register rule found into the locations
  67 pointed to by the arguments
  68 .Ar type ,
  69 .Ar offset_relevant ,
  70 .Ar register_num ,
  71 .Ar offset_or_block_len ,
  72 .Ar block_ptr
  73 and
  74 .Ar row_pc .
  75 .Pp
  76 Argument
  77 .Ar type
  78 should point to a location which will hold the type code of the
  79 register rule found.
  80 The returned value is one of the
  81 .Dv DW_EXPR_*
  82 contants defined in the header file
  83 .In libdwarf.h .
  84 .Pp
  85 If there is an offset value associated with the CFA register rule,
  86 the location pointed to by argument
  87 .Ar offset_relevant
  88 will be set to 1.
  89 .Pp
  90 Argument
  91 .Ar register_num
  92 should point to a location which will hold the register number associated
  93 with the CFA register rule.
  94 .Pp
  95 If the CFA register rule is of type
  96 .Dv DW_EXPR_OFFSET
  97 or
  98 .Dv DW_EXPR_VAL_OFFSET ,
  99 the location pointed to by argument
 100 .Ar offset_or_block_len
 101 will be set to the offset value associated with the register rule,
 102 or to 0 if the register rule does not have an offset value.
 103 If the type code is
 104 .Dv DW_EXPR_EXPRESSION
 105 or
 106 .Dv DW_EXPR_VAL_EXPRESSION ,
 107 the location pointed to by argument
 108 .Ar offset_or_block_len
 109 will be set to the length in bytes of the DWARF expression block
 110 associated with the register rule.
 111 .Pp
 112 Argument
 113 .Ar block_ptr
 114 should point to a location which will be set to a pointer to the
 115 content of the DWARF expression block associated with the CFA register
 116 rule.
 117 .Pp
 118 Argument
 119 .Ar row_pc
 120 should point to a location which will be set to the lowest program
 121 counter address associated with the register rule found.
 122 .Pp
 123 If argument
 124 .Ar err
 125 is not NULL, it will be used to return an error descriptor in case
 126 of an error.
 127 .Sh RETURN VALUES
 128 Function
 129 .Fn dwarf_get_fde_info_for_cfa_reg3
 130 returns
 131 .Dv DW_DLV_OK
 132 when it succeeds.
 133 In case of an error, it returns
 134 .Dv DW_DLV_ERROR
 135 and sets the argument
 136 .Ar err .
 137 .Sh ERRORS
 138 Function
 139 .Fn dwarf_get_fde_info_for_cfa_reg3
 140 can fail with:
 141 .Bl -tag -width ".Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE"
 142 .It Bq Er DW_DLE_ARGUMENT
 143 One of the arguments
 144 .Ar block_ptr ,
 145 .Ar fde ,
 146 .Ar offset_or_block_len ,
 147 .Ar offset_relevant ,
 148 .Ar register_num ,
 149 .Ar row_pc ,
 150 or
 151 .Ar type
 152 was NULL.
 153 .It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE
 154 The program counter value provided in argument
 155 .Ar pc
 156 did not fall in the range covered by argument
 157 .Ar fde .
 158 .El
 159 .Sh SEE ALSO
 160 .Xr dwarf 3 ,
 161 .Xr dwarf_get_fde_at_pc 3 ,
 162 .Xr dwarf_get_fde_info_for_all_regs 3 ,
 163 .Xr dwarf_get_fde_info_for_all_regs3 3 ,
 164 .Xr dwarf_get_fde_info_for_reg 3 ,
 165 .Xr dwarf_get_fde_info_for_reg3 3 ,
 166 .Xr dwarf_get_fde_n 3 ,
 167 .Xr dwarf_set_frame_cfa_value 3 ,
 168 .Xr dwarf_set_frame_rule_initial_value 3 ,
 169 .Xr dwarf_set_frame_rule_table_size 3 ,
 170 .Xr dwarf_set_frame_same_value 3 ,
 171 .Xr dwarf_set_frame_undefined_value 3