contrib/elftoolchain/libdwarf/dwarf_attrval_signed.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_attrval_signed.3 2980 2014-01-21 20:15:54Z kaiwang27 $
  26 .\"
  27 .Dd January 18, 2014
  28 .Os
  29 .Dt DWARF_ATTRVAL_SIGNED 3
  30 .Sh NAME
  31 .Nm dwarf_attrval_flag ,
  32 .Nm dwarf_attrval_signed ,
  33 .Nm dwarf_attrval_string ,
  34 .Nm dwarf_attrval_unsigned
  35 .Nd retrieve the value of an attribute within a DWARF debugging information entry
  36 .Sh LIBRARY
  37 .Lb libdwarf
  38 .Sh SYNOPSIS
  39 .In libdwarf.h
  40 .Ft int
  41 .Fo dwarf_attrval_flag
  42 .Fa "Dwarf_Die die"
  43 .Fa "Dwarf_Half attr"
  44 .Fa "Dwarf_Bool *ret"
  45 .Fa "Dwarf_Error *err"
  46 .Fc
  47 .Ft int
  48 .Fo dwarf_attrval_signed
  49 .Fa "Dwarf_Die die"
  50 .Fa "Dwarf_Half attr"
  51 .Fa "Dwarf_Signed *ret"
  52 .Fa "Dwarf_Error *err"
  53 .Fc
  54 .Ft int
  55 .Fo dwarf_attrval_string
  56 .Fa "Dwarf_Die die"
  57 .Fa "Dwarf_Half attr"
  58 .Fa "const char **ret"
  59 .Fa "Dwarf_Error *err"
  60 .Fc
  61 .Ft int
  62 .Fo dwarf_attrval_unsigned
  63 .Fa "Dwarf_Die die"
  64 .Fa "Dwarf_Half attr"
  65 .Fa "Dwarf_Unsigned *ret"
  66 .Fa "Dwarf_Error *err"
  67 .Fc
  68 .Sh DESCRIPTION
  69 These functions search the debugging information entry referenced
  70 by argument
  71 .Ar die
  72 for the attribute named by argument
  73 .Ar attr .
  74 If the named attribute is found, the functions set the location
  75 pointed to by argument
  76 .Ar ret
  77 to the value of the attribute.
  78 The argument
  79 .Ar err ,
  80 if non NULL,
  81 will be used to return an error descriptor in case of an error.
  82 .Pp
  83 Function
  84 .Fn dwarf_attrval_flag
  85 sets the location pointed to by argument
  86 .Ar ret
  87 to either 0 or 1. If the form of the attribute named by argument
  88 .Ar attr
  89 is
  90 .Dv DW_FORM_flag ,
  91 function
  92 .Fn dwarf_attrval_flag
  93 sets the location pointed to by argument
  94 .Ar ret
  95 to 1 if the attribute has a non-zero value, or to 0 otherwise.
  96 If the form of the attribute named by argument
  97 .Ar attr
  98 is
  99 .Dv DW_FORM_flag_present ,
 100 function
 101 .Fn dwarf_attrval_flag
 102 unconditionally sets the location pointed to by argument
 103 .Ar ret
 104 to 1.
 105 The form of the attribute must be one of
 106 .Dv DW_FORM_flag
 107 or
 108 .Dv DW_FORM_flag_present .
 109 .Pp
 110 Function
 111 .Fn dwarf_attrval_signed
 112 stores the value for the attribute named by argument
 113 .Ar attr ,
 114 into the location pointed to by argument
 115 .Ar ret .
 116 The attribute's value is treated as a signed integral quantity and is
 117 sign-extended as needed.
 118 The attribute named by the argument
 119 .Ar attr
 120 must belong to the
 121 .Dv CONSTANT
 122 class and must have one of the following forms:
 123 .Dv DW_FORM_data1 ,
 124 .Dv DW_FORM_data2 ,
 125 .Dv DW_FORM_data4 ,
 126 .Dv DW_FORM_data8
 127 or
 128 .Dv DW_FORM_sdata .
 129 .Pp
 130 Function
 131 .Fn dwarf_attrval_string
 132 sets the location pointed to by argument
 133 .Ar ret
 134 to a pointer to a NUL-terminated string that is the value of the
 135 attribute named by argument
 136 .Ar attr .
 137 The form of the attribute must be one of
 138 .Dv DW_FORM_string
 139 or
 140 .Dv DW_FORM_strp .
 141 .Pp
 142 Function
 143 .Fn dwarf_attrval_unsigned
 144 stores the value for the attribute named by argument
 145 .Ar attr
 146 into the location pointed to by argument
 147 .Ar ret .
 148 The attribute's value is treated as an unsigned integral quantity, and
 149 is zero-extended as needed.
 150 The named attribute must belong to one of the
 151 .Dv CONSTANT ,
 152 .Dv ADDRESS
 153 or
 154 .Dv REFERENCE
 155 classes and must have one of the following forms:
 156 .Dv DW_FORM_addr ,
 157 .Dv DW_FORM_data1 ,
 158 .Dv DW_FORM_data2 ,
 159 .Dv DW_FORM_data4 ,
 160 .Dv DW_FORM_data8 ,
 161 .Dv DW_FORM_udata ,
 162 .Dv DW_FORM_ref1 ,
 163 .Dv DW_FORM_ref2 ,
 164 .Dv DW_FORM_ref4 ,
 165 .Dv DW_FORM_ref8 ,
 166 or
 167 .Dv DW_FORM_ref_udata .
 168 .Pp
 169 If the attribute named by argument
 170 .Ar attr
 171 is not present in the debugging information entry referenced by
 172 argument
 173 .Ar die ,
 174 and if a
 175 .Dv DW_AT_abstract_origin
 176 attribute is present in the debugging information entry,
 177 function
 178 .Fn dwarf_attrval_unsigned
 179 will search for the named attribute in the debugging information entry
 180 referenced by the
 181 .Dv DW_AT_abstract_origin
 182 attribute.
 183 .Sh RETURN VALUES
 184 On success, these functions returns
 185 .Dv DW_DLV_OK .
 186 If the named attribute was not found in the specified debugging
 187 information entry descriptor these functions return
 188 .Dv DW_DLV_NO_ENTRY
 189 and set argument
 190 .Ar err .
 191 For other errors, these functions return
 192 .Dv DW_DLV_ERROR
 193 and set argument
 194 .Ar err .
 195 .Sh COMPATIBILITY
 196 These functions are extensions added by this implementation of the
 197 DWARF(3) API.
 198 .Sh ERRORS
 199 These functions may fail with the following errors:
 200 .Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD"
 201 .It Bq Er DW_DLE_ARGUMENT
 202 Either of the arguments
 203 .Va die
 204 or
 205 .Va ret
 206 was NULL.
 207 .It Bq Er DW_DLE_NO_ENTRY
 208 Argument
 209 .Ar die
 210 did not contain an attribute corresponding to the value in argument
 211 .Ar attr .
 212 .It Bq Er DW_DLE_ATTR_FORM_BAD
 213 The attribute named by argument
 214 .Ar attr
 215 was not of a permitted form.
 216 .El
 217 .Sh SEE ALSO
 218 .Xr dwarf 3 ,
 219 .Xr dwarf_attr 3 ,
 220 .Xr dwarf_hasattr 3