1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_loclist.3 2122 2011-11-09 15:35:14Z jkoshy $
33 .Nd retrieve DWARF location expression information
40 .Fa "Dwarf_Attribute at"
41 .Fa "Dwarf_Locdesc **llbuf"
42 .Fa "Dwarf_Signed *listlen"
43 .Fa "Dwarf_Error *error"
47 .Fa "Dwarf_Attribute at"
48 .Fa "Dwarf_Locdesc ***llbuf"
49 .Fa "Dwarf_Signed *listlen"
50 .Fa "Dwarf_Error *error"
53 These functions retrieve the location expressions
54 associated with a DWARF attribute.
59 New application code should instead use function
64 retrieves the list of location expressions associated with a DWARF
68 should reference a valid DWARF attribute.
71 should point to a location which will hold a returned array of
77 should point to a location which will be set to the number of
78 elements contained in the returned array.
81 is not NULL, it will be used to store error information in case
86 retrieves the first location expression associated with an attribute.
89 should reference a valid DWARF attribute.
92 should point to a location which will hold the returned pointer
98 should point to a location which will be always set to 1.
101 is not NULL, it will be used to store error information in case
105 descriptors are defined in the header file
107 and consist of following fields:
109 .Bl -tag -width ".Va ld_cents" -compact
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
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
119 The number of entries returned in
123 Pointer to an array of
130 descriptor represents one operation of a location expression.
131 These descriptors are defined in the header file
133 and consist of following fields:
135 .Bl -tag -width ".Va lr_number2" -compact
137 The operator name, one of the
139 constants defined in the header file
142 The first operand of this operation.
144 The second operand of this operation.
146 The byte offset of this operation within the containing location
149 .Ss Memory Management
150 The memory area used for the descriptor array returned in argument
154 When the descriptor array is no longer needed, application code should
157 to free the memory area in the following manner:
164 descriptor should be deallocated using the allocation type
165 .Dv DW_DLA_LOC_BLOCK .
167 Then, the application should free each
169 descriptor using the allocation type
174 pointer should be deallocated using the allocation type
178 On success, these functions returns
180 In case of an error, they return
185 These functions can fail with:
186 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
187 .It Bq Er DW_DLE_ARGUMENT
194 .It Bq Er DW_DLE_ARGUMENT
195 The attribute provided by argument
197 does not contain a location expression or is not associated with a
198 location expression list.
201 To retrieve the location list associated with an attribute, use:
202 .Bd -literal -offset indent
204 Dwarf_Locdesc **llbuf;
210 if (dwarf_loclist_n(at, &llbuf, &lcnt, &de) != DW_DLV_OK)
211 errx(EXIT_FAILURE, "dwarf_loclist_n failed: %s",
214 for (i = 0; i < lcnt; i++) {
215 /* ... Use llbuf[i] ... */
216 for (j = 0; (Dwarf_Half) j < llbuf[i]->ld_cents; j++) {
217 lr = &llbuf[i]->ld_s[j];
218 /* ... Use each Dwarf_Loc descriptor ... */
220 dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK);
221 dwarf_dealloc(dbg, llbuf[i], DW_DLA_LOCDESC);
223 dwarf_dealloc(dbg, llbuf, DW_DLA_LIST);
227 .Xr dwarf_dealloc 3 ,
228 .Xr dwarf_loclist_from_expr 3 ,
229 .Xr dwarf_loclist_from_expr_a 3 ,
230 .Xr dwarf_get_loclist_entry 3