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_get_fde_info_for_cfa_reg3.3 2071 2011-10-27 03:20:00Z jkoshy $
26.\"
27.Dd June 12, 2011
28.Os
29.Dt DWARF_GET_FDE_INFO_FOR_CFA_REGS3 3
30.Sh NAME
31.Nm dwarf_get_fde_info_for_cfa_regs3
32.Nd retrieve a CFA register rule
33.Sh LIBRARY
34.Lb libdwarf
35.Sh SYNOPSIS
36.In libdwarf.h
37.Ft int
38.Fo dwarf_get_fde_info_for_cfa_regs3
39.Fa "Dwarf_Fde fde"
40.Fa "Dwarf_Addr pc"
41.Fa "Dwarf_Small *type"
42.Fa "Dwarf_Signed *offset_relevant"
43.Fa "Dwarf_Signed *register_num"
44.Fa "Dwarf_Signed *offset_or_block_len"
45.Fa "Dwarf_Ptr *block_ptr"
46.Fa "Dwarf_Addr *row_pc"
47.Fa "Dwarf_Error *err"
48.Fc
49.Sh DESCRIPTION
50Function
51.Fn dwarf_get_fde_info_for_cfa_reg3
52retrieves the CFA register rule for a given program counter address
53from the register rule table associated with an FDE descriptor.
54.Pp
55Argument
56.Ar fde
57should reference a valid DWARF FDE descriptor.
58.Pp
59Argument
60.Ar pc
61should hold the program counter address to be used to locate the
62desired register rule row.
63.Pp
64On successful execution,
65.Fn dwarf_get_fde_info_for_cfa_reg3
66stores information about the CFA register rule found into the locations
67pointed to by the arguments
68.Ar type ,
69.Ar offset_relevant ,
70.Ar register_num ,
71.Ar offset_or_block_len ,
72.Ar block_ptr
73and
74.Ar row_pc .
75.Pp
76Argument
77.Ar type
78should point to a location which will hold the type code of the
79register rule found.
80The returned value is one of the
81.Dv DW_EXPR_*
82contants defined in the header file
83.In libdwarf.h .
84.Pp
85If there is an offset value associated with the CFA register rule,
86the location pointed to by argument
87.Ar offset_relevant
88will be set to 1.
89.Pp
90Argument
91.Ar register_num
92should point to a location which will hold the register number associated
93with the CFA register rule.
94.Pp
95If the CFA register rule is of type
96.Dv DW_EXPR_OFFSET
97or
98.Dv DW_EXPR_VAL_OFFSET ,
99the location pointed to by argument
100.Ar offset_or_block_len
101will be set to the offset value associated with the register rule,
102or to 0 if the register rule does not have an offset value.
103If the type code is
104.Dv DW_EXPR_EXPRESSION
105or
106.Dv DW_EXPR_VAL_EXPRESSION ,
107the location pointed to by argument
108.Ar offset_or_block_len
109will be set to the length in bytes of the DWARF expression block
110associated with the register rule.
111.Pp
112Argument
113.Ar block_ptr
114should point to a location which will be set to a pointer to the
115content of the DWARF expression block associated with the CFA register
116rule.
117.Pp
118Argument
119.Ar row_pc
120should point to a location which will be set to the lowest program
121counter address associated with the register rule found.
122.Pp
123If argument
124.Ar err
125is not NULL, it will be used to return an error descriptor in case
126of an error.
127.Sh RETURN VALUES
128Function
129.Fn dwarf_get_fde_info_for_cfa_reg3
130returns
131.Dv DW_DLV_OK
132when it succeeds.
133In case of an error, it returns
134.Dv DW_DLV_ERROR
135and sets the argument
136.Ar err .
137.Sh ERRORS
138Function
139.Fn dwarf_get_fde_info_for_cfa_reg3
140can fail with:
141.Bl -tag -width ".Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE"
142.It Bq Er DW_DLE_ARGUMENT
143One of the arguments
144.Ar block_ptr ,
145.Ar fde ,
146.Ar offset_or_block_len ,
147.Ar offset_relevant ,
148.Ar register_num ,
149.Ar row_pc ,
150or
151.Ar type
152was NULL.
153.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE
154The program counter value provided in argument
155.Ar pc
156did not fall in the range covered by argument
157.Ar fde .
158.El
159.Sh SEE ALSO
160.Xr dwarf 3 ,
161.Xr dwarf_get_fde_at_pc 3 ,
162.Xr dwarf_get_fde_info_for_all_regs 3 ,
163.Xr dwarf_get_fde_info_for_all_regs3 3 ,
164.Xr dwarf_get_fde_info_for_reg 3 ,
165.Xr dwarf_get_fde_info_for_reg3 3 ,
166.Xr dwarf_get_fde_n 3 ,
167.Xr dwarf_set_frame_cfa_value 3 ,
168.Xr dwarf_set_frame_rule_table_size 3 ,
169.Xr dwarf_set_frame_rule_initial_value 3 ,
170.Xr dwarf_set_frame_same_value 3 ,
171.Xr dwarf_set_frame_undefined_value 3
172