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 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd April 02, 2011
  28 .Dt DWARF_GET_ABBREV_ENTRY 3
  29 .Os
  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 EXAMPLES
 100 To loop through all the attribute entries contained in the
 101 abbreviation section, use:
 102 .Bd -literal -offset indent
 103 Dwarf_Debug dbg;
 104 Dwarf_Abbrev ab;
 105 Dwarf_Off aboff, atoff;
 106 Dwarf_Signed form;
 107 Dwarf_Half attr;
 108 Dwarf_Unsigned length, attr_count;
 109 Dwarf_Error de;
 110 int i, ret;
 111
 112 /* ...allocate 'dbg' using dwarf_init(3) ... */
 113
 114 while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff,
 115     NULL, NULL, &de)) ==  DW_DLV_OK) {
 116         while ((ret = dwarf_get_abbrev(dbg, aboff, &ab, &length,
 117             &attr_count, &de)) == DW_DLV_OK) {
 118                 if (length == 1)        /* Last entry. */
 119                         break;
 120                 aboff += length;
 121                 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
 122                         if (dwarf_get_abbrev_entry(ab, i,
 123                             &attr, &form, &atoff, &de) != DW_DLV_OK) {
 124                                 warnx("dwarf_get_abbrev_entry failed:"
 125                                     " %s", dwarf_errmsg(de));
 126                                 continue;
 127                         }
 128                         /* .. use the retrieved information ... */
 129                 }
 130         }
 131
 132         if (ret != DW_DLV_OK)
 133                 warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de));
 134 }
 135
 136 if (ret == DW_DLV_ERROR)
 137         warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de));
 138 .Ed
 139 .Sh ERRORS
 140 Function
 141 .Fn dwarf_get_abbrev_entry
 142 can fail with:
 143 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 144 .It Bq Er DW_DLE_ARGUMENT
 145 One of the arguments
 146 .Ar abbrev ,
 147 .Ar code ,
 148 .Ar form
 149 or
 150 .Ar offset
 151 was NULL.
 152 .It Bq Er DW_DLE_NO_ENTRY
 153 The attribute index specified by argument
 154 .Ar ndx
 155 was out of range.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr dwarf 3 ,
 159 .Xr dwarf_get_abbrev 3