1 .\" Copyright (c) 2010,2014 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_next_cu_header.3 3128 2014-12-21 20:06:22Z jkoshy $
29 .Dt DWARF_NEXT_CU_HEADER 3
31 .Nm dwarf_next_cu_header ,
32 .Nm dwarf_next_cu_header_b ,
33 .Nm dwarf_next_cu_header_c
34 .Nd step through compilation units in a DWARF debug context
40 .Fo dwarf_next_cu_header
42 .Fa "Dwarf_Unsigned *cu_length"
43 .Fa "Dwarf_Half *cu_version"
44 .Fa "Dwarf_Off *cu_abbrev_offset"
45 .Fa "Dwarf_Half *cu_pointer_size"
46 .Fa "Dwarf_Unsigned *cu_next_offset"
47 .Fa "Dwarf_Error *err"
50 .Fo dwarf_next_cu_header_b
52 .Fa "Dwarf_Unsigned *cu_length"
53 .Fa "Dwarf_Half *cu_version"
54 .Fa "Dwarf_Off *cu_abbrev_offset"
55 .Fa "Dwarf_Half *cu_pointer_size"
56 .Fa "Dwarf_Half *cu_offset_size"
57 .Fa "Dwarf_Half *cu_extension_size"
58 .Fa "Dwarf_Unsigned *cu_next_offset"
59 .Fa "Dwarf_Error *err"
62 .Fo dwarf_next_cu_header_c
64 .Fa "Dwarf_Bool is_info"
65 .Fa "Dwarf_Unsigned *cu_length"
66 .Fa "Dwarf_Half *cu_version"
67 .Fa "Dwarf_Off *cu_abbrev_offset"
68 .Fa "Dwarf_Half *cu_pointer_size"
69 .Fa "Dwarf_Half *cu_offset_size"
70 .Fa "Dwarf_Half *cu_extension_size"
71 .Fa "Dwarf_Sig8 *type_signature"
72 .Fa "Dwarf_Unsigned *type_offset"
73 .Fa "Dwarf_Unsigned *cu_next_offset"
74 .Fa "Dwarf_Error *err"
77 These functions are used to step through compilation or type units
78 associated with a DWARF debug context, optionally returning information
82 .Fn dwarf_next_cu_header_c
83 is the API recommended for new application code.
85 .Fn dwarf_next_cu_header
87 .Fn dwarf_next_cu_header_b
88 can only operate on compilation units associated with the
91 They are less general than function
92 .Fn dwarf_next_cu_header_c ,
93 and are deprecated for use by new application code.
97 should reference a DWARF debug context allocated using
102 the function returns information for compilation units found in the
108 the function returns information for type units found in the
113 should point to a location that will be set to the
114 length of the compilation or type unit.
117 should point to a location that will be set to the
118 version number for the compilation or type unit.
121 should point to a location that will be set to the
122 starting offset (in the
124 section) of the set of debugging information entry abbreviations
125 associated with this compilation or type unit.
128 should point to a location that will be set to the
129 size in bytes of an address for the machine architecture of the
130 underlying object being debugged.
133 should point to a location that will be set to the
134 size in bytes for a DWARF offset in the compilation or type unit.
136 .Ar cu_extension_size
137 is only needed for processing MIPS/IRIX objects that use
138 a non-standard DWARF format.
139 It should point to a location that will be set to 4 for normal
140 objects and to 0 for non-standard ones.
145 is only needed for processing type units.
148 should point to a location that will be set to the 64-bit unique signature
149 of the type described in the type unit.
152 should point to a location that will be set to the offset of the debugging
153 information entry that describes the type.
156 should point to a location that will be set to the
157 offset of the next compilation unit header in the
160 or the offset of the next type unit header in the
165 should point to a location that will hold an error descriptor in case
169 .Fn dwarf_next_cu_header_b
170 is identical to function
171 .Fn dwarf_next_cu_header_c
172 except that it does not provide arguments
179 .Fn dwarf_next_cu_header
180 is identical to function
181 .Fn dwarf_next_cu_header_b
182 except that it does not provide arguments
185 .Ar cu_extension_size .
187 A value of NULL may be used for any of the arguments
190 .Ar cu_abbrev_offset ,
191 .Ar cu_pointer_size ,
193 .Ar cu_extension_size ,
199 if the caller is not interested in the respective value.
200 .Ss Iterating Through Compilation Units in a Debug Context
202 The first call to function
203 .Fn dwarf_next_cu_header_c
204 for a given debug context with argument
206 set to 1 will return information about the first
207 compilation unit in the
210 Subsequent calls to the function will iterate through the remaining
211 compilation units in the section.
212 On stepping past the last compilation unit in the section,
214 .Fn dwarf_next_cu_header_c
217 and resets its internal state.
218 The next call to the function will restart from the first compilation
220 .Ss Iterating Through Type Units in a Debug Context
221 When a DWARF debug context is allocated using
223 an internal pointer assoicated with the context will point to the
226 section found in the debug object.
227 The first call to function
228 .Fn dwarf_next_cu_header_c
229 for the debug context with argument
231 set to 0 will return information about the first
235 Subsequent calls to the function will iterate through the remaining
236 type units in the section.
237 On stepping past the last type unit in the debug context,
239 .Fn dwarf_next_cu_header_c
242 and resets its internal state.
243 The next call to the function will restart from the first type
248 If the debug object contains multiple
250 sections, the function
251 .Fn dwarf_next_types_section
252 can be called to move the internal pointer to the next
255 As a result, subsequent calls of the function
256 .Fn dwarf_next_cu_header_c
257 will operate on the new
261 .Fn dwarf_next_types_section
264 when there are no more
266 sections left in the debug object.
268 On success, these functions return
270 In case of an error, they return
274 When there are no more compilation units left to traverse, they return
275 .Dv DW_DLV_NO_ENTRY .
277 These functions can fail with the following error:
278 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
279 .It Bq Er DW_DLE_ARGUMENT
286 .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
288 .Xr dwarf_next_types_section 3 ,
289 .Xr dwarf_siblingof 3