1.\"	$NetBSD: dwarf_expand_frame_instructions.3,v 1.2 2014/03/09 16:58:03 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_expand_frame_instructions.3 2122 2011-11-09 15:35:14Z jkoshy
28.\"
29.Dd November 9, 2011
30.Os
31.Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3
32.Sh NAME
33.Nm dwarf_expand_frame_instructions
34.Nd expand frame instructions
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft int
40.Fo dwarf_expand_frame_instructions
41.Fa "Dwarf_Cie cie"
42.Fa "Dwarf_Ptr instructions"
43.Fa "Dwarf_Unsigned len"
44.Fa "Dwarf_Frame_Op **ret_ops"
45.Fa "Dwarf_Signed *ret_opcnt"
46.Fa "Dwarf_Error *error"
47.Fc
48.Sh DESCRIPTION
49Function
50.Fn dwarf_expand_frame_instructions
51translates DWARF frame instruction bytes into an array of
52.Vt Dwarf_Frame_Op
53descriptors.
54.Pp
55Argument
56.Ar cie
57should reference the CIE descriptor associated with the instructions
58to be translated.
59.Pp
60Arugment
61.Ar instructions
62should point to an array of frame instruction bytes, as
63returned by the functions
64.Xr dwarf_get_cie_info 3
65or
66.Xr dwarf_get_fde_instr_bytes 3 .
67.Pp
68Argument
69.Ar len
70should specify the number of the frame instruction bytes to be
71translated.
72.Pp
73Argument
74.Ar ret_ops
75should point to a location that will be set to a pointer to
76an array of translated
77.Vt Dwarf_Frame_Op
78descriptors.
79.Pp
80Argument
81.Ar ret_opcnt
82should point to a location that will hold the total number of the
83returned descriptors.
84.Pp
85If argument
86.Ar err
87is not NULL, it will be used to store error information in case of an
88error.
89.Ss Memory Management
90The memory area used for the descriptor array returned in argument
91.Ar ret_ops
92is allocated by
93.Lb libdwarf .
94Application code should use function
95.Xr dwarf_dealloc 3
96with type
97.Dv DW_DLA_FRAME_BLOCK
98to free the memory area when the descriptor array is no longer needed.
99.Sh RETURN VALUES
100Function
101.Fn dwarf_expand_frame_instructions
102returns
103.Dv DW_DLV_OK
104when it succeeds.
105In case of an error, it returns
106.Dv DW_DLV_ERROR
107and sets the argument
108.Ar err .
109.Sh ERRORS
110Function
111.Fn dwarf_expand_frame_instructions
112can fail with:
113.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
114.It Bq Er DW_DLE_ARGUMENT
115One of the arguments
116.Ar cie ,
117.Ar instructions ,
118.Ar ret_ops
119or
120.Ar ret_opcnt
121was NULL.
122.It Bq Er DW_DLE_ARGUMENT
123Argument
124.Ar len
125was 0.
126.It Bq Er DW_DLE_MEMORY
127An out of memory condition was encountered during the execution of
128this function.
129.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR
130An unknown instruction was found in the instruction bytes provided
131in argument
132.Ar instructions .
133.El
134.Sh EXAMPLE
135To retrieve and expand the frame instructions for a given FDE
136descriptor, use:
137.Bd -literal -offset indent
138Dwarf_Dbg dbg;
139Dwarf_Cie cie;
140Dwarf_Fde fde;
141Dwarf_Ptr fde_inst;
142Dwarf_Unsigned fde_instlen;
143Dwarf_Frame_Op *ops;
144Dwarf_Signed opcnt;
145Dwarf_Error de;
146
147/* ... assuming `dbg` references a valid DWARF debugging context,
148  `fde` references a valid FDE descriptor and `cie` holds the CIE
149  descriptor associated with the FDE descriptor ... */
150
151if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen,
152    &de) != DW_DLV_OK)
153	errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s",
154	    dwarf_errmsg(de));
155
156if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen,
157    &ops, &opcnt, &de) != DW_DLV_OK)
158	errx(EXIT_FAILURE,
159	    "dwarf_expand_frame_instructions failed: %s",
160	    dwarf_errmsg(de));
161
162for (i = 0; i < opcnt; i++) {
163	/* ... use ops[i] ... */
164}
165
166/* Free the memory area when no longer needed. */
167dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK);
168.Ed
169.Sh SEE ALSO
170.Xr dwarf 3 ,
171.Xr dwarf_frame_instructions_dealloc 3 ,
172.Xr dwarf_get_cie_info 3 ,
173.Xr dwarf_get_cie_index 3 ,
174.Xr dwarf_get_cie_of_fde ,
175.Xr dwarf_get_fde_at_pc 3 ,
176.Xr dwarf_get_fde_info_for_all_regs 3 ,
177.Xr dwarf_get_fde_info_for_all_regs3 3 ,
178.Xr dwarf_get_fde_info_for_cfa_reg3 3 ,
179.Xr dwarf_get_fde_info_for_reg 3 ,
180.Xr dwarf_get_fde_info_for_reg3 3 ,
181.Xr dwarf_get_fde_instr_bytes 3 ,
182.Xr dwarf_get_fde_list 3 ,
183.Xr dwarf_get_fde_list_eh 3 ,
184.Xr dwarf_get_fde_n 3
185