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