contrib/elftoolchain/libdwarf/dwarf_get_abbrev_entry.3

   1 .\" Copyright (c) 2011 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_get_abbrev_entry.3 2071 2011-10-27 03:20:00Z jkoshy $
  26 .\"
  27 .Dd April 02, 2011
  28 .Os
  29 .Dt DWARF_GET_ABBREV_ENTRY 3
  30 .Sh NAME
  31 .Nm dwarf_get_abbrev_entry
  32 .Nd retrieve attribute information from an abbreviation descriptor
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_get_abbrev_entry
  39 .Fa "Dwarf_Abbrev abbrev"
  40 .Fa "Dwarf_Signed ndx"
  41 .Fa "Dwarf_Half *code"
  42 .Fa "Dwarf_Signed *form"
  43 .Fa "Dwarf_Off *offset"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Sh DESCRIPTION
  47 Function
  48 .Fn dwarf_get_abbrev_entry
  49 retrieves attribute information from a DWARF abbreviation descriptor.
  50 .Pp
  51 Argument
  52 .Ar abbrev
  53 should be a valid abbreviation descriptor, as returned by function
  54 .Xr dwarf_get_abbrev 3 .
  55 .Pp
  56 Argument
  57 .Ar ndx
  58 specifies the 0-based index of the attribute.
  59 The total count of the attributes contained in the abbreviation
  60 entry can be retrieved using the function
  61 .Xr dwarf_get_abbrev 3 .
  62 .Pp
  63 Argument
  64 .Ar code
  65 should point to a location which will hold a returned
  66 attribute code.
  67 .Pp
  68 Argument
  69 .Ar form
  70 should point to a location which will hold the returned
  71 form of the attribute.
  72 .Pp
  73 Argument
  74 .Ar offset
  75 should point to a location which will hold a returned offset, relative
  76 to the
  77 .Dq ".debug_abbrev"
  78 section, for the specified attribute.
  79 .Pp
  80 If argument
  81 .Ar err
  82 is not NULL, it will be used to return an error descriptor in case
  83 of an error.
  84 .Sh RETURN VALUES
  85 Function
  86 .Fn dwarf_get_abbrev_entry
  87 returns
  88 .Dv DW_DLV_OK
  89 when it succeeds.
  90 It returns
  91 .Dv DW_DLV_NO_ENTRY
  92 if the attribute index specified by argument
  93 .Ar ndx
  94 is out of range.
  95 In case of an error, it returns
  96 .Dv DW_DLV_ERROR
  97 and sets the argument
  98 .Ar err .
  99 .Sh ERRORS
 100 Function
 101 .Fn dwarf_get_abbrev_entry
 102 can fail with:
 103 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 104 .It Bq Er DW_DLE_ARGUMENT
 105 One of the arguments
 106 .Ar abbrev ,
 107 .Ar code ,
 108 .Ar form
 109 or
 110 .Ar offset
 111 was NULL.
 112 .It Bq Er DW_DLE_NO_ENTRY
 113 The attribute index specified by argument
 114 .Ar ndx
 115 was out of range.
 116 .El
 117 .Sh EXAMPLE
 118 To loop through all the attribute entries contained in the
 119 abbreviation section, use:
 120 .Bd -literal -offset indent
 121 Dwarf_Debug dbg;
 122 Dwarf_Abbrev ab;
 123 Dwarf_Off aboff, atoff;
 124 Dwarf_Signed form;
 125 Dwarf_Half attr;
 126 Dwarf_Unsigned length, attr_count;
 127 Dwarf_Error de;
 128 int i, ret;
 129
 130 /* ...allocate 'dbg' using dwarf_init(3) ... */
 131
 132 while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff,
 133     NULL, NULL, &de)) ==  DW_DLV_OK) {
 134         while ((ret = dwarf_get_abbrev(dbg, aboff, &ab, &length,
 135             &attr_count, &de)) == DW_DLV_OK) {
 136                 if (length == 1)        /* Last entry. */
 137                         break;
 138                 aboff += length;
 139                 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
 140                         if (dwarf_get_abbrev_entry(ab, i,
 141                             &attr, &form, &atoff, &de) != DW_DLV_OK) {
 142                                 warnx("dwarf_get_abbrev_entry failed:"
 143                                     " %s", dwarf_errmsg(de));
 144                                 continue;
 145                         }
 146                         /* .. use the retrieved information ... */
 147                 }
 148         }
 149
 150         if (ret != DW_DLV_OK)
 151                 warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de));
 152 }
 153
 154 if (ret == DW_DLV_ERROR)
 155         warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de));
 156 .Ed
 157 .Sh SEE ALSO
 158 .Xr dwarf 3 ,
 159 .Xr dwarf_get_abbrev 3