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

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