1 .\" Copyright (c) 2010 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 2122 2011-11-09 15:35:14Z jkoshy $
34 .Nd retrieve DWARF Debugging Information Entry descriptors
40 .Fn dwarf_child "Dwarf_Die die" "Dwarf_Die *ret_die" "Dwarf_Error *err"
45 .Fa "Dwarf_Die *ret_die"
46 .Fa "Dwarf_Error *err"
51 .Fa "Dwarf_Off offset"
52 .Fa "Dwarf_Die *ret_die"
53 .Fa "Dwarf_Error *err"
56 These functions are used to retrieve and traverse DWARF
57 Debugging Information Entry (DIE) descriptors associated with
59 These descriptors are arranged in the form of a tree, traversable
67 DWARF Debugging Information Entry descriptors are represented
74 retrieves the child of descriptor denoted by argument
76 and stores it in the location pointed to by argument
81 retrieves the sibling of the descriptor denoted by argument
83 and stores it in the location pointed to by argument
87 is NULL, the first debugging information entry descriptor for the
88 current compilation unit will be returned.
89 This function and function
91 may be used together to traverse the tree of debugging information
92 entry descriptors for a compilation unit.
96 retrieves the debugging information entry descriptor at global offset
100 section of the object associated with argument
102 The returned descriptor is written to the location pointed to by argument
104 .Ss Memory Management
105 The memory area used for the
107 descriptor returned in argument
111 Application code should use function
113 with the allocation type
115 to free the memory area when the
117 descriptor is no longer needed.
119 These functions return the following values:
120 .Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY"
123 .It Bq Er DW_DLV_ERROR
124 The requested operation failed.
125 Additional information about the error encountered will be recorded in
129 .It Bq Er DW_DLV_NO_ENTRY
133 .Fn dwarf_siblingof ,
134 the descriptor denoted by argument
136 did not have a child or sibling.
139 there was no debugging information entry at the offset specified by
144 These functions may fail with the following errors:
145 .Bl -tag -width ".Bq Er DW_DLE_DIE_NO_CU_CONTEXT"
146 .It Bq Er DW_DLE_ARGUMENT
153 .It Bq Er DW_DLE_DIE_NO_CU_CONTEXT
156 was not associated with a compilation unit.
157 .It Bq Er DW_DLE_NO_ENTRY
158 The descriptor denoted by argument
160 had no child or sibling, or there was no DWARF debugging information
161 entry at the offset specified by argument
165 To retrieve the first DWARF Debugging Information Entry descriptor for
166 the first compilation unit associated with a
168 instance, and to traverse all its children, use:
169 .Bd -literal -offset indent
174 \&... allocate dbg using dwarf_init() etc ...
176 if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) !=
178 errx(EXIT_FAILURE, "dwarf_next_cu_header: %s",
181 /* Get the first DIE for the current compilation unit. */
183 if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK)
184 errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de));
186 /* Get the first child of this DIE. */
188 if (dwarf_child(die, &die0, &de) != DW_DLV_OK)
189 errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de));
191 /* Get the rest of children. */
194 if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR)
195 errx(EXIT_FAILURE, "dwarf_siblingof: %s",
197 } while (die0 != NULL);
202 .Xr dwarf_next_cu_header 3