xref: /freebsd/contrib/elftoolchain/libdwarf/dwarf_next_cu_header.3 (revision 0b3105a37d7adcadcb720112fed4dc4e8040be99) 
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 3182 2015-04-10 16:08:10Z emaste $
26.\"
27.Dd December 21, 2014
28.Os
29.Dt DWARF_NEXT_CU_HEADER 3
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
201.Pp
202The first call to function
203.Fn dwarf_next_cu_header_c
204for a given debug context with argument
205.Ar is_info
206set to 1 will return information about the first
207compilation unit in the
208.Dq \&.debug_info
209section.
210Subsequent calls to the function will iterate through the remaining
211compilation units in the section.
212On stepping past the last compilation unit in the section,
213function
214.Fn dwarf_next_cu_header_c
215returns
216.Dv DW_DLV_NO_ENTRY
217and resets its internal state.
218The next call to the function will restart from the first compilation
219unit in the section.
220.Ss Iterating Through Type Units in a Debug Context
221When a DWARF debug context is allocated using
222.Xr dwarf_init 3 ,
223an internal pointer associated with the context will point to the first
224.Dq \&.debug_types
225section found in the debug object.
226The first call to function
227.Fn dwarf_next_cu_header_c
228for the debug context with argument
229.Ar is_info
230set to 0 will return information about the first
231type unit in that
232.Dq \&.debug_types
233section.
234Subsequent calls to the function will iterate through the remaining
235type units in the section.
236On stepping past the last type unit in the debug context,
237function
238.Fn dwarf_next_cu_header_c
239returns
240.Dv DW_DLV_NO_ENTRY
241and resets its internal state.
242The next call to the function will restart from the first type
243unit in the
244.Dq \&.debug_types
245section.
246.Pp
247If the debug object contains multiple
248.Dq \&.debug_types
249sections, the function
250.Fn dwarf_next_types_section
251can be called to move the internal pointer to the next
252.Dq \&.debug_types
253section.
254As a result, subsequent calls of the function
255.Fn dwarf_next_cu_header_c
256will operate on the new
257.Dq \&.debug_types
258section.
259Function
260.Fn dwarf_next_types_section
261returns
262.Dv DW_DLV_NO_ENTRY
263when there are no more
264.Dq \&.debug_types
265sections left in the debug object.
266.Sh RETURN VALUES
267On success, these functions return
268.Dv DW_DLV_OK .
269In case of an error, they return
270.Dv DW_DLV_ERROR
271and set argument
272.Ar err .
273When there are no more compilation units left to traverse, they return
274.Dv DW_DLV_NO_ENTRY .
275.Sh ERRORS
276These functions can fail with the following error:
277.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
278.It Bq Er DW_DLE_ARGUMENT
279Argument
280.Va dbg
281was NULL.
282.El
283.Sh SEE ALSO
284.Xr dwarf 3 ,
285.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
286.Xr dwarf_init 3 ,
287.Xr dwarf_next_types_section 3 ,
288.Xr dwarf_siblingof 3
289