1 .\" Copyright (c) 2010 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 2074 2011-10-27 03:34:33Z jkoshy $
29 .Dt DWARF_NEXT_CU_HEADER 3
31 .Nm dwarf_next_cu_header ,
32 .Nm dwarf_next_cu_header_b
33 .Nd step through compilation units in a DWARF debug context
39 .Fo dwarf_next_cu_header
41 .Fa "Dwarf_Unsigned *cu_length"
42 .Fa "Dwarf_Half *cu_version"
43 .Fa "Dwarf_Off *cu_abbrev_offset"
44 .Fa "Dwarf_Half *cu_pointer_size"
45 .Fa "Dwarf_Unsigned *cu_next_offset"
46 .Fa "Dwarf_Error *err"
49 .Fo dwarf_next_cu_header_b
51 .Fa "Dwarf_Unsigned *cu_length"
52 .Fa "Dwarf_Half *cu_version"
53 .Fa "Dwarf_Off *cu_abbrev_offset"
54 .Fa "Dwarf_Half *cu_pointer_size"
55 .Fa "Dwarf_Half *cu_offset_size"
56 .Fa "Dwarf_Half *cu_extension_size"
57 .Fa "Dwarf_Unsigned *cu_next_offset"
58 .Fa "Dwarf_Error *err"
61 These functions are used to step through compilation unit contexts
62 associated with a DWARF debug context, optionally returning information
66 .Fn dwarf_next_cu_header_b
67 is the API recommended for new application code.
70 should reference a DWARF debug context allocated using
74 should point to a location that will be set to the
75 length of the compilation unit.
78 should point to a location that will be set to the
79 version number for the compilation unit.
82 should point to a location that will be set to the
83 starting offset (in the
85 section) of the set of debugging information entry abbreviations
86 associated with this compilation unit.
89 should point to a location that will be set to the
90 size in bytes of an address for the machine architecture of the
91 underlying object being debugged.
94 should point to a location that will be set to the
95 size in bytes for a DWARF offset in the compilation unit.
98 is only needed for processing MIPS/IRIX objects that use
99 a non-standard DWARF format.
100 It should point to a location that will be set to 4 for normal
101 objects and to 0 for non-standard ones.
104 should point to a location that will be set to the
105 offset of the next compilation unit header in the
110 should point to a location that will hold an error descriptor in case
114 .Fn dwarf_next_cu_header
116 .Fn dwarf_next_cu_header_b ,
117 and is deprecated for use by new application code.
120 should reference a DWARF debug context allocated using
124 should point to a location that will be set to the
125 length of the compilation unit.
128 should point to a location that will be set to the
129 version number for the compilation unit.
132 should point to a location that will be set to the
133 starting offset in the
135 section of the set of debugging information entry abbreviations
136 associated with this compilation unit.
139 should point to a location that will be set to the
140 size of an address in bytes for the machine architecture of the
141 underlying debugging object.
144 should point to a location that will be set to the
145 offset of the next compilation unit.
148 should point to a location that will hold an error descriptor in case
151 A value of NULL may be used for any of the arguments
154 .Ar cu_abbrev_offset ,
155 .Ar cu_pointer_size ,
157 .Ar cu_extension_size ,
161 if the caller is not interested in the respective value.
162 .Ss Iterating Through Compilation Units in a Debug Context
164 The first call to functions
165 .Fn dwarf_next_cu_header_b
167 .Fn dwarf_next_cu_header
168 for a given debug context will return information about the first
169 compilation unit in the debug context.
170 Subsequent calls to these functions will iterate through the remaining
171 compilation units in the debug context.
172 On stepping past the last compilation unit in the debug context,
174 .Fn dwarf_next_cu_header
176 .Fn dwarf_next_cu_header_b
179 and reset their internal state.
180 The next call to these functions will restart from the first compilation
181 unit in the debug context.
183 On success, these functions return
185 In case of an error, they return
189 When there are no more compilation units left to traverse, they return
190 .Dv DW_DLV_NO_ENTRY .
192 These functions can fail with the following error:
193 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
194 .It Bq Er DW_DLE_ARGUMENT
201 .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
203 .Xr dwarf_siblingof 3