1.\" Copyright (c) 2010 Joseph Koshy.  All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" This software is provided by Joseph Koshy ``as is'' and
13.\" any express or implied warranties, including, but not limited to, the
14.\" implied warranties of merchantability and fitness for a particular purpose
15.\" are disclaimed.  in no event shall Joseph Koshy be liable
16.\" for any direct, indirect, incidental, special, exemplary, or consequential
17.\" damages (including, but not limited to, procurement of substitute goods
18.\" or services; loss of use, data, or profits; or business interruption)
19.\" however caused and on any theory of liability, whether in contract, strict
20.\" liability, or tort (including negligence or otherwise) arising in any way
21.\" out of the use of this software, even if advised of the possibility of
22.\" such damage.
23.\"
24.\" $Id: dwarf_hasform.3 3640 2018-10-14 14:09:13Z jkoshy $
25.\"
26.Dd May 22, 2010
27.Dt DWARF_HASFORM 3
28.Os
29.Sh NAME
30.Nm dwarf_hasform ,
31.Nm dwarf_whatform ,
32.Nm dwarf_whatform_direct
33.Nd query attribute forms
34.Sh LIBRARY
35.Lb libdwarf
36.Sh SYNOPSIS
37.In libdwarf.h
38.Ft int
39.Fo dwarf_hasform
40.Fa "Dwarf_Attribute attr"
41.Fa "Dwarf_Half form"
42.Fa "Dwarf_Bool *ret"
43.Fa "Dwarf_Error *err"
44.Fc
45.Ft int
46.Fo dwarf_whatform
47.Fa "Dwarf_Attribute attr"
48.Fa "Dwarf_Half *retform"
49.Fa "Dwarf_Error *err"
50.Fc
51.Ft int
52.Fo dwarf_whatform_direct
53.Fa "Dwarf_Attribute attr"
54.Fa "Dwarf_Half *retform"
55.Fa "Dwarf_Error *err"
56.Fc
57.Sh DESCRIPTION
58Function
59.Fn dwarf_hasform
60indicates whether the DWARF attribute denoted by argument
61.Ar attr
62has the attribute form specified by argument
63.Ar form .
64If the attribute has the specified form, then
65argument
66.Ar ret
67is set to a non-zero value, otherwise it is set to zero.
68If argument
69.Ar err
70is non-NULL, it will be used to return an error descriptor in
71case of an error.
72.Pp
73Function
74.Fn dwarf_whatform
75sets the location specified by argument
76.Ar retform
77to the attribute form code for the DWARF attribute referenced
78by argument
79.Ar attr .
80If the attribute referenced by argument
81.Ar attr
82has an indirect form attribute, this function will return the final
83form for the attribute.
84If argument
85.Ar err
86is non-NULL, it will be used to return an error descriptor in
87case of an error.
88.Pp
89Function
90.Fn dwarf_whatform_direct
91sets the location specified by argument
92.Ar retform
93to the attribute form code for the DWARF attribute referenced
94by argument
95.Ar attr .
96If the form is an indirect form, the function sets the location
97specified by argument
98.Ar retform
99to
100.Dv DW_FORM_indirect .
101If argument
102.Ar err
103is non-NULL, it will be used to return an error descriptor in
104case of an error.
105.Sh RETURN VALUES
106These functions return
107.Dv DW_DLV_OK
108on success.
109In case of an error, these functions return
110.Dv DW_DLV_ERR
111and set argument
112.Ar err .
113.Sh ERRORS
114These functions may fail with the following errors:
115.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
116.It Bq Er DW_DLE_ARGUMENT
117Any of the arguments
118.Ar attr ,
119.Ar ret ,
120or
121.Ar retform
122was NULL.
123.El
124.Sh SEE ALSO
125.Xr dwarf 3 ,
126.Xr dwarf_attr 3 ,
127.Xr dwarf_hasattr 3
128