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