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

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