contrib/elftoolchain/libdwarf/dwarf_attr.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_attr.3 3093 2014-09-02 22:09:40Z kaiwang27 $
  26 .\"
  27 .Dd April 8, 2010
  28 .Os
  29 .Dt DWARF_ATTR 3
  30 .Sh NAME
  31 .Nm dwarf_attr
  32 .Nd retrieve an attribute descriptor associated with a DWARF debugging information entry
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_attr
  39 .Fa "Dwarf_Die die"
  40 .Fa "Dwarf_Half attr"
  41 .Fa "Dwarf_Attribute *atp"
  42 .Fa "Dwarf_Error *err"
  43 .Fc
  44 .Sh DESCRIPTION
  45 Function
  46 .Fn dwarf_attr
  47 retrieves the attribute descriptor for an attribute associated
  48 with the DWARF debugging information entry descriptor in
  49 argument
  50 .Ar die .
  51 .Pp
  52 DWARF attribute descriptors are represented by value of the opaque
  53 type
  54 .Vt Dwarf_Attribute ,
  55 see
  56 .Xr dwarf 3 .
  57 .Pp
  58 Argument
  59 .Ar attr
  60 names the desired DWARF attribute.
  61 Legal values for argument
  62 .Ar attr
  63 are those denoted by the
  64 .Dv DW_AT_*
  65 constants in the DWARF specification.
  66 .Pp
  67 Argument
  68 .Ar atp
  69 points to a location into which the returned attribute descriptor
  70 will be written.
  71 The returned descriptor may then be passed to the form query functions in the
  72 .Xr dwarf 3
  73 API set to access the data associated with the attribute.
  74 .Pp
  75 If argument
  76 .Ar err
  77 is non-NULL, it will be used to return an error descriptor in case
  78 of an error.
  79 .Sh RETURN VALUES
  80 Function
  81 .Fn dwarf_attr
  82 returns
  83 .Dv DW_DLV_OK on success.
  84 .Pp
  85 If the debugging information entry descriptor denoted by argument
  86 .Ar die
  87 does not contain the named attribute, the function returns
  88 .Dv DW_DLV_NO_ENTRY
  89 and sets argument
  90 .Ar err .
  91 For other errors, it returns
  92 .Dv DW_DLV_ERROR
  93 and sets argument
  94 .Ar err .
  95 .Sh ERRORS
  96 Function
  97 .Fn dwarf_attr
  98 can fail with the following errors:
  99 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 100 .It Bq Er DW_DLE_ARGUMENT
 101 Either of arguments
 102 .Ar die
 103 or
 104 .Ar atp
 105 was NULL.
 106 .It Bq Er DW_DLE_NO_ENTRY
 107 Argument
 108 .Ar die
 109 had no attribute corresponding to the value
 110 in argument
 111 .Ar attr .
 112 .El
 113 .Sh SEE ALSO
 114 .Xr dwarf 3 ,
 115 .Xr dwarf_attrlist 3 ,
 116 .Xr dwarf_attroffset 3 ,
 117 .Xr dwarf_hasattr 3 ,
 118 .Xr dwarf_hasform 3 ,
 119 .Xr dwarf_whatattr 3 ,
 120 .Xr dwarf_whatform 3