contrib/elftoolchain/libdwarf/dwarf_get_abbrev.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.3 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd March 27, 2011
  28 .Dt DWARF_GET_ABBREV 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_get_abbrev
  32 .Nd retrieve abbreviation information
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_get_abbrev
  39 .Fa "Dwarf_Debug dbg"
  40 .Fa "Dwarf_Unsigned offset"
  41 .Fa "Dwarf_Abbrev *ret_abbrev"
  42 .Fa "Dwarf_Unsigned *length"
  43 .Fa "Dwarf_Unsigned *attr_count"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Sh DESCRIPTION
  47 Function
  48 .Fn dwarf_get_abbrev
  49 retrieves information about an abbreviation from the DWARF abbreviations
  50 section,
  51 .Dq ".debug_abbrev" .
  52 Abbreviation information is returned using an opaque descriptor
  53 of type
  54 .Vt Dwarf_Abbrev .
  55 The returned
  56 .Vt Dwarf_Abbrev
  57 descriptor may then be passed to the other abbreviation related APIs
  58 in the DWARF(3) API to retrieve specific information about the
  59 abbreviation.
  60 .Pp
  61 Argument
  62 .Ar dbg
  63 should reference a DWARF debug context allocated using
  64 .Xr dwarf_init 3 .
  65 .Pp
  66 Argument
  67 .Ar offset
  68 should be an offset, relative to the
  69 .Dq ".debug_abbrev"
  70 section, to the start of an abbreviation entry.
  71 .Pp
  72 Argument
  73 .Ar ret_abbrev
  74 should point to a location that will hold a pointer to the
  75 returned
  76 .Vt Dwarf_Abbrev
  77 descriptor.
  78 .Pp
  79 Argument
  80 .Ar length
  81 should point to a location that will hold the number of bytes used
  82 by the abbrevation in the DWARF
  83 .Dq ".debug_abbrev"
  84 section.
  85 .Pp
  86 Argument
  87 .Ar attr_count
  88 should point to a location that will hold the number of
  89 attributes in the abbrevation.
  90 .Pp
  91 If argument
  92 .Ar err
  93 is not NULL, it will be used to store error information in case of an
  94 error.
  95 .Ss Memory Management
  96 The memory area used for the
  97 .Vt Dwarf_Abbrev
  98 descriptor returned in argument
  99 .Ar ret_abbrev
 100 is allocated by the
 101 .Lb libdwarf .
 102 Application code should use function
 103 .Fn dwarf_dealloc
 104 with the allocation type
 105 .Dv DW_DLA_ABBREV
 106 to free the memory area when the
 107 .Vt Dwarf_Abbrev
 108 descriptor is no longer needed.
 109 .Ss Application Programming Notes
 110 The last abbreviation entry in a standard DWARF abbreviation section
 111 will have a special length value of 1.
 112 .Sh RETURN VALUES
 113 Function
 114 .Fn dwarf_get_abbrev
 115 returns
 116 .Dv DW_DLV_OK
 117 when it succeeds.
 118 It returns
 119 .Dv DW_DLV_NO_ENTRY
 120 if there is no abbreviation information at offset
 121 .Ar offset .
 122 In case of an error, it returns
 123 .Dv DW_DLV_ERROR
 124 and sets the argument
 125 .Ar err .
 126 .Sh EXAMPLES
 127 To loop through all the abbreviation information associated with
 128 a DWARF debug context, use:
 129 .Bd -literal -offset indent
 130 Dwarf_Debug dbg;
 131 Dwarf_Abbrev ab;
 132 Dwarf_Off aboff;
 133 Dwarf_Unsigned length, attr_count;
 134 Dwarf_Half tag;
 135 Dwarf_Error de;
 136 int ret;
 137
 138 while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff,
 139     NULL, NULL, &de)) ==  DW_DLV_OK) {
 140         while ((ret = dwarf_get_abbrev(re->dbg, aboff, &ab, &length,
 141             &attr_count, &de)) == DW_DLV_OK) {
 142                 if (length == 1)        /* Last entry. */
 143                         break;
 144                 aboff += length;
 145                 if (dwarf_get_abbrev_tag(ab, &tag, &de) != DW_DLV_OK) {
 146                         warnx("dwarf_get_abbrev_tag failed: %s",
 147                             dwarf_errmsg(de));
 148                         continue;
 149                 }
 150         if (ret != DW_DLV_OK)
 151                 warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de));
 152 }
 153 if (ret == DW_DLV_ERROR)
 154         warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de));
 155 .Ed
 156 .Sh ERRORS
 157 Function
 158 .Fn dwarf_get_abbrev
 159 can fail with:
 160 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 161 .It Bq Er DW_DLE_ARGUMENT
 162 One of the arguments
 163 .Ar dbg ,
 164 .Ar ret_abbrev ,
 165 .Ar length
 166 or
 167 .Ar attr_count
 168 was NULL.
 169 .It Bq Er DW_DLE_NO_ENTRY
 170 There is no abbreviation information at offset
 171 .Ar offset .
 172 .El
 173 .Sh SEE ALSO
 174 .Xr dwarf 3 ,
 175 .Xr dwarf_dealloc 3 ,
 176 .Xr dwarf_get_abbrev_children_flag 3 ,
 177 .Xr dwarf_get_abbrev_code 3 ,
 178 .Xr dwarf_get_abbrev_entry 3 ,
 179 .Xr dwarf_get_abbrev_tag 3