contrib/elftoolchain/libdwarf/dwarf_formref.3

   1 .\" Copyright (c) 2010 Joseph Koshy
   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_formref.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd June 21, 2010
  28 .Dt DWARF_FORMREF 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_formref ,
  32 .Nm dwarf_global_formref
  33 .Nd retrieve offsets for REFERENCE class attributes
  34 .Sh LIBRARY
  35 .Lb libdwarf
  36 .Sh SYNOPSIS
  37 .In libdwarf.h
  38 .Ft int
  39 .Fo dwarf_formref
  40 .Fa "Dwarf_Attribute attr"
  41 .Fa "Dwarf_Off *retoffset"
  42 .Fa "Dwarf_Error *err"
  43 .Fc
  44 .Ft int
  45 .Fo dwarf_global_formref
  46 .Fa "Dwarf_Attribute attr"
  47 .Fa "Dwarf_Off *retoffset"
  48 .Fa "Dwarf_Error *err"
  49 .Fc
  50 .Sh DESCRIPTION
  51 These functions return the offsets associated with a DWARF attribute
  52 descriptor.
  53 .Pp
  54 Function
  55 .Fn dwarf_formref
  56 returns the compilation unit relative offset of the descriptor
  57 referenced by argument
  58 .Ar attr
  59 in the location pointed to by argument
  60 .Ar retoffset .
  61 Argument
  62 .Ar attr
  63 must be a reference that is local to a compilation unit.
  64 Permitted forms for argument
  65 .Ar attr
  66 are
  67 .Dv DW_FORM_ref1 ,
  68 .Dv DW_FORM_ref2 ,
  69 .Dv DW_FORM_ref4 ,
  70 .Dv DW_FORM_ref8
  71 and
  72 .Dv DW_FORM_ref_udata .
  73 .Pp
  74 Function
  75 .Fn dwarf_global_formref
  76 returns the section-relative offset of the descriptor referenced by
  77 argument
  78 .Ar attr
  79 in the location pointed to by argument
  80 .Ar retoffset .
  81 Argument
  82 .Ar attr
  83 should be a legal
  84 .Sy REFERENCE
  85 class form.
  86 Permitted forms for argument
  87 .Ar attr
  88 are:
  89 .Dv DW_FORM_ref_addr ,
  90 .Dv DW_FORM_ref_udata ,
  91 .Dv DW_FORM_ref1 ,
  92 .Dv DW_FORM_ref2 ,
  93 .Dv DW_FORM_ref4 ,
  94 .Dv DW_FORM_ref8
  95 and
  96 .Dv DW_FORM_sec_offset .
  97 The returned offset is relative to the start of the
  98 .Dq .debug_info
  99 ELF section.
 100 .Pp
 101 If argument
 102 .Ar err
 103 is not NULL, it will be used to return an error descriptor in case
 104 of an error.
 105 .Sh RETURN VALUES
 106 These functions return
 107 .Dv DW_DLV_OK
 108 on success.
 109 In case of an error, these functions return
 110 .Dv DW_DLV_ERROR
 111 and sets argument
 112 .Ar err .
 113 .Sh ERRORS
 114 These functions may fail with the following errors:
 115 .Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD"
 116 .It Bq Er DW_DLE_ARGUMENT
 117 Either of arguments
 118 .Ar attr
 119 or
 120 .Ar retoffset
 121 was NULL.
 122 .It Bq Er DW_DLE_ATTR_FORM_BAD
 123 The attribute referenced by argument
 124 .Ar attr
 125 was not of a permitted kind.
 126 .El
 127 .Sh SEE ALSO
 128 .Xr dwarf 3 ,
 129 .Xr dwarf_attr 3 ,
 130 .Xr dwarf_formblock 3 ,
 131 .Xr dwarf_formflag 3 ,
 132 .Xr dwarf_formsdata 3 ,
 133 .Xr dwarf_formsig8 3 ,
 134 .Xr dwarf_formstring 3 ,
 135 .Xr dwarf_formudata 3 ,
 136 .Xr dwarf_hasattr 3