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