contrib/elftoolchain/libdwarf/dwarf_child.3

   1 .\" Copyright (c) 2010 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 2122 2011-11-09 15:35:14Z jkoshy $
  26 .\"
  27 .Dd November 9, 2011
  28 .Os
  29 .Dt DWARF_CHILD 3
  30 .Sh NAME
  31 .Nm dwarf_child ,
  32 .Nm dwarf_siblingof ,
  33 .Nm dwarf_offdie
  34 .Nd retrieve DWARF Debugging Information Entry descriptors
  35 .Sh LIBRARY
  36 .Lb libdwarf
  37 .Sh SYNOPSIS
  38 .In libdwarf.h
  39 .Ft int
  40 .Fn dwarf_child "Dwarf_Die die" "Dwarf_Die *ret_die" "Dwarf_Error *err"
  41 .Ft int
  42 .Fo dwarf_siblingof
  43 .Fa "Dwarf_Debug dbg"
  44 .Fa "Dwarf_Die die"
  45 .Fa "Dwarf_Die *ret_die"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Ft int
  49 .Fo dwarf_offdie
  50 .Fa "Dwarf_Debug dbg"
  51 .Fa "Dwarf_Off offset"
  52 .Fa "Dwarf_Die *ret_die"
  53 .Fa "Dwarf_Error *err"
  54 .Fc
  55 .Sh DESCRIPTION
  56 These functions are used to retrieve and traverse DWARF
  57 Debugging Information Entry (DIE) descriptors associated with
  58 a compilation unit.
  59 These descriptors are arranged in the form of a tree, traversable
  60 using
  61 .Dq child
  62 and
  63 .Dq sibling
  64 links; see
  65 .Xr dwarf 3
  66 for more information.
  67 DWARF Debugging Information Entry descriptors are represented
  68 by the
  69 .Vt Dwarf_Die
  70 opaque type.
  71 .Pp
  72 Function
  73 .Fn dwarf_child
  74 retrieves the child of descriptor denoted by argument
  75 .Ar die ,
  76 and stores it in the location pointed to by argument
  77 .Ar ret_die .
  78 .Pp
  79 Function
  80 .Fn dwarf_siblingof
  81 retrieves the sibling of the descriptor denoted by argument
  82 .Ar die ,
  83 and stores it in the location pointed to by argument
  84 .Ar ret_die .
  85 If argument
  86 .Ar die
  87 is NULL, the first debugging information entry descriptor for the
  88 current compilation unit will be returned.
  89 This function and function
  90 .Fn dwarf_child
  91 may be used together to traverse the tree of debugging information
  92 entry descriptors for a compilation unit.
  93 .Pp
  94 Function
  95 .Fn dwarf_offdie
  96 retrieves the debugging information entry descriptor at global offset
  97 .Ar offset
  98 in the
  99 .Dq .debug_info
 100 section of the object associated with argument
 101 .Ar dbg .
 102 The returned descriptor is written to the location pointed to by argument
 103 .Ar ret_die .
 104 .Ss Memory Management
 105 The memory area used for the
 106 .Vt Dwarf_Die
 107 descriptor returned in argument
 108 .Ar ret_die
 109 is allocated by the
 110 .Lb libdwarf .
 111 Application code should use function
 112 .Fn dwarf_dealloc
 113 with the allocation type
 114 .Dv DW_DLA_DIE
 115 to free the memory area when the
 116 .Vt Dwarf_Die
 117 descriptor is no longer needed.
 118 .Sh RETURN VALUES
 119 These functions return the following values:
 120 .Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY"
 121 .It Bq Er DW_DLV_OK
 122 The call succeeded.
 123 .It Bq Er DW_DLV_ERROR
 124 The requested operation failed.
 125 Additional information about the error encountered will be recorded in
 126 argument
 127 .Ar err ,
 128 if it is not NULL.
 129 .It Bq Er DW_DLV_NO_ENTRY
 130 For functions
 131 .Fn dwarf_child
 132 and
 133 .Fn dwarf_siblingof ,
 134 the descriptor denoted by argument
 135 .Ar die
 136 did not have a child or sibling.
 137 For function
 138 .Fn dwarf_offdie ,
 139 there was no debugging information entry at the offset specified by
 140 argument
 141 .Ar offset .
 142 .El
 143 .Sh ERRORS
 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
 147 Arguments
 148 .Ar dbg ,
 149 .Ar die
 150 or
 151 .Ar ret_die
 152 were NULL.
 153 .It Bq Er DW_DLE_DIE_NO_CU_CONTEXT
 154 Argument
 155 .Ar dbg
 156 was not associated with a compilation unit.
 157 .It Bq Er DW_DLE_NO_ENTRY
 158 The descriptor denoted by argument
 159 .Ar die
 160 had no child or sibling, or there was no DWARF debugging information
 161 entry at the offset specified by argument
 162 .Va offset .
 163 .El
 164 .Sh EXAMPLES
 165 To retrieve the first DWARF Debugging Information Entry descriptor for
 166 the first compilation unit associated with a
 167 .Vt Dwarf_Debug
 168 instance, and to traverse all its children, use:
 169 .Bd -literal -offset indent
 170 Dwarf_Debug dbg;
 171 Dwarf_Die die, die0;
 172 Dwarf_Error de;
 173
 174 \&... allocate dbg using dwarf_init() etc ...
 175
 176 if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) !=
 177     DW_DLV_OK)
 178         errx(EXIT_FAILURE, "dwarf_next_cu_header: %s",
 179             dwarf_errmsg(de));
 180
 181 /* Get the first DIE for the current compilation unit. */
 182 die = NULL;
 183 if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK)
 184         errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de));
 185
 186 /* Get the first child of this DIE. */
 187 die = die0;
 188 if (dwarf_child(die, &die0, &de) != DW_DLV_OK)
 189         errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de));
 190
 191 /* Get the rest of children. */
 192 do {
 193         die = die0;
 194         if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR)
 195                 errx(EXIT_FAILURE, "dwarf_siblingof: %s",
 196                     dwarf_errmsg(de));
 197 } while (die0 != NULL);
 198 .Ed
 199 .Sh SEE ALSO
 200 .Xr dwarf 3 ,
 201 .Xr dwarf_errmsg 3 ,
 202 .Xr dwarf_next_cu_header 3