xref: /freebsd/contrib/elftoolchain/libdwarf/dwarf_child.3 (revision f7c32ed617858bcd22f8d1b03199099d50125721) 
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_child.3 3644 2018-10-15 19:55:01Z jkoshy $
26.\"
27.Dd December 21, 2014
28.Dt DWARF_CHILD 3
29.Os
30.Sh NAME
31.Nm dwarf_child ,
32.Nm dwarf_offdie ,
33.Nm dwarf_offdie_b ,
34.Nm dwarf_siblingof ,
35.Nm dwarf_siblingof_b
36.Nd retrieve DWARF Debugging Information Entry descriptors
37.Sh LIBRARY
38.Lb libdwarf
39.Sh SYNOPSIS
40.In libdwarf.h
41.Ft int
42.Fn dwarf_child "Dwarf_Die die" "Dwarf_Die *ret_die" "Dwarf_Error *err"
43.Ft int
44.Fo dwarf_offdie
45.Fa "Dwarf_Debug dbg"
46.Fa "Dwarf_Off offset"
47.Fa "Dwarf_Die *ret_die"
48.Fa "Dwarf_Error *err"
49.Fc
50.Ft int
51.Fo dwarf_offdie_b
52.Fa "Dwarf_Debug dbg"
53.Fa "Dwarf_Off offset"
54.Fa "Dwarf_Bool is_info"
55.Fa "Dwarf_Die *ret_die"
56.Fa "Dwarf_Error *err"
57.Fc
58.Ft int
59.Fo dwarf_siblingof
60.Fa "Dwarf_Debug dbg"
61.Fa "Dwarf_Die die"
62.Fa "Dwarf_Die *ret_die"
63.Fa "Dwarf_Error *err"
64.Fc
65.Ft int
66.Fo dwarf_siblingof_b
67.Fa "Dwarf_Debug dbg"
68.Fa "Dwarf_Die die"
69.Fa "Dwarf_Die *ret_die"
70.Fa "Dwarf_Bool is_info"
71.Fa "Dwarf_Error *err"
72.Fc
73.Sh DESCRIPTION
74These functions are used to retrieve and traverse DWARF
75Debugging Information Entry (DIE) descriptors associated with
76a compilation unit.
77These descriptors are arranged in the form of a tree, traversable
78using
79.Dq child
80and
81.Dq sibling
82links; see
83.Xr dwarf 3
84for more information.
85DWARF Debugging Information Entry descriptors are represented
86by the
87.Vt Dwarf_Die
88opaque type.
89.Pp
90Function
91.Fn dwarf_child
92retrieves the child of descriptor denoted by argument
93.Ar die ,
94and stores it in the location pointed to by argument
95.Ar ret_die .
96.Pp
97Function
98.Fn dwarf_siblingof
99retrieves the sibling of the descriptor denoted by argument
100.Ar die ,
101and stores it in the location pointed to by argument
102.Ar ret_die .
103If argument
104.Ar die
105is NULL, the first debugging information entry descriptor for the
106current compilation unit will be returned.
107This function and function
108.Fn dwarf_child
109may be used together to traverse the tree of debugging information
110entry descriptors for a compilation unit.
111.Pp
112Function
113.Fn dwarf_siblingof_b
114is identical to the function
115.Fn dwarf_siblingof
116except that it can retrieve the sibling descriptor from either the
117current compilation unit or type unit.
118If argument
119.Ar is_info
120is non-zero, the function behaves identically to function
121.Fn dwarf_siblingof .
122If argument
123.Ar is_info
124is zero, the descriptor referred by argument
125.Ar die
126should be associated with a debugging information entry in the
127type unit.
128The function will store the sibling of the descriptor in the location
129pointed to by argument
130.Ar ret_die .
131If argument
132.Ar is_info
133is zero and argument
134.Ar die
135is
136.Dv NULL ,
137the first debugging information entry descriptor for the
138current type unit will be returned.
139.Pp
140Function
141.Fn dwarf_offdie
142retrieves the debugging information entry descriptor at global offset
143.Ar offset
144in the
145.Dq .debug_info
146section of the object associated with argument
147.Ar dbg .
148The returned descriptor is written to the location pointed to by argument
149.Ar ret_die .
150.Pp
151Function
152.Fn dwarf_offdie_b
153is identical to the function
154.Fn dwarf_offdie
155except that it can retrieve the debugging information entry descriptor at
156global offset
157.Ar offset
158from either of the
159.Dq .debug_info
160and
161.Dq .debug_types
162sections of the object associated with argument
163.Ar dbg .
164If argument
165.Ar is_info
166is non-zero, the function will retrieve the debugging information
167entry from the
168.Dq .debug_info
169section, otherwise the function will retrieve the debugging
170information entry from the
171.Dq .debug_types
172section.
173The returned descriptor is written to the location pointed to by argument
174.Ar ret_die .
175.Ss Memory Management
176The memory area used for the
177.Vt Dwarf_Die
178descriptor returned in argument
179.Ar ret_die
180is allocated by the
181.Lb libdwarf .
182Application code should use function
183.Fn dwarf_dealloc
184with the allocation type
185.Dv DW_DLA_DIE
186to free the memory area when the
187.Vt Dwarf_Die
188descriptor is no longer needed.
189.Sh RETURN VALUES
190These functions return the following values:
191.Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY"
192.It Bq Er DW_DLV_OK
193The call succeeded.
194.It Bq Er DW_DLV_ERROR
195The requested operation failed.
196Additional information about the error encountered will be recorded in
197argument
198.Ar err ,
199if it is not NULL.
200.It Bq Er DW_DLV_NO_ENTRY
201For functions
202.Fn dwarf_child ,
203.Fn dwarf_siblingof
204and
205.Fn dwarf_siblingof_b ,
206the descriptor denoted by argument
207.Ar die
208did not have a child or sibling.
209.Pp
210For functions
211.Fn dwarf_offdie
212and
213.Fn dwarf_offdie_b ,
214there was no debugging information entry at the offset specified by
215argument
216.Ar offset .
217.El
218.Sh EXAMPLES
219To retrieve the first DWARF Debugging Information Entry descriptor for
220the first compilation unit associated with a
221.Vt Dwarf_Debug
222instance, and to traverse all its children, use:
223.Bd -literal -offset indent
224Dwarf_Debug dbg;
225Dwarf_Die die, die0;
226Dwarf_Error de;
227
228\&... allocate dbg using dwarf_init() etc ...
229
230if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) !=
231    DW_DLV_OK)
232	errx(EXIT_FAILURE, "dwarf_next_cu_header: %s",
233	    dwarf_errmsg(de));
234
235/* Get the first DIE for the current compilation unit. */
236die = NULL;
237if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK)
238	errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de));
239
240/* Get the first child of this DIE. */
241die = die0;
242if (dwarf_child(die, &die0, &de) != DW_DLV_OK)
243	errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de));
244
245/* Get the rest of children. */
246do {
247	die = die0;
248	if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR)
249		errx(EXIT_FAILURE, "dwarf_siblingof: %s",
250		    dwarf_errmsg(de));
251} while (die0 != NULL);
252.Ed
253.Sh ERRORS
254These functions may fail with the following errors:
255.Bl -tag -width ".Bq Er DW_DLE_DIE_NO_CU_CONTEXT"
256.It Bq Er DW_DLE_ARGUMENT
257Arguments
258.Ar dbg ,
259.Ar die
260or
261.Ar ret_die
262were NULL.
263.It Bq Er DW_DLE_DIE_NO_CU_CONTEXT
264Argument
265.Ar dbg
266was not associated with a compilation unit.
267.It Bq Er DW_DLE_NO_ENTRY
268The descriptor denoted by argument
269.Ar die
270had no child or sibling, or there was no DWARF debugging information
271entry at the offset specified by argument
272.Va offset .
273.El
274.Sh SEE ALSO
275.Xr dwarf 3 ,
276.Xr dwarf_errmsg 3 ,
277.Xr dwarf_get_die_infotypes_flag 3 ,
278.Xr dwarf_next_cu_header 3
279