1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_get_types.3 2071 2011-10-27 03:20:00Z jkoshy $
32 .Nm dwarf_type_cu_offset ,
33 .Nm dwarf_type_die_offset ,
34 .Nm dwarf_type_name_offsets ,
36 .Nd retrieve information about user-defined types
44 .Fa "Dwarf_Type **types"
45 .Fa "Dwarf_Signed *ntypes"
46 .Fa "Dwarf_Error *err"
49 .Fo dwarf_type_cu_offset
51 .Fa "Dwarf_Off *cu_offset"
52 .Fa "Dwarf_Error *err"
55 .Fo dwarf_type_die_offset
57 .Fa "Dwarf_Off *die_offset"
58 .Fa "Dwarf_Error *err"
61 .Fo dwarf_type_name_offsets
64 .Fa "Dwarf_Off *die_offset"
65 .Fa "Dwarf_Off *cu_die_offset"
66 .Fa "Dwarf_Error *err"
72 .Fa "Dwarf_Error *err"
75 These APIs retrieve information about user-defined types from the
77 .Dq ".debug_typenames"
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
86 .Xr dwarf_pubtypename 3 ,
87 which operate on the equivalent
89 section defined by the DWARF3 standard.
91 Information about user-defined types is returned using opaque descriptors
94 Applications need to use the functions described below to retrieve
95 the name and offset information contained in these descriptors.
99 retrieves descriptors for all user-defined types associated with the
100 DWARF debug context specified by argument
104 should point to a location that will be set to a pointer to an array
110 should point to a location that will be set to the number of
111 descriptors returned.
114 .Fn dwarf_type_cu_offset
115 returns the offset, relative to the
117 section, of the compilation unit that contains the debugging
118 information entry associated with the argument
122 should point to a location that will hold the returned offset.
125 .Fn dwarf_type_die_offset
126 retrieves the offset, relative to the
128 section, of the debugging information entry associated with the
131 and stores it into the location pointed to by the argument
135 .Fn dwarf_type_name_offsets
136 retrieves the name and offsets for the debugging information
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
146 should point to a location which will be set to the offset, relative
149 section, of the associated debugging information entry.
152 should point to a location which will be set to a offset, relative to
155 section, of the first debugging information entry in the compilation
156 unit associated with argument
161 sets the location pointed to by argument
163 to a pointer to a NUL-terminated string holding the name of the
164 debugging information entry associated with the argument
166 .Ss Memory Management
167 The memory area used for the array of
169 descriptors returned in argument
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.
180 The memory area used for the string returned in the
182 argument to functions
183 .Fn dwarf_type_name_offsets
188 Portable code should indicate that the memory area can
195 is not NULL, these functions will use it to store error information,
198 On success, these functions returns
200 In case of an error, they return
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
219 .It Bq Er DW_DLE_NO_ENTRY
220 The DWARF debugging context referenced by argument
222 did not contain information about user-defined types.
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