contrib/elftoolchain/libdwarf/dwarf_dieoffset.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_dieoffset.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd December 21, 2014
  28 .Dt DWARF_DIEOFFSET 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_die_CU_offset ,
  32 .Nm dwarf_die_CU_offset_range ,
  33 .Nm dwarf_dieoffset ,
  34 .Nm dwarf_get_cu_die_offset_given_cu_header_offset ,
  35 .Nm dwarf_get_cu_die_offset_given_cu_header_offset_b
  36 .Nd return offsets of DWARF debugging information entries
  37 .Sh LIBRARY
  38 .Lb libdwarf
  39 .Sh SYNOPSIS
  40 .In libdwarf.h
  41 .Ft int
  42 .Fo dwarf_die_CU_offset
  43 .Fa "Dwarf_Die die"
  44 .Fa "Dwarf_Off *ret_offset"
  45 .Fa "Dwarf_Error *err"
  46 .Fc
  47 .Ft int
  48 .Fo dwarf_die_CU_offset_range
  49 .Fa "Dwarf_Die die"
  50 .Fa "Dwarf_Off *cu_offset"
  51 .Fa "Dwarf_Off *cu_length"
  52 .Fa "Dwarf_Error *err"
  53 .Fc
  54 .Ft int
  55 .Fo dwarf_dieoffset
  56 .Fa "Dwarf_Die die"
  57 .Fa "Dwarf_Off *ret_offset"
  58 .Fa "Dwarf_Error *err"
  59 .Fc
  60 .Ft int
  61 .Fo dwarf_get_cu_die_offset_given_cu_header_offset
  62 .Fa "Dwarf_Debug dbg"
  63 .Fa "Dwarf_Off in_cu_header_offset"
  64 .Fa "Dwarf_Off *out_cu_die_offset"
  65 .Fa "Dwarf_Error *err"
  66 .Fc
  67 .Ft int
  68 .Fo dwarf_get_cu_die_offset_given_cu_header_offset_b
  69 .Fa "Dwarf_Debug dbg"
  70 .Fa "Dwarf_Off in_cu_header_offset"
  71 .Fa "Dwarf_Bool is_info"
  72 .Fa "Dwarf_Off *out_cu_die_offset"
  73 .Fa "Dwarf_Error *err"
  74 .Fc
  75 .Sh DESCRIPTION
  76 These functions are used to retrieve offsets for DWARF debugging
  77 information entries.
  78 .Pp
  79 Function
  80 .Fn dwarf_die_CU_offset
  81 returns the offset of the debugging information entry referenced by
  82 argument
  83 .Ar die
  84 relative to the start of its containing compilation unit.
  85 Argument
  86 .Ar ret_offset
  87 should point to the location that is to hold the returned offset.
  88 If argument
  89 .Ar err
  90 is non-NULL, it will be used to return an error descriptor in case of
  91 an error.
  92 .Pp
  93 Function
  94 .Fn dwarf_die_CU_offset_range
  95 returns the section-relative offset and length of the compilation unit
  96 containing the debugging information entry referenced by argument
  97 .Ar die .
  98 Argument
  99 .Ar cu_offset
 100 should point to a location that will hold the returned offset.
 101 Argument
 102 .Ar cu_length
 103 should point to a location that will hold the returned length of the
 104 compilation unit.
 105 If argument
 106 .Ar err
 107 is non-NULL, it will be used to return an error descriptor in case of
 108 an error.
 109 .Pp
 110 Function
 111 .Fn dwarf_dieoffset
 112 retrieves the section-relative offset of the debugging information
 113 entry referenced by argument
 114 .Ar die .
 115 Argument
 116 .Ar ret_offset
 117 should point to a location that is to hold the returned
 118 section-relative offset.
 119 If argument
 120 .Ar err
 121 is non-NULL, it will be used to return an error descriptor in case of
 122 an error.
 123 .Pp
 124 Function
 125 .Fn dwarf_get_cu_die_offset_given_cu_header_offset
 126 returns the offset for the first debugging information entry for a
 127 compilation unit, given an offset to the header of the compilation
 128 unit.
 129 Argument
 130 .Ar dbg
 131 should reference a valid debugging context allocated using
 132 .Xr dwarf_init 3 .
 133 Argument
 134 .Ar in_cu_header_offset
 135 contains the offset to the start of a compilation unit.
 136 Argument
 137 .Ar out_cu_die_offset
 138 points to a location that will hold the returned offset.
 139 If argument
 140 .Ar err
 141 is non-NULL, it will be used to return an error descriptor in case of
 142 an error.
 143 .Pp
 144 Function
 145 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
 146 behaves identically to the function
 147 .Fn dwarf_get_cu_die_offset_given_cu_header_offset
 148 when the argument
 149 .Ar is_info
 150 is non-zero.
 151 When the argument
 152 .Ar is_info
 153 is zero, function
 154 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
 155 returns the offset for the first debugging information entry for a
 156 type unit, given an offset to the header of the type unit in argument
 157 .Ar in_cu_header_offset .
 158 Argument
 159 .Ar out_cu_die_offset
 160 points to a location that will hold the returned offset.
 161 If the argument
 162 .Ar err
 163 is non-NULL, it will be used to return an error descriptor in case of
 164 an error.
 165 .Sh RETURN VALUES
 166 On success, these functions return
 167 .Dv DW_DLV_OK .
 168 In case of an error, these functions return
 169 .Dv DW_DLV_ERROR
 170 and set argument
 171 .Ar err .
 172 .Pp
 173 Function
 174 .Fn dwarf_get_cu_die_offset_given_cu_header_offset
 175 and
 176 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
 177 returns
 178 .Dv DW_DLV_NO_ENTRY
 179 and sets argument
 180 .Ar err
 181 if there is no compilation or type unit located at the
 182 offset specified in argument
 183 .Ar in_cu_header_offset .
 184 .Sh ERRORS
 185 These functions may fail with the following errors:
 186 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 187 .It Bq Er DW_DLE_ARGUMENT
 188 One of the arguments
 189 .Va cu_length ,
 190 .Va cu_offset ,
 191 .Va dbg ,
 192 .Va die ,
 193 .Va out_cu_die_offset
 194 or
 195 .Va ret_offset
 196 was NULL.
 197 .It Bq Er DW_DLE_NO_ENTRY
 198 Argument
 199 .Ar in_cu_header_offset
 200 specified an unknown offset.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr dwarf 3 ,
 204 .Xr dwarf_next_cu_header 3 ,
 205 .Xr dwarf_offdie 3 ,
 206 .Xr dwarf_offdie_b 3