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

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