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