Annotation of src/external/bsd/elftoolchain/dist/libdwarf/dwarf_get_fde_info_for_reg3.3, Revision 1.3
1.2 christos 1: .\" $NetBSD$
2: .\"
1.1 christos 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_get_fde_info_for_reg3.3 2122 2011-11-09 15:35:14Z jkoshy
28: .\"
29: .Dd November 9, 2011
30: .Os
31: .Dt DWARF_GET_FDE_INFO_FOR_REG3 3
32: .Sh NAME
33: .Nm dwarf_get_fde_info_for_reg3
34: .Nd retrieve register rule
35: .Sh LIBRARY
36: .Lb libdwarf
37: .Sh SYNOPSIS
38: .In libdwarf.h
39: .Ft int
40: .Fo dwarf_get_fde_info_for_reg3
41: .Fa "Dwarf_Fde fde"
42: .Fa "Dwarf_Half table_column"
43: .Fa "Dwarf_Addr pc"
44: .Fa "Dwarf_Small *type"
45: .Fa "Dwarf_Signed *offset_relevant"
46: .Fa "Dwarf_Signed *register_num"
47: .Fa "Dwarf_Signed *offset_or_block_len"
48: .Fa "Dwarf_Ptr *block_ptr"
49: .Fa "Dwarf_Addr *row_pc"
50: .Fa "Dwarf_Error *error"
51: .Fc
52: .Sh DESCRIPTION
53: Function
54: .Fn dwarf_get_fde_info_for_reg3
55: retrieves a register rule from the register rule table associated with
56: a given FDE descriptor, given a program counter address and rule
57: column number.
58: .Pp
59: Argument
60: .Ar fde
61: should reference a valid DWARF FDE descriptor.
62: .Pp
63: Arugment
64: .Ar table_column
65: should hold the column number of the register rule desired.
66: .Pp
67: Argument
68: .Ar pc
69: should hold the program counter address to be used to locate the
70: desired register rule row.
71: .Pp
72: On successful execution,
73: .Fn dwarf_get_fde_info_for_reg3
74: stores information about the register rule found into the locations
75: pointed to by the arguments
76: .Ar type ,
77: .Ar offset_relevant ,
78: .Ar register_num ,
79: .Ar offset_or_block_len ,
80: .Ar block_ptr
81: and
82: .Ar row_pc .
83: .Pp
84: Argument
85: .Ar type
86: should point to a location which will hold the type code of the
87: register rule found.
88: The returned value is one of the
89: .Dv DW_EXPR_*
90: contants defined in the header file
91: .In libdwarf.h .
92: .Pp
93: If there is an offset value associated with the register rule,
94: the location pointed to by argument
95: .Ar offset_relevant
96: will be set to 1.
97: .Pp
98: Argument
99: .Ar register_num
100: should point to a location which will hold the register number associated
101: with the register rule.
102: .Pp
103: If the register rule is of type
104: .Dv DW_EXPR_OFFSET
105: or
106: .Dv DW_EXPR_VAL_OFFSET ,
107: the location pointed to by argument
108: .Ar offset_or_block_len
109: will be set to the offset value associated with the register rule,
110: or to 0 if the register rule does not have an offset value.
111: If the type code is
112: .Dv DW_EXPR_EXPRESSION
113: or
114: .Dv DW_EXPR_VAL_EXPRESSION ,
115: the location pointed to by argument
116: .Ar offset_or_block_len
117: will be set to the length in bytes of the DWARF expression block
118: associated with the register rule.
119: .Pp
120: Argument
121: .Ar block_ptr
122: should point to a location which will be set to a pointer to the
123: content of the DWARF expression block associated with the register
124: rule.
125: .Pp
126: Argument
127: .Ar row_pc
128: should point to a location which will be set to the lowest program
129: counter address associated with the register rule found.
130: .Pp
131: If argument
132: .Ar err
133: is not NULL, it will be used to return an error descriptor in case
134: of an error.
135: .Sh RETURN VALUES
136: Function
137: .Fn dwarf_get_fde_info_for_reg3
138: returns
139: .Dv DW_DLV_OK
140: when it succeeds.
141: In case of an error, it returns
142: .Dv DW_DLV_ERROR
143: and sets the argument
144: .Ar err .
145: .Sh ERRORS
146: Function
147: .Fn dwarf_get_fde_info_for_reg3
148: can fail with:
149: .Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD"
150: .It Bq Er DW_DLE_ARGUMENT
151: One of the arguments
152: .Ar block_ptr ,
153: .Ar fde ,
154: .Ar offset_or_block_len ,
155: .Ar offset_relevant ,
156: .Ar register_num ,
157: .Ar row_pc ,
158: or
159: .Ar type
160: was NULL.
161: .It Bq Er DW_DLE_FRAME_TABLE_COL_BAD
162: The column number provided in argument
163: .Ar table_column
164: was too large.
165: .It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE
166: The program counter value provided in argument
167: .Ar pc
168: did not fall in the range covered by argument
169: .Ar fde .
170: .El
171: .Sh EXAMPLE
172: To retrieve the register rules at column 3 from a rule table
173: associated with a FDE descriptor:
174: .Bd -literal -offset indent
175: Dwarf_Fde fde;
176: Dwarf_Off fde_offset, cie_offset;
177: Dwarf_Unsigned func_len, fde_length;
178: Dwarf_Signed cie_index, offset_relevant, register_num;
179: Dwarf_Signed offset_or_block_len;
180: Dwarf_Addr low_pc, row_pc;
181: Dwarf_Ptr fde_addr, block_ptr;
182: Dwarf_Small type;
183: Dwarf_Error de;
184:
185: /* ... assuming `fde` references a valid FDE descriptor... */
186: if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr,
187: &fde_length, &cie_offset, &cie_index, &fde_offset,
188: &de) != DW_DLV_OK)
189: errx(EXIT_FAILURE, "dwarf_get_fde_range failed: %s",
190: dwarf_errmsg(de));
191:
192: /* Iterate all the table rows. */
193: for (pc = low_pc; pc < low_pc + func_len; pc++) {
194: if (dwarf_get_fde_info_for_reg3(fde, 3, pc, &type,
195: &offset_relevant, ®ister_num, &offset_or_block_len,
196: &block_ptr, &row_pc, &de) != DW_DLV_OK) {
197: warnx("dwarf_get_fde_info_for_reg3 failed: %s",
198: dwarf_errmsg(de));
199: continue;
200: }
201: /* ... use the retrieved register rule ... */
202: }
203: .Ed
204: .Sh SEE ALSO
205: .Xr dwarf 3 ,
206: .Xr dwarf_get_fde_at_pc 3 ,
207: .Xr dwarf_get_fde_info_for_all_regs 3 ,
208: .Xr dwarf_get_fde_info_for_all_regs3 3 ,
209: .Xr dwarf_get_fde_info_for_cfa_reg3 3 ,
210: .Xr dwarf_get_fde_info_for_reg 3 ,
211: .Xr dwarf_get_fde_n 3 ,
212: .Xr dwarf_set_frame_cfa_value 3 ,
213: .Xr dwarf_set_frame_rule_table_size 3 ,
214: .Xr dwarf_set_frame_rule_initial_value 3 ,
215: .Xr dwarf_set_frame_same_value 3 ,
216: .Xr dwarf_set_frame_undefined_value 3
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to dwarf_get_fde_info_for_reg3.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / external / bsd / elftoolchain / dist / libdwarf