external/bsd/elftoolchain/dist/libdwarf/dwarf_dieoffset.3

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