contrib/elftoolchain/libdwarf/dwarf_child.3

   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
  74 These functions are used to retrieve and traverse DWARF
  75 Debugging Information Entry (DIE) descriptors associated with
  76 a compilation unit.
  77 These descriptors are arranged in the form of a tree, traversable
  78 using
  79 .Dq child
  80 and
  81 .Dq sibling
  82 links; see
  83 .Xr dwarf 3
  84 for more information.
  85 DWARF Debugging Information Entry descriptors are represented
  86 by the
  87 .Vt Dwarf_Die
  88 opaque type.
  89 .Pp
  90 Function
  91 .Fn dwarf_child
  92 retrieves the child of descriptor denoted by argument
  93 .Ar die ,
  94 and stores it in the location pointed to by argument
  95 .Ar ret_die .
  96 .Pp
  97 Function
  98 .Fn dwarf_siblingof
  99 retrieves the sibling of the descriptor denoted by argument
 100 .Ar die ,
 101 and stores it in the location pointed to by argument
 102 .Ar ret_die .
 103 If argument
 104 .Ar die
 105 is NULL, the first debugging information entry descriptor for the
 106 current compilation unit will be returned.
 107 This function and function
 108 .Fn dwarf_child
 109 may be used together to traverse the tree of debugging information
 110 entry descriptors for a compilation unit.
 111 .Pp
 112 Function
 113 .Fn dwarf_siblingof_b
 114 is identical to the function
 115 .Fn dwarf_siblingof
 116 except that it can retrieve the sibling descriptor from either the
 117 current compilation unit or type unit.
 118 If argument
 119 .Ar is_info
 120 is non-zero, the function behaves identically to function
 121 .Fn dwarf_siblingof .
 122 If argument
 123 .Ar is_info
 124 is zero, the descriptor referred by argument
 125 .Ar die
 126 should be associated with a debugging information entry in the
 127 type unit.
 128 The function will store the sibling of the descriptor in the location
 129 pointed to by argument
 130 .Ar ret_die .
 131 If argument
 132 .Ar is_info
 133 is zero and argument
 134 .Ar die
 135 is
 136 .Dv NULL ,
 137 the first debugging information entry descriptor for the
 138 current type unit will be returned.
 139 .Pp
 140 Function
 141 .Fn dwarf_offdie
 142 retrieves the debugging information entry descriptor at global offset
 143 .Ar offset
 144 in the
 145 .Dq .debug_info
 146 section of the object associated with argument
 147 .Ar dbg .
 148 The returned descriptor is written to the location pointed to by argument
 149 .Ar ret_die .
 150 .Pp
 151 Function
 152 .Fn dwarf_offdie_b
 153 is identical to the function
 154 .Fn dwarf_offdie
 155 except that it can retrieve the debugging information entry descriptor at
 156 global offset
 157 .Ar offset
 158 from either of the
 159 .Dq .debug_info
 160 and
 161 .Dq .debug_types
 162 sections of the object associated with argument
 163 .Ar dbg .
 164 If argument
 165 .Ar is_info
 166 is non-zero, the function will retrieve the debugging information
 167 entry from the
 168 .Dq .debug_info
 169 section, otherwise the function will retrieve the debugging
 170 information entry from the
 171 .Dq .debug_types
 172 section.
 173 The returned descriptor is written to the location pointed to by argument
 174 .Ar ret_die .
 175 .Ss Memory Management
 176 The memory area used for the
 177 .Vt Dwarf_Die
 178 descriptor returned in argument
 179 .Ar ret_die
 180 is allocated by the
 181 .Lb libdwarf .
 182 Application code should use function
 183 .Fn dwarf_dealloc
 184 with the allocation type
 185 .Dv DW_DLA_DIE
 186 to free the memory area when the
 187 .Vt Dwarf_Die
 188 descriptor is no longer needed.
 189 .Sh RETURN VALUES
 190 These functions return the following values:
 191 .Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY"
 192 .It Bq Er DW_DLV_OK
 193 The call succeeded.
 194 .It Bq Er DW_DLV_ERROR
 195 The requested operation failed.
 196 Additional information about the error encountered will be recorded in
 197 argument
 198 .Ar err ,
 199 if it is not NULL.
 200 .It Bq Er DW_DLV_NO_ENTRY
 201 For functions
 202 .Fn dwarf_child ,
 203 .Fn dwarf_siblingof
 204 and
 205 .Fn dwarf_siblingof_b ,
 206 the descriptor denoted by argument
 207 .Ar die
 208 did not have a child or sibling.
 209 .Pp
 210 For functions
 211 .Fn dwarf_offdie
 212 and
 213 .Fn dwarf_offdie_b ,
 214 there was no debugging information entry at the offset specified by
 215 argument
 216 .Ar offset .
 217 .El
 218 .Sh EXAMPLES
 219 To retrieve the first DWARF Debugging Information Entry descriptor for
 220 the first compilation unit associated with a
 221 .Vt Dwarf_Debug
 222 instance, and to traverse all its children, use:
 223 .Bd -literal -offset indent
 224 Dwarf_Debug dbg;
 225 Dwarf_Die die, die0;
 226 Dwarf_Error de;
 227
 228 \&... allocate dbg using dwarf_init() etc ...
 229
 230 if (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. */
 236 die = NULL;
 237 if (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. */
 241 die = die0;
 242 if (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. */
 246 do {
 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
 254 These 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
 257 Arguments
 258 .Ar dbg ,
 259 .Ar die
 260 or
 261 .Ar ret_die
 262 were NULL.
 263 .It Bq Er DW_DLE_DIE_NO_CU_CONTEXT
 264 Argument
 265 .Ar dbg
 266 was not associated with a compilation unit.
 267 .It Bq Er DW_DLE_NO_ENTRY
 268 The descriptor denoted by argument
 269 .Ar die
 270 had no child or sibling, or there was no DWARF debugging information
 271 entry 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