1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_attrval_signed.3 2980 2014-01-21 20:15:54Z kaiwang27 $
29 .Dt DWARF_ATTRVAL_SIGNED 3
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
41 .Fo dwarf_attrval_flag
45 .Fa "Dwarf_Error *err"
48 .Fo dwarf_attrval_signed
51 .Fa "Dwarf_Signed *ret"
52 .Fa "Dwarf_Error *err"
55 .Fo dwarf_attrval_string
58 .Fa "const char **ret"
59 .Fa "Dwarf_Error *err"
62 .Fo dwarf_attrval_unsigned
65 .Fa "Dwarf_Unsigned *ret"
66 .Fa "Dwarf_Error *err"
69 These functions search the debugging information entry referenced
72 for the attribute named by argument
74 If the named attribute is found, the functions set the location
75 pointed to by argument
77 to the value of the attribute.
81 will be used to return an error descriptor in case of an error.
84 .Fn dwarf_attrval_flag
85 sets the location pointed to by argument
87 to either 0 or 1. If the form of the attribute named by argument
92 .Fn dwarf_attrval_flag
93 sets the location pointed to by argument
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
99 .Dv DW_FORM_flag_present ,
101 .Fn dwarf_attrval_flag
102 unconditionally sets the location pointed to by argument
105 The form of the attribute must be one of
108 .Dv DW_FORM_flag_present .
111 .Fn dwarf_attrval_signed
112 stores the value for the attribute named by argument
114 into the location pointed to by argument
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
122 class and must have one of the following forms:
131 .Fn dwarf_attrval_string
132 sets the location pointed to by argument
134 to a pointer to a NUL-terminated string that is the value of the
135 attribute named by argument
137 The form of the attribute must be one of
143 .Fn dwarf_attrval_unsigned
144 stores the value for the attribute named by argument
146 into the location pointed to by argument
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
155 classes and must have one of the following forms:
167 .Dv DW_FORM_ref_udata .
169 If the attribute named by argument
171 is not present in the debugging information entry referenced by
175 .Dv DW_AT_abstract_origin
176 attribute is present in the debugging information entry,
178 .Fn dwarf_attrval_unsigned
179 will search for the named attribute in the debugging information entry
181 .Dv DW_AT_abstract_origin
184 On success, these functions returns
186 If the named attribute was not found in the specified debugging
187 information entry descriptor these functions return
191 For other errors, these functions return
196 These functions are extensions added by this implementation of the
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
207 .It Bq Er DW_DLE_NO_ENTRY
210 did not contain an attribute corresponding to the value in argument
212 .It Bq Er DW_DLE_ATTR_FORM_BAD
213 The attribute named by argument
215 was not of a permitted form.