contrib/elftoolchain/libdwarf/dwarf_get_types.3

   1 .\" Copyright (c) 2011 Kai Wang
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Id: dwarf_get_types.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd April 10, 2011
  28 .Dt DWARF_GET_TYPES 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_get_types ,
  32 .Nm dwarf_type_cu_offset ,
  33 .Nm dwarf_type_die_offset ,
  34 .Nm dwarf_type_name_offsets ,
  35 .Nm dwarf_typename
  36 .Nd retrieve information about user-defined types
  37 .Sh LIBRARY
  38 .Lb libdwarf
  39 .Sh SYNOPSIS
  40 .In libdwarf.h
  41 .Ft int
  42 .Fo dwarf_get_types
  43 .Fa "Dwarf_Debug dbg"
  44 .Fa "Dwarf_Type **types"
  45 .Fa "Dwarf_Signed *ntypes"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Ft int
  49 .Fo dwarf_type_cu_offset
  50 .Fa "Dwarf_Type type"
  51 .Fa "Dwarf_Off *cu_offset"
  52 .Fa "Dwarf_Error *err"
  53 .Fc
  54 .Ft int
  55 .Fo dwarf_type_die_offset
  56 .Fa "Dwarf_Type type"
  57 .Fa "Dwarf_Off *die_offset"
  58 .Fa "Dwarf_Error *err"
  59 .Fc
  60 .Ft int
  61 .Fo dwarf_type_name_offsets
  62 .Fa "Dwarf_Type type"
  63 .Fa "char **name"
  64 .Fa "Dwarf_Off *die_offset"
  65 .Fa "Dwarf_Off *cu_die_offset"
  66 .Fa "Dwarf_Error *err"
  67 .Fc
  68 .Ft int
  69 .Fo dwarf_typename
  70 .Fa "Dwarf_Type type"
  71 .Fa "char **name"
  72 .Fa "Dwarf_Error *err"
  73 .Fc
  74 .Sh DESCRIPTION
  75 These APIs retrieve information about user-defined types from the
  76 SGI-specific
  77 .Dq ".debug_typenames"
  78 section.
  79 .Pp
  80 Standards-conformant applications should use the functions
  81 .Xr dwarf_get_pubtypes 3 ,
  82 .Xr dwarf_pubtype_cu_offset 3 ,
  83 .Xr dwarf_pubtype_die_offset 3 ,
  84 .Xr dwarf_pubtype_name_offsets 3
  85 and
  86 .Xr dwarf_pubtypename 3 ,
  87 which operate on the equivalent
  88 .Dq ".debug_pubtypes"
  89 section defined by the DWARF3 standard.
  90 .Pp
  91 Information about user-defined types is returned using opaque descriptors
  92 of type
  93 .Vt Dwarf_Type .
  94 Applications need to use the functions described below to retrieve
  95 the name and offset information contained in these descriptors.
  96 .Pp
  97 Function
  98 .Fn dwarf_get_types
  99 retrieves descriptors for all user-defined types associated with the
 100 DWARF debug context specified by argument
 101 .Ar dbg .
 102 The argument
 103 .Ar types
 104 should point to a location that will be set to a pointer to an array
 105 of
 106 .Vt Dwarf_Type
 107 descriptors.
 108 The argument
 109 .Ar ntypes
 110 should point to a location that will be set to the number of
 111 descriptors returned.
 112 .Pp
 113 Function
 114 .Fn dwarf_type_cu_offset
 115 returns the offset, relative to the
 116 .Dq ".debug_info"
 117 section, of the compilation unit that contains the debugging
 118 information entry associated with the argument
 119 .Ar type .
 120 Argument
 121 .Ar cu_offset
 122 should point to a location that will hold the returned offset.
 123 .Pp
 124 Function
 125 .Fn dwarf_type_die_offset
 126 retrieves the offset, relative to the
 127 .Dq ".debug_info"
 128 section, of the debugging information entry associated with the
 129 argument
 130 .Ar type ,
 131 and stores it into the location pointed to by the argument
 132 .Ar die_offset .
 133 .Pp
 134 Function
 135 .Fn dwarf_type_name_offsets
 136 retrieves the name and offsets for the debugging information
 137 entry for argument
 138 .Ar type .
 139 Argument
 140 .Ar name
 141 should point to a location which will be set to a pointer to a
 142 NUL-terminated string containing the name of the associated debugging
 143 information entry.
 144 Argument
 145 .Ar die_offset
 146 should point to a location which will be set to the offset, relative
 147 to the
 148 .Dq ".debug_info"
 149 section, of the associated debugging information entry.
 150 Argument
 151 .Ar cu_die_offset
 152 should point to a location which will be set to a offset, relative to
 153 the
 154 .Dq ".debug_info"
 155 section, of the first debugging information entry in the compilation
 156 unit associated with argument
 157 .Ar type .
 158 .Pp
 159 Function
 160 .Fn dwarf_typename
 161 sets the location pointed to by argument
 162 .Ar name
 163 to a pointer to a NUL-terminated string holding the name of the
 164 debugging information entry associated with the argument
 165 .Ar type .
 166 .Ss Memory Management
 167 The memory area used for the array of
 168 .Vt Dwarf_Type
 169 descriptors returned in argument
 170 .Ar types
 171 by function
 172 .Fn dwarf_get_types
 173 is owned by the
 174 .Lb libdwarf .
 175 Application code should not attempt to directly free this pointer.
 176 Portable code should instead use the function
 177 .Xr dwarf_types_dealloc 3
 178 to indicate that the memory area may be freed.
 179 .Pp
 180 The memory area used for the string returned in the
 181 .Ar name
 182 argument to functions
 183 .Fn dwarf_type_name_offsets
 184 and
 185 .Fn dwarf_typename
 186 is owned by the
 187 .Lb libdwarf .
 188 Portable code should indicate that the memory area can
 189 be freed using the
 190 .Xr dwarf_dealloc 3
 191 function.
 192 .Ss Error Returns
 193 If argument
 194 .Ar err
 195 is not NULL, these functions will use it to store error information,
 196 in case of an error.
 197 .Sh RETURN VALUES
 198 On success, these functions returns
 199 .Dv DW_DLV_OK .
 200 In case of an error, they return
 201 .Dv DW_DLV_ERROR
 202 and set the argument
 203 .Ar err .
 204 .Sh ERRORS
 205 These functions may fail with the following errors:
 206 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 207 .It Bq Er DW_DLE_ARGUMENT
 208 One of the arguments
 209 .Va cu_die_offset ,
 210 .Va cu_offset ,
 211 .Va dbg ,
 212 .Va die_offset ,
 213 .Va type ,
 214 .Va types ,
 215 .Va name ,
 216 or
 217 .Va ntypes
 218 was NULL.
 219 .It Bq Er DW_DLE_NO_ENTRY
 220 The DWARF debugging context referenced by argument
 221 .Ar dbg
 222 did not contain information about user-defined types.
 223 .El
 224 .Sh SEE ALSO
 225 .Xr dwarf 3 ,
 226 .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
 227 .Xr dwarf_get_pubtypes 3 ,
 228 .Xr dwarf_pubtype_cu_offset 3 ,
 229 .Xr dwarf_pubtype_die_offset 3 ,
 230 .Xr dwarf_pubtype_name_offsets 3 ,
 231 .Xr dwarf_pubtypename 3 ,
 232 .Xr dwarf_types_dealloc 3