Annotation of src/external/bsd/elftoolchain/dist/libdwarf/dwarf_get_fde_instr_bytes.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_instr_bytes.3 2071 2011-10-27 03:20:00Z jkoshy
28: .\"
29: .Dd May 23, 2011
30: .Os
31: .Dt DWARF_GET_FDE_INSTR_BYTES 3
32: .Sh NAME
33: .Nm dwarf_get_fde_instr_bytes
34: .Nd retrieve instructions from FDE descritpor
35: .Sh LIBRARY
36: .Lb libdwarf
37: .Sh SYNOPSIS
38: .In libdwarf.h
39: .Ft int
40: .Fo dwarf_get_fde_instr_bytes
41: .Fa "Dwarf_Fde fde"
42: .Fa "Dwarf_Ptr *ret_inst"
43: .Fa "Dwarf_Unsigned *ret_len"
44: .Fa "Dwarf_Error *error"
45: .Fc
46: .Sh DESCRIPTION
47: Function
48: .Fn dwarf_get_fde_instr_bytes
49: retrieves instruction bytes from a given FDE descriptor.
50: .Pp
51: Argument
52: .Ar fde
53: should reference a valid DWARF FDE descriptor.
54: .Pp
55: Argument
56: .Ar ret_inst
57: should point to a location that will be set to a pointer
58: to an array of bytes containing the instructions of the
59: FDE descriptor.
60: .Pp
61: Argument
62: .Ar ret_len
63: should point to a location that will hold the length in
64: bytes of the instructions returned in argument
65: .Ar ret_inst .
66: .Pp
67: If argument
68: .Ar err
69: is not NULL, it will be used to store error information in case of an
70: error.
71: .Pp
72: Applications can use the function
73: .Xr dwarf_expand_frame_instructions 3
74: to parse and expand the returned instruction bytes into an array of
75: .Vt Dwarf_Frame_Op
76: descriptors.
77: .Sh RETURN VALUES
78: Function
79: .Fn dwarf_get_fde_instr_bytes
80: returns
81: .Dv DW_DLV_OK
82: when it succeeds.
83: In case of an error, it returns
84: .Dv DW_DLV_ERROR
85: and sets the argument
86: .Ar err .
87: .Sh ERRORS
88: Function
89: .Fn dwarf_get_fde_instr_bytes
90: can fail with:
91: .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
92: .It Bq Er DW_DLE_ARGUMENT
93: One of the arguments
94: .Ar fde ,
95: .Ar ret_inst
96: or
97: .Ar ret_len
98: was NULL.
99: .El
100: .Sh SEE ALSO
101: .Xr dwarf 3 ,
102: .Xr dwarf_expand_frame_instructions 3 ,
103: .Xr dwarf_get_cie_info 3 ,
104: .Xr dwarf_get_cie_index 3 ,
105: .Xr dwarf_get_cie_of_fde ,
106: .Xr dwarf_get_fde_at_pc 3 ,
107: .Xr dwarf_get_fde_info_for_all_regs 3 ,
108: .Xr dwarf_get_fde_info_for_all_regs3 3 ,
109: .Xr dwarf_get_fde_info_for_cfa_reg3 3 ,
110: .Xr dwarf_get_fde_info_for_reg 3 ,
111: .Xr dwarf_get_fde_info_for_reg3 3 ,
112: .Xr dwarf_get_fde_list 3 ,
113: .Xr dwarf_get_fde_list_eh 3 ,
114: .Xr dwarf_get_fde_n 3 ,
115: .Xr dwarf_get_fde_range 3
CVSweb <webmaster@jp.NetBSD.org>