Annotation of src/external/bsd/elftoolchain/dist/libdwarf/dwarf_attrval_signed.3, Revision 1.2
1.2 ! christos 1: .\" $NetBSD$
! 2: .\"
1.1 christos 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
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to dwarf_attrval_signed.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / external / bsd / elftoolchain / dist / libdwarf