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 3509 2016-12-29 03:58:41Z emaste $
  26 .\"
  27 .Dd December 26, 2016
  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
 172 .Dv DW_AT_type
 173 and is not present in the debugging information entry referenced by argument
 174 .Ar die ,
 175 and if a
 176 .Dv DW_AT_abstract_origin
 177 or
 178 .Dv DW_AT_specification
 179 attribute is present in the debugging information entry,
 180 function
 181 .Fn dwarf_attrval_unsigned
 182 will search for the named attribute in the debugging information entry
 183 referenced by the
 184 .Dv DW_AT_abstract_origin
 185 or
 186 .Dv DW_AT_specification
 187 attribute.
 188 .Sh RETURN VALUES
 189 On success, these functions returns
 190 .Dv DW_DLV_OK .
 191 If the named attribute was not found in the specified debugging
 192 information entry descriptor these functions return
 193 .Dv DW_DLV_NO_ENTRY
 194 and set argument
 195 .Ar err .
 196 For other errors, these functions return
 197 .Dv DW_DLV_ERROR
 198 and set argument
 199 .Ar err .
 200 .Sh COMPATIBILITY
 201 These functions are extensions added by this implementation of the
 202 DWARF(3) API.
 203 .Sh ERRORS
 204 These functions may fail with the following errors:
 205 .Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD"
 206 .It Bq Er DW_DLE_ARGUMENT
 207 Either of the arguments
 208 .Va die
 209 or
 210 .Va ret
 211 was NULL.
 212 .It Bq Er DW_DLE_NO_ENTRY
 213 Argument
 214 .Ar die
 215 did not contain an attribute corresponding to the value in argument
 216 .Ar attr .
 217 .It Bq Er DW_DLE_ATTR_FORM_BAD
 218 The attribute named by argument
 219 .Ar attr
 220 was not of a permitted form.
 221 .El
 222 .Sh SEE ALSO
 223 .Xr dwarf 3 ,
 224 .Xr dwarf_attr 3 ,
 225 .Xr dwarf_hasattr 3