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 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd November 9, 2011
  28 .Dt DWARF_GET_RANGES 3
  29 .Os
  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 beginning 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 RETURN VALUES
 163 These functions
 164 return
 165 .Dv DW_DLV_OK
 166 when they succeed.
 167 They return
 168 .Dv DW_DLV_NO_ENTRY
 169 if there is no address range list at the specified offset
 170 .Ar offset .
 171 In case of an error, they return
 172 .Dv DW_DLV_ERROR
 173 and set the argument
 174 .Ar err .
 175 .Sh EXAMPLES
 176 To retrieve the address range list associated with a debugging
 177 information entry, use:
 178 .Bd -literal -offset indent
 179 Dwarf_Debug dbg;
 180 Dwarf_Die die;
 181 Dwarf_Error de;
 182 Dwarf_Addr base;
 183 Dwarf_Attribute *attr_list;
 184 Dwarf_Ranges *ranges;
 185 Dwarf_Signed cnt;
 186 Dwarf_Unsigned off, attr_count, bytecnt;
 187 int i, j;
 188
 189 if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
 190     DW_DLV_OK)
 191         errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
 192             dwarf_errmsg(de));
 193
 194 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
 195         if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
 196                 warnx("dwarf_whatattr failed: %s",
 197                     dwarf_errmsg(de));
 198                 continue;
 199         }
 200         if (attr != DW_AT_ranges)
 201                 continue;
 202         if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
 203                 warnx("dwarf_formudata failed: %s",
 204                     dwarf_errmsg(de));
 205                 continue;
 206         }
 207         if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
 208             &bytecnt, &de) != DW_DLV_OK)
 209                 continue;
 210         for (j = 0; j < cnt; j++) {
 211                 if (ranges[j].dwr_type == DW_RANGES_END)
 212                         break;
 213                 else if (ranges[j].dwr_type ==
 214                     DW_RANGES_ADDRESS_SELECTION)
 215                         base = ranges[j].dwr_addr2;
 216                 else {
 217                         /*
 218                          * DW_RANGES_ENTRY entry.
 219                          * .. Use dwr_addr1 and dwr_addr2 ..
 220                          */
 221                 }
 222         }
 223 }
 224 .Ed
 225 .Sh COMPATIBILITY
 226 Function
 227 .Fn dwarf_get_ranges_a
 228 is identical to
 229 .Fn dwarf_get_ranges ,
 230 except that it requires one additional argument
 231 .Ar die
 232 denoting the debugging information entry associated with
 233 the address range list.
 234 In this implementation of the
 235 .Lb libdwarf ,
 236 the argument
 237 .Ar die
 238 is ignored, and function
 239 .Fn dwarf_get_ranges_a
 240 is only provided for compatibility with other implementations of the
 241 DWARF(3) API.
 242 .Sh ERRORS
 243 These function can fail with:
 244 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 245 .It Bq Er DW_DLE_ARGUMENT
 246 One of the arguments
 247 .Ar dbg ,
 248 .Ar ranges
 249 or
 250 .Ar cnt
 251 was NULL.
 252 .It Bq Er DW_DLE_NO_ENTRY
 253 There is no address range list at the specified offset
 254 .Ar offset .
 255 .El
 256 .Sh SEE ALSO
 257 .Xr dwarf 3 ,
 258 .Xr dwarf_ranges_dealloc 3