1.\"	$NetBSD: dwarf_loclist_from_expr.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_from_expr.3 2074 2011-10-27 03:34:33Z jkoshy
28.\"
29.Dd July 6, 2011
30.Os
31.Dt DWARF_LOCLIST_FROM_EXPR 3
32.Sh NAME
33.Nm dwarf_loclist_from_expr ,
34.Nm dwarf_loclist_from_expr_a
35.Nd translate DWARF location expression bytes
36.Sh LIBRARY
37.Lb libdwarf
38.Sh SYNOPSIS
39.In libdwarf.h
40.Ft int
41.Fo dwarf_loclist_from_expr
42.Fa "Dwarf_Debug dbg"
43.Fa "Dwarf_Ptr bytes_in"
44.Fa "Dwarf_Unsigned bytes_len"
45.Fa "Dwarf_Locdesc **llbuf"
46.Fa "Dwarf_Signed *listlen"
47.Fa "Dwarf_Error *err"
48.Fc
49.Ft int
50.Fo dwarf_loclist_from_expr_a
51.Fa "Dwarf_Debug dbg"
52.Fa "Dwarf_Ptr bytes_in"
53.Fa "Dwarf_Unsigned bytes_len"
54.Fa "Dwarf_Half addr_size"
55.Fa "Dwarf_Locdesc **llbuf"
56.Fa "Dwarf_Signed *listlen"
57.Fa "Dwarf_Error *err"
58.Fc
59.Sh DESCRIPTION
60Function
61.Fn dwarf_loclist_from_expr
62translates DWARF location expression bytes into a
63.Vt Dwarf_Locdesc
64descriptor.
65The size for address related data is taken to be the default address
66size for the object being read.
67.Pp
68Argument
69.Ar dbg
70should reference a DWARF debug context allocated using
71.Xr dwarf_init 3 .
72.Pp
73Argument
74.Ar bytes_in
75should point to an array of DWARF location expression bytes.
76.Pp
77Argument
78.Ar bytes_len
79should specify the number of the location expression bytes to be
80translated.
81.Pp
82Argument
83.Ar llbuf
84should point to a location which will be set to a pointer
85to a returned
86.Vt Dwarf_Locdesc
87descriptor.
88.Pp
89Argument
90.Ar listlen
91should point to a location which will hold the number of the
92.Vt Dwarf_Locdesc
93descriptors returned.
94In this case it is always set to 1.
95.Pp
96If argument
97.Ar err
98is not NULL, it will be used to store error information in case of an
99error.
100.Pp
101Function
102.Fn dwarf_loclist_from_expr_a
103is identical to function
104.Fn dwarf_loclist_from_expr ,
105except that it requires one additional argument
106.Ar addr_size ,
107which specifies the address size to use when translating the location
108expression bytes.
109.Ss Memory Management
110The memory area used for the descriptor returned in argument
111.Ar llbuf
112is allocated by
113.Lb libdwarf .
114When the descriptor is no longer needed, application code should use
115function
116.Xr dwarf_dealloc 3
117to free the memory area in two steps:
118.Bl -enum -compact
119.It
120First, the array of
121.Vt Dwarf_Loc
122descriptors pointed to by the
123.Ar ld_s
124field of the
125.Vt Dwarf_Locdesc
126descriptor should be deallocated using the allocation type
127.Dv DW_DLA_LOC_BLOCK .
128.It
129Next, the application should free the
130.Ar llbuf
131pointer using the allocation type
132.Dv DW_DLA_LOCDESC .
133.El
134.Sh RETURN VALUES
135On success, these functions returns
136.Dv DW_DLV_OK .
137In case of an error, they return
138.Dv DW_DLV_ERROR
139and set the argument
140.Ar err .
141.Sh ERRORS
142These functions may fail with the following errors:
143.Bl -tag -width ".Bq Er DW_DLE_LOC_EXPR_BAD"
144.It Bq Er DW_DLE_ARGUMENT
145One of the arguments
146.Va dbg ,
147.Va bytes_in ,
148.Va llbuf
149or
150.Va listlen
151was NULL.
152.It Bq Er DW_DLE_ARGUMENT
153Argument
154.Ar bytes_len
155was 0.
156.It Bq Er DW_DLE_ARGUMENT
157The value of argument
158.Ar addr_size
159was invalid.
160.It Bq Er DW_DLE_LOC_EXPR_BAD
161An unknown or invalid operation was found in the location expression
162bytes provided in argument
163.Ar bytes_in .
164.It Bq Er DW_DLE_MEMORY
165An out of memory condition was encountered during the execution of
166this function.
167.El
168.Sh SEE ALSO
169.Xr dwarf 3 ,
170.Xr dwarf_dealloc 3 ,
171.Xr dwarf_loclist_n 3 ,
172.Xr dwarf_get_fde_info_for_all_regs3 3 ,
173.Xr dwarf_get_fde_info_for_cfa_reg3 3 ,
174.Xr dwarf_get_fde_info_for_reg3 3 ,
175.Xr dwarf_get_loclist_entry 3
176