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

   1 .\"     $NetBSD: dwarf_get_ranges.3,v 1.2 2014/03/09 16:58:04 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_ranges.3 2122 2011-11-09 15:35:14Z jkoshy
  28 .\"
  29 .Dd November 9, 2011
  30 .Os
  31 .Dt DWARF_GET_RANGES 3
  32 .Sh NAME
  33 .Nm dwarf_get_ranges
  34 .Nd retrieve non-contiguous address ranges
  35 .Sh LIBRARY
  36 .Lb libdwarf
  37 .Sh SYNOPSIS
  38 .In libdwarf.h
  39 .Ft int
  40 .Fo dwarf_get_ranges
  41 .Fa "Dwarf_Debug dbg"
  42 .Fa "Dwarf_Off offset"
  43 .Fa "Dwarf_Ranges **ranges"
  44 .Fa "Dwarf_Signed *cnt"
  45 .Fa "Dwarf_Unsigned *byte_cnt"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Ft int
  49 .Fo dwarf_get_ranges_a
  50 .Fa "Dwarf_Debug dbg"
  51 .Fa "Dwarf_Off offset"
  52 .Fa "Dwarf_Die die"
  53 .Fa "Dwarf_Ranges **ranges"
  54 .Fa "Dwarf_Signed *cnt"
  55 .Fa "Dwarf_Unsigned *byte_cnt"
  56 .Fa "Dwarf_Error *err"
  57 .Fc
  58 .Sh DESCRIPTION
  59 Function
  60 .Fn dwarf_get_ranges
  61 retrieves information about the non-contiguous address ranges associated
  62 with a DWARF debugging information entry.
  63 Information about address ranges is returned as an array of
  64 descriptors of type
  65 .Vt Dwarf_Ranges ,
  66 with each
  67 .Vt Dwarf_Ranges
  68 descriptor describing one address range entry.
  69 .Pp
  70 Argument
  71 .Ar dbg
  72 should reference a DWARF debug context allocated using
  73 .Xr dwarf_init 3 .
  74 .Pp
  75 Argument
  76 .Ar offset
  77 is an offset, relative to the
  78 .Dq ".debug_ranges"
  79 section, to the start of the desired list of address ranges.
  80 The offset of an address ranges list is indicated by the
  81 .Dv DW_AT_ranges
  82 attribute of a debugging information entry.
  83 .Pp
  84 Argument
  85 .Ar die
  86 (function
  87 .Fn dwarf_get_ranges_a
  88 only) is ignored in this implementation; see the section
  89 .Sx "Compatibility Notes"
  90 below.
  91 .Pp
  92 Argument
  93 .Ar ranges
  94 should point to a location that will be set to a pointer to an array
  95 of
  96 .Vt Dwarf_Ranges
  97 descriptors.
  98 .Pp
  99 Argument
 100 .Ar cnt
 101 should point to a location that will be set to the number of entries
 102 returned.
 103 If argument
 104 .Ar byte_cnt
 105 is not NULL, it will be set to the number of bytes occupied by the
 106 returned entries in the
 107 .Dq ".debug_ranges"
 108 section.
 109 .Pp
 110 If argument
 111 .Ar err
 112 is not NULL, it will be used to store error information in case
 113 of an error.
 114 .Pp
 115 .Vt Dwarf_Ranges
 116 descriptors are defined in the header file
 117 .In libdwarf.h ,
 118 and consists of the following fields:
 119 .Bl -tag -width ".Va dwr_addr1"
 120 .It Va dwr_addr1
 121 The first address offset, whose meaning depends on the type of the
 122 entry.
 123 .It Va dwr_addr2
 124 The second address offset, whose meaning depends on the type of the
 125 entry.
 126 .It Va dwr_type
 127 The type of this address range entry:
 128 .Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact
 129 .It Dv DW_RANGES_ENTRY
 130 A range list entry.
 131 For this type of entry, the fields
 132 .Va dwr_addr1
 133 and
 134 .Va dwr_addr2
 135 hold the beginning and ending offsets of the address range, respectively.
 136 .It Dv DW_RANGES_ADDRESS_SELECTION
 137 A base address selection entry.
 138 For this type of entry, the field
 139 .Va dwr_addr1
 140 is the value of the largest representable address offset, and
 141 .Va dwr_addr2
 142 is a base address for the begining and ending address offsets of
 143 subsequent address range entries in the list.
 144 .It Dv DW_RANGES_END
 145 An end of list mark.
 146 Both
 147 .Va dwr_addr1
 148 and
 149 .Va dwr_addr2
 150 are set to 0.
 151 .El
 152 .El
 153 .Ss Memory Management
 154 The memory area used for the array of
 155 .Vt Dwarf_Ranges
 156 descriptors returned in argument
 157 .Ar ranges
 158 is owned by the
 159 .Lb libdwarf .
 160 The application should not attempt to directly free this pointer.
 161 Portable code should instead use
 162 .Fn dwarf_ranges_dealloc
 163 to indicate that the memory may be freed.
 164 .Sh COMPATIBILITY
 165 Function
 166 .Fn dwarf_get_ranges_a
 167 is identical to
 168 .Fn dwarf_get_ranges ,
 169 except that it requires one additional argument
 170 .Ar die
 171 denoting the debugging information entry associated with
 172 the address range list.
 173 In this implementation of the
 174 .Lb libdwarf ,
 175 the argument
 176 .Ar die
 177 is ignored, and function
 178 .Fn dwarf_get_ranges_a
 179 is only provided for compatibility with other implementations of the
 180 DWARF(3) API.
 181 .Sh RETURN VALUES
 182 These functions
 183 return
 184 .Dv DW_DLV_OK
 185 when they succeed.
 186 They return
 187 .Dv DW_DLV_NO_ENTRY
 188 if there is no address range list at the specified offset
 189 .Ar offset .
 190 In case of an error, they return
 191 .Dv DW_DLV_ERROR
 192 and set the argument
 193 .Ar err .
 194 .Sh ERRORS
 195 These function can fail with:
 196 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 197 .It Bq Er DW_DLE_ARGUMENT
 198 One of the arguments
 199 .Ar dbg ,
 200 .Ar ranges
 201 or
 202 .Ar cnt
 203 was NULL.
 204 .It Bq Er DW_DLE_NO_ENTRY
 205 There is no address range list at the specified offset
 206 .Ar offset .
 207 .El
 208 .Sh EXAMPLE
 209 To retrieve the address range list associated with a debugging
 210 information entry, use:
 211 .Bd -literal -offset indent
 212 Dwarf_Debug dbg;
 213 Dwarf_Die die;
 214 Dwarf_Error de;
 215 Dwarf_Addr base;
 216 Dwarf_Attribute *attr_list;
 217 Dwarf_Ranges *ranges;
 218 Dwarf_Signed cnt;
 219 Dwarf_Unsigned off, attr_count, bytecnt;
 220 int i, j;
 221
 222 if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
 223     DW_DLV_OK)
 224         errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
 225             dwarf_errmsg(de));
 226
 227 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
 228         if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
 229                 warnx("dwarf_whatattr failed: %s",
 230                     dwarf_errmsg(de));
 231                 continue;
 232         }
 233         if (attr != DW_AT_ranges)
 234                 continue;
 235         if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
 236                 warnx("dwarf_formudata failed: %s",
 237                     dwarf_errmsg(de));
 238                 continue;
 239         }
 240         if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
 241             &bytecnt, &de) != DW_DLV_OK)
 242                 continue;
 243         for (j = 0; j < cnt; j++) {
 244                 if (ranges[j].dwr_type == DW_RANGES_END)
 245                         break;
 246                 else if (ranges[j].dwr_type ==
 247                     DW_RANGES_ADDRESS_SELECTION)
 248                         base = ranges[j].dwr_addr2;
 249                 else {
 250                         /*
 251                          * DW_RANGES_ENTRY entry.
 252                          * .. Use dwr_addr1 and dwr_addr2 ..
 253                          */
 254                 }
 255         }
 256 }
 257 .Ed
 258 .Sh SEE ALSO
 259 .Xr dwarf 3 ,
 260 .Xr dwarf_ranges_dealloc 3