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