| blob | 19b68f80829bbf34ef06bd92bf0c597088fd565f |
1 .\" $NetBSD: dwarf_dealloc.3,v 1.2 2014/03/09 16:58:03 christos Exp $
2 .\"
3 .\" Copyright (c) 2009-2011 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_dealloc.3 2073 2011-10-27 03:30:47Z jkoshy
27 .\"
28 .Dd July 23, 2011
29 .Os
30 .Dt DWARF_DEALLOC 3
31 .Sh NAME
32 .Nm dwarf_dealloc ,
33 .Nm dwarf_fde_cie_list_dealloc ,
34 .Nm dwarf_funcs_dealloc ,
35 .Nm dwarf_globals_dealloc ,
36 .Nm dwarf_pubtypes_dealloc ,
37 .Nm dwarf_ranges_dealloc ,
38 .Nm dwarf_srclines_dealloc ,
39 .Nm dwarf_types_dealloc ,
40 .Nm dwarf_vars_dealloc ,
41 .Nm dwarf_weaks_dealloc
42 .Nd release resources
43 .Sh LIBRARY
44 .Lb libdwarf
45 .Sh SYNOPSIS
46 .In libdwarf.h
47 .Ft void
48 .Fo dwarf_dealloc
49 .Fa "Dwarf_Debug dbg"
50 .Fa "Dwarf_Ptr ptr"
51 .Fa "Dwarf_Unsigned type"
52 .Fc
53 .Fo dwarf_fde_cie_list_dealloc
54 .Fa "Dwarf_Debug dbg"
55 .Fa "Dwarf_Cie *cie_list"
56 .Fa "Dwarf_Signed cie_count"
57 .Fa "Dwarf_Fde *fde_list"
58 .Fa "Dwarf_Signed fde_count"
59 .Fc
60 .Ft void
61 .Fo dwarf_funcs_dealloc
62 .Fa "Dwarf_Debug dbg"
63 .Fa "Dwarf_Func *funcs"
64 .Fa "Dwarf_Signed funccount"
65 .Fc
66 .Ft void
67 .Fo dwarf_globals_dealloc
68 .Fa "Dwarf_Debug dbg"
69 .Fa "Dwarf_Global *globals"
70 .Fa "Dwarf_Signed globalcount"
71 .Fc
72 .Ft void
73 .Fo dwarf_pubtypes_dealloc
74 .Fa "Dwarf_Debug dbg"
75 .Fa "Dwarf_Type *pubtypes"
76 .Fa "Dwarf_Signed pubtypecount"
77 .Fc
78 .Ft void
79 .Fo dwarf_ranges_dealloc
80 .Fa "Dwarf_Debug dbg"
81 .Fa "Dwarf_Ranges *ranges"
82 .Fa "Dwarf_Signed rangecount"
83 .Fc
84 .Ft void
85 .Fo dwarf_srclines_dealloc
86 .Fa "Dwarf_Debug dbg"
87 .Fa "Dwarf_Line *lines"
88 .Fa "Dwarf_Signed linecount"
89 .Fc
90 .Ft void
91 .Fo dwarf_types_dealloc
92 .Fa "Dwarf_Debug dbg"
93 .Fa "Dwarf_Type *types"
94 .Fa "Dwarf_Signed typecount"
95 .Fc
96 .Ft void
97 .Fo dwarf_vars_dealloc
98 .Fa "Dwarf_Debug dbg"
99 .Fa "Dwarf_Var *vars"
100 .Fa "Dwarf_Signed varcount"
101 .Fc
102 .Ft void
103 .Fo dwarf_weaks_dealloc
104 .Fa "Dwarf_Debug dbg"
105 .Fa "Dwarf_Weak *weaks"
106 .Fa "Dwarf_Signed weakcount"
107 .Fc
108 .Sh DESCRIPTION
109 The function
110 .Fn dwarf_dealloc
111 is used by applications to indicate that memory areas returned by
112 .Lb libdwarf
113 may be safely disposed off.
114 Due to the way memory is managed in the current implementation, the
115 use of
116 .Fn dwarf_dealloc
117 is only necessary for a small set of DWARF types.
118 .Pp
119 Argument
120 .Ar dbg
121 should reference a valid debugging context allocated using
122 .Xr dwarf_init 3 .
123 .Pp
124 Argument
125 .Ar ptr
126 should point to an object or memory area obtained by a prior call
127 to a DWARF(3) function.
128 .Pp
129 Argument
130 .Ar type
131 indicates the type of object being deallocated.
132 The indicated type must match that of the object being passed in
133 argument
134 .Ar ptr .
135 Valid values for the
136 .Ar type
137 argument are:
138 .Bl -tag -width ".Dv DW_DLA_FRAME_BLOCK"
139 .It Dv DW_DLA_ABBREV
140 An object of type
141 .Vt Dwarf_Abbrev ,
142 as returned by a call to the function
143 .Xr dwarf_get_abbrev 3 .
144 .It Dv DW_DLA_DIE
145 An object of type
146 .Vt Dwarf_Die ,
147 as returned by calls to the functions
148 .Xr dwarf_child 3 ,
149 .Xr dwarf_offdie 3
150 or
151 .Xr dwarf_siblingof 3 .
152 .It Dv DW_DLA_FRAME_BLOCK
153 An array of objects of type
154 .Vt Dwarf_Frame_op ,
155 as returned by a call to the function
156 .Xr dwarf_expand_frame_instructions 3 .
157 .El
158 .Pp
159 Calls to
160 .Fn dwarf_dealloc
161 with other values for argument
162 .Ar type
163 are no-ops in this implementation.
164 .Pp
165 The functions
166 .Fn dwarf_fde_cie_list_dealloc ,
167 .Fn dwarf_funcs_dealloc ,
168 .Fn dwarf_globals_dealloc ,
169 .Fn dwarf_pubtypes_dealloc ,
170 .Fn dwarf_ranges_dealloc ,
171 .Fn dwarf_srclines_dealloc ,
172 .Fn dwarf_types_dealloc ,
173 .Fn dwarf_vars_dealloc
174 and
175 .Fn dwarf_weaks_dealloc
176 are provided for compatibility with other implementations of the
177 DWARF(3) API.
178 Due to the way memory is managed in the current implementation, these
179 functions are effectively no-ops.
180 .Pp
181 See
182 .Xr dwarf 3
183 for more information about the memory management scheme in this
184 implementation of the DWARF(3) API.
185 .Sh RETURN VALUES
186 Functions
187 .Fn dwarf_dealloc ,
188 .Fn dwarf_fde_cie_list_dealloc ,
189 .Fn dwarf_funcs_dealloc ,
190 .Fn dwarf_globals_dealloc ,
191 .Fn dwarf_pubtypes_dealloc ,
192 .Fn dwarf_ranges_dealloc ,
193 .Fn dwarf_srclines_dealloc ,
194 .Fn dwarf_types_dealloc ,
195 .Fn dwarf_vars_dealloc
196 and
197 .Fn dwarf_weaks_dealloc
198 have no return value.
199 .Sh SEE ALSO
200 .Xr dwarf 3 ,
201 .Xr dwarf_child 3 ,
202 .Xr dwarf_expand_frame_instructions 3 ,
203 .Xr dwarf_get_abbrev 3 ,
204 .Xr dwarf_offdie 3 ,
205 .Xr dwarf_siblingof 3