contrib/elftoolchain/libdwarf/dwarf_dealloc.3

   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
 107 The function
 108 .Fn dwarf_dealloc
 109 is used by applications to indicate that memory areas returned by
 110 .Lb libdwarf
 111 may be safely disposed off.
 112 Due to the way memory is managed in the current implementation, the
 113 use of
 114 .Fn dwarf_dealloc
 115 is only necessary for a small set of DWARF types.
 116 .Pp
 117 Argument
 118 .Ar dbg
 119 should reference a valid debugging context allocated using
 120 .Xr dwarf_init 3 .
 121 .Pp
 122 Argument
 123 .Ar ptr
 124 should point to an object or memory area obtained by a prior call
 125 to a DWARF(3) function.
 126 .Pp
 127 Argument
 128 .Ar type
 129 indicates the type of object being deallocated.
 130 The indicated type must match that of the object being passed in
 131 argument
 132 .Ar ptr .
 133 Valid values for the
 134 .Ar type
 135 argument are:
 136 .Bl -tag -width ".Dv DW_DLA_FRAME_BLOCK"
 137 .It Dv DW_DLA_ABBREV
 138 An object of type
 139 .Vt Dwarf_Abbrev ,
 140 as returned by a call to the function
 141 .Xr dwarf_get_abbrev 3 .
 142 .It Dv DW_DLA_DIE
 143 An object of type
 144 .Vt Dwarf_Die ,
 145 as returned by calls to the functions
 146 .Xr dwarf_child 3 ,
 147 .Xr dwarf_offdie 3
 148 or
 149 .Xr dwarf_siblingof 3 .
 150 .It Dv DW_DLA_FRAME_BLOCK
 151 An array of objects of type
 152 .Vt Dwarf_Frame_op ,
 153 as returned by a call to the function
 154 .Xr dwarf_expand_frame_instructions 3 .
 155 .El
 156 .Pp
 157 Calls to
 158 .Fn dwarf_dealloc
 159 with other values for argument
 160 .Ar type
 161 are no-ops in this implementation.
 162 .Pp
 163 The 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
 172 and
 173 .Fn dwarf_weaks_dealloc
 174 are provided for compatibility with other implementations of the
 175 DWARF(3) API.
 176 Due to the way memory is managed in the current implementation, these
 177 functions are effectively no-ops.
 178 .Pp
 179 See
 180 .Xr dwarf 3
 181 for more information about the memory management scheme in this
 182 implementation of the DWARF(3) API.
 183 .Sh RETURN VALUES
 184 Functions
 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
 194 and
 195 .Fn dwarf_weaks_dealloc
 196 have 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