contrib/elftoolchain/libdwarf/dwarf_highpc.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_highpc.3 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd July 22, 2014
  28 .Dt DWARF_HIGHPC 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_arrayorder ,
  32 .Nm dwarf_bitoffset ,
  33 .Nm dwarf_bitsize ,
  34 .Nm dwarf_bytesize ,
  35 .Nm dwarf_highpc ,
  36 .Nm dwarf_highpc_b ,
  37 .Nm dwarf_lowpc ,
  38 .Nm dwarf_srclang
  39 .Nd retrieve the value of a DWARF attribute
  40 .Sh LIBRARY
  41 .Lb libdwarf
  42 .Sh SYNOPSIS
  43 .In libdwarf.h
  44 .Ft int
  45 .Fo dwarf_arrayorder
  46 .Fa "Dwarf_Die die"
  47 .Fa "Dwarf_Unsigned *ret_order"
  48 .Fa "Dwarf_Error *err"
  49 .Fc
  50 .Ft int
  51 .Fo dwarf_bitoffset
  52 .Fa "Dwarf_Die die"
  53 .Fa "Dwarf_Unsigned *ret_size"
  54 .Fa "Dwarf_Error *err"
  55 .Fc
  56 .Ft int
  57 .Fo dwarf_bitsize
  58 .Fa "Dwarf_Die die"
  59 .Fa "Dwarf_Unsigned *ret_size"
  60 .Fa "Dwarf_Error *err"
  61 .Fc
  62 .Ft int
  63 .Fo dwarf_bytesize
  64 .Fa "Dwarf_Die die"
  65 .Fa "Dwarf_Unsigned *ret_size"
  66 .Fa "Dwarf_Error *err"
  67 .Fc
  68 .Ft int
  69 .Fo dwarf_highpc
  70 .Fa "Dwarf_Die die"
  71 .Fa "Dwarf_Addr *ret_highpc"
  72 .Fa "Dwarf_Error *err"
  73 .Fc
  74 .Ft int
  75 .Fo dwarf_highpc_b
  76 .Fa "Dwarf_Die die"
  77 .Fa "Dwarf_Addr *ret_highpc"
  78 .Fa "Dwarf_Half *ret_form"
  79 .Fa "enum Dwarf_Form_Class *ret_class"
  80 .Fa "Dwarf_Error *err"
  81 .Fc
  82 .Ft int
  83 .Fo dwarf_lowpc
  84 .Fa "Dwarf_Die die"
  85 .Fa "Dwarf_Addr *ret_lowpc"
  86 .Fa "Dwarf_Error *err"
  87 .Fc
  88 .Ft int
  89 .Fo dwarf_srclang
  90 .Fa "Dwarf_Die die"
  91 .Fa "Dwarf_Unsigned *ret_lang"
  92 .Fa "Dwarf_Error *err"
  93 .Fc
  94 .Sh DESCRIPTION
  95 These convenience functions are used to retrieve DWARF attribute
  96 values associated with a Debugging Information Entry (DIE) descriptor
  97 denoted by argument
  98 .Ar die .
  99 These functions store the value of the requested attribute into the
 100 location pointed to by their second argument, provided that the requested
 101 attribute exists in the debugging information entry.
 102 .Pp
 103 The list of functions and the DWARF attribute that they retrieve are:
 104 .Pp
 105 .Bl -tag -width ".Fn dwarf_arrayorder" -compact
 106 .It Fn dwarf_arrayorder
 107 Retrieve the
 108 .Dv DW_AT_ordering
 109 attribute value.
 110 .It Fn dwarf_bitoffset
 111 Retrieve the
 112 .Dv DW_AT_bit_offset
 113 attribute value.
 114 .It Fn dwarf_bitsize
 115 Retrieve the
 116 .Dv DW_AT_bit_size
 117 attribute value.
 118 .It Fn dwarf_bytesize
 119 Retrieve the
 120 .Dv DW_AT_byte_size
 121 attribute value.
 122 .It Fn dwarf_highpc
 123 Retrieve the
 124 .Dv DW_AT_high_pc
 125 attribute value.
 126 .It Fn dwarf_highpc_b
 127 Retrieve the
 128 .Dv DW_AT_high_pc
 129 attribute value.
 130 .It Fn dwarf_lowpc
 131 Retrieve the
 132 .Dv DW_AT_low_pc
 133 attribute value.
 134 .It Fn dwarf_srclang
 135 Retrieve the
 136 .Dv DW_AT_language
 137 attribute value.
 138 .El
 139 .Pp
 140 Function
 141 .Fn dwarf_highpc_b
 142 is an enhanced version of function
 143 .Fn dwarf_highpc .
 144 It sets the location specified by argument
 145 .Ar ret_form
 146 to the form code of the attribute
 147 .Dv DW_AT_high_pc ,
 148 and sets the location specified by argument
 149 .Ar ret_class
 150 to the class of that form.
 151 A value of NULL may be used for either of the arguments
 152 .Ar ret_form
 153 or
 154 .Ar ret_class
 155 if the caller is not interested in the respective value.
 156 .Sh RETURN VALUES
 157 These functions return
 158 .Dv DW_DLV_OK
 159 on success.
 160 .Pp
 161 If the debugging information entry descriptor denoted by argument
 162 .Ar die
 163 does not contain the requested attribute, these functions return
 164 .Dv DW_DLV_NO_ENTRY
 165 and set argument
 166 .Ar err .
 167 For other errors, they return
 168 .Dv DW_DLV_ERROR
 169 and set argument
 170 .Ar err .
 171 .Sh ERRORS
 172 These functions can fail with the following errors:
 173 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 174 .It Bq Er DW_DLE_ARGUMENT
 175 Arguments
 176 .Ar die ,
 177 .Ar ret_highpc ,
 178 .Ar ret_lowpc ,
 179 .Ar ret_size ,
 180 .Ar ret_lang
 181 or
 182 .Ar ret_order
 183 were NULL.
 184 .It Bq Er DW_DLE_NO_ENTRY
 185 Argument
 186 .Ar die
 187 had no requested attribute.
 188 .El
 189 .Sh SEE ALSO
 190 .Xr dwarf 3 ,
 191 .Xr dwarf_attr 3 ,
 192 .Xr dwarf_attrlist 3 ,
 193 .Xr dwarf_get_form_class 3 ,
 194 .Xr dwarf_hasattr 3