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

   1 .\"     $NetBSD: dwarf_loclist.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_loclist.3 2122 2011-11-09 15:35:14Z jkoshy
  28 .\"
  29 .Dd November 9, 2011
  30 .Os
  31 .Dt DWARF_LOCLIST 3
  32 .Sh NAME
  33 .Nm dwarf_loclist ,
  34 .Nm dwarf_loclist_n
  35 .Nd retrieve DWARF location expression information
  36 .Sh LIBRARY
  37 .Lb libdwarf
  38 .Sh SYNOPSIS
  39 .In libdwarf.h
  40 .Ft int
  41 .Fo dwarf_loclist
  42 .Fa "Dwarf_Attribute at"
  43 .Fa "Dwarf_Locdesc **llbuf"
  44 .Fa "Dwarf_Signed *listlen"
  45 .Fa "Dwarf_Error *error"
  46 .Fc
  47 .Ft int
  48 .Fo dwarf_loclist_n
  49 .Fa "Dwarf_Attribute at"
  50 .Fa "Dwarf_Locdesc ***llbuf"
  51 .Fa "Dwarf_Signed *listlen"
  52 .Fa "Dwarf_Error *error"
  53 .Fc
  54 .Sh DESCRIPTION
  55 These functions retrieve the location expressions
  56 associated with a DWARF attribute.
  57 .Pp
  58 Note: function
  59 .Fn dwarf_loclist
  60 is deprecated.
  61 New application code should instead use function
  62 .Fn dwarf_loclist_n
  63 .Pp
  64 Function
  65 .Fn dwarf_loclist_n
  66 retrieves the list of location expressions associated with a DWARF
  67 attribute.
  68 Argument
  69 .Ar at
  70 should reference a valid DWARF attribute.
  71 Argument
  72 .Ar llbuf
  73 should point to a location which will hold a returned array of
  74 pointers to
  75 .Vt Dwarf_Locdesc
  76 descriptors.
  77 Argument
  78 .Ar listlen
  79 should point to a location which will be set to the number of
  80 elements contained in the returned array.
  81 If argument
  82 .Ar err
  83 is not NULL, it will be used to store error information in case
  84 of an error.
  85 .Pp
  86 Function
  87 .Fn dwarf_loclist
  88 retrieves the first location expression associated with an attribute.
  89 Argument
  90 .Ar at
  91 should reference a valid DWARF attribute.
  92 Argument
  93 .Ar llbuf
  94 should point to a location which will hold the returned pointer
  95 to a
  96 .Vt Dwarf_Locdesc
  97 descriptor.
  98 Argument
  99 .Ar listlen
 100 should point to a location which will be always set to 1.
 101 If argument
 102 .Ar err
 103 is not NULL, it will be used to store error information in case
 104 of an error.
 105 .Pp
 106 .Vt Dwarf_Locdesc
 107 descriptors are defined in the header file
 108 .In libdwarf.h ,
 109 and consist of following fields:
 110 .Pp
 111 .Bl -tag -width ".Va ld_cents" -compact
 112 .It Va ld_lopc
 113 The lowest program counter address covered by the descriptor.
 114 This field will be set to 0 if the descriptor is not associated with
 115 an address range.
 116 .It Va ld_hipc
 117 The highest program counter address covered by the descriptor.
 118 This field will be set to 0 if the descriptor is not associated with
 119 an address range.
 120 .It Va ld_cents
 121 The number of entries returned in
 122 .Va ld_s
 123 field.
 124 .It Va ld_s
 125 Pointer to an array of
 126 .Vt Dwarf_Loc
 127 descriptors.
 128 .El
 129 .Pp
 130 Each
 131 .Vt Dwarf_Loc
 132 descriptor represents one operation of a location expression.
 133 These descriptors are defined in the header file
 134 .In libdwarf.h ,
 135 and consist of following fields:
 136 .Pp
 137 .Bl -tag -width ".Va lr_number2" -compact
 138 .It Va lr_atom
 139 The operator name, one of the
 140 .Dv DW_OP_*
 141 constants defined in the header file
 142 .In dwarf.h .
 143 .It Va lr_number
 144 The first operand of this operation.
 145 .It Va lr_number2
 146 The second operand of this operation.
 147 .It Va lr_offset
 148 The byte offset of this operation within the containing location
 149 expression.
 150 .El
 151 .Ss Memory Management
 152 The memory area used for the descriptor array returned in argument
 153 .Ar llbuf
 154 is allocated by the
 155 .Lb libdwarf .
 156 When the descriptor array is no longer needed, application code should
 157 use function
 158 .Xr dwarf_dealloc 3
 159 to free the memory area in the following manner:
 160 .Bl -enum
 161 .It
 162 First, the
 163 .Ar ld_s
 164 field of each
 165 .Vt Dwarf_Locdesc
 166 descriptor should be deallocated using the allocation type
 167 .Dv DW_DLA_LOC_BLOCK .
 168 .It
 169 Then, the application should free each
 170 .Vt Dwarf_Locdesc
 171 descriptor using the allocation type
 172 .Dv DW_DLA_LOCDESC .
 173 .It
 174 Finally, the
 175 .Va llbuf
 176 pointer should be deallocated using the allocation type
 177 .Dv DW_DLA_LIST .
 178 .El
 179 .Sh RETURN VALUES
 180 On success, these functions returns
 181 .Dv DW_DLV_OK .
 182 In case of an error, they return
 183 .Dv DW_DLV_ERROR
 184 and set the argument
 185 .Ar err .
 186 .Sh ERRORS
 187 These functions can fail with:
 188 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 189 .It Bq Er DW_DLE_ARGUMENT
 190 One of the arguments
 191 .Ar at ,
 192 .Ar llbuf
 193 or
 194 .Ar listlen
 195 was NULL.
 196 .It Bq Er DW_DLE_ARGUMENT
 197 The attribute provided by argument
 198 .Ar at
 199 does not contain a location expression or is not associated with a
 200 location expression list.
 201 .El
 202 .Sh EXAMPLE
 203 To retrieve the location list associated with an attribute, use:
 204 .Bd -literal -offset indent
 205 Dwarf_Attribute at;
 206 Dwarf_Locdesc **llbuf;
 207 Dwarf_Signed lcnt;
 208 Dwarf_Loc *lr;
 209 Dwarf_Error de;
 210 int i;
 211
 212 if (dwarf_loclist_n(at, &llbuf, &lcnt, &de) != DW_DLV_OK)
 213         errx(EXIT_FAILURE, "dwarf_loclist_n failed: %s",
 214             dwarf_errmsg(de));
 215
 216 for (i = 0; i < lcnt; i++) {
 217         /* ... Use llbuf[i] ... */
 218         for (j = 0; (Dwarf_Half) j < llbuf[i]->ld_cents; j++) {
 219                 lr = &llbuf[i]->ld_s[j];
 220                 /* ... Use each Dwarf_Loc descriptor ... */
 221         }
 222         dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK);
 223         dwarf_dealloc(dbg, llbuf[i], DW_DLA_LOCDESC);
 224 }
 225 dwarf_dealloc(dbg, llbuf, DW_DLA_LIST);
 226 .Ed
 227 .Sh SEE ALSO
 228 .Xr dwarf 3 ,
 229 .Xr dwarf_dealloc 3 ,
 230 .Xr dwarf_loclist_from_expr 3 ,
 231 .Xr dwarf_loclist_from_expr_a 3 ,
 232 .Xr dwarf_get_loclist_entry 3