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 3182 2015-04-10 16:08:10Z emaste $
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 associated with the context will point to the first
225 section found in the debug object.
226 The first call to function
227 .Fn dwarf_next_cu_header_c
228 for the debug context with argument
230 set to 0 will return information about the first
234 Subsequent calls to the function will iterate through the remaining
235 type units in the section.
236 On stepping past the last type unit in the debug context,
238 .Fn dwarf_next_cu_header_c
241 and resets its internal state.
242 The next call to the function will restart from the first type
247 If the debug object contains multiple
249 sections, the function
250 .Fn dwarf_next_types_section
251 can be called to move the internal pointer to the next
254 As a result, subsequent calls of the function
255 .Fn dwarf_next_cu_header_c
256 will operate on the new
260 .Fn dwarf_next_types_section
263 when there are no more
265 sections left in the debug object.
267 On success, these functions return
269 In case of an error, they return
273 When there are no more compilation units left to traverse, they return
274 .Dv DW_DLV_NO_ENTRY .
276 These functions can fail with the following error:
277 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
278 .It Bq Er DW_DLE_ARGUMENT
285 .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
287 .Xr dwarf_next_types_section 3 ,
288 .Xr dwarf_siblingof 3