xref: /freebsd/contrib/elftoolchain/libdwarf/dwarf_next_cu_header.3 (revision 95ee2897e98f5d444f26ed2334cc7c439f9c16c6) 
1.\" Copyright (c) 2010,2014 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_next_cu_header.3 3644 2018-10-15 19:55:01Z jkoshy $
26.\"
27.Dd December 21, 2014
28.Dt DWARF_NEXT_CU_HEADER 3
29.Os
30.Sh NAME
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
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft int
40.Fo dwarf_next_cu_header
41.Fa "Dwarf_Debug dbg"
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"
48.Fc
49.Ft int
50.Fo dwarf_next_cu_header_b
51.Fa "Dwarf_Debug dbg"
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"
60.Fc
61.Ft int
62.Fo dwarf_next_cu_header_c
63.Fa "Dwarf_Debug dbg"
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"
75.Fc
76.Sh DESCRIPTION
77These functions are used to step through compilation or type units
78associated with a DWARF debug context, optionally returning information
79about the unit.
80.Pp
81Function
82.Fn dwarf_next_cu_header_c
83is the API recommended for new application code.
84Function
85.Fn dwarf_next_cu_header
86and
87.Fn dwarf_next_cu_header_b
88can only operate on compilation units associated with the
89.Dq \&.debug_info
90section.
91They are less general than function
92.Fn dwarf_next_cu_header_c ,
93and are deprecated for use by new application code.
94.Pp
95Argument
96.Ar dbg
97should reference a DWARF debug context allocated using
98.Xr dwarf_init 3 .
99If argument
100.Ar is_info
101is set to 1,
102the function returns information for compilation units found in the
103.Dq \&.debug_info
104section.
105If argument
106.Ar is_info
107is set to 0,
108the function returns information for type units found in the
109.Dq \&.debug_types
110sections.
111Argument
112.Ar cu_length
113should point to a location that will be set to the
114length of the compilation or type unit.
115Argument
116.Ar cu_version
117should point to a location that will be set to the
118version number for the compilation or type unit.
119Argument
120.Ar cu_abbrev_offset
121should point to a location that will be set to the
122starting offset (in the
123.Dq .debug_abbrev
124section) of the set of debugging information entry abbreviations
125associated with this compilation or type unit.
126Argument
127.Ar cu_pointer_size
128should point to a location that will be set to the
129size in bytes of an address for the machine architecture of the
130underlying object being debugged.
131Argument
132.Ar cu_offset_size
133should point to a location that will be set to the
134size in bytes for a DWARF offset in the compilation or type unit.
135Argument
136.Ar cu_extension_size
137is only needed for processing MIPS/IRIX objects that use
138a non-standard DWARF format.
139It should point to a location that will be set to 4 for normal
140objects and to 0 for non-standard ones.
141Argument
142.Ar type_signature
143and
144.Ar type_offset
145is only needed for processing type units.
146Argument
147.Ar type_signature
148should point to a location that will be set to the 64-bit unique signature
149of the type described in the type unit.
150Argument
151.Ar type_offset
152should point to a location that will be set to the offset of the debugging
153information entry that describes the type.
154Argument
155.Ar cu_next_offset
156should point to a location that will be set to the
157offset of the next compilation unit header in the
158.Dq \&.debug_info
159section,
160or the offset of the next type unit header in the
161.Dq \&.debug_types
162section.
163Argument
164.Ar err
165should point to a location that will hold an error descriptor in case
166of an error.
167.Pp
168Function
169.Fn dwarf_next_cu_header_b
170is identical to function
171.Fn dwarf_next_cu_header_c
172except that it does not provide arguments
173.Ar is_info ,
174.Ar type_signature
175and
176.Ar type_offset .
177.Pp
178Function
179.Fn dwarf_next_cu_header
180is identical to function
181.Fn dwarf_next_cu_header_b
182except that it does not provide arguments
183.Ar cu_offset_size
184and
185.Ar cu_extension_size .
186.Pp
187A value of NULL may be used for any of the arguments
188.Ar cu_length ,
189.Ar cu_version ,
190.Ar cu_abbrev_offset ,
191.Ar cu_pointer_size ,
192.Ar cu_offset_size ,
193.Ar cu_extension_size ,
194.Ar type_signature ,
195.Ar type_offset ,
196.Ar cu_next_offset
197and
198.Ar err
199if the caller is not interested in the respective value.
200.Ss Iterating Through Compilation Units in a Debug Context
201The first call to function
202.Fn dwarf_next_cu_header_c
203for a given debug context with argument
204.Ar is_info
205set to 1 will return information about the first
206compilation unit in the
207.Dq \&.debug_info
208section.
209Subsequent calls to the function will iterate through the remaining
210compilation units in the section.
211On stepping past the last compilation unit in the section,
212function
213.Fn dwarf_next_cu_header_c
214returns
215.Dv DW_DLV_NO_ENTRY
216and resets its internal state.
217The next call to the function will restart from the first compilation
218unit in the section.
219.Ss Iterating Through Type Units in a Debug Context
220When a DWARF debug context is allocated using
221.Xr dwarf_init 3 ,
222an internal pointer associated with the context will point to the first
223.Dq \&.debug_types
224section found in the debug object.
225The first call to function
226.Fn dwarf_next_cu_header_c
227for the debug context with argument
228.Ar is_info
229set to 0 will return information about the first
230type unit in that
231.Dq \&.debug_types
232section.
233Subsequent calls to the function will iterate through the remaining
234type units in the section.
235On stepping past the last type unit in the debug context,
236function
237.Fn dwarf_next_cu_header_c
238returns
239.Dv DW_DLV_NO_ENTRY
240and resets its internal state.
241The next call to the function will restart from the first type
242unit in the
243.Dq \&.debug_types
244section.
245.Pp
246If the debug object contains multiple
247.Dq \&.debug_types
248sections, the function
249.Fn dwarf_next_types_section
250can be called to move the internal pointer to the next
251.Dq \&.debug_types
252section.
253As a result, subsequent calls of the function
254.Fn dwarf_next_cu_header_c
255will operate on the new
256.Dq \&.debug_types
257section.
258Function
259.Fn dwarf_next_types_section
260returns
261.Dv DW_DLV_NO_ENTRY
262when there are no more
263.Dq \&.debug_types
264sections left in the debug object.
265.Sh RETURN VALUES
266On success, these functions return
267.Dv DW_DLV_OK .
268In case of an error, they return
269.Dv DW_DLV_ERROR
270and set argument
271.Ar err .
272When there are no more compilation units left to traverse, they return
273.Dv DW_DLV_NO_ENTRY .
274.Sh ERRORS
275These functions can fail with the following error:
276.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
277.It Bq Er DW_DLE_ARGUMENT
278Argument
279.Va dbg
280was NULL.
281.El
282.Sh SEE ALSO
283.Xr dwarf 3 ,
284.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
285.Xr dwarf_init 3 ,
286.Xr dwarf_next_types_section 3 ,
287.Xr dwarf_siblingof 3
288