xref: /freebsd/contrib/elftoolchain/libdwarf/dwarf_attrval_signed.3 (revision 3b8f08459569bf0faa21473e5cec2491e95c9349)
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 2072 2011-10-27 03:26:49Z jkoshy $
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
69These functions search the debugging information entry referenced
70by argument
71.Ar die
72for the attribute named by argument
73.Ar attr .
74If the named attribute is found, the functions set the location
75pointed to by argument
76.Ar ret
77to the value of the attribute.
78The argument
79.Ar err ,
80if non NULL,
81will be used to return an error descriptor in case of an error.
82.Pp
83Function
84.Fn dwarf_attrval_flag
85sets the location pointed to by argument
86.Ar ret
87to either 0 or 1. If the form of the attribute named by argument
88.Ar attr
89is
90.Dv DW_FORM_flag ,
91function
92.Fn dwarf_attrval_flag
93sets the location pointed to by argument
94.Ar ret
95to 1 if the attribute has a non-zero value, or to 0 otherwise.
96If the form of the attribute named by argument
97.Ar attr
98is
99.Dv DW_FORM_flag_present ,
100function
101.Fn dwarf_attrval_flag
102unconditionally sets the location pointed to by argument
103.Ar ret
104to 1.
105The form of the attribute must be one of
106.Dv DW_FORM_flag
107or
108.Dv DW_FORM_flag_present .
109.Pp
110Function
111.Fn dwarf_attrval_signed
112stores the value for the attribute named by argument
113.Ar attr ,
114into the location pointed to by argument
115.Ar ret .
116The attribute's value is treated as a signed integral quantity and is
117sign-extended as needed.
118The attribute named by the argument
119.Ar attr
120must belong to the
121.Dv CONSTANT
122class 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
127or
128.Dv DW_FORM_sdata .
129.Pp
130Function
131.Fn dwarf_attrval_string
132sets the location pointed to by argument
133.Ar ret
134to a pointer to a NUL-terminated string that is the value of the
135attribute named by argument
136.Ar attr .
137The form of the attribute must be one of
138.Dv DW_FORM_string
139or
140.Dv DW_FORM_strp .
141.Pp
142Function
143.Fn dwarf_attrval_unsigned
144stores the value for the attribute named by argument
145.Ar attr
146into the location pointed to by argument
147.Ar ret .
148The attribute's value is treated as an unsigned integral quantity, and
149is zero-extended as needed.
150The named attribute must belong to one of the
151.Dv CONSTANT ,
152.Dv ADDRESS
153or
154.Dv REFERENCE
155classes 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 ,
166or
167.Dv DW_FORM_ref_udata .
168.Pp
169If the attribute named by argument
170.Ar attr
171is not present in the debugging information entry referenced by
172argument
173.Ar die ,
174and if a
175.Dv DW_AT_abstract_origin
176attribute is present in the debugging information entry,
177function
178.Fn dwarf_attrval_unsigned
179will search for the named attribute in the debugging information entry
180referenced by the
181.Dv DW_AT_abstract_origin
182attribute.
183.Sh RETURN VALUES
184On success, these functions returns
185.Dv DW_DLV_OK .
186If the named attribute was not found in the specified debugging
187information entry descriptor these functions return
188.Dv DW_DLV_NO_ENTRY
189and set argument
190.Ar err .
191For other errors, these functions return
192.Dv DW_DLV_ERROR
193and set argument
194.Ar err .
195.Sh COMPATIBILITY
196These functions are extensions added by this implementation of the
197DWARF(3) API.
198.Sh ERRORS
199These 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
202Either of the arguments
203.Va die
204or
205.Va ret
206was NULL.
207.It Bq Er DW_DLE_NO_ENTRY
208Argument
209.Ar die
210did not contain an attribute corresponding to the value in argument
211.Ar attr .
212.It Bq Er DW_DLE_ATTR_FORM_BAD
213The attribute named by argument
214.Ar attr
215was 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
221