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