Annotation of src/external/bsd/elftoolchain/dist/libdwarf/dwarf_get_vars.3, Revision 1.1.1.2
1.1.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_vars.3 2071 2011-10-27 03:20:00Z jkoshy
28: .\"
29: .Dd April 2, 2011
30: .Os
31: .Dt DWARF_GET_VARS 3
32: .Sh NAME
33: .Nm dwarf_get_vars ,
34: .Nm dwarf_var_cu_offset ,
35: .Nm dwarf_var_die_offset ,
36: .Nm dwarf_var_name_offsets ,
37: .Nm dwarf_varname
38: .Nd retrieve information about static variables
39: .Sh LIBRARY
40: .Lb libdwarf
41: .Sh SYNOPSIS
42: .In libdwarf.h
43: .Ft int
44: .Fo dwarf_get_vars
45: .Fa "Dwarf_Debug dbg"
46: .Fa "Dwarf_Var **vars"
47: .Fa "Dwarf_Signed *nvars"
48: .Fa "Dwarf_Error *err"
49: .Fc
50: .Ft int
51: .Fo dwarf_var_cu_offset
52: .Fa "Dwarf_Var var"
53: .Fa "Dwarf_Off *cu_offset"
54: .Fa "Dwarf_Error *err"
55: .Fc
56: .Ft int
57: .Fo dwarf_var_die_offset
58: .Fa "Dwarf_Var var"
59: .Fa "Dwarf_Off *die_offset"
60: .Fa "Dwarf_Error *err"
61: .Fc
62: .Ft int
63: .Fo dwarf_var_name_offsets
64: .Fa "Dwarf_Var var"
65: .Fa "char **name"
66: .Fa "Dwarf_Off *die_offset"
67: .Fa "Dwarf_Off *cu_die_offset"
68: .Fa "Dwarf_Error *err"
69: .Fc
70: .Ft int
71: .Fo dwarf_varname
72: .Fa "Dwarf_Var var"
73: .Fa "char **name"
74: .Fa "Dwarf_Error *err"
75: .Fc
76: .Sh DESCRIPTION
77: These functions retrieve information about the file scope static
78: variables associated with a DWARF debug context.
79: Information about these static variables is returned using opaque
80: descriptors of type
81: .Vt Dwarf_Var .
82: Applications need to use the functions described below to retrieve
83: the name and offset information contained in these descriptors.
84: .Pp
85: Function
86: .Fn dwarf_get_vars
87: retrieves descriptors for all the static variables associated with the
88: DWARF debug context specified by argument
89: .Ar dbg .
90: The argument
91: .Ar vars
92: should point to a location that will be set to a pointer to an array
93: of
94: .Vt Dwarf_Var
95: descriptors.
96: The argument
97: .Ar nvars
98: should point to a location that will be set to the number of
99: descriptors returned.
100: .Pp
101: Function
102: .Fn dwarf_var_cu_offset
103: returns the section-relative offset, relative to the
104: .Dq ".debug_info"
105: section, of the compilation unit that
106: contains the debugging information entry associated with the argument
107: .Ar var .
108: Argument
109: .Ar cu_offset
110: should point to a location that will hold the returned offset.
111: .Pp
112: Function
113: .Fn dwarf_var_die_offset
114: retrieves the section-relative offset, relative to the
115: .Dq ".debug_info"
116: section, of the debugging information
117: entry associated with the argument
118: .Ar var ,
119: and stores it into the location pointed to by the argument
120: .Ar die_offset .
121: .Pp
122: Function
123: .Fn dwarf_var_name_offsets
124: retrieves both the name and the associated offsets for the debugging
125: information entry for argument
126: .Ar var .
127: Argument
128: .Ar name
129: should point to a location which will be set to a pointer to a
130: NUL-terminated string containing the name of the associated debugging
131: information entry.
132: Argument
133: .Ar die_offset
134: should point to a location which will be set to a section-relative
135: offset, relative to the
136: .Dq ".debug_info"
137: section, of the associated debugging information entry.
138: Argument
139: .Ar cu_die_offset
140: should point to a location which will be set to a
141: section-relative offset, relative to the
142: .Dq ".debug_info"
143: section, of the first debugging information entry in
144: the compilation unit associated with argument
145: .Ar var .
146: .Pp
147: Function
148: .Fn dwarf_varname
149: sets the location pointed to by argument
150: .Ar name
151: to a pointer to a NUL-terminated string holding the name of the
152: debugging information entry associated with the argument
153: .Ar var .
154: .Ss Memory Management
155: The memory area used for the array of
156: .Vt Dwarf_Var
157: descriptors returned in argument
158: .Ar vars
159: by function
160: .Fn dwarf_get_vars
161: is owned by the
162: .Lb libdwarf .
163: Application code should not attempt to directly free this pointer.
164: Portable code should instead use the function
165: .Xr dwarf_vars_dealloc 3
166: to indicate that the memory area may be freed.
167: .Pp
168: The memory area used for the string returned in the
169: .Ar name
170: argument to functions
171: .Fn dwarf_var_name_offsets
172: and
173: .Fn dwarf_varname
174: is owned by the
175: .Lb libdwarf .
176: Portable code should indicate that the memory area can
177: be freed using the
178: .Xr dwarf_dealloc 3
179: function.
180: .Ss Error Returns
181: If argument
182: .Ar err
183: is not NULL, these functions will use it to store error information,
184: in case of an error.
185: .Sh RETURN VALUES
186: On success, these functions returns
187: .Dv DW_DLV_OK .
188: In case of an error, they return
189: .Dv DW_DLV_ERROR
190: and set the argument
191: .Ar err .
192: .Sh ERRORS
193: These functions may fail with the following errors:
194: .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
195: .It Bq Er DW_DLE_ARGUMENT
196: One of the arguments
197: .Va cu_die_offset ,
198: .Va cu_offset ,
199: .Va dbg ,
200: .Va die_offset ,
201: .Va var ,
202: .Va vars ,
203: .Va name ,
204: or
205: .Va nvars
206: was NULL.
207: .El
208: .Sh SEE ALSO
209: .Xr dwarf 3 ,
210: .Xr dwarf_dealloc 3 ,
211: .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
212: .Xr dwarf_vars_dealloc 3
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to dwarf_get_vars.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