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