xref: /netbsd-src/external/bsd/elftoolchain/dist/libdwarf/dwarf_next_cu_header.3 (revision 5ac3bc719ce6e70593039505b491894133237d12)
1.\"	$NetBSD: dwarf_next_cu_header.3,v 1.6 2024/03/03 17:37:31 christos Exp $
2.\"
3.\" Copyright (c) 2010,2014,2023 Kai Wang
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" Id: dwarf_next_cu_header.3 4013 2023-10-14 22:40:50Z kaiwang27
28.\"
29.Dd October 15, 2023
30.Dt DWARF_NEXT_CU_HEADER 3
31.Os
32.Sh NAME
33.Nm dwarf_next_cu_header ,
34.Nm dwarf_next_cu_header_b ,
35.Nm dwarf_next_cu_header_c ,
36.Nm dwarf_next_cu_header_d
37.Nd step through compilation units in a DWARF debug context
38.Sh LIBRARY
39.Lb libdwarf
40.Sh SYNOPSIS
41.In libdwarf.h
42.Ft int
43.Fo dwarf_next_cu_header
44.Fa "Dwarf_Debug dbg"
45.Fa "Dwarf_Unsigned *cu_length"
46.Fa "Dwarf_Half *cu_version"
47.Fa "Dwarf_Off *cu_abbrev_offset"
48.Fa "Dwarf_Half *cu_pointer_size"
49.Fa "Dwarf_Unsigned *cu_next_offset"
50.Fa "Dwarf_Error *err"
51.Fc
52.Ft int
53.Fo dwarf_next_cu_header_b
54.Fa "Dwarf_Debug dbg"
55.Fa "Dwarf_Unsigned *cu_length"
56.Fa "Dwarf_Half *cu_version"
57.Fa "Dwarf_Off *cu_abbrev_offset"
58.Fa "Dwarf_Half *cu_pointer_size"
59.Fa "Dwarf_Half *cu_offset_size"
60.Fa "Dwarf_Half *cu_extension_size"
61.Fa "Dwarf_Unsigned *cu_next_offset"
62.Fa "Dwarf_Error *err"
63.Fc
64.Ft int
65.Fo dwarf_next_cu_header_c
66.Fa "Dwarf_Debug dbg"
67.Fa "Dwarf_Bool is_info"
68.Fa "Dwarf_Unsigned *cu_length"
69.Fa "Dwarf_Half *cu_version"
70.Fa "Dwarf_Off *cu_abbrev_offset"
71.Fa "Dwarf_Half *cu_pointer_size"
72.Fa "Dwarf_Half *cu_offset_size"
73.Fa "Dwarf_Half *cu_extension_size"
74.Fa "Dwarf_Sig8 *type_signature"
75.Fa "Dwarf_Unsigned *type_offset"
76.Fa "Dwarf_Unsigned *cu_next_offset"
77.Fa "Dwarf_Error *err"
78.Fc
79.Ft int
80.Fo dwarf_next_cu_header_d
81.Fa "Dwarf_Debug dbg"
82.Fa "Dwarf_Bool is_info"
83.Fa "Dwarf_Unsigned *cu_length"
84.Fa "Dwarf_Half *cu_version"
85.Fa "Dwarf_Off *cu_abbrev_offset"
86.Fa "Dwarf_Half *cu_pointer_size"
87.Fa "Dwarf_Half *cu_offset_size"
88.Fa "Dwarf_Half *cu_extension_size"
89.Fa "Dwarf_Sig8 *type_signature"
90.Fa "Dwarf_Unsigned *type_offset"
91.Fa "Dwarf_Unsigned *cu_next_offset"
92.Fa "Dwarf_Half *cu_type"
93.Fa "Dwarf_Error *err"
94.Fc
95.Sh DESCRIPTION
96These functions are used to step through compilation or type units
97associated with a DWARF debug context, optionally returning information
98about the unit.
99.Pp
100Function
101.Fn dwarf_next_cu_header_d
102is the API recommended for new application code.
103Function
104.Fn dwarf_next_cu_header_c
105can not return the unit type defined by the DWARF5 standard.
106Function
107.Fn dwarf_next_cu_header
108and
109.Fn dwarf_next_cu_header_b
110can only operate on compilation units associated with the
111.Dq \&.debug_info
112section.
113The earlier revisions are less general than function
114.Fn dwarf_next_cu_header_d ,
115and are deprecated for use by new application code.
116.Pp
117Argument
118.Fa dbg
119should reference a DWARF debug context allocated using
120.Xr dwarf_init 3 .
121If argument
122.Fa is_info
123is set to 1,
124the function returns information for compilation units found in the
125.Dq \&.debug_info
126section.
127If argument
128.Fa is_info
129is set to 0,
130the function returns information for type units found in the
131.Dq \&.debug_types
132sections.
133Argument
134.Fa cu_length
135should point to a location that will be set to the
136length of the compilation or type unit.
137Argument
138.Fa cu_version
139should point to a location that will be set to the
140version number for the compilation or type unit.
141Argument
142.Fa cu_abbrev_offset
143should point to a location that will be set to the
144starting offset (in the
145.Dq .debug_abbrev
146section) of the set of debugging information entry abbreviations
147associated with this compilation or type unit.
148Argument
149.Fa cu_pointer_size
150should point to a location that will be set to the
151size in bytes of an address for the machine architecture of the
152underlying object being debugged.
153Argument
154.Fa cu_offset_size
155should point to a location that will be set to the
156size in bytes for a DWARF offset in the compilation or type unit.
157Argument
158.Fa cu_extension_size
159is only needed for processing MIPS/IRIX objects that use
160a non-standard DWARF format.
161It should point to a location that will be set to 4 for normal
162objects and to 0 for non-standard ones.
163Argument
164.Fa type_signature
165and
166.Fa type_offset
167is only needed for processing type units.
168Argument
169.Fa type_signature
170should point to a location that will be set to the 64-bit unique signature
171of the type described in the type unit.
172Argument
173.Fa type_offset
174should point to a location that will be set to the offset of the debugging
175information entry that describes the type.
176Argument
177.Fa cu_next_offset
178should point to a location that will be set to the
179offset of the next compilation unit header in the
180.Dq \&.debug_info
181section,
182or the offset of the next type unit header in the
183.Dq \&.debug_types
184section.
185Argument
186.Fa cu_type
187should point to a location that will be set to the
188type of the compilation unit.
189Argument
190.Fa err
191should point to a location that will hold an error descriptor in case
192of an error.
193.Pp
194Function
195.Fn dwarf_next_cu_header_c
196is identical to function
197.Fn dwarf_next_cu_header_d
198except that it does not provide argument
199.Fa cu_type .
200.Pp
201Function
202.Fn dwarf_next_cu_header_b
203is identical to function
204.Fn dwarf_next_cu_header_c
205except that it does not provide arguments
206.Fa is_info ,
207.Fa type_signature
208and
209.Fa type_offset .
210.Pp
211Function
212.Fn dwarf_next_cu_header
213is identical to function
214.Fn dwarf_next_cu_header_b
215except that it does not provide arguments
216.Fa cu_offset_size
217and
218.Fa cu_extension_size .
219.Pp
220A value of
221.Dv NULL
222may be used for any of the arguments
223.Fa cu_length ,
224.Fa cu_version ,
225.Fa cu_abbrev_offset ,
226.Fa cu_pointer_size ,
227.Fa cu_offset_size ,
228.Fa cu_extension_size ,
229.Fa type_signature ,
230.Fa type_offset ,
231.Fa cu_next_offset ,
232.Fa cu_type
233and
234.Fa err
235if the caller is not interested in the respective value.
236.Ss Iterating Through Compilation Units in a Debug Context
237The first call to function
238.Fn dwarf_next_cu_header_c
239for a given debug context with argument
240.Fa is_info
241set to 1 will return information about the first
242compilation unit in the
243.Dq \&.debug_info
244section.
245Subsequent calls to the function will iterate through the remaining
246compilation units in the section.
247On stepping past the last compilation unit in the section,
248function
249.Fn dwarf_next_cu_header_d
250returns
251.Dv DW_DLV_NO_ENTRY
252and resets its internal state.
253The next call to the function will restart from the first compilation
254unit in the section.
255.Ss Iterating Through Type Units in a Debug Context
256When a DWARF debug context is allocated using
257.Xr dwarf_init 3 ,
258an internal pointer associated with the context will point to the first
259.Dq \&.debug_types
260section found in the debug object.
261The first call to function
262.Fn dwarf_next_cu_header_d
263for the debug context with argument
264.Fa is_info
265set to 0 will return information about the first
266type unit in that
267.Dq \&.debug_types
268section.
269Subsequent calls to the function will iterate through the remaining
270type units in the section.
271On stepping past the last type unit in the debug context,
272function
273.Fn dwarf_next_cu_header_d
274returns
275.Dv DW_DLV_NO_ENTRY
276and resets its internal state.
277The next call to the function will restart from the first type
278unit in the
279.Dq \&.debug_types
280section.
281.Pp
282If the debug object contains multiple
283.Dq \&.debug_types
284sections, the function
285.Fn dwarf_next_types_section
286can be called to move the internal pointer to the next
287.Dq \&.debug_types
288section.
289As a result, subsequent calls of the function
290.Fn dwarf_next_cu_header_d
291will operate on the new
292.Dq \&.debug_types
293section.
294Function
295.Fn dwarf_next_types_section
296returns
297.Dv DW_DLV_NO_ENTRY
298when there are no more
299.Dq \&.debug_types
300sections left in the debug object.
301.Sh RETURN VALUES
302On success, these functions return
303.Dv DW_DLV_OK .
304In case of an error, they return
305.Dv DW_DLV_ERROR
306and set argument
307.Fa err .
308When there are no more compilation units left to traverse, they return
309.Dv DW_DLV_NO_ENTRY .
310.Sh ERRORS
311These functions can fail with the following error:
312.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
313.It Bq Er DW_DLE_ARGUMENT
314Argument
315.Va dbg
316was
317.Dv NULL .
318.El
319.Sh SEE ALSO
320.Xr dwarf 3 ,
321.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
322.Xr dwarf_init 3 ,
323.Xr dwarf_next_types_section 3 ,
324.Xr dwarf_siblingof 3
325