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

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