xref: /netbsd-src/external/bsd/elftoolchain/dist/libdwarf/dwarf_formudata.3 (revision 5ac3bc719ce6e70593039505b491894133237d12)
1.\"	$NetBSD: dwarf_formudata.3,v 1.6 2024/03/03 17:37:31 christos Exp $
2.\"
3.\" Copyright (c) 2010 Joseph Koshy
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_formudata.3 3962 2022-03-12 15:56:10Z jkoshy
28.\"
29.Dd June 21, 2010
30.Dt DWARF_FORMUDATA 3
31.Os
32.Sh NAME
33.Nm dwarf_formudata ,
34.Nm dwarf_formsdata
35.Nd return the value of a CONSTANT class attribute
36.Sh LIBRARY
37.Lb libdwarf
38.Sh SYNOPSIS
39.In libdwarf.h
40.Ft int
41.Fo dwarf_formudata
42.Fa "Dwarf_Attribute attr"
43.Fa "Dwarf_Unsigned *ret"
44.Fa "Dwarf_Error *err"
45.Fc
46.Ft int
47.Fo dwarf_formsdata
48.Fa "Dwarf_Attribute attr"
49.Fa "Dwarf_Signed *ret"
50.Fa "Dwarf_Error *err"
51.Fc
52.Sh DESCRIPTION
53These functions return the value associated with a DWARF attribute
54describing a constant.
55.Pp
56Function
57.Fn dwarf_formudata
58sets the location pointed to by argument
59.Fa ret
60to the value of the attribute referenced by argument
61.Fa attr ,
62treating the value as an unsigned quantity.
63Argument
64.Fa attr
65must have one of the following forms:
66.Dv DW_FORM_data1 ,
67.Dv DW_FORM_data2 ,
68.Dv DW_FORM_data4 ,
69.Dv DW_FORM_data8
70and
71.Dv DW_FORM_udata .
72.Pp
73Function
74.Fn dwarf_formsdata
75sets the location pointed to by argument
76.Fa ret
77to the value of the attribute referenced by argument
78.Fa attr ,
79appropriately sign extended.
80Argument
81.Fa attr
82must have one of the following forms:
83.Dv DW_FORM_data1 ,
84.Dv DW_FORM_data2 ,
85.Dv DW_FORM_data4 ,
86.Dv DW_FORM_data8
87and
88.Dv DW_FORM_sdata .
89.Pp
90If argument
91.Fa err
92is not
93.Dv NULL ,
94it will be used to return an error descriptor in case of an error.
95.Sh RETURN VALUES
96These functions return
97.Dv DW_DLV_OK
98on success.
99In case of an error, they return
100.Dv DW_DLV_ERROR
101and set argument
102.Fa err .
103.Sh ERRORS
104These functions may fail with the following errors:
105.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD"
106.It Bq Er DW_DLE_ARGUMENT
107Either of arguments
108.Fa attr
109or
110.Fa ret
111was
112.Dv NULL .
113.It Bq Er DW_DLE_ATTR_FORM_BAD
114The attribute referenced by argument
115.Fa attr
116was not of a permitted kind.
117.El
118.Sh SEE ALSO
119.Xr dwarf 3 ,
120.Xr dwarf_attr 3 ,
121.Xr dwarf_formblock 3 ,
122.Xr dwarf_formflag 3 ,
123.Xr dwarf_formref 3 ,
124.Xr dwarf_formsig8 3 ,
125.Xr dwarf_formstring 3 ,
126.Xr dwarf_hasattr 3
127