1 .\" Copyright (c) 2010,2014 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_child.3 3127 2014-12-21 19:09:19Z jkoshy $
36 .Nd retrieve DWARF Debugging Information Entry descriptors
42 .Fn dwarf_child "Dwarf_Die die" "Dwarf_Die *ret_die" "Dwarf_Error *err"
46 .Fa "Dwarf_Off offset"
47 .Fa "Dwarf_Die *ret_die"
48 .Fa "Dwarf_Error *err"
53 .Fa "Dwarf_Off offset"
54 .Fa "Dwarf_Bool is_info"
55 .Fa "Dwarf_Die *ret_die"
56 .Fa "Dwarf_Error *err"
62 .Fa "Dwarf_Die *ret_die"
63 .Fa "Dwarf_Error *err"
69 .Fa "Dwarf_Die *ret_die"
70 .Fa "Dwarf_Bool is_info"
71 .Fa "Dwarf_Error *err"
74 These functions are used to retrieve and traverse DWARF
75 Debugging Information Entry (DIE) descriptors associated with
77 These descriptors are arranged in the form of a tree, traversable
85 DWARF Debugging Information Entry descriptors are represented
92 retrieves the child of descriptor denoted by argument
94 and stores it in the location pointed to by argument
99 retrieves the sibling of the descriptor denoted by argument
101 and stores it in the location pointed to by argument
105 is NULL, the first debugging information entry descriptor for the
106 current compilation unit will be returned.
107 This function and function
109 may be used together to traverse the tree of debugging information
110 entry descriptors for a compilation unit.
113 .Fn dwarf_siblingof_b
114 is identical to the function
116 except that it can retrieve the sibling descriptor from either the
117 current compilation unit or type unit.
120 is non-zero, the function behaves identically to function
121 .Fn dwarf_siblingof .
124 is zero, the descriptor referred by argument
126 should be associated with a debugging information entry in the
128 The function will store the sibling of the descriptor in the location
129 pointed to by argument
137 the first debugging information entry descriptor for the
138 current type unit will be returned.
142 retrieves the debugging information entry descriptor at global offset
146 section of the object associated with argument
148 The returned descriptor is written to the location pointed to by argument
153 is identical to the function
155 except that it can retrieve the debugging information entry descriptor at
162 sections of the object associated with argument
166 is non-zero, the function will retrieve the debugging information
169 section, otherwise the function will retrieve the debugging
170 information entry from the
173 The returned descriptor is written to the location pointed to by argument
175 .Ss Memory Management
176 The memory area used for the
178 descriptor returned in argument
182 Application code should use function
184 with the allocation type
186 to free the memory area when the
188 descriptor is no longer needed.
190 These functions return the following values:
191 .Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY"
194 .It Bq Er DW_DLV_ERROR
195 The requested operation failed.
196 Additional information about the error encountered will be recorded in
200 .It Bq Er DW_DLV_NO_ENTRY
205 .Fn dwarf_siblingof_b ,
206 the descriptor denoted by argument
208 did not have a child or sibling.
214 there was no debugging information entry at the offset specified by
219 These functions may fail with the following errors:
220 .Bl -tag -width ".Bq Er DW_DLE_DIE_NO_CU_CONTEXT"
221 .It Bq Er DW_DLE_ARGUMENT
228 .It Bq Er DW_DLE_DIE_NO_CU_CONTEXT
231 was not associated with a compilation unit.
232 .It Bq Er DW_DLE_NO_ENTRY
233 The descriptor denoted by argument
235 had no child or sibling, or there was no DWARF debugging information
236 entry at the offset specified by argument
240 To retrieve the first DWARF Debugging Information Entry descriptor for
241 the first compilation unit associated with a
243 instance, and to traverse all its children, use:
244 .Bd -literal -offset indent
249 \&... allocate dbg using dwarf_init() etc ...
251 if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) !=
253 errx(EXIT_FAILURE, "dwarf_next_cu_header: %s",
256 /* Get the first DIE for the current compilation unit. */
258 if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK)
259 errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de));
261 /* Get the first child of this DIE. */
263 if (dwarf_child(die, &die0, &de) != DW_DLV_OK)
264 errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de));
266 /* Get the rest of children. */
269 if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR)
270 errx(EXIT_FAILURE, "dwarf_siblingof: %s",
272 } while (die0 != NULL);
277 .Xr dwarf_get_die_infotypes_flag.3 ,
278 .Xr dwarf_next_cu_header 3