contrib/elftoolchain/libdwarf/dwarf_set_frame_cfa_value.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_set_frame_cfa_value.3 2075 2011-10-27 03:47:28Z jkoshy $
  26 .\"
  27 .Dd June 18, 2011
  28 .Os
  29 .Dt DWARF_SET_FRAME_CFA_VALUE 3
  30 .Sh NAME
  31 .Nm dwarf_set_frame_cfa_value ,
  32 .Nm dwarf_set_frame_rule_initial_value ,
  33 .Nm dwarf_set_frame_rule_table_size ,
  34 .Nm dwarf_set_frame_same_value ,
  35 .Nm dwarf_set_frame_undefined_value
  36 .Nd set internal register rule table parameters
  37 .Sh LIBRARY
  38 .Lb libdwarf
  39 .Sh SYNOPSIS
  40 .In libdwarf.h
  41 .Ft Dwarf_Half
  42 .Fo dwarf_set_frame_cfa_value
  43 .Fa "Dwarf_Debug dbg"
  44 .Fa "Dwarf_Half value"
  45 .Fc
  46 .Ft Dwarf_Half
  47 .Fo dwarf_set_frame_rule_initial_value
  48 .Fa "Dwarf_Debug dbg"
  49 .Fa "Dwarf_Half value"
  50 .Fc
  51 .Ft Dwarf_Half
  52 .Fo dwarf_set_frame_rule_table_size
  53 .Fa "Dwarf_Debug dbg"
  54 .Fa "Dwarf_Half value"
  55 .Fc
  56 .Ft Dwarf_Half
  57 .Fo dwarf_set_frame_same_value
  58 .Fa "Dwarf_Debug dbg"
  59 .Fa "Dwarf_Half value"
  60 .Fc
  61 .Ft Dwarf_Half
  62 .Fo dwarf_set_frame_undefined_value
  63 .Fa "Dwarf_Debug dbg"
  64 .Fa "Dwarf_Half value"
  65 .Fc
  66 .Sh DESCRIPTION
  67 These functions set the parameters of the internal register
  68 rule table.
  69 .Pp
  70 Argument
  71 .Ar dbg
  72 should reference a DWARF debug context allocated using
  73 .Xr dwarf_init 3 .
  74 .Pp
  75 Argument
  76 .Ar value
  77 should hold the parameter value to set.
  78 .Pp
  79 Function
  80 .Fn dwarf_set_frame_cfa_value
  81 sets the column number for the CFA register rule in the internal
  82 register rule table.
  83 The constant
  84 .Dv DW_FRAME_CFA_COL
  85 is the default CFA register column number for DWARF2-only
  86 interfaces, and the constant
  87 .Dv DW_FRAME_CFA_COL3
  88 is the default CFA column number for DWARF3-compatible interfaces.
  89 .Pp
  90 Function
  91 .Fn dwarf_set_frame_rule_initial_value
  92 sets the initial value of the register rules in the internal register
  93 rule table.
  94 The default initial value is the constant
  95 .Dv DW_FRAME_REG_INITIAL_VALUE ,
  96 defined in the header file
  97 .In libdwarf.h .
  98 .Pp
  99 Function
 100 .Fn dwarf_set_frame_rule_table_size
 101 sets the maxmium number of columns of the internal register rule table.
 102 Argument
 103 .Ar value
 104 should be at least as large as the number of real registers in the ABI.
 105 .Pp
 106 Function
 107 .Fn dwarf_set_frame_same_value
 108 sets the register number representing the
 109 .Dq "same value"
 110 register rule.
 111 The default register number for the
 112 .Dq "same value"
 113 rule is the constant
 114 .Dv DW_FRAME_SAME_VAL ,
 115 defined in the header file
 116 .In libdwarf.h .
 117 .Pp
 118 Function
 119 .Fn dwarf_set_frame_undefined_value
 120 sets the register number representing the
 121 .Dq undefined
 122 register rule.
 123 The default register number for the
 124 .Dq undefined
 125 rule is the constant
 126 .Dv DW_FRAME_UNDEFINED_VAL ,
 127 defined in the header file
 128 .In libdwarf.h .
 129 .Sh RETURN VALUES
 130 These functions return the previous value of the parameter being
 131 set.
 132 .Sh SEE ALSO
 133 .Xr dwarf 3 ,
 134 .Xr dwarf_get_fde_at_pc 3 ,
 135 .Xr dwarf_get_fde_info_for_all_regs 3 ,
 136 .Xr dwarf_get_fde_info_for_all_regs3 3 ,
 137 .Xr dwarf_get_fde_info_for_cfa_reg3 3 ,
 138 .Xr dwarf_get_fde_info_for_reg 3 ,
 139 .Xr dwarf_get_fde_info_for_reg3 3 ,
 140 .Xr dwarf_get_fde_n 3