|
1 \." |
|
2 \." the following line may be removed if the ff ligature works on your machine |
|
3 .lg 0 |
|
4 \." set up heading formats |
|
5 .ds HF 3 3 3 3 3 2 2 |
|
6 .ds HP +2 +2 +1 +0 +0 |
|
7 .nr Hs 5 |
|
8 .nr Hb 5 |
|
9 \." ============================================== |
|
10 \." Put current date in the following at each rev |
|
11 .ds vE rev 1.66, 04 July 2007 |
|
12 \." ============================================== |
|
13 \." ============================================== |
|
14 .ds | | |
|
15 .ds ~ ~ |
|
16 .ds ' ' |
|
17 .if t .ds Cw \&\f(CW |
|
18 .if n .ds Cw \fB |
|
19 .de Cf \" Place every other arg in Cw font, beginning with first |
|
20 .if \\n(.$=1 \&\*(Cw\\$1\fP |
|
21 .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2 |
|
22 .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP |
|
23 .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4 |
|
24 .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP |
|
25 .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6 |
|
26 .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP |
|
27 .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8 |
|
28 .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\ |
|
29 *(Cw |
|
30 .. |
|
31 .nr Cl 4 |
|
32 .SA 1 |
|
33 .TL |
|
34 A Consumer Library Interface to DWARF |
|
35 .AF "" |
|
36 .AU "David Anderson" |
|
37 .PF "'\*(vE'- \\\\nP -''" |
|
38 .AS 1 |
|
39 This document describes an interface to a library of functions |
|
40 .FS |
|
41 UNIX is a registered trademark of UNIX System Laboratories, Inc. |
|
42 in the United States and other countries. |
|
43 .FE |
|
44 to access DWARF debugging information entries and DWARF line number |
|
45 information (and other DWARF2/3 information). |
|
46 It does not make recommendations as to how the functions |
|
47 described in this document should be implemented nor does it |
|
48 suggest possible optimizations. |
|
49 .P |
|
50 The document is oriented to reading DWARF version 2 |
|
51 and version 3. |
|
52 There are certain sections which are SGI-specific (those |
|
53 are clearly identified in the document). |
|
54 .P |
|
55 \*(vE |
|
56 |
|
57 .AE |
|
58 .MT 4 |
|
59 |
|
60 .H 1 "INTRODUCTION" |
|
61 This document describes an interface to \fIlibdwarf\fP, a |
|
62 library of functions to provide access to DWARF debugging information |
|
63 records, DWARF line number information, DWARF address range and global |
|
64 names information, weak names information, DWARF frame description |
|
65 information, DWARF static function names, DWARF static variables, and |
|
66 DWARF type information. |
|
67 .P |
|
68 The document has long mentioned the |
|
69 "Unix International Programming Languages Special Interest Group" |
|
70 (PLSIG), under whose auspices the |
|
71 DWARF committtee was formed around 1991. |
|
72 "Unix International" |
|
73 was disbanded in the 1990's and no longer exists. |
|
74 .P |
|
75 The DWARF committee published DWARF2 July 27, 1993. |
|
76 .P |
|
77 In the mid 1990's this document and the library it describes |
|
78 (which the committee never endorsed, having decided |
|
79 not to endorse or approve any particular library interface) |
|
80 was made available on the internet by Silcon Graphics, Inc. |
|
81 .P |
|
82 In 2005 the DWARF committee began an affiliation with FreeStandards.org. |
|
83 In 2007 FreeStandards.org merged with The Linux Foundation. |
|
84 The DWARF committee dropped its affiliation with FreeStandards.org |
|
85 in 2007 and established the dwarfstd.org website. |
|
86 See "http://www.dwarfstd.org" for current |
|
87 information on standardization activities |
|
88 and a copy of the standard. |
|
89 .H 2 "Copyright" |
|
90 Copyright 1993-2006 Silicon Graphics, Inc. |
|
91 |
|
92 Copyright 2007 David Anderson. |
|
93 |
|
94 Permission is hereby granted to |
|
95 copy or republish or use any or all of this document without |
|
96 restriction except that when publishing more than a small amount |
|
97 of the document |
|
98 please acknowledge Silicon Graphics, Inc and David Anderson. |
|
99 |
|
100 This document is distributed in the hope that it would be useful, but |
|
101 WITHOUT ANY WARRANTY; without even the implied warranty of |
|
102 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
|
103 .P |
|
104 |
|
105 .H 2 "Purpose and Scope" |
|
106 The purpose of this document is to document a library of functions |
|
107 to access DWARF debugging information. There is no effort made in |
|
108 this document to address the creation of these records as those |
|
109 issues are addressed separately |
|
110 (see "A Producer Library Interface to DWARF"). |
|
111 |
|
112 .P |
|
113 Additionally, the focus of this document is the functional interface, |
|
114 and as such, implementation as well as optimization issues are |
|
115 intentionally ignored. |
|
116 |
|
117 |
|
118 .H 2 "Document History" |
|
119 .P |
|
120 A document was written about 1991 which had similar |
|
121 layout and interfaces. |
|
122 Written by people from Hal Corporation, |
|
123 That document described a library for reading DWARF1. |
|
124 The authors distributed paper copies to the committee |
|
125 with the clearly expressed intent to propose the document as |
|
126 a supported interface definition. |
|
127 The committee decided not to pursue a library definition. |
|
128 .P |
|
129 SGI wrote the document you are now reading in 1993 |
|
130 with a similar layout and content and organization, but |
|
131 it was complete document rewrite with the intent to read DWARF2 |
|
132 (the DWARF version then in existence). |
|
133 The intent was (and is) to also cover |
|
134 future revisions of DWARF. |
|
135 All the function interfaces were changed |
|
136 in 1994 to uniformly |
|
137 return a simple integer success-code (see DW_DLV_OK etc), |
|
138 generally following |
|
139 the recomendations in the chapter titled "Candy Machine Interfaces" |
|
140 of "Writing Solid Code", a book by |
|
141 Steve Maguire (published by Microsoft Press). |
|
142 .H 2 "Definitions" |
|
143 DWARF debugging information entries (DIEs) are the segments of information |
|
144 placed in the \f(CW.debug_*\fP sections by compilers, assemblers, and |
|
145 linkage editors that, in conjunction with line number entries, are |
|
146 necessary for symbolic source-level debugging. |
|
147 Refer to the latest |
|
148 "\fIDWARF Debugging Information Format\fP" from www.dwarfstd.org for a more |
|
149 complete description of these entries. |
|
150 |
|
151 .P |
|
152 This document adopts all the terms and definitions in "\fIDWARF Debugging |
|
153 Information Format\fP" versions 2 and 3. |
|
154 It originally focused on the implementation at |
|
155 Silicon Graphics, Inc., but now |
|
156 attempts to be more generally useful. |
|
157 |
|
158 .H 2 "Overview" |
|
159 The remaining sections of this document describe the proposed interface |
|
160 to \f(CWlibdwarf\fP, first by describing the purpose of additional types |
|
161 defined by the interface, followed by descriptions of the available |
|
162 operations. This document assumes you are thoroughly familiar with the |
|
163 information contained in the \fIDWARF Debugging Information Format\fP |
|
164 document. |
|
165 .P |
|
166 We separate the functions into several categories to emphasize that not |
|
167 all consumers want to use all the functions. We call the categories |
|
168 Debugger, Internal-level, High-level, and Miscellaneous not because one is more |
|
169 important than another but as a way of making the rather large set of |
|
170 function calls easier to understand. |
|
171 .P |
|
172 Unless otherwise specified, all functions and structures should be |
|
173 taken as being designed for Debugger consumers. |
|
174 .P |
|
175 The Debugger Interface of this library is intended to be used by debuggers. |
|
176 The interface is low-level (close to dwarf) but suppresses irrelevant detail. |
|
177 A debugger will want to absorb all of some sections at startup and will |
|
178 want to see little or nothing of some sections except at need. And even |
|
179 then will probably want to absorb only the information in a single compilation |
|
180 unit at a time. A debugger does not care about |
|
181 implementation details of the library. |
|
182 .P |
|
183 The Internal-level Interface is for a DWARF prettyprinter and checker. |
|
184 A |
|
185 thorough prettyprinter will want to know all kinds of internal things |
|
186 (like actual FORM numbers and actual offsets) so it can check for |
|
187 appropriate structure in the DWARF data and print (on request) all |
|
188 that internal information for human users and libdwarf authors and |
|
189 compiler-writers. |
|
190 Calls in this interface provide data a debugger |
|
191 does not care about. |
|
192 .P |
|
193 The High-level Interface is for higher level access |
|
194 (it's not really a high level interface!). |
|
195 Programs such as |
|
196 disassemblers will want to be able to display relevant information |
|
197 about functions and line numbers without having to invest too much |
|
198 effort in looking at DWARF. |
|
199 .P |
|
200 The miscellaneous interface is just what is left over: the error handler |
|
201 functions. |
|
202 .P |
|
203 The following is a brief mention of the changes in this libdwarf from |
|
204 the libdwarf draft for DWARF Version 1 and recent changes. |
|
205 .H 2 "Items Changed" |
|
206 .P |
|
207 Added support for various DWARF3 features, but primarily |
|
208 a new frame-information interface tailorable at run-time |
|
209 to more than a single ABI. |
|
210 See dwarf_set_frame_rule_inital_value() and dwarf_set_frame_rule_table_size(). |
|
211 See also dwarf_get_fde_info_for_reg3() and |
|
212 dwarf_get_fde_info_for_cfa_reg3(). (April 2006) |
|
213 .P |
|
214 Added support for DWARF3 .debug_pubtypes section. |
|
215 Corrected various leaks (revising dealloc() calls, adding |
|
216 new functions) and corrected dwarf_formstring() documentation. |
|
217 .P |
|
218 Added dwarf_srclines_dealloc() as the previous deallocation |
|
219 method documented for data returned by |
|
220 dwarf_srclines() was incapable of freeing |
|
221 all the allocated storage (14 July 2005). |
|
222 .P |
|
223 dwarf_nextglob(), dwarf_globname(), and dwarf_globdie() were all changed |
|
224 to operate on the items in the .debug_pubnames section. |
|
225 .P |
|
226 All functions were modified to return solely an error code. |
|
227 Data is returned through pointer arguments. |
|
228 This makes writing safe and correct library-using-code far easier. |
|
229 For justification for this approach, see the book by |
|
230 Steve Maguire titled "Writing Solid Code" at your bookstore. |
|
231 |
|
232 |
|
233 .H 2 "Items Removed" |
|
234 .P |
|
235 Dwarf_Type |
|
236 was removed since types are no longer special. |
|
237 .P |
|
238 dwarf_typeof() |
|
239 was removed since types are no longer special. |
|
240 .P |
|
241 Dwarf_Ellist |
|
242 was removed since element lists no longer are a special format. |
|
243 .P |
|
244 Dwarf_Bounds |
|
245 was removed since bounds have been generalized. |
|
246 .P |
|
247 dwarf_nextdie() |
|
248 was replaced by dwarf_next_cu_header() to reflect the |
|
249 real way DWARF is organized. |
|
250 The dwarf_nextdie() was only useful for getting to compilation |
|
251 unit beginnings, so it does not seem harmful to remove it in favor |
|
252 of a more direct function. |
|
253 .P |
|
254 dwarf_childcnt() is removed on grounds |
|
255 that no good use was apparent. |
|
256 .P |
|
257 dwarf_prevline() and dwarf_nextline() were removed on grounds this |
|
258 is better left to a debugger to do. |
|
259 Similarly, dwarf_dieline() was removed. |
|
260 .P |
|
261 dwarf_is1stline() was removed as it was not meaningful for the |
|
262 revised DWARF line operations. |
|
263 .P |
|
264 Any libdwarf implementation might well decide to support all the |
|
265 removed functionality and to retain the DWARF Version 1 meanings |
|
266 of that functionality. |
|
267 This would be difficult because the |
|
268 original libdwarf draft |
|
269 specification used traditional C library interfaces which |
|
270 confuse the values returned by successful calls with |
|
271 exceptional conditions like failures and 'no more data' indications. |
|
272 |
|
273 .H 2 "Revision History" |
|
274 .VL 15 |
|
275 .LI "March 93" |
|
276 Work on DWARF2 SGI draft begins |
|
277 .LI "June 94" |
|
278 The function returns are changed to return an error/success code |
|
279 only. |
|
280 .LI "April 2006: |
|
281 Support for DWARF3 consumer operations is close to completion. |
|
282 .LE |
|
283 |
|
284 .H 1 "Types Definitions" |
|
285 |
|
286 .H 2 "General Description" |
|
287 The \fIlibdwarf.h\fP header file contains typedefs and preprocessor |
|
288 definitions of types and symbolic names used to reference objects |
|
289 of \fIlibdwarf\fP. The types defined by typedefs contained in |
|
290 \fIlibdwarf.h\fP all use the convention of adding \f(CWDwarf_\fP |
|
291 as a prefix and can be placed in three categories: |
|
292 |
|
293 .BL |
|
294 .LI |
|
295 Scalar types : The scalar types defined in \fIlibdwarf.h\fP are |
|
296 defined primarily for notational convenience and identification. |
|
297 Depending on the individual definition, they are interpreted as a |
|
298 value, a pointer, or as a flag. |
|
299 .LI |
|
300 Aggregate types : Some values can not be represented by a single |
|
301 scalar type; they must be represented by a collection of, or as a |
|
302 union of, scalar and/or aggregate types. |
|
303 .LI |
|
304 Opaque types : The complete definition of these types is intentionally |
|
305 omitted; their use is as handles for query operations, which will yield |
|
306 either an instance of another opaque type to be used in another query, or |
|
307 an instance of a scalar or aggregate type, which is the actual result. |
|
308 .P |
|
309 |
|
310 .H 2 "Scalar Types" |
|
311 The following are the defined by \fIlibdwarf.h\fP: |
|
312 |
|
313 .DS |
|
314 \f(CW |
|
315 typedef int Dwarf_Bool; |
|
316 typedef unsigned long long Dwarf_Off; |
|
317 typedef unsigned long long Dwarf_Unsigned; |
|
318 typedef unsigned short Dwarf_Half; |
|
319 typedef unsigned char Dwarf_Small; |
|
320 typedef signed long long Dwarf_Signed; |
|
321 typedef unsigned long long Dwarf_Addr; |
|
322 typedef void *Dwarf_Ptr; |
|
323 typedef void (*Dwarf_Handler)(Dwarf_Error *error, Dwarf_Ptr errarg); |
|
324 .DE |
|
325 |
|
326 .nr aX \n(Fg+1 |
|
327 Dwarf_Ptr is an address for use by the host program calling the library, |
|
328 not for representing pc-values/addresses within the target object file. |
|
329 Dwarf_Addr is for pc-values within the target object file. The sample |
|
330 scalar type assignments above are for a \fIlibdwarf.h\fP that can read |
|
331 and write |
|
332 32-bit or 64-bit binaries on a 32-bit or 64-bit host machine. |
|
333 The types must be defined appropriately |
|
334 for each implementation of libdwarf. |
|
335 A description of these scalar types in the SGI/MIPS |
|
336 environment is given in Figure \n(aX. |
|
337 |
|
338 .DS |
|
339 .TS |
|
340 center box, tab(:); |
|
341 lfB lfB lfB lfB |
|
342 l c c l. |
|
343 NAME:SIZE:ALIGNMENT:PURPOSE |
|
344 _ |
|
345 Dwarf_Bool:4:4:Boolean states |
|
346 Dwarf_Off:8:8:Unsigned file offset |
|
347 Dwarf_Unsigned:8:8:Unsigned large integer |
|
348 Dwarf_Half:2:2:Unsigned medium integer |
|
349 Dwarf_Small:1:1:Unsigned small integer |
|
350 Dwarf_Signed:8:8:Signed large integer |
|
351 Dwarf_Addr:8:8:Program address |
|
352 :::(target program) |
|
353 Dwarf_Ptr:4|8:4|8:Dwarf section pointer |
|
354 :::(host program) |
|
355 Dwarf_Handler:4|8:4|8:Pointer to |
|
356 :::error handler function |
|
357 .TE |
|
358 .FG "Scalar Types" |
|
359 .DE |
|
360 |
|
361 .H 2 "Aggregate Types" |
|
362 The following aggregate types are defined by |
|
363 \fIlibdwarf.h\fP: |
|
364 \f(CWDwarf_Loc\fP, |
|
365 \f(CWDwarf_Locdesc\fP, |
|
366 \f(CWDwarf_Block\fP, |
|
367 \f(CWDwarf_Frame_Op\fP. |
|
368 \f(CWDwarf_Regtable\fP. |
|
369 \f(CWDwarf_Regtable3\fP. |
|
370 While most of \f(CWlibdwarf\fP acts on or returns simple values or |
|
371 opaque pointer types, this small set of structures seems useful. |
|
372 |
|
373 .H 3 "Location Record" |
|
374 The \f(CWDwarf_Loc\fP type identifies a single atom of a location description |
|
375 or a location expression. |
|
376 |
|
377 .DS |
|
378 \f(CWtypedef struct { |
|
379 Dwarf_Small lr_atom; |
|
380 Dwarf_Unsigned lr_number; |
|
381 Dwarf_Unsigned lr_number2; |
|
382 Dwarf_Unsigned lr_offset; |
|
383 } Dwarf_Loc;\fP |
|
384 .DE |
|
385 |
|
386 The \f(CWlr_atom\fP identifies the atom corresponding to the \f(CWDW_OP_*\fP |
|
387 definition in \fIdwarf.h\fP and it represents the operation to be performed |
|
388 in order to locate the item in question. |
|
389 |
|
390 .P |
|
391 The \f(CWlr_number\fP field is the operand to be used in the calculation |
|
392 specified by the \f(CWlr_atom\fP field; not all atoms use this field. |
|
393 Some atom operations imply signed numbers so it is necessary to cast |
|
394 this to a \f(CWDwarf_Signed\fP type for those operations. |
|
395 |
|
396 .P |
|
397 The \f(CWlr_number2\fP field is the second operand specified by the |
|
398 \f(CWlr_atom\fP field; only \f(CWDW_OP_BREGX\fP has this field. Some |
|
399 atom operations imply signed numbers so it may be necessary to cast |
|
400 this to a \f(CWDwarf_Signed\fP type for those operations. |
|
401 |
|
402 .P |
|
403 The \f(CWlr_offset\fP field is the byte offset (within the block the |
|
404 location record came from) of the atom specified by the \f(CWlr_atom\fP |
|
405 field. This is set on all atoms. This is useful for operations |
|
406 \f(CWDW_OP_SKIP\fP and \f(CWDW_OP_BRA\fP. |
|
407 |
|
408 .H 3 "Location Description" |
|
409 The \f(CWDwarf_Locdesc\fP type represents an ordered list of |
|
410 \f(CWDwarf_Loc\fP records used in the calculation to locate |
|
411 an item. Note that in many cases, the location can only be |
|
412 calculated at runtime of the associated program. |
|
413 |
|
414 .DS |
|
415 \f(CWtypedef struct { |
|
416 Dwarf_Addr ld_lopc; |
|
417 Dwarf_Addr ld_hipc; |
|
418 Dwarf_Unsigned ld_cents; |
|
419 Dwarf_Loc* ld_s; |
|
420 } Dwarf_Locdesc;\fP |
|
421 .DE |
|
422 |
|
423 The \f(CWld_lopc\fP and \f(CWld_hipc\fP fields provide an address range for |
|
424 which this location descriptor is valid. Both of these fields are set to |
|
425 \fIzero\fP if the location descriptor is valid throughout the scope of the |
|
426 item it is associated with. These addresses are virtual memory addresses, |
|
427 not offsets-from-something. The virtual memory addresses do not account |
|
428 for dso movement (none of the pc values from libdwarf do that, it is up to |
|
429 the consumer to do that). |
|
430 |
|
431 .P |
|
432 The \f(CWld_cents\fP field contains a count of the number of \f(CWDwarf_Loc\fP |
|
433 entries pointed to by the \f(CWld_s\fP field. |
|
434 |
|
435 .P |
|
436 The \f(CWld_s\fP field points to an array of \f(CWDwarf_Loc\fP records. |
|
437 |
|
438 .H 3 "Data Block" |
|
439 .SP |
|
440 The \f(CWDwarf_Block\fP type is used to contain the value of an attribute |
|
441 whose form is either \f(CWDW_FORM_block1\fP, \f(CWDW_FORM_block2\fP, |
|
442 \f(CWDW_FORM_block4\fP, \f(CWDW_FORM_block8\fP, or \f(CWDW_FORM_block\fP. |
|
443 Its intended use is to deliver the value for an attribute of any of these |
|
444 forms. |
|
445 |
|
446 .DS |
|
447 \f(CWtypedef struct { |
|
448 Dwarf_Unsigned bl_len; |
|
449 Dwarf_Ptr bl_data; |
|
450 } Dwarf_Block;\fP |
|
451 .DE |
|
452 |
|
453 .P |
|
454 The \f(CWbl_len\fP field contains the length in bytes of the data pointed |
|
455 to by the \f(CWbl_data\fP field. |
|
456 |
|
457 .P |
|
458 The \f(CWbl_data\fP field contains a pointer to the uninterpreted data. |
|
459 Since we use a \f(CWDwarf_Ptr\fP here one must copy the pointer to some |
|
460 other type (typically an \f(CWunsigned char *\fP) so one can add increments |
|
461 to index through the data. The data pointed to by \f(CWbl_data\fP is not |
|
462 necessarily at any useful alignment. |
|
463 |
|
464 .H 3 "Frame Operation Codes: DWARF 2" |
|
465 This interface is adequate for DWARF2 but not for DWARF3. |
|
466 A separate interface usable for DWARF3 and for DWARF2 is described below. |
|
467 .P |
|
468 The DWARF2 \f(CWDwarf_Frame_Op\fP type is used to contain the data of a single |
|
469 instruction of an instruction-sequence of low-level information from the |
|
470 section containing frame information. This is ordinarily used by |
|
471 Internal-level Consumers trying to print everything in detail. |
|
472 |
|
473 .DS |
|
474 \f(CWtypedef struct { |
|
475 Dwarf_Small fp_base_op; |
|
476 Dwarf_Small fp_extended_op; |
|
477 Dwarf_Half fp_register; |
|
478 Dwarf_Signed fp_offset; |
|
479 Dwarf_Offset fp_instr_offset; |
|
480 } Dwarf_Frame_Op; |
|
481 .DE |
|
482 |
|
483 \f(CWfp_base_op\fP is the 2-bit basic op code. \f(CWfp_extended_op\fP is |
|
484 the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an |
|
485 extended op code) and is zero otherwise. |
|
486 .P |
|
487 \f(CWfp_register\fP |
|
488 is any (or the first) register value as defined |
|
489 in the \f(CWCall Frame Instruction Encodings\fP figure |
|
490 in the \f(CWdwarf\fP document. |
|
491 If not used with the Op it is 0. |
|
492 .P |
|
493 \f(CWfp_offset\fP |
|
494 is the address, delta, offset, or second register as defined |
|
495 in the \f(CWCall Frame Instruction Encodings\fP figure |
|
496 in the \f(CWdwarf\fP document. |
|
497 If this is an \f(CWaddress\fP then the value should be cast to |
|
498 \f(CW(Dwarf_Addr)\fP before being used. |
|
499 In any implementation this field *must* be as large as the |
|
500 larger of Dwarf_Signed and Dwarf_Addr for this to work properly. |
|
501 If not used with the op it is 0. |
|
502 .P |
|
503 \f(CWfp_instr_offset\fP is the byte_offset (within the instruction |
|
504 stream of the frame instructions) of this operation. It starts at 0 |
|
505 for a given frame descriptor. |
|
506 |
|
507 .H 3 "Frame Regtable: DWARF 2" |
|
508 This interface is adequate for DWARF2 but not for DWARF3. |
|
509 A separate interface usable for DWARF3 and for DWARF2 is described below. |
|
510 .P |
|
511 The \f(CWDwarf_Regtable\fP type is used to contain the |
|
512 register-restore information for all registers at a given |
|
513 PC value. |
|
514 Normally used by debuggers. |
|
515 .DS |
|
516 /* DW_REG_TABLE_SIZE must reflect the number of registers |
|
517 *(DW_FRAME_LAST_REG_NUM) as defined in dwarf.h |
|
518 */ |
|
519 #define DW_REG_TABLE_SIZE <fill in size here, 66 for MIPS/IRIX> |
|
520 \f(CWtypedef struct { |
|
521 struct { |
|
522 Dwarf_Small dw_offset_relevant; |
|
523 Dwarf_Half dw_regnum; |
|
524 Dwarf_Addr dw_offset; |
|
525 } rules[DW_REG_TABLE_SIZE]; |
|
526 } Dwarf_Regtable;\fP |
|
527 .DE |
|
528 .P |
|
529 The array is indexed by register number. |
|
530 The field values for each index are described next. |
|
531 For clarity we describe the field values for index rules[M] |
|
532 (M being any legal array element index). |
|
533 .P |
|
534 \f(CWdw_offset_relevant\fP is non-zero to indicate the \f(CWdw_offset\fP |
|
535 field is meaningful. If zero then the \f(CWdw_offset\fP is zero |
|
536 and should be ignored. |
|
537 .P |
|
538 \f(CWdw_regnum \fPis the register number\fP applicable. |
|
539 If \f(CWdw_offset_relevant\fP is zero, then this is the register |
|
540 number of the register containing the value for register M. |
|
541 If \f(CWdw_offset_relevant\fP is non-zero, then this is |
|
542 the register number of the register to use as a base (M may be |
|
543 DW_FRAME_CFA_COL, for example) and the \f(CWdw_offset\fP |
|
544 value applies. The value of register M is therefore |
|
545 the value of register \f(CWdw_regnum\vP . |
|
546 .P |
|
547 \f(CWdw_offset\fP should be ignored if \f(CWdw_offset_relevant\fP is zero. |
|
548 If \f(CWdw_offset_relevant\fP is non-zero, then |
|
549 the consumer code should add the value to |
|
550 the value of the register \f(CWdw_regnum\fP to produce the |
|
551 value. |
|
552 |
|
553 .H 3 "Frame Operation Codes: DWARF 3 (and DWARF2)" |
|
554 This interface is adequate for DWARF3 and for DWARF2. |
|
555 It is new in libdwarf in April 2006. |
|
556 .P |
|
557 The DWARF2 \f(CWDwarf_Frame_Op3\fP type is used to contain the data of a single |
|
558 instruction of an instruction-sequence of low-level information from the |
|
559 section containing frame information. This is ordinarily used by |
|
560 Internal-level Consumers trying to print everything in detail. |
|
561 |
|
562 .DS |
|
563 \f(CWtypedef struct { |
|
564 Dwarf_Small fp_base_op; |
|
565 Dwarf_Small fp_extended_op; |
|
566 Dwarf_Half fp_register; |
|
567 |
|
568 /* Value may be signed, depends on op. |
|
569 Any applicable data_alignment_factor has |
|
570 not been applied, this is the raw offset. */ |
|
571 Dwarf_Unsigned fp_offset_or_block_len; |
|
572 Dwarf_Small *fp_expr_block; |
|
573 |
|
574 Dwarf_Off fp_instr_offset; |
|
575 } Dwarf_Frame_Op3;\fP |
|
576 .DE |
|
577 |
|
578 \f(CWfp_base_op\fP is the 2-bit basic op code. \f(CWfp_extended_op\fP is |
|
579 the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an |
|
580 extended op code) and is zero otherwise. |
|
581 .P |
|
582 \f(CWfp_register\fP |
|
583 is any (or the first) register value as defined |
|
584 in the \f(CWCall Frame Instruction Encodings\fP figure |
|
585 in the \f(CWdwarf\fP document. |
|
586 If not used with the Op it is 0. |
|
587 .P |
|
588 \f(CWfp_offset_or_block_len\fP |
|
589 is the address, delta, offset, or second register as defined |
|
590 in the \f(CWCall Frame Instruction Encodings\fP figure |
|
591 in the \f(CWdwarf\fP document. Or (depending on the op, it |
|
592 may be the length of the dwarf-expression block pointed to |
|
593 by \f(CWfp_expr_block\fP. |
|
594 If this is an \f(CWaddress\fP then the value should be cast to |
|
595 \f(CW(Dwarf_Addr)\fP before being used. |
|
596 In any implementation this field *must* be as large as the |
|
597 larger of Dwarf_Signed and Dwarf_Addr for this to work properly. |
|
598 If not used with the op it is 0. |
|
599 .P |
|
600 \f(CWfp_expr_block\fP (if applicable to the op) |
|
601 points to a dwarf-expression block whch is \f(CWfp_offset_or_block_len\fP |
|
602 bytes long. |
|
603 .P |
|
604 \f(CWfp_instr_offset\fP is the byte_offset (within the instruction |
|
605 stream of the frame instructions) of this operation. It starts at 0 |
|
606 for a given frame descriptor. |
|
607 |
|
608 .H 3 "Frame Regtable: DWARF 3" |
|
609 This interface is adequate for DWARF3 and for DWARF2. |
|
610 It is new in libdwarf as of April 2006. |
|
611 .P |
|
612 The \f(CWDwarf_Regtable3\fP type is used to contain the |
|
613 register-restore information for all registers at a given |
|
614 PC value. |
|
615 Normally used by debuggers. |
|
616 .DS |
|
617 \f(CWtypedef struct Dwarf_Regtable_Entry3_s { |
|
618 Dwarf_Small dw_offset_relevant; |
|
619 Dwarf_Small dw_value_type; |
|
620 Dwarf_Half dw_regnum; |
|
621 Dwarf_Unsigned dw_offset_or_block_len; |
|
622 Dwarf_Ptr dw_block_ptr; |
|
623 }Dwarf_Regtable_Entry3; |
|
624 |
|
625 typedef struct Dwarf_Regtable3_s { |
|
626 struct Dwarf_Regtable_Entry3_s rt3_cfa_rule; |
|
627 |
|
628 Dwarf_Half rt3_reg_table_size; |
|
629 struct Dwarf_Regtable_Entry3_s * rt3_rules; |
|
630 } Dwarf_Regtable3;\fP |
|
631 |
|
632 .DE |
|
633 .P |
|
634 The array is indexed by register number. |
|
635 The field values for each index are described next. |
|
636 For clarity we describe the field values for index rules[M] |
|
637 (M being any legal array element index). |
|
638 (DW_FRAME_CFA_COL3 DW_FRAME_SAME_VAL, DW_FRAME_UNDEFINED_VAL |
|
639 are not legal array indexes, nor is any index < 0 or > |
|
640 rt3_reg_table_size); |
|
641 The caller of routines using this |
|
642 struct must create data space for rt3_reg_table_size entries |
|
643 of struct Dwarf_Regtable_Entry3_s and arrange that |
|
644 rt3_rules points to that space and that rt3_reg_table_size |
|
645 is set correctly. The caller need not (but may) |
|
646 initialize the contents of the rt3_cfa_rule or the rt3_rules array. |
|
647 The following applies to each rt3_rules rule M: |
|
648 .P |
|
649 .in +4 |
|
650 \f(CWdw_regnum\fP is the register number applicable. |
|
651 If \f(CWdw_regnum\fP is DW_FRAME_UNDEFINED_VAL, then the |
|
652 register I has undefined value. |
|
653 If \f(CWdw_regnum\fP is DW_FRAME_SAME_VAL, then the |
|
654 register I has the same value as in the previous frame. |
|
655 .P |
|
656 If \f(CWdw_regnum\fP is neither of these two, then the following apply: |
|
657 .P |
|
658 .P |
|
659 \f(CWdw_value_type\fP determines the meaning of the other fields. |
|
660 It is one of DW_EXPR_OFFSET (0), |
|
661 DW_EXPR_VAL_OFFSET(1), DW_EXPR_EXPRESSION(2) or |
|
662 DW_EXPR_VAL_EXPRESSION(3). |
|
663 |
|
664 .P |
|
665 If \f(CWdw_value_type\fP is DW_EXPR_OFFSET (0) then |
|
666 this is as in DWARF2 and the offset(N) rule or the register(R) |
|
667 rule |
|
668 of the DWARF3 and DWARF2 document applies. |
|
669 The value is either: |
|
670 .in +4 |
|
671 If \f(CWdw_offset_relevant\fP is non-zero, then \f(CWdw_regnum\fP |
|
672 is effectively ignored but must be identical to |
|
673 DW_FRAME_CFA_COL3 and the \f(CWdw_offset\fP value applies. |
|
674 The value of register M is therefore |
|
675 the value of CFA plus the value |
|
676 of \f(CWdw_offset\fP. The result of the calculation |
|
677 is the address in memory where the value of register M resides. |
|
678 This is the offset(N) rule of the DWARF2 and DWARF3 documents. |
|
679 .P |
|
680 \f(CWdw_offset_relevant\fP is zero it indicates the \f(CWdw_offset\fP |
|
681 field is not meaningful. |
|
682 The value of register M is |
|
683 the value currently in register \f(CWdw_regnum\fP (the |
|
684 value DW_FRAME_CFA_COL3 must not appear, only real registers). |
|
685 This is the register(R) rule of the DWARF3 spec. |
|
686 .in -4 |
|
687 |
|
688 .P |
|
689 If \f(CWdw_value_type\fP is DW_EXPR_OFFSET (1) then |
|
690 this is the the val_offset(N) rule of the DWARF3 spec applies. |
|
691 The calculation is identical to that of DW_EXPR_OFFSET (0) |
|
692 but the value is interpreted as the value of register M |
|
693 (rather than the address where register M's value is stored). |
|
694 .P |
|
695 If \f(CWdw_value_type\fP is DW_EXPR_EXPRESSION (2) then |
|
696 this is the the expression(E) rule of the DWARF3 document. |
|
697 .P |
|
698 .in +4 |
|
699 \f(CWdw_offset_or_block_len\fP is the length in bytes of |
|
700 the in-memory block pointed at by \f(CWdw_block_ptr\fP. |
|
701 \f(CWdw_block_ptr\fP is a DWARF expression. |
|
702 Evaluate that expression and the result is the address |
|
703 where the previous value of register M is found. |
|
704 .in -4 |
|
705 .P |
|
706 If \f(CWdw_value_type\fP is DW_EXPR_VAL_EXPRESSION (3) then |
|
707 this is the the val_expression(E) rule of the DWARF3 spec. |
|
708 .P |
|
709 .in +4 |
|
710 \f(CWdw_offset_or_block_len\fP is the length in bytes of |
|
711 the in-memory block pointed at by \f(CWdw_block_ptr\fP. |
|
712 \f(CWdw_block_ptr\fP is a DWARF expression. |
|
713 Evaluate that expression and the result is the |
|
714 previous value of register M. |
|
715 .in -4 |
|
716 .P |
|
717 The rule \f(CWrt3_cfa_rule\fP is the current value of |
|
718 the CFA. It is interpreted exactly like |
|
719 any register M rule (as described just above) except that |
|
720 \f(CWdw_regnum\fP cannot be CW_FRAME_CFA_REG3 or |
|
721 DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL but must |
|
722 be a real register number. |
|
723 .in -4 |
|
724 |
|
725 |
|
726 |
|
727 .H 3 "Macro Details Record" |
|
728 The \f(CWDwarf_Macro_Details\fP type gives information about |
|
729 a single entry in the .debug.macinfo section. |
|
730 .DS |
|
731 \f(CWstruct Dwarf_Macro_Details_s { |
|
732 Dwarf_Off dmd_offset; |
|
733 Dwarf_Small dmd_type; |
|
734 Dwarf_Signed dmd_lineno; |
|
735 Dwarf_Signed dmd_fileindex; |
|
736 char * dmd_macro; |
|
737 }; |
|
738 typedef struct Dwarf_Macro_Details_s Dwarf_Macro_Details; |
|
739 .DE |
|
740 .P |
|
741 \f(CWdmd_offset\fP is the byte offset, within the .debug_macinfo |
|
742 section, of this macro information. |
|
743 .P |
|
744 \f(CWdmd_type\fP is the type code of this macro info entry |
|
745 (or 0, the type code indicating that this is the end of |
|
746 macro information entries for a compilation unit. |
|
747 See \f(CWDW_MACINFO_define\fP, etc in the DWARF document. |
|
748 .P |
|
749 \f(CWdmd_lineno\fP is the line number where this entry was found, |
|
750 or 0 if there is no applicable line number. |
|
751 .P |
|
752 \f(CWdmd_fileindex\fP is the file index of the file involved. |
|
753 This is only guaranteed meaningful on a \f(CWDW_MACINFO_start_file\fP |
|
754 \f(CWdmd_type\fP. Set to -1 if unknown (see the functional |
|
755 interface for more details). |
|
756 .P |
|
757 \f(CWdmd_macro\fP is the applicable string. |
|
758 For a \f(CWDW_MACINFO_define\fP |
|
759 this is the macro name and value. |
|
760 For a |
|
761 \f(CWDW_MACINFO_undef\fP, or |
|
762 this is the macro name. |
|
763 For a |
|
764 \f(CWDW_MACINFO_vendor_ext\fP |
|
765 this is the vendor-defined string value. |
|
766 For other \f(CWdmd_type\fPs this is 0. |
|
767 |
|
768 .H 2 "Opaque Types" |
|
769 The opaque types declared in \fIlibdwarf.h\fP are used as descriptors |
|
770 for queries against DWARF information stored in various debugging |
|
771 sections. Each time an instance of an opaque type is returned as a |
|
772 result of a \fIlibdwarf\fP operation (\f(CWDwarf_Debug\fP excepted), |
|
773 it should be free'd, using \f(CWdwarf_dealloc()\fP when it is no longer |
|
774 of use (read the following documentation for details, as in at least |
|
775 one case there is a special routine provided for deallocation |
|
776 and \f(CWdwarf_dealloc()\fP is not directly called: |
|
777 see \f(CWdwarf_srclines()\fP). |
|
778 Some functions return a number of instances of an opaque type |
|
779 in a block, by means of a pointer to the block and a count of the number |
|
780 of opaque descriptors in the block: |
|
781 see the function description for deallocation rules for such functions. |
|
782 The list of opaque types defined |
|
783 in \fIlibdwarf.h\fP that are pertinent to the Consumer Library, and their |
|
784 intended use is described below. |
|
785 |
|
786 .DS |
|
787 \f(CWtypedef struct Dwarf_Debug_s* Dwarf_Debug;\fP |
|
788 .DE |
|
789 An instance of the \f(CWDwarf_Debug\fP type is created as a result of a |
|
790 successful call to \f(CWdwarf_init()\fP, or \f(CWdwarf_elf_init()\fP, |
|
791 and is used as a descriptor for subsequent access to most \f(CWlibdwarf\fP |
|
792 functions on that object. The storage pointed to by this descriptor |
|
793 should be not be free'd, using the \f(CWdwarf_dealloc()\fP function. |
|
794 Instead free it with \f(CWdwarf_finish()\fP. |
|
795 .P |
|
796 |
|
797 .DS |
|
798 \f(CWtypedef struct Dwarf_Die_s* Dwarf_Die;\fP |
|
799 .DE |
|
800 An instance of a \f(CWDwarf_Die\fP type is returned from a successful |
|
801 call to the \f(CWdwarf_siblingof()\fP, \f(CWdwarf_child\fP, or |
|
802 \f(CWdwarf_offdie()\fP function, and is used as a descriptor for queries |
|
803 about information related to that DIE. The storage pointed to by this |
|
804 descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the allocation |
|
805 type \f(CWDW_DLA_DIE\fP when no longer needed. |
|
806 |
|
807 .DS |
|
808 \f(CWtypedef struct Dwarf_Line_s* Dwarf_Line;\fP |
|
809 .DE |
|
810 Instances of \f(CWDwarf_Line\fP type are returned from a successful call |
|
811 to the \f(CWdwarf_srclines()\fP function, and are used as descriptors for |
|
812 queries about source lines. The storage pointed to by these descriptors |
|
813 should be individually free'd, using \f(CWdwarf_dealloc()\fP with the |
|
814 allocation type \f(CWDW_DLA_LINE\fP when no longer needed. |
|
815 |
|
816 .DS |
|
817 \f(CWtypedef struct Dwarf_Global_s* Dwarf_Global;\fP |
|
818 .DE |
|
819 Instances of \f(CWDwarf_Global\fP type are returned from a successful |
|
820 call to the \f(CWdwarf_get_globals()\fP function, and are used as |
|
821 descriptors for queries about global names (pubnames). |
|
822 |
|
823 .DS |
|
824 \f(CWtypedef struct Dwarf_Weak_s* Dwarf_Weak;\fP |
|
825 .DE |
|
826 Instances of \f(CWDwarf_Weak\fP type are returned from a successful call |
|
827 to the |
|
828 SGI-specific \f(CWdwarf_get_weaks()\fP |
|
829 function, and are used as descriptors for |
|
830 queries about weak names. The storage pointed to by these descriptors |
|
831 should be individually free'd, using \f(CWdwarf_dealloc()\fP with the |
|
832 allocation type |
|
833 \f(CWDW_DLA_WEAK_CONTEXT\fP |
|
834 (or |
|
835 \f(CWDW_DLA_WEAK\fP, an older name, supported for compatibility) |
|
836 when no longer needed. |
|
837 |
|
838 .DS |
|
839 \f(CWtypedef struct Dwarf_Func_s* Dwarf_Func;\fP |
|
840 .DE |
|
841 Instances of \f(CWDwarf_Func\fP type are returned from a successful |
|
842 call to the |
|
843 SGI-specific \f(CWdwarf_get_funcs()\fP |
|
844 function, and are used as |
|
845 descriptors for queries about static function names. |
|
846 |
|
847 .DS |
|
848 \f(CWtypedef struct Dwarf_Type_s* Dwarf_Type;\fP |
|
849 .DE |
|
850 Instances of \f(CWDwarf_Type\fP type are returned from a successful call |
|
851 to the |
|
852 SGI-specific \f(CWdwarf_get_types()\fP |
|
853 function, and are used as descriptors for |
|
854 queries about user defined types. |
|
855 |
|
856 .DS |
|
857 \f(CWtypedef struct Dwarf_Var_s* Dwarf_Var;\fP |
|
858 .DE |
|
859 Instances of \f(CWDwarf_Var\fP type are returned from a successful call |
|
860 to the SGI-specific \f(CWdwarf_get_vars()\fP |
|
861 function, and are used as descriptors for |
|
862 queries about static variables. |
|
863 |
|
864 .DS |
|
865 \f(CWtypedef struct Dwarf_Error_s* Dwarf_Error;\fP |
|
866 .DE |
|
867 This descriptor points to a structure that provides detailed information |
|
868 about errors detected by \f(CWlibdwarf\fP. Users typically provide a |
|
869 location for \f(CWlibdwarf\fP to store this descriptor for the user to |
|
870 obtain more information about the error. The storage pointed to by this |
|
871 descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the |
|
872 allocation type \f(CWDW_DLA_ERROR\fP when no longer needed. |
|
873 |
|
874 .DS |
|
875 \f(CWtypedef struct Dwarf_Attribute_s* Dwarf_Attribute;\fP |
|
876 .DE |
|
877 Instances of \f(CWDwarf_Attribute\fP type are returned from a successful |
|
878 call to the \f(CWdwarf_attrlist()\fP, or \f(CWdwarf_attr()\fP functions, |
|
879 and are used as descriptors for queries about attribute values. The storage |
|
880 pointed to by this descriptor should be individually free'd, using |
|
881 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ATTR\fP when |
|
882 no longer needed. |
|
883 |
|
884 .DS |
|
885 \f(CWtypedef struct Dwarf_Abbrev_s* Dwarf_Abbrev;\fP |
|
886 .DE |
|
887 An instance of a \f(CWDwarf_Abbrev\fP type is returned from a successful |
|
888 call to \f(CWdwarf_get_abbrev()\fP, and is used as a descriptor for queries |
|
889 about abbreviations in the .debug_abbrev section. The storage pointed to |
|
890 by this descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the |
|
891 allocation type \f(CWDW_DLA_ABBREV\fP when no longer needed. |
|
892 |
|
893 .DS |
|
894 \f(CWtypedef struct Dwarf_Fde_s* Dwarf_Fde;\fP |
|
895 .DE |
|
896 Instances of \f(CWDwarf_Fde\fP type are returned from a successful call |
|
897 to the \f(CWdwarf_get_fde_list()\fP, \f(CWdwarf_get_fde_for_die()\fP, or |
|
898 \f(CWdwarf_get_fde_at_pc()\fP functions, and are used as descriptors for |
|
899 queries about frames descriptors. |
|
900 |
|
901 .DS |
|
902 \f(CWtypedef struct Dwarf_Cie_s* Dwarf_Cie;\fP |
|
903 .DE |
|
904 Instances of \f(CWDwarf_Cie\fP type are returned from a successful call |
|
905 to the \f(CWdwarf_get_fde_list()\fP function, and are used as descriptors |
|
906 for queries about information that is common to several frames. |
|
907 |
|
908 .DS |
|
909 \f(CWtypedef struct Dwarf_Arange_s* Dwarf_Arange;\fP |
|
910 .DE |
|
911 Instances of \f(CWDwarf_Arange\fP type are returned from successful calls |
|
912 to the \f(CWdwarf_get_aranges()\fP, or \f(CWdwarf_get_arange()\fP functions, |
|
913 and are used as descriptors for queries about address ranges. The storage |
|
914 pointed to by this descriptor should be individually free'd, using |
|
915 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ARANGE\fP when |
|
916 no longer needed. |
|
917 |
|
918 .H 1 "Error Handling" |
|
919 The method for detection and disposition of error conditions that arise |
|
920 during access of debugging information via \fIlibdwarf\fP is consistent |
|
921 across all \fIlibdwarf\fP functions that are capable of producing an |
|
922 error. This section describes the method used by \fIlibdwarf\fP in |
|
923 notifying client programs of error conditions. |
|
924 |
|
925 .P |
|
926 Most functions within \fIlibdwarf\fP accept as an argument a pointer to |
|
927 a \f(CWDwarf_Error\fP descriptor where a \f(CWDwarf_Error\fP descriptor |
|
928 is stored if an error is detected by the function. Routines in the client |
|
929 program that provide this argument can query the \f(CWDwarf_Error\fP |
|
930 descriptor to determine the nature of the error and perform appropriate |
|
931 processing. |
|
932 |
|
933 .P |
|
934 A client program can also specify a function to be invoked upon detection |
|
935 of an error at the time the library is initialized (see \f(CWdwarf_init()\fP). |
|
936 When a \fIlibdwarf\fP routine detects an error, this function is called |
|
937 with two arguments: a code indicating the nature of the error and a pointer |
|
938 provided by the client at initialization (again see \f(CWdwarf_init()\fP). |
|
939 This pointer argument can be used to relay information between the error |
|
940 handler and other routines of the client program. A client program can |
|
941 specify or change both the error handling function and the pointer argument |
|
942 after initialization using \f(CWdwarf_seterrhand()\fP and |
|
943 \f(CWdwarf_seterrarg()\fP. |
|
944 |
|
945 .P |
|
946 In the case where \fIlibdwarf\fP functions are not provided a pointer |
|
947 to a \f(CWDwarf_Error\fP descriptor, and no error handling function was |
|
948 provided at initialization, \fIlibdwarf\fP functions terminate execution |
|
949 by calling \f(CWabort(3C)\fP. |
|
950 |
|
951 .P |
|
952 The following lists the processing steps taken upon detection of an |
|
953 error: |
|
954 .AL 1 |
|
955 .LI |
|
956 Check the \f(CWerror\fP argument; if not a \fINULL\fP pointer, allocate |
|
957 and initialize a \f(CWDwarf_Error\fP descriptor with information describing |
|
958 the error, place this descriptor in the area pointed to by \f(CWerror\fP, |
|
959 and return a value indicating an error condition. |
|
960 .LI |
|
961 If an \f(CWerrhand\fP argument was provided to \f(CWdwarf_init()\fP |
|
962 at initialization, call \f(CWerrhand()\fP passing it the error descriptor |
|
963 and the value of the \f(CWerrarg\fP argument provided to \f(CWdwarf_init()\fP. |
|
964 If the error handling function returns, return a value indicating an |
|
965 error condition. |
|
966 .LI |
|
967 Terminate program execution by calling \f(CWabort(3C)\fP. |
|
968 .LE |
|
969 .SP |
|
970 |
|
971 In all cases, it is clear from the value returned from a function |
|
972 that an error occurred in executing the function, since |
|
973 DW_DLV_ERROR is returned. |
|
974 .P |
|
975 As can be seen from the above steps, the client program can provide |
|
976 an error handler at initialization, and still provide an \f(CWerror\fP |
|
977 argument to \fIlibdwarf\fP functions when it is not desired to have |
|
978 the error handler invoked. |
|
979 |
|
980 .P |
|
981 If a \f(CWlibdwarf\fP function is called with invalid arguments, the |
|
982 behaviour is undefined. In particular, supplying a \f(CWNULL\fP pointer |
|
983 to a \f(CWlibdwarf\fP function (except where explicitly permitted), |
|
984 or pointers to invalid addresses or uninitialized data causes undefined |
|
985 behaviour; the return value in such cases is undefined, and the function |
|
986 may fail to invoke the caller supplied error handler or to return a |
|
987 meaningful error number. Implementations also may abort execution for |
|
988 such cases. |
|
989 |
|
990 .P |
|
991 .H 2 "Returned values in the functional interface" |
|
992 Values returned by \f(CWlibdwarf\fP functions to indicate |
|
993 success and errors |
|
994 .nr aX \n(Fg+1 |
|
995 are enumerated in Figure \n(aX. |
|
996 The \f(CWDW_DLV_NO_ENTRY\fP |
|
997 case is useful for functions |
|
998 need to indicate that while there was no data to return |
|
999 there was no error either. |
|
1000 For example, \f(CWdwarf_siblingof()\fP |
|
1001 may return \f(CWDW_DLV_NO_ENTRY\fP to indicate that that there was |
|
1002 no sibling to return. |
|
1003 .DS |
|
1004 .TS |
|
1005 center box, tab(:); |
|
1006 lfB cfB lfB |
|
1007 l c l. |
|
1008 SYMBOLIC NAME:VALUE:MEANING |
|
1009 _ |
|
1010 DW_DLV_ERROR:1:Error |
|
1011 DW_DLV_OK:0:Successful call |
|
1012 DW_DLV_NO_ENTRY:-1:No applicable value |
|
1013 .TE |
|
1014 .FG "Error Indications" |
|
1015 .DE |
|
1016 .P |
|
1017 Each function in the interface that returns a value returns one |
|
1018 of the integers in the above figure. |
|
1019 .P |
|
1020 If \f(CWDW_DLV_ERROR\fP is returned and a pointer to a \f(CWDwarf_Error\fP |
|
1021 pointer is passed to the function, then a Dwarf_Error handle is returned |
|
1022 thru the pointer. No other pointer value in the interface returns a value. |
|
1023 After the \f(CWDwarf_Error\fP is no longer of interest, |
|
1024 a \f(CWdwarf_dealloc(dbg,dw_err,DW_DLA_ERROR)\fP on the error |
|
1025 pointer is appropriate to free any space used by the error information. |
|
1026 .P |
|
1027 If \f(CWDW_DLV_NO_ENTRY\fP is returned no pointer value in the |
|
1028 interface returns a value. |
|
1029 .P |
|
1030 If \f(CWDW_DLV_OK\fP is returned the \f(CWDwarf_Error\fP pointer, if |
|
1031 supplied, is not touched, but any other values to be returned |
|
1032 through pointers are returned. |
|
1033 In this case calls (depending on the exact function |
|
1034 returning the error) to \f(CWdwarf_dealloc()\fP may be appropriate |
|
1035 once the particular pointer returned is no longer of interest. |
|
1036 .P |
|
1037 Pointers passed to allow values to be returned thru them are |
|
1038 uniformly the last pointers |
|
1039 in each argument list. |
|
1040 .P |
|
1041 All the interface functions are defined from the point of view of |
|
1042 the writer-of-the-library (as is traditional for UN*X library |
|
1043 documentation), not from the point of view of the user of the library. |
|
1044 The caller might code: |
|
1045 .P |
|
1046 .DS |
|
1047 Dwarf_Line line; |
|
1048 Dwarf_Signed ret_loff; |
|
1049 Dwarf_Error err; |
|
1050 int retval = dwarf_lineoff(line,&ret_loff,&err); |
|
1051 .DE |
|
1052 for the function defined as |
|
1053 .P |
|
1054 .DS |
|
1055 int dwarf_lineoff(Dwarf_Line line,Dwarf_Signed *return_lineoff, |
|
1056 Dwarf_Error* err); |
|
1057 .DE |
|
1058 and this document refers to the function as |
|
1059 returning the value thru *err or *return_lineoff or |
|
1060 uses the phrase "returns in |
|
1061 the location pointed to by err". |
|
1062 Sometimes other similar phrases are used. |
|
1063 |
|
1064 .H 1 "Memory Management" |
|
1065 Several of the functions that comprise \fIlibdwarf\fP return pointers |
|
1066 (opaque descriptors) to structures that have been dynamically allocated |
|
1067 by the library. To aid in the management of dynamic memory, the function |
|
1068 \f(CWdwarf_dealloc()\fP is provided to free storage allocated as a result |
|
1069 of a call to a \fIlibdwarf\fP function. This section describes the strategy |
|
1070 that should be taken by a client program in managing dynamic storage. |
|
1071 |
|
1072 .H 2 "Read-only Properties" |
|
1073 All pointers (opaque descriptors) returned by or as a result of a |
|
1074 \fIlibdwarf Consumer Library\fP |
|
1075 call should be assumed to point to read-only memory. |
|
1076 The results are undefined for \fIlibdwarf\fP clients that attempt |
|
1077 to write to a region pointed to by a value returned by a |
|
1078 \fIlibdwarf Consumer Library\fP |
|
1079 call. |
|
1080 |
|
1081 .H 2 "Storage Deallocation" |
|
1082 See the section "Returned values in the functional interface", |
|
1083 above, for the general rules where |
|
1084 calls to \f(CWdwarf_dealloc()\fP |
|
1085 is appropriate. |
|
1086 .P |
|
1087 In some cases the pointers returned by a \fIlibdwarf\fP call are pointers |
|
1088 to data which is not free-able. |
|
1089 The library knows from the allocation type |
|
1090 provided to it whether the space is freeable or not and will not free |
|
1091 inappropriately when \f(CWdwarf_dealloc()\fP is called. |
|
1092 So it is vital |
|
1093 that \f(CWdwarf_dealloc()\fP be called with the proper allocation type. |
|
1094 .P |
|
1095 For most storage allocated by \fIlibdwarf\fP, the client can free the |
|
1096 storage for reuse by calling \f(CWdwarf_dealloc()\fP, providing it with |
|
1097 the \f(CWDwarf_Debug\fP descriptor specifying the object for which the |
|
1098 storage was allocated, a pointer to the area to be free-ed, and an |
|
1099 identifier that specifies what the pointer points to (the allocation |
|
1100 type). For example, to free a \f(CWDwarf_Die die\fP belonging the the |
|
1101 object represented by \f(CWDwarf_Debug dbg\fP, allocated by a call to |
|
1102 \f(CWdwarf_siblingof()\fP, the call to \f(CWdwarf_dealloc()\fP would be: |
|
1103 .DS |
|
1104 \f(CWdwarf_dealloc(dbg, die, DW_DLA_DIE);\fP |
|
1105 .DE |
|
1106 |
|
1107 To free storage allocated in the form of a list of pointers (opaque |
|
1108 descriptors), each member of the list should be deallocated, followed |
|
1109 by deallocation of the actual list itself. The following code fragment |
|
1110 uses an invocation of \f(CWdwarf_attrlist()\fP as an example to illustrate |
|
1111 a technique that can be used to free storage from any \fIlibdwarf\fP |
|
1112 routine that returns a list: |
|
1113 .DS |
|
1114 \f(CWDwarf_Unsigned atcnt; |
|
1115 Dwarf_Attribute *atlist; |
|
1116 int errv; |
|
1117 |
|
1118 errv = dwarf_attrlist(somedie, &atlist,&atcnt, &error); |
|
1119 if (errv == DW_DLV_OK) { |
|
1120 |
|
1121 for (i = 0; i < atcnt; ++i) { |
|
1122 /* use atlist[i] */ |
|
1123 dwarf_dealloc(dbg, atlist[i], DW_DLA_ATTR); |
|
1124 } |
|
1125 dwarf_dealloc(dbg, atlist, DW_DLA_LIST); |
|
1126 }\fP |
|
1127 .DE |
|
1128 |
|
1129 The \f(CWDwarf_Debug\fP returned from \f(CWdwarf_init()\fP |
|
1130 or \f(CWdwarf_elf_init()\fP |
|
1131 cannot be free'd using \f(CWdwarf_dealloc()\fP. |
|
1132 The function \f(CWdwarf_finish()\fP will deallocate all dynamic storage |
|
1133 associated with an instance of a \f(CWDwarf_Debug\fP type. In particular, |
|
1134 it will deallocate all dynamically allocated space associated with the |
|
1135 \f(CWDwarf_Debug\fP descriptor, and finally make the descriptor invalid. |
|
1136 |
|
1137 An \f(CWDwarf_Error\fP returned from \f(CWdwarf_init()\fP |
|
1138 or \f(CWdwarf_elf_init()\fP |
|
1139 in case of a failure cannot be free'd |
|
1140 using \f(CWdwarf_dealloc()\fP. |
|
1141 The only way to free the \f(CWDwarf_Error\fP from either of those |
|
1142 calls is to use \f2free(3)\fP directly. |
|
1143 Every \f(CWDwarf_Error\fP must be free'd |
|
1144 by \f(CWdwarf_dealloc()\fP except those |
|
1145 returned by \f(CWdwarf_init()\fP |
|
1146 or \f(CWdwarf_elf_init()\fP. |
|
1147 |
|
1148 .P |
|
1149 The codes that identify the storage pointed to in calls to |
|
1150 .nr aX \n(Fg+1 |
|
1151 \f(CWdwarf_dealloc()\fP are described in figure \n(aX. |
|
1152 .DS |
|
1153 .TS |
|
1154 center box, tab(:); |
|
1155 lfB lfB |
|
1156 l l. |
|
1157 IDENTIFIER:USED TO FREE |
|
1158 _ |
|
1159 DW_DLA_STRING : char* |
|
1160 DW_DLA_LOC : Dwarf_Loc |
|
1161 DW_DLA_LOCDESC : Dwarf_Locdesc |
|
1162 DW_DLA_ELLIST : Dwarf_Ellist (not used) |
|
1163 DW_DLA_BOUNDS : Dwarf_Bounds (not used) |
|
1164 DW_DLA_BLOCK : Dwarf_Block |
|
1165 DW_DLA_DEBUG : Dwarf_Debug (do not use) |
|
1166 DW_DLA_DIE : Dwarf_Die |
|
1167 DW_DLA_LINE : Dwarf_Line |
|
1168 DW_DLA_ATTR : Dwarf_Attribute |
|
1169 DW_DLA_TYPE : Dwarf_Type (not used) |
|
1170 DW_DLA_SUBSCR : Dwarf_Subscr (not used) |
|
1171 DW_DLA_GLOBAL_CONTEXT : Dwarf_Global |
|
1172 DW_DLA_ERROR : Dwarf_Error |
|
1173 DW_DLA_LIST : a list of opaque descriptors |
|
1174 DW_DLA_LINEBUF : Dwarf_Line* (not used) |
|
1175 DW_DLA_ARANGE : Dwarf_Arange |
|
1176 DW_DLA_ABBREV : Dwarf_Abbrev |
|
1177 DW_DLA_FRAME_OP : Dwarf_Frame_Op |
|
1178 DW_DLA_CIE : Dwarf_Cie |
|
1179 DW_DLA_FDE : Dwarf_Fde |
|
1180 DW_DLA_LOC_BLOCK : Dwarf_Loc Block |
|
1181 DW_DLA_FRAME_BLOCK : Dwarf_Frame Block (not used) |
|
1182 DW_DLA_FUNC_CONTEXT : Dwarf_Func |
|
1183 DW_DLA_TYPENAME_CONTEXT : Dwarf_Type |
|
1184 DW_DLA_VAR_CONTEXT : Dwarf_Var |
|
1185 DW_DLA_WEAK_CONTEXT : Dwarf_Weak |
|
1186 DW_DLA_PUBTYPES_CONTEXT : Dwarf_Pubtype |
|
1187 .TE |
|
1188 .FG "Allocation/Deallocation Identifiers" |
|
1189 .DE |
|
1190 |
|
1191 .P |
|
1192 .H 1 "Functional Interface" |
|
1193 This section describes the functions available in the \fIlibdwarf\fP |
|
1194 library. Each function description includes its definition, followed |
|
1195 by one or more paragraph describing the function's operation. |
|
1196 |
|
1197 .P |
|
1198 The following sections describe these functions. |
|
1199 |
|
1200 .H 2 "Initialization Operations" |
|
1201 These functions are concerned with preparing an object file for subsequent |
|
1202 access by the functions in \fIlibdwarf\fP and with releasing allocated |
|
1203 resources when access is complete. |
|
1204 |
|
1205 .H 3 "dwarf_init()" |
|
1206 |
|
1207 .DS |
|
1208 \f(CWint dwarf_init( |
|
1209 int fd, |
|
1210 Dwarf_Unsigned access, |
|
1211 Dwarf_Handler errhand, |
|
1212 Dwarf_Ptr errarg, |
|
1213 Dwarf_Debug * dbg, |
|
1214 Dwarf_Error *error)\fP |
|
1215 .DE |
|
1216 When it returns \f(CWDW_DLV_OK\fP, |
|
1217 the function \f(CWdwarf_init()\fP returns thru |
|
1218 \f(CWdbg\fP a \f(CWDwarf_Debug\fP descriptor |
|
1219 that represents a handle for accessing debugging records associated with |
|
1220 the open file descriptor \f(CWfd\fP. |
|
1221 \f(CWDW_DLV_NO_ENTRY\fP is returned if the object |
|
1222 does not contain DWARF debugging information. |
|
1223 \f(CWDW_DLV_ERROR\fP is returned if |
|
1224 an error occurred. |
|
1225 The |
|
1226 \f(CWaccess\fP argument indicates what access is allowed for the section. |
|
1227 The \f(CWDW_DLC_READ\fP parameter is valid |
|
1228 for read access (only read access is defined or discussed in this |
|
1229 document). |
|
1230 The \f(CWerrhand\fP |
|
1231 argument is a pointer to a function that will be invoked whenever an error |
|
1232 is detected as a result of a \fIlibdwarf\fP operation. The \f(CWerrarg\fP |
|
1233 argument is passed as an argument to the \f(CWerrhand\fP function. |
|
1234 The file |
|
1235 descriptor associated with the \f(CWfd\fP argument must refer to an ordinary |
|
1236 file (i.e. not a pipe, socket, device, /proc entry, etc.), be opened with |
|
1237 the at least as much permission as specified by the \f(CWaccess\fP argument, |
|
1238 and cannot be closed or used as an argument to any system calls by the |
|
1239 client until after \f(CWdwarf_finish()\fP is called. |
|
1240 The seek position of |
|
1241 the file associated with \f(CWfd\fP is undefined upon return of |
|
1242 \f(CWdwarf_init()\fP. |
|
1243 |
|
1244 With SGI IRIX, by default it is allowed that the app |
|
1245 \f(CWclose()\fP \f(CWfd\fP immediately after calling \f(CWdwarf_init()\fP, |
|
1246 but that is not a portable approach (that it |
|
1247 works is an accidental |
|
1248 side effect of the fact that SGI IRIX uses \f(CWELF_C_READ_MMAP\fP |
|
1249 in its hidden internal call to \f(CWelf_begin()\fP). |
|
1250 The portable approach is to consider that \f(CWfd\fP |
|
1251 must be left open till after the corresponding dwarf_finish() call |
|
1252 has returned. |
|
1253 |
|
1254 Since \f(CWdwarf_init()\fP uses the same error handling processing as other |
|
1255 \fIlibdwarf\fP functions (see \fIError Handling\fP above), client programs |
|
1256 will generally supply an \f(CWerror\fP parameter to bypass the default actions |
|
1257 during initialization unless the default actions are appropriate. |
|
1258 |
|
1259 .H 3 "dwarf_elf_init()" |
|
1260 .DS |
|
1261 \f(CWint dwarf_elf_init( |
|
1262 Elf * elf_file_pointer, |
|
1263 Dwarf_Unsigned access, |
|
1264 Dwarf_Handler errhand, |
|
1265 Dwarf_Ptr errarg, |
|
1266 Dwarf_Debug * dbg, |
|
1267 Dwarf_Error *error)\fP |
|
1268 .DE |
|
1269 The function \f(CWdwarf_elf_init()\fP is identical to \f(CWdwarf_init()\fP |
|
1270 except that an open \f(CWElf *\fP pointer is passed instead of a file |
|
1271 descriptor. |
|
1272 In systems supporting \f(CWELF\fP object files this may be |
|
1273 more space or time-efficient than using \f(CWdwarf_init()\fP. |
|
1274 The client is allowed to use the \f(CWElf *\fP pointer |
|
1275 for its own purposes without restriction during the time the |
|
1276 \f(CWDwarf_Debug\fP |
|
1277 is open, except that the client should not \f(CWelf_end()\fP the |
|
1278 pointer till after \f(CWdwarf_finish\fP is called. |
|
1279 |
|
1280 .H 3 "dwarf_get_elf()" |
|
1281 .DS |
|
1282 \f(CWint dwarf_get_elf( |
|
1283 Dwarf_Debug dbg, |
|
1284 Elf ** elf, |
|
1285 Dwarf_Error *error)\fP |
|
1286 .DE |
|
1287 When it returns \f(CWDW_DLV_OK\fP, |
|
1288 the function \f(CWdwarf_get_elf()\fP returns thru the |
|
1289 pointer \f(CWelf\fP the \f(CWElf *\fP handle |
|
1290 used to access the object represented by the \f(CWDwarf_Debug\fP |
|
1291 descriptor \f(CWdbg\fP. It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1292 |
|
1293 Because \f(CWint dwarf_init()\fP opens an Elf descriptor |
|
1294 on its fd and \f(CWdwarf_finish()\fP does not close that |
|
1295 descriptor, an app should use \f(CWdwarf_get_elf\fP |
|
1296 and should call \f(CWelf_end\fP with the pointer returned |
|
1297 thru the \f(CWElf**\fP handle created by \f(CWint dwarf_init()\fP. |
|
1298 |
|
1299 This function is not meaningful for a system that does not use the |
|
1300 Elf format for objects. |
|
1301 |
|
1302 .H 3 "dwarf_finish()" |
|
1303 .DS |
|
1304 \f(CWint dwarf_finish( |
|
1305 Dwarf_Debug dbg, |
|
1306 Dwarf_Error *error)\fP |
|
1307 .DE |
|
1308 The function |
|
1309 \f(CWdwarf_finish()\fP releases all \fILibdwarf\fP internal resources |
|
1310 associated with the descriptor \f(CWdbg\fP, and invalidates \f(CWdbg\fP. |
|
1311 It returns \f(CWDW_DLV_ERROR\fP if there is an error during the |
|
1312 finishing operation. It returns \f(CWDW_DLV_OK\fP |
|
1313 for a successful operation. |
|
1314 |
|
1315 Because \f(CWint dwarf_init()\fP opens an Elf descriptor |
|
1316 on its fd and \f(CWdwarf_finish()\fP does not close that |
|
1317 descriptor, an app should use \f(CWdwarf_get_elf\fP |
|
1318 and should call \f(CWelf_end\fP with the pointer returned |
|
1319 thru the \f(CWElf**\fP handle created by \f(CWint dwarf_init()\fP. |
|
1320 |
|
1321 .H 2 "Debugging Information Entry Delivery Operations" |
|
1322 These functions are concerned with accessing debugging information |
|
1323 entries. |
|
1324 |
|
1325 .H 3 "Debugging Information Entry Debugger Delivery Operations" |
|
1326 |
|
1327 .H 3 "dwarf_next_cu_header()" |
|
1328 .DS |
|
1329 \f(CWint dwarf_next_cu_header( |
|
1330 Dwarf_debug dbg, |
|
1331 Dwarf_Unsigned *cu_header_length, |
|
1332 Dwarf_Half *version_stamp, |
|
1333 Dwarf_Unsigned *abbrev_offset, |
|
1334 Dwarf_Half *address_size, |
|
1335 Dwarf_Unsigned *next_cu_header, |
|
1336 Dwarf_Error *error); |
|
1337 .DE |
|
1338 The function |
|
1339 \f(CWdwarf_next_cu_header()\fP returns \f(CWDW_DLV_ERROR\fP |
|
1340 if it fails, and |
|
1341 \f(CWDW_DLV_OK\fP if it succeeds. |
|
1342 .P |
|
1343 If it succeeds, \f(CW*next_cu_header\fP is set to |
|
1344 the offset in the .debug_info section of the next |
|
1345 compilation-unit header if it succeeds. On reading the last |
|
1346 compilation-unit header in the .debug_info section it contains |
|
1347 the size of the .debug_info section. |
|
1348 The next call to |
|
1349 \f(CWdwarf_next_cu_header()\fP returns \f(CWDW_DLV_NO_ENTRY\fP |
|
1350 without reading a |
|
1351 compilation-unit or setting \f(CW*next_cu_header\fP. |
|
1352 Subsequent calls to \f(CWdwarf_next_cu_header()\fP |
|
1353 repeat the cycle by reading the first compilation-unit and so on. |
|
1354 .P |
|
1355 The other |
|
1356 values returned through pointers are the values in the compilation-unit |
|
1357 header. If any of \f(CWcu_header_length\fP, \f(CWversion_stamp\fP, |
|
1358 \f(CWabbrev_offset\fP, or \f(CWaddress_size\fP is \f(CWNULL\fP, the |
|
1359 argument is ignored (meaning it is not an error to provide a |
|
1360 \f(CWNULL\fP pointer). |
|
1361 |
|
1362 .H 3 "dwarf_siblingof()" |
|
1363 .DS |
|
1364 \f(CWint dwarf_siblingof( |
|
1365 Dwarf_Debug dbg, |
|
1366 Dwarf_Die die, |
|
1367 Dwarf_Die *return_sib, |
|
1368 Dwarf_Error *error)\fP |
|
1369 .DE |
|
1370 The function \f(CWdwarf_siblingof()\fP |
|
1371 returns \f(CWDW_DLV_ERROR\fP and sets the \f(CWerror\fP pointer on error. |
|
1372 If there is no sibling it returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
1373 When it succeeds, |
|
1374 \f(CWdwarf_siblingof()\fP returns |
|
1375 \f(CWDW_DLV_OK\fP and sets \f(CW*return_sib\fP to the \f(CWDwarf_Die\fP |
|
1376 descriptor of the sibling of \f(CWdie\fP. |
|
1377 If \f(CWdie\fP is \fINULL\fP, the \f(CWDwarf_Die\fP descriptor of the |
|
1378 first die in the compilation-unit is returned. |
|
1379 This die has the |
|
1380 \f(CWDW_TAG_compile_unit\fP tag. |
|
1381 .H 3 "dwarf_child()" |
|
1382 .DS |
|
1383 \f(CWint dwarf_child( |
|
1384 Dwarf_Die die, |
|
1385 Dwarf_Die *return_kid, |
|
1386 Dwarf_Error *error)\fP |
|
1387 .DE |
|
1388 The function \f(CWdwarf_child()\fP |
|
1389 returns \f(CWDW_DLV_ERROR\fP and sets the \f(CWerror\fP die on error. |
|
1390 If there is no child it returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
1391 When it succeeds, |
|
1392 \f(CWdwarf_child()\fP returns |
|
1393 \f(CWDW_DLV_OK\fP and sets \f(CW*return_kid\fP |
|
1394 to the \f(CWDwarf_Die\fP descriptor |
|
1395 of the first child of \f(CWdie\fP. |
|
1396 The function |
|
1397 \f(CWdwarf_siblingof()\fP can be used with the return value of |
|
1398 \f(CWdwarf_child()\fP to access the other children of \f(CWdie\fP. |
|
1399 |
|
1400 .H 3 "dwarf_offdie()" |
|
1401 .DS |
|
1402 \f(CWint dwarf_offdie( |
|
1403 Dwarf_Debug dbg, |
|
1404 Dwarf_Off offset, |
|
1405 Dwarf_Die *return_die, |
|
1406 Dwarf_Error *error)\fP |
|
1407 .DE |
|
1408 The function \f(CWdwarf_offdie()\fP |
|
1409 returns \f(CWDW_DLV_ERROR\fP and sets the \f(CWerror\fP die on error. |
|
1410 When it succeeds, |
|
1411 \f(CWdwarf_offdie()\fP returns |
|
1412 \f(CWDW_DLV_OK\fP and sets \f(CW*return_die\fP |
|
1413 to the |
|
1414 the \f(CWDwarf_Die\fP |
|
1415 descriptor of the debugging information entry at \f(CWoffset\fP in |
|
1416 the section containing debugging information entries i.e the .debug_info |
|
1417 section. |
|
1418 A return of \f(CWDW_DLV_NO_ENTRY\fP |
|
1419 means that the \f(CWoffset\fP in the section is of a byte containing |
|
1420 all 0 bits, indicating that there |
|
1421 is no abbreviation code. Meaning this 'die offset' is not |
|
1422 the offset of a real die, but is instead an offset of a null die, |
|
1423 a padding die, or of some random zero byte: this should |
|
1424 not be returned in normal use. |
|
1425 It is the user's |
|
1426 responsibility to make sure that \f(CWoffset\fP is the start of a valid |
|
1427 debugging information entry. The result of passing it an invalid |
|
1428 offset could be chaos. |
|
1429 |
|
1430 .\"#if 0 |
|
1431 .\".H 3 "Debugging Entry Delivery High-level Operations" |
|
1432 .\"The following "higher level" operations are typically not used by |
|
1433 .\"debuggers or DWARF prettyprinters. A disassembler (for example) |
|
1434 .\"might find them useful. |
|
1435 .\" |
|
1436 .\".DS |
|
1437 .\"\f(CWDwarf_Die dwarf_pcfile( |
|
1438 .\" Dwarf_Debug dbg, |
|
1439 .\" Dwarf_Addr pc, |
|
1440 .\" Dwarf_Error *error)\fP |
|
1441 .\".DE |
|
1442 .\"The function \f(CWdwarf_pcfile()\fP returns the \f(CWDwarf_Die\fP |
|
1443 .\"descriptor of the compilation unit debugging information entry that |
|
1444 .\"contains the address of \f(CWpc\fP. It returns \fINULL\fP if no |
|
1445 .\"entry exists or an error occurred. Currently compilation unit |
|
1446 .\"debugging information entries are defined as those having a tag of: |
|
1447 .\"\f(CWDW_TAG_compile_unit\fP. This function is currently unimplemented. |
|
1448 .\" |
|
1449 .\".DS |
|
1450 .\"\f(CWDwarf_Die dwarf_pcsubr( |
|
1451 .\" Dwarf_Debug dbg, |
|
1452 .\" Dwarf_Addr pc, |
|
1453 .\" Dwarf_Error *error)\fP |
|
1454 .\".DE |
|
1455 .\"The function |
|
1456 .\"\f(CWdwarf_pcsubr()\fP returns the \f(CWDwarf_Die\fP descriptor of the |
|
1457 .\"subroutine debugging entry that contains the address of \f(CWpc\fP. It |
|
1458 .\"returns \fINULL\fP if no entry exists or an error occurred. Currently |
|
1459 .\"subroutine debugging information entries are defined as those having a |
|
1460 .\"tag of: \f(CWDW_TAG_subprogram\fP, or \f(CWTAG_inlined_subroutine\fP. |
|
1461 .\"This function is currently unimplemented. |
|
1462 .\" |
|
1463 .\".DS |
|
1464 .\"\f(CWDwarf_Die dwarf_pcscope( |
|
1465 .\" Dwarf_Debug dbg, |
|
1466 .\" Dwarf_Addr pc, |
|
1467 .\" Dwarf_Error *error)\fP |
|
1468 .\".DE |
|
1469 .\"The function |
|
1470 .\"\f(CWdwarf_pcscope()\fP returns the \f(CWDwarf_Die\fP descriptor for |
|
1471 .\"the debugging information entry that represents the innermost enclosing |
|
1472 .\"scope containing \f(CWpc\fP, or \fINULL\fP if no entry exists or an |
|
1473 .\"error occurred. Debugging information entries that represent a \fIscope\fP |
|
1474 .\"are those containing a low pc attribute and either a high pc or byte |
|
1475 .\"size attribute that delineates a range. For example: a debugging information |
|
1476 .\"entry for a lexical block is considered one having a scope whereas a |
|
1477 .\"debugging information entry for a label is not. This function is |
|
1478 .\"currently unimplemented. |
|
1479 .\"#endif |
|
1480 |
|
1481 |
|
1482 .H 2 "Debugging Information Entry Query Operations" |
|
1483 These queries return specific information about debugging information |
|
1484 entries or a descriptor that can be used on subsequent queries when |
|
1485 given a \f(CWDwarf_Die\fP descriptor. Note that some operations are |
|
1486 specific to debugging information entries that are represented by a |
|
1487 \f(CWDwarf_Die\fP descriptor of a specific type. |
|
1488 For example, not all |
|
1489 debugging information entries contain an attribute having a name, so |
|
1490 consequently, a call to \f(CWdwarf_diename()\fP using a \f(CWDwarf_Die\fP |
|
1491 descriptor that does not have a name attribute will return |
|
1492 \f(CWDW_DLV_NO_ENTRY\fP. |
|
1493 This is not an error, i.e. calling a function that needs a specific |
|
1494 attribute is not an error for a die that does not contain that specific |
|
1495 attribute. |
|
1496 .P |
|
1497 There are several methods that can be used to obtain the value of an |
|
1498 attribute in a given die: |
|
1499 .AL 1 |
|
1500 .LI |
|
1501 Call \f(CWdwarf_hasattr()\fP to determine if the debugging information |
|
1502 entry has the attribute of interest prior to issuing the query for |
|
1503 information about the attribute. |
|
1504 |
|
1505 .LI |
|
1506 Supply an \f(CWerror\fP argument, and check its value after the call to |
|
1507 a query indicates an unsuccessful return, to determine the nature of the |
|
1508 problem. The \f(CWerror\fP argument will indicate whether an error occurred, |
|
1509 or the specific attribute needed was missing in that die. |
|
1510 |
|
1511 .LI |
|
1512 Arrange to have an error handling function invoked upon detection of an |
|
1513 error (see \f(CWdwarf_init()\fP). |
|
1514 |
|
1515 .LI |
|
1516 Call \f(CWdwarf_attrlist()\fP and iterate through the returned list of |
|
1517 attributes, dealing with each one as appropriate. |
|
1518 .LE |
|
1519 .P |
|
1520 |
|
1521 .H 3 "dwarf_tag()" |
|
1522 .DS |
|
1523 \f(CWint dwarf_tag( |
|
1524 Dwarf_Die die, |
|
1525 Dwarf_Half *tagval, |
|
1526 Dwarf_Error *error)\fP |
|
1527 .DE |
|
1528 The function \f(CWdwarf_tag()\fP returns the \fItag\fP of \f(CWdie\fP |
|
1529 thru the pointer \f(CWtagval\fP if it succeeds. |
|
1530 It returns \f(CWDW_DLV_OK\fP if it succeeds. |
|
1531 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1532 |
|
1533 .H 3 "dwarf_dieoffset()" |
|
1534 .DS |
|
1535 \f(CWint dwarf_dieoffset( |
|
1536 Dwarf_Die die, |
|
1537 Dwarf_Off * return_offset, |
|
1538 Dwarf_Error *error)\fP |
|
1539 .DE |
|
1540 When it succeeds, |
|
1541 the function \f(CWdwarf_dieoffset()\fP returns |
|
1542 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP |
|
1543 to the position of \f(CWdie\fP |
|
1544 in the section containing debugging information entries |
|
1545 (the \f(CWreturn_offset\fP is a section-relative offset). |
|
1546 In other words, |
|
1547 it sets \f(CWreturn_offset\fP |
|
1548 to the offset of the start of the debugging information entry |
|
1549 described by \f(CWdie\fP in the section containing die's i.e .debug_info. |
|
1550 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1551 |
|
1552 .H 3 "dwarf_die_CU_offset()" |
|
1553 .DS |
|
1554 \f(CWint dwarf_die_CU_offset( |
|
1555 Dwarf_Die die, |
|
1556 Dwarf_Off *return_offset, |
|
1557 Dwarf_Error *error)\fP |
|
1558 .DE |
|
1559 The function \f(CWdwarf_die_CU_offset()\fP is similar to |
|
1560 \f(CWdwarf_dieoffset()\fP, except that it puts the offset of the DIE |
|
1561 represented by the \f(CWDwarf_Die\fP \f(CWdie\fP, from the |
|
1562 start of the compilation-unit that it belongs to rather than the start |
|
1563 of .debug_info (the \f(CWreturn_offset\fP is a CU-relative offset). |
|
1564 |
|
1565 |
|
1566 .H 3 "dwarf_diename()" |
|
1567 .DS |
|
1568 \f(CWint dwarf_diename( |
|
1569 Dwarf_Die die, |
|
1570 char ** return_name, |
|
1571 Dwarf_Error *error)\fP |
|
1572 .DE |
|
1573 When it succeeds, |
|
1574 the function \f(CWdwarf_diename()\fP returns |
|
1575 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP |
|
1576 to |
|
1577 a pointer to a |
|
1578 null-terminated string of characters that represents the name |
|
1579 attribute of \f(CWdie\fP. |
|
1580 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not have a name attribute. |
|
1581 It returns \f(CWDW_DLV_ERROR\fP if |
|
1582 an error occurred. |
|
1583 The storage pointed to by a successful return of |
|
1584 \f(CWdwarf_diename()\fP should be free'd using the allocation type |
|
1585 \f(CWDW_DLA_STRING\fP when no longer of interest (see |
|
1586 \f(CWdwarf_dealloc()\fP). |
|
1587 |
|
1588 .H 3 "dwarf_attrlist()" |
|
1589 .DS |
|
1590 \f(CWint dwarf_attrlist( |
|
1591 Dwarf_Die die, |
|
1592 Dwarf_Attribute** attrbuf, |
|
1593 Dwarf_Signed *attrcount, |
|
1594 Dwarf_Error *error)\fP |
|
1595 .DE |
|
1596 When it returns \f(CWDW_DLV_OK\fP, |
|
1597 the function \f(CWdwarf_attrlist()\fP sets \f(CWattrbuf\fP to point |
|
1598 to an array of \f(CWDwarf_Attribute\fP descriptors corresponding to |
|
1599 each of the attributes in die, and returns the number of elements in |
|
1600 the array thru \f(CWattrcount\fP. |
|
1601 \f(CWDW_DLV_NO_ENTRY\fP is returned if the count is zero (no |
|
1602 \f(CWattrbuf\fP is allocated in this case). |
|
1603 \f(CWDW_DLV_ERROR\fP is returned on error. |
|
1604 On a successful return from \f(CWdwarf_attrlist()\fP, each of the |
|
1605 \f(CWDwarf_Attribute\fP descriptors should be individually free'd using |
|
1606 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ATTR\fP, |
|
1607 followed by free-ing the list pointed to by \f(CW*attrbuf\fP using |
|
1608 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_LIST\fP, |
|
1609 when no longer of interest (see \f(CWdwarf_dealloc()\fP). |
|
1610 |
|
1611 Freeing the attrlist: |
|
1612 .in +2 |
|
1613 .DS |
|
1614 \f(CWDwarf_Unsigned atcnt; |
|
1615 Dwarf_Attribute *atlist; |
|
1616 int errv; |
|
1617 |
|
1618 errv = dwarf_attrlist(somedie, &atlist,&atcnt, &error); |
|
1619 if (errv == DW_DLV_OK) { |
|
1620 |
|
1621 for (i = 0; i < atcnt; ++i) { |
|
1622 /* use atlist[i] */ |
|
1623 dwarf_dealloc(dbg, atlist[i], DW_DLA_ATTR); |
|
1624 } |
|
1625 dwarf_dealloc(dbg, atlist, DW_DLA_LIST); |
|
1626 }\fP |
|
1627 .DE |
|
1628 .in -2 |
|
1629 .P |
|
1630 .H 3 "dwarf_hasattr()" |
|
1631 .DS |
|
1632 \f(CWint dwarf_hasattr( |
|
1633 Dwarf_Die die, |
|
1634 Dwarf_Half attr, |
|
1635 Dwarf_Bool *return_bool, |
|
1636 Dwarf_Error *error)\fP |
|
1637 .DE |
|
1638 When it succeeds, the |
|
1639 function \f(CWdwarf_hasattr()\fP returns \f(CWDW_DLV_OK\fP |
|
1640 and sets \f(CW*return_bool\fP to \fInon-zero\fP if |
|
1641 \f(CWdie\fP has the attribute \f(CWattr\fP and \fIzero\fP otherwise. |
|
1642 If it fails, it returns \f(CWDW_DLV_ERROR\fP. |
|
1643 |
|
1644 .H 3 "dwarf_attr()" |
|
1645 .DS |
|
1646 \f(CWint dwarf_attr( |
|
1647 Dwarf_Die die, |
|
1648 Dwarf_Half attr, |
|
1649 Dwarf_Attribute *return_attr, |
|
1650 Dwarf_Error *error)\fP |
|
1651 .DE |
|
1652 When it returns \f(CWDW_DLV_OK\fP, |
|
1653 the function \f(CWdwarf_attr()\fP |
|
1654 sets |
|
1655 \f(CW*return_attr\fP to the \f(CWDwarf_Attribute\fP |
|
1656 descriptor of \f(CWdie\fP having the attribute \f(CWattr\fP. |
|
1657 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWattr\fP is not contained |
|
1658 in \f(CWdie\fP. |
|
1659 It returns \f(CWDW_DLV_ERROR\fP if an error occurred. |
|
1660 |
|
1661 .\"#if 0 |
|
1662 .\".DS |
|
1663 .\"\f(CWDwarf_Locdesc* dwarf_stringlen( |
|
1664 .\" Dwarf_Die die, |
|
1665 .\" Dwarf_Error *error)\fP |
|
1666 .\".DE |
|
1667 .\"The function \f(CWdwarf_stringlen()\fP returns a pointer to a |
|
1668 .\"\f(CWDwarf_Locdesc\fP with one Locdesc entry that when evaluated, |
|
1669 .\"yields the length of the string represented by \f(CWdie\fP. It |
|
1670 .\"returns \f(CWNULL\fP if \f(CWdie\fP does not contain a string length |
|
1671 .\"attribute or the string length attribute is not a location-description |
|
1672 .\"or an error occurred. The address range of the list is set to 0 thru |
|
1673 .\"the highest possible address if a loclist pointer is returned. The |
|
1674 .\"storage pointed to by a successful return of \f(CWdwarf_stringlen()\fP |
|
1675 .\"should be free'd when no longer of interest (see \f(CWdwarf_dealloc()\fP). |
|
1676 .\"This function is currently unimplemented. |
|
1677 .\"#endif |
|
1678 |
|
1679 .\"#if 0 |
|
1680 .\".DS |
|
1681 .\"\f(CWDwarf_Signed dwarf_subscrcnt( |
|
1682 .\" Dwarf_Die die, |
|
1683 .\" Dwarf_Error *error)\fP |
|
1684 .\".DE |
|
1685 .\"The function \f(CWdwarf_subscrcnt()\fP returns the number of subscript |
|
1686 .\"die's that are owned by the array type represented by \f(CWdie\fP. It |
|
1687 .\"returns \f(CWDW_DLV_NOCOUNT\fP on error. This function is currently |
|
1688 .\"unimplemented. |
|
1689 .\" |
|
1690 .\".DS |
|
1691 .\"\f(CWDwarf_Die dwarf_nthsubscr( |
|
1692 .\" Dwarf_Die die, |
|
1693 .\" Dwarf_Unsigned ssndx, |
|
1694 .\" Dwarf_Error *error)\fP |
|
1695 .\".DE |
|
1696 .\"The function \f(CWdwarf_nthsubscr()\fP returns a \f(CWDwarf_Die\fP |
|
1697 .\"descriptor that describes the \f(CWssndx\fP subscript of the array |
|
1698 .\"type debugging information entry represented by \f(CWdie\fP, where |
|
1699 .\"\fI1\fP is the first member. It returns \fINULL\fP if \f(CWdie\fP |
|
1700 .\"does not have an \f(CWssndx\fP subscript, or an error occurred. |
|
1701 .\"This function is currently unimplemented. |
|
1702 .\"#endif |
|
1703 |
|
1704 .H 3 "dwarf_lowpc()" |
|
1705 .DS |
|
1706 \f(CWint dwarf_lowpc( |
|
1707 Dwarf_Die die, |
|
1708 Dwarf_Addr * return_lowpc, |
|
1709 Dwarf_Error * error)\fP |
|
1710 .DE |
|
1711 The function \f(CWdwarf_lowpc()\fP returns |
|
1712 \f(CWDW_DLV_OK\fP and sets \f(CW*return_lowpc\fP |
|
1713 to the low program counter |
|
1714 value associated with the \f(CWdie\fP descriptor if \f(CWdie\fP |
|
1715 represents a debugging information entry with this attribute. |
|
1716 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not have this |
|
1717 attribute. |
|
1718 It returns \f(CWDW_DLV_ERROR\fP if an error occurred. |
|
1719 |
|
1720 .H 3 "dwarf_highpc()" |
|
1721 .DS |
|
1722 \f(CWint dwarf_highpc( |
|
1723 Dwarf_Die die, |
|
1724 Dwarf_Addr * return_highpc, |
|
1725 Dwarf_Error *error)\fP |
|
1726 .DE |
|
1727 The function \f(CWdwarf_highpc()\fP returns |
|
1728 \f(CWDW_DLV_OK\fP and sets \f(CW*return_highpc\fP |
|
1729 the high program counter |
|
1730 value associated with the \f(CWdie\fP descriptor if \f(CWdie\fP |
|
1731 represents a debugging information entry with this attribute. |
|
1732 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not have this |
|
1733 attribute. |
|
1734 It returns \f(CWDW_DLV_ERROR\fP if an error occurred. |
|
1735 |
|
1736 .H 3 "dwarf_bytesize()" |
|
1737 .DS |
|
1738 \f(CWDwarf_Signed dwarf_bytesize( |
|
1739 Dwarf_Die die, |
|
1740 Dwarf_Unsigned *return_size, |
|
1741 Dwarf_Error *error)\fP |
|
1742 .DE |
|
1743 When it succeeds, |
|
1744 \f(CWdwarf_bytesize()\fP returns |
|
1745 \f(CWDW_DLV_OK\fP and sets \f(CW*return_size\fP |
|
1746 to the number of bytes |
|
1747 needed to contain an instance of the aggregate debugging information |
|
1748 entry represented by \f(CWdie\fP. |
|
1749 It returns \f(CWDW_DLV_NO_ENTRY\fP if |
|
1750 \f(CWdie\fP does not contain the byte size attribute \f(CWDW_AT_byte_size\fP. |
|
1751 It returns \f(CWDW_DLV_ERROR\fP if |
|
1752 an error occurred. |
|
1753 |
|
1754 .\"#if 0 |
|
1755 .\".DS |
|
1756 .\"\f(CWDwarf_Bool dwarf_isbitfield( |
|
1757 .\" Dwarf_Die die, |
|
1758 .\" Dwarf_Error *error)\fP |
|
1759 .\".DE |
|
1760 .\"The function \f(CWdwarf_isbitfield()\fP returns \fInon-zero\fP if |
|
1761 .\"\f(CWdie\fP is a descriptor for a debugging information entry that |
|
1762 .\"represents a bit field member. It returns \fIzero\fP if \f(CWdie\fP |
|
1763 .\"is not associated with a bit field member. This function is currently |
|
1764 .\"unimplemented. |
|
1765 .\"#endif |
|
1766 |
|
1767 .H 3 "dwarf_bitsize()" |
|
1768 .DS |
|
1769 \f(CWint dwarf_bitsize( |
|
1770 Dwarf_Die die, |
|
1771 Dwarf_Unsigned *return_size, |
|
1772 Dwarf_Error *error)\fP |
|
1773 .DE |
|
1774 When it succeeds, |
|
1775 \f(CWdwarf_bitsize()\fP returns |
|
1776 \f(CWDW_DLV_OK\fP and sets \f(CW*return_size\fP |
|
1777 to the number of |
|
1778 bits |
|
1779 occupied by the bit field value that is an attribute of the given |
|
1780 die. |
|
1781 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not |
|
1782 contain the bit size attribute \f(CWDW_AT_bit_size\fP. |
|
1783 It returns \f(CWDW_DLV_ERROR\fP if |
|
1784 an error occurred. |
|
1785 |
|
1786 .H 3 "dwarf_bitoffset()" |
|
1787 .DS |
|
1788 \f(CWint dwarf_bitoffset( |
|
1789 Dwarf_Die die, |
|
1790 Dwarf_Unsigned *return_size, |
|
1791 Dwarf_Error *error)\fP |
|
1792 .DE |
|
1793 When it succeeds, |
|
1794 \f(CWdwarf_bitoffset()\fP returns |
|
1795 \f(CWDW_DLV_OK\fP and sets \f(CW*return_size\fP |
|
1796 to the number of bits |
|
1797 to the left of the most significant bit of the bit field value. |
|
1798 This bit offset is not necessarily the net bit offset within the |
|
1799 structure or class , since \f(CWDW_AT_data_member_location\fP |
|
1800 may give a byte offset to this \f(CWDIE\fP and the bit offset |
|
1801 returned through the pointer |
|
1802 does not include the bits in the byte offset. |
|
1803 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not contain the |
|
1804 bit offset attribute \f(CWDW_AT_bit_offset\fP. |
|
1805 It returns \f(CWDW_DLV_ERROR\fP if |
|
1806 an error occurred. |
|
1807 |
|
1808 .H 3 "dwarf_srclang()" |
|
1809 .DS |
|
1810 \f(CWint dwarf_srclang( |
|
1811 Dwarf_Die die, |
|
1812 Dwarf_Unsigned *return_lang, |
|
1813 Dwarf_Error *error)\fP |
|
1814 .DE |
|
1815 When it succeeds, |
|
1816 \f(CWdwarf_srclang()\fP returns |
|
1817 \f(CWDW_DLV_OK\fP and sets \f(CW*return_lang\fP |
|
1818 to |
|
1819 a code indicating the |
|
1820 source language of the compilation unit represented by the descriptor |
|
1821 \f(CWdie\fP. |
|
1822 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not |
|
1823 represent a source file debugging information entry (i.e. contain the |
|
1824 attribute \f(CWDW_AT_language\fP). |
|
1825 It returns \f(CWDW_DLV_ERROR\fP if |
|
1826 an error occurred. |
|
1827 |
|
1828 .H 3 "dwarf_arrayorder()" |
|
1829 .DS |
|
1830 \f(CWint dwarf_arrayorder( |
|
1831 Dwarf_Die die, |
|
1832 Dwarf_Unsigned *return_order, |
|
1833 Dwarf_Error *error)\fP |
|
1834 .DE |
|
1835 When it succeeds, |
|
1836 \f(CWdwarf_arrayorder()\fP returns |
|
1837 \f(CWDW_DLV_OK\fP and sets \f(CW*return_order\fP |
|
1838 a code indicating |
|
1839 the ordering of the array represented by the descriptor \f(CWdie\fP. |
|
1840 It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not contain the |
|
1841 array order attribute \f(CWDW_AT_ordering\fP. |
|
1842 It returns \f(CWDW_DLV_ERROR\fP if |
|
1843 an error occurred. |
|
1844 |
|
1845 .H 2 "Attribute Form Queries" |
|
1846 Based on the attribute's form, these operations are concerned with |
|
1847 returning uninterpreted attribute data. Since it is not always |
|
1848 obvious from the return value of these functions if an error occurred, |
|
1849 one should always supply an \f(CWerror\fP parameter or have arranged |
|
1850 to have an error handling function invoked (see \f(CWdwarf_init()\fP) |
|
1851 to determine the validity of the returned value and the nature of any |
|
1852 errors that may have occurred. |
|
1853 |
|
1854 A \f(CWDwarf_Attribute\fP descriptor describes an attribute of a |
|
1855 specific die. Thus, each \f(CWDwarf_Attribute\fP descriptor is |
|
1856 implicitly associated with a specific die. |
|
1857 |
|
1858 .H 3 "dwarf_hasform()" |
|
1859 .DS |
|
1860 \f(CWnt dwarf_hasform( |
|
1861 Dwarf_Attribute attr, |
|
1862 Dwarf_Half form, |
|
1863 Dwarf_Bool *return_hasform, |
|
1864 Dwarf_Error *error)\fP |
|
1865 .DE |
|
1866 The function \f(CWdwarf_hasform()\fP returns |
|
1867 \f(CWDW_DLV_OK\fP and and puts a |
|
1868 \fInon-zero\fP |
|
1869 value in the |
|
1870 \f(CW*return_hasform\fP boolean if the |
|
1871 attribute represented by the \f(CWDwarf_Attribute\fP descriptor |
|
1872 \f(CWattr\fP has the attribute form \f(CWform\fP. |
|
1873 If the attribute does not have that form \fIzero\fP |
|
1874 is put into \f(CW*return_hasform\fP. |
|
1875 \f(CWDW_DLV_ERROR\fP is returned on error. |
|
1876 |
|
1877 .H 3 "dwarf_whatform()" |
|
1878 .DS |
|
1879 \f(CWint dwarf_whatform( |
|
1880 Dwarf_Attribute attr, |
|
1881 Dwarf_Half *return_form, |
|
1882 Dwarf_Error *error)\fP |
|
1883 .DE |
|
1884 When it succeeds, |
|
1885 \f(CWdwarf_whatform()\fP returns |
|
1886 \f(CWDW_DLV_OK\fP and sets \f(CW*return_form\fP |
|
1887 to the attribute form code of |
|
1888 the attribute represented by the \f(CWDwarf_Attribute\fP descriptor |
|
1889 \f(CWattr\fP. |
|
1890 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1891 An attribute using DW_FORM_indirect effectively has two forms. |
|
1892 This function returns the 'final' form for \f(CWDW_FORM_indirect\fP, |
|
1893 not the \f(CWDW_FORM_indirect\fP itself. This function is |
|
1894 what most applications will want to call. |
|
1895 |
|
1896 .H 3 "dwarf_whatform_direct()" |
|
1897 .DS |
|
1898 \f(CWint dwarf_whatform_direct( |
|
1899 Dwarf_Attribute attr, |
|
1900 Dwarf_Half *return_form, |
|
1901 Dwarf_Error *error)\fP |
|
1902 .DE |
|
1903 When it succeeds, |
|
1904 \f(CWdwarf_whatform_direct()\fP returns |
|
1905 \f(CWDW_DLV_OK\fP and sets \f(CW*return_form\fP |
|
1906 to the attribute form code of |
|
1907 the attribute represented by the \f(CWDwarf_Attribute\fP descriptor |
|
1908 \f(CWattr\fP. |
|
1909 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1910 An attribute using \f(CWDW_FORM_indirect\fP effectively has two forms. |
|
1911 This returns the form 'directly' in the initial form field. |
|
1912 So when the form field is \f(CWDW_FORM_indirect\fP |
|
1913 this call returns the \f(CWDW_FORM_indirect\fP form, |
|
1914 which is sometimes useful for dump utilities. |
|
1915 |
|
1916 .H 3 "dwarf_whatattr()" |
|
1917 .DS |
|
1918 \f(CWint dwarf_whatattr( |
|
1919 Dwarf_Attribute attr, |
|
1920 Dwarf_Half *return_attr, |
|
1921 Dwarf_Error *error)\fP |
|
1922 .DE |
|
1923 When it succeeds, |
|
1924 \f(CWdwarf_whatattr()\fP returns |
|
1925 \f(CWDW_DLV_OK\fP and sets \f(CW*return_attr\fP |
|
1926 to the attribute code |
|
1927 represented by the \f(CWDwarf_Attribute\fP descriptor \f(CWattr\fP. |
|
1928 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1929 |
|
1930 .H 3 "dwarf_formref()" |
|
1931 .DS |
|
1932 \f(CWint dwarf_formref( |
|
1933 Dwarf_Attribute attr, |
|
1934 Dwarf_Off *return_offset, |
|
1935 Dwarf_Error *error)\fP |
|
1936 .DE |
|
1937 When it succeeds, |
|
1938 \f(CWdwarf_formref()\fP returns |
|
1939 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP |
|
1940 to the CU-relative offset |
|
1941 represented by the descriptor \f(CWattr\fP if the form of the attribute |
|
1942 belongs to the \f(CWREFERENCE\fP class. |
|
1943 \f(CWattr\fP must be a CU-local reference, |
|
1944 not form \f(CWDW_FORM_ref_addr\fP. |
|
1945 It is an error for the form to |
|
1946 not belong to this class or to be form \f(CWDW_FORM_ref_addr\fP. |
|
1947 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1948 See also \f(CWdwarf_global_formref\fP below. |
|
1949 |
|
1950 .H 3 "dwarf_global_formref()" |
|
1951 .DS |
|
1952 \f(CWint dwarf_global_formref( |
|
1953 Dwarf_Attribute attr, |
|
1954 Dwarf_Off *return_offset, |
|
1955 Dwarf_Error *error)\fP |
|
1956 .DE |
|
1957 When it succeeds, |
|
1958 \f(CWdwarf_global_formref()\fP returns |
|
1959 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP |
|
1960 to the .debug_info-section-relative offset |
|
1961 represented by the descriptor \f(CWattr\fP if the form of the attribute |
|
1962 belongs to the \f(CWREFERENCE\fP class. |
|
1963 \f(CWattr\fP can be any legal |
|
1964 \f(CWREFERENCE\fP class form including \f(CWDW_FORM_ref_addr\fP. |
|
1965 It is an error for the form to |
|
1966 not belong to this class. |
|
1967 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1968 See also \f(CWdwarf_formref\fP above. |
|
1969 |
|
1970 .H 3 "dwarf_formaddr()" |
|
1971 .DS |
|
1972 \f(CWint dwarf_formaddr( |
|
1973 Dwarf_Attribute attr, |
|
1974 Dwarf_Addr * return_addr, |
|
1975 Dwarf_Error *error)\fP |
|
1976 .DE |
|
1977 When it succeeds, |
|
1978 \f(CWdwarf_formaddr()\fP returns |
|
1979 \f(CWDW_DLV_OK\fP and sets \f(CW*return_addr\fP |
|
1980 to |
|
1981 the address |
|
1982 represented by the descriptor \f(CWattr\fP if the form of the attribute |
|
1983 belongs to the \f(CWADDRESS\fP class. |
|
1984 It is an error for the form to |
|
1985 not belong to this class. |
|
1986 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
1987 |
|
1988 .H 3 "dwarf_formflag()" |
|
1989 .DS |
|
1990 \f(CWint dwarf_formflag( |
|
1991 Dwarf_Attribute attr, |
|
1992 Dwarf_Bool * return_bool, |
|
1993 Dwarf_Error *error)\fP |
|
1994 .DE |
|
1995 When it succeeds, |
|
1996 \f(CWdwarf_formflag()\fP returns |
|
1997 \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP |
|
1998 \f(CW1\fP (i.e. true) (if the attribute has a non-zero value) |
|
1999 or \f(CW0\fP (i.e. false) (if the attribute has a zero value). |
|
2000 It returns \f(CWDW_DLV_ERROR\fP on error or if the \f(CWattr\fP |
|
2001 does not have form flag. |
|
2002 |
|
2003 .H 3 "dwarf_formudata()" |
|
2004 .DS |
|
2005 \f(CWint dwarf_formudata( |
|
2006 Dwarf_Attribute attr, |
|
2007 Dwarf_Unsigned * return_uvalue, |
|
2008 Dwarf_Error * error)\fP |
|
2009 .DE |
|
2010 The function |
|
2011 \f(CWdwarf_formudata()\fP returns |
|
2012 \f(CWDW_DLV_OK\fP and sets \f(CW*return_uvalue\fP |
|
2013 to |
|
2014 the \f(CWDwarf_Unsigned\fP |
|
2015 value of the attribute represented by the descriptor \f(CWattr\fP if the |
|
2016 form of the attribute belongs to the \f(CWCONSTANT\fP class. |
|
2017 It is an |
|
2018 error for the form to not belong to this class. |
|
2019 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2020 |
|
2021 .H 3 "dwarf_formsdata()" |
|
2022 .DS |
|
2023 \f(CWint dwarf_formsdata( |
|
2024 Dwarf_Attribute attr, |
|
2025 Dwarf_Signed * return_svalue, |
|
2026 Dwarf_Error *error)\fP |
|
2027 .DE |
|
2028 The function \f(CWdwarf_formsdata()\fP returns |
|
2029 \f(CWDW_DLV_OK\fP and sets \f(CW*return_svalue\fP |
|
2030 to |
|
2031 the \f(CWDwarf_Signed\fP |
|
2032 value of the attribute represented by the descriptor \f(CWattr\fP if the |
|
2033 form of the attribute belongs to the \f(CWCONSTANT\fP class. |
|
2034 It is an |
|
2035 error for the form to not belong to this class. |
|
2036 If the size of the data |
|
2037 attribute referenced is smaller than the size of the \f(CWDwarf_Signed\fP |
|
2038 type, its value is sign extended. |
|
2039 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2040 |
|
2041 .H 3 "dwarf_formblock()" |
|
2042 .DS |
|
2043 \f(CWint dwarf_formblock( |
|
2044 Dwarf_Attribute attr, |
|
2045 Dwarf_Block ** return_block, |
|
2046 Dwarf_Error * error)\fP |
|
2047 .DE |
|
2048 The function \f(CWdwarf_formblock()\fP returns |
|
2049 \f(CWDW_DLV_OK\fP and sets \f(CW*return_block\fP |
|
2050 to |
|
2051 a pointer to a |
|
2052 \f(CWDwarf_Block\fP structure containing the value of the attribute |
|
2053 represented by the descriptor \f(CWattr\fP if the form of the |
|
2054 attribute belongs to the \f(CWBLOCK\fP class. |
|
2055 It is an error |
|
2056 for the form to not belong to this class. |
|
2057 The storage pointed |
|
2058 to by a successful return of \f(CWdwarf_formblock()\fP should |
|
2059 be free'd using the allocation type \f(CWDW_DLA_BLOCK\fP, when |
|
2060 no longer of interest (see \f(CWdwarf_dealloc()\fP). |
|
2061 It returns |
|
2062 \f(CWDW_DLV_ERROR\fP on error. |
|
2063 |
|
2064 .H 3 "dwarf_formstring()" |
|
2065 |
|
2066 .DS |
|
2067 \f(CWint dwarf_formstring( |
|
2068 Dwarf_Attribute attr, |
|
2069 char ** return_string, |
|
2070 Dwarf_Error *error)\fP |
|
2071 .DE |
|
2072 The function \f(CWdwarf_formstring()\fP returns |
|
2073 \f(CWDW_DLV_OK\fP and sets \f(CW*return_string\fP |
|
2074 to |
|
2075 a pointer to a |
|
2076 null-terminated string containing the value of the attribute |
|
2077 represented by the descriptor \f(CWattr\fP if the form of the |
|
2078 attribute belongs to the \f(CWSTRING\fP class. |
|
2079 It is an error |
|
2080 for the form to not belong to this class. |
|
2081 The storage pointed |
|
2082 to by a successful return of \f(CWdwarf_formstring()\fP |
|
2083 should not be free'd. The pointer points into |
|
2084 existing DWARF memory and the pointer becomes stale/invalid |
|
2085 after a call to \f(CWdwarf_finish\fP. |
|
2086 \f(CWdwarf_formstring()\fP returns \f(CWDW_DLV_ERROR\fP on error. |
|
2087 |
|
2088 .H 4 "dwarf_loclist_n()" |
|
2089 .DS |
|
2090 \f(CWint dwarf_loclist_n( |
|
2091 Dwarf_Attribute attr, |
|
2092 Dwarf_Locdesc ***llbuf, |
|
2093 Dwarf_Signed *listlen, |
|
2094 Dwarf_Error *error)\fP |
|
2095 .DE |
|
2096 The function \f(CWdwarf_loclist_n()\fP sets \f(CW*llbuf\fP to point to |
|
2097 an array of \f(CWDwarf_Locdesc\fP pointers corresponding to each of |
|
2098 the location expressions in a location list, and sets |
|
2099 \f(CW*listlen\fP to the number |
|
2100 of elements in the array and |
|
2101 returns \f(CWDW_DLV_OK\fP if the attribute is |
|
2102 appropriate. |
|
2103 .P |
|
2104 This is the preferred function for Dwarf_Locdesc as |
|
2105 it is the interface allowing access to an entire |
|
2106 loclist. (use of \f(CWdwarf_loclist_n()\fP is |
|
2107 suggested as the better interface, though |
|
2108 \f(CWdwarf_loclist()\fP is still |
|
2109 supported.) |
|
2110 .P |
|
2111 If the attribute is a reference to a location list |
|
2112 (DW_FORM_data4 or DW_FORM_data8) |
|
2113 the location list entries are used to fill |
|
2114 in all the fields of the \f(CWDwarf_Locdesc\fP(s) returned. |
|
2115 .P |
|
2116 If the attribute is a location description |
|
2117 (DW_FORM_block2 or DW_FORM_block4) |
|
2118 then some of the \f(CWDwarf_Locdesc\fP values of the single |
|
2119 \f(CWDwarf_Locdesc\fP record are set to 'sensible' |
|
2120 but arbitrary values. Specifically, ld_lopc is set to 0 and |
|
2121 ld_hipc is set to all-bits-on. And \f(CW*listlen\fP is set to 1. |
|
2122 .P |
|
2123 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2124 \f(CWdwarf_loclist_n()\fP works on \f(CWDW_AT_location\fP, |
|
2125 \f(CWDW_AT_data_member_location\fP, \f(CWDW_AT_vtable_elem_location\fP, |
|
2126 \f(CWDW_AT_string_length\fP, \f(CWDW_AT_use_location\fP, and |
|
2127 \f(CWDW_AT_return_addr\fP attributes. |
|
2128 .P |
|
2129 Storage allocated by a successful call of \f(CWdwarf_loclist_n()\fP should |
|
2130 be deallocated when no longer of interest (see \f(CWdwarf_dealloc()\fP). |
|
2131 The block of \f(CWDwarf_Loc\fP structs pointed to by the \f(CWld_s\fP |
|
2132 field of each \f(CWDwarf_Locdesc\fP structure |
|
2133 should be deallocated with the allocation type |
|
2134 \f(CWDW_DLA_LOC_BLOCK\fP. |
|
2135 and the \f(CWllbuf[]\fP space pointed to should be deallocated with |
|
2136 allocation type \f(CWDW_DLA_LOCDESC\fP. |
|
2137 This should be followed by deallocation of the \f(CWllbuf\fP |
|
2138 using the allocation type \f(CWDW_DLA_LIST\fP. |
|
2139 .in +2 |
|
2140 .DS |
|
2141 \f(CWDwarf_Signed lcnt; |
|
2142 Dwarf_Locdesc **llbuf; |
|
2143 int lres; |
|
2144 |
|
2145 lres = dwarf_loclist_n(someattr, &llbuf,&lcnt &error); |
|
2146 if (lres == DW_DLV_OK) { |
|
2147 for (i = 0; i < lcnt; ++i) { |
|
2148 /* use llbuf[i] */ |
|
2149 |
|
2150 dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK); |
|
2151 dwarf_dealloc(dbg,llbuf[i], DW_DLA_LOCDESC); |
|
2152 } |
|
2153 dwarf_dealloc(dbg, llbuf, DW_DLA_LIST); |
|
2154 }\fP |
|
2155 .DE |
|
2156 .in -2 |
|
2157 .P |
|
2158 |
|
2159 .H 4 "dwarf_loclist()" |
|
2160 .DS |
|
2161 \f(CWint dwarf_loclist( |
|
2162 Dwarf_Attribute attr, |
|
2163 Dwarf_Locdesc **llbuf, |
|
2164 Dwarf_Signed *listlen, |
|
2165 Dwarf_Error *error)\fP |
|
2166 .DE |
|
2167 The function \f(CWdwarf_loclist()\fP sets \f(CW*llbuf\fP to point to |
|
2168 a \f(CWDwarf_Locdesc\fP pointer for the single location expression |
|
2169 it can return. |
|
2170 It sets |
|
2171 \f(CW*listlen\fP to 1. |
|
2172 and returns \f(CWDW_DLV_OK\fP |
|
2173 if the attribute is |
|
2174 appropriate. |
|
2175 .P |
|
2176 It is less flexible than \f(CWdwarf_loclist_n()\fP in that |
|
2177 \f(CWdwarf_loclist()\fP can handle a maximum of one |
|
2178 location expression, not a full location list. |
|
2179 If a location-list is present it returns only |
|
2180 the first location-list entry location description. |
|
2181 Use \f(CWdwarf_loclist_n()\fP instead. |
|
2182 .P |
|
2183 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2184 \f(CWdwarf_loclist()\fP works on \f(CWDW_AT_location\fP, |
|
2185 \f(CWDW_AT_data_member_location\fP, \f(CWDW_AT_vtable_elem_location\fP, |
|
2186 \f(CWDW_AT_string_length\fP, \f(CWDW_AT_use_location\fP, and |
|
2187 \f(CWDW_AT_return_addr\fP attributes. |
|
2188 .P |
|
2189 Storage allocated by a successful call of \f(CWdwarf_loclist()\fP should |
|
2190 be deallocated when no longer of interest (see \f(CWdwarf_dealloc()\fP). |
|
2191 The block of \f(CWDwarf_Loc\fP structs pointed to by the \f(CWld_s\fP |
|
2192 field of each \f(CWDwarf_Locdesc\fP structure |
|
2193 should be deallocated with the allocation type \f(CWDW_DLA_LOC_BLOCK\fP. |
|
2194 This should be followed by deallocation of the \f(CWllbuf\fP |
|
2195 using the allocation type \f(CWDW_DLA_LOCDESC\fP. |
|
2196 .in +2 |
|
2197 .DS |
|
2198 \f(CWDwarf_Signed lcnt; |
|
2199 Dwarf_Locdesc *llbuf; |
|
2200 int lres; |
|
2201 |
|
2202 lres = dwarf_loclist(someattr, &llbuf,&lcnt,&error); |
|
2203 if (lres == DW_DLV_OK) { |
|
2204 /* lcnt is always 1, (and has always been 1) */ */ |
|
2205 |
|
2206 /* Use llbuf here. */ |
|
2207 |
|
2208 |
|
2209 dwarf_dealloc(dbg, llbuf->ld_s, DW_DLA_LOC_BLOCK); |
|
2210 dwarf_dealloc(dbg, llbuf, DW_DLA_LOCDESC); |
|
2211 /* Earlier version. |
|
2212 * for (i = 0; i < lcnt; ++i) { |
|
2213 * /* use llbuf[i] */ |
|
2214 * |
|
2215 * /* Deallocate Dwarf_Loc block of llbuf[i] */ |
|
2216 * dwarf_dealloc(dbg, llbuf[i].ld_s, DW_DLA_LOC_BLOCK); |
|
2217 * } |
|
2218 * dwarf_dealloc(dbg, llbuf, DW_DLA_LOCDESC); |
|
2219 */ |
|
2220 |
|
2221 }\fP |
|
2222 .DE |
|
2223 .in -2 |
|
2224 .P |
|
2225 |
|
2226 .H 4 "dwarf_loclist_from_expr()" |
|
2227 .DS |
|
2228 \f(CWint dwarf_loclist_from_expr( |
|
2229 Dwarf_Ptr bytes_in, |
|
2230 Dwarf_Unsigned bytes_len, |
|
2231 Dwarf_Locdesc **llbuf, |
|
2232 Dwarf_Signed *listlen, |
|
2233 Dwarf_Error *error)\fP |
|
2234 .DE |
|
2235 The function \f(CWdwarf_loclist_from_expr()\fP sets \f(CW*llbuf\fP to point to |
|
2236 a \f(CWDwarf_Locdesc\fP pointer for the single location expression |
|
2237 which is pointed to by \f(CW*bytes_in\fP (whose length is |
|
2238 \f(CW*bytes_len\fP). |
|
2239 It sets |
|
2240 \f(CW*listlen\fP to 1. |
|
2241 and returns \f(CWDW_DLV_OK\fP |
|
2242 if decoding is successful. |
|
2243 Some sources of bytes of expressions are dwarf expressions |
|
2244 in frame operations like \f(CWDW_CFA_def_cfa_expression\fP, |
|
2245 \f(CWDW_CFA_expression\fP, and \f(CWDW_CFA_val_expression\fP. |
|
2246 .P |
|
2247 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2248 .P |
|
2249 Storage allocated by a successful call of \f(CWdwarf_loclist_from_expr()\fP should |
|
2250 be deallocated when no longer of interest (see \f(CWdwarf_dealloc()\fP). |
|
2251 The block of \f(CWDwarf_Loc\fP structs pointed to by the \f(CWld_s\fP |
|
2252 field of each \f(CWDwarf_Locdesc\fP structure |
|
2253 should be deallocated with the allocation type \f(CWDW_DLA_LOC_BLOCK\fP. |
|
2254 This should be followed by deallocation of the \f(CWllbuf\fP |
|
2255 using the allocation type \f(CWDW_DLA_LOCDESC\fP. |
|
2256 .in +2 |
|
2257 .DS |
|
2258 \f(CWDwarf_Signed lcnt; |
|
2259 Dwarf_Locdesc *llbuf; |
|
2260 int lres; |
|
2261 /* Example with an empty buffer here. */ |
|
2262 Dwarf_Ptr data = ""; |
|
2263 Dwarf_Unsigned len = 0; |
|
2264 |
|
2265 lres = dwarf_loclist_from_expr(data,len, &llbuf,&lcnt, &error); |
|
2266 if (lres == DW_DLV_OK) { |
|
2267 /* lcnt is always 1 */ |
|
2268 |
|
2269 /* Use llbuf here.*/ |
|
2270 |
|
2271 dwarf_dealloc(dbg, llbuf->ld_s, DW_DLA_LOC_BLOCK); |
|
2272 dwarf_dealloc(dbg, llbuf, DW_DLA_LOCDESC); |
|
2273 |
|
2274 }\fP |
|
2275 .DE |
|
2276 .in -2 |
|
2277 .P |
|
2278 |
|
2279 |
|
2280 .P |
|
2281 .H 2 "Line Number Operations" |
|
2282 These functions are concerned with accessing line number entries, |
|
2283 mapping debugging information entry objects to their corresponding |
|
2284 source lines, and providing a mechanism for obtaining information |
|
2285 about line number entries. Although, the interface talks of "lines" |
|
2286 what is really meant is "statements". In case there is more than |
|
2287 one statement on the same line, there will be at least one descriptor |
|
2288 per statement, all with the same line number. If column number is |
|
2289 also being represented they will have the column numbers of the start |
|
2290 of the statements also represented. |
|
2291 .P |
|
2292 There can also be more than one Dwarf_Line per statement. |
|
2293 For example, if a file is preprocessed by a language translator, |
|
2294 this could result in translator output showing 2 or more sets of line |
|
2295 numbers per translated line of output. |
|
2296 |
|
2297 .H 3 "Get A Set of Lines" |
|
2298 The function returns information about every source line for a |
|
2299 particular compilation-unit. |
|
2300 The compilation-unit is specified |
|
2301 by the corresponding die. |
|
2302 .H 4 "dwarf_srclines()" |
|
2303 .DS |
|
2304 \f(CWint dwarf_srclines( |
|
2305 Dwarf_Die die, |
|
2306 Dwarf_Line **linebuf, |
|
2307 Dwarf_Signed *linecount, |
|
2308 Dwarf_Error *error)\fP |
|
2309 .DE |
|
2310 The function \f(CWdwarf_srclines()\fP places all line number descriptors |
|
2311 for a single compilation unit into a single block, sets \f(CW*linebuf\fP |
|
2312 to point to that block, |
|
2313 sets \f(CW*linecount\fP to the number of descriptors in this block |
|
2314 and returns \f(CWDW_DLV_OK\fP. |
|
2315 The compilation-unit is indicated by the given \f(CWdie\fP which must be |
|
2316 a compilation-unit die. |
|
2317 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2318 On |
|
2319 successful return, line number information |
|
2320 should be free'd using \f(CWdwarf_srclines_dealloc()\fP |
|
2321 when no longer of interest. |
|
2322 .P |
|
2323 .in +2 |
|
2324 .DS |
|
2325 \f(CWDwarf_Signed cnt; |
|
2326 Dwarf_Line *linebuf; |
|
2327 int sres; |
|
2328 |
|
2329 sres = dwarf_srclines(somedie, &linebuf,&cnt, &error); |
|
2330 if (sres == DW_DLV_OK) { |
|
2331 for (i = 0; i < cnt; ++i) { |
|
2332 /* use linebuf[i] */ |
|
2333 } |
|
2334 dwarf_srclines_dealloc(dbg, linebuf, cnt); |
|
2335 }\fP |
|
2336 .DE |
|
2337 |
|
2338 .in -2 |
|
2339 .P |
|
2340 The following dealloc code (the only documented method before July 2005) |
|
2341 still works, but does not completely free all data allocated. |
|
2342 The \f(CWdwarf_srclines_dealloc()\fP routine was created |
|
2343 to fix the problem of incomplete deallocation. |
|
2344 .P |
|
2345 .in +2 |
|
2346 .DS |
|
2347 \f(CWDwarf_Signed cnt; |
|
2348 Dwarf_Line *linebuf; |
|
2349 int sres; |
|
2350 |
|
2351 sres = dwarf_srclines(somedie, &linebuf,&cnt, &error); |
|
2352 if (sres == DW_DLV_OK) { |
|
2353 for (i = 0; i < cnt; ++i) { |
|
2354 /* use linebuf[i] */ |
|
2355 dwarf_dealloc(dbg, linebuf[i], DW_DLA_LINE); |
|
2356 } |
|
2357 dwarf_dealloc(dbg, linebuf, DW_DLA_LIST); |
|
2358 }\fP |
|
2359 .DE |
|
2360 .in -2 |
|
2361 |
|
2362 .H 3 "Get the set of Source File Names" |
|
2363 |
|
2364 The function returns the names of the source files that have contributed |
|
2365 to the compilation-unit represented by the given DIE. Only the source |
|
2366 files named in the statement program prologue are returned. |
|
2367 |
|
2368 |
|
2369 .DS |
|
2370 \f(CWint dwarf_srcfiles( |
|
2371 Dwarf_Die die, |
|
2372 char ***srcfiles, |
|
2373 Dwarf_Signed *srccount, |
|
2374 Dwarf_Error *error)\fP |
|
2375 .DE |
|
2376 When it succeeds |
|
2377 \f(CWdwarf_srcfiles()\fP returns |
|
2378 \f(CWDW_DLV_OK\fP |
|
2379 and |
|
2380 puts |
|
2381 the number of source |
|
2382 files named in the statement program prologue indicated by the given |
|
2383 \f(CWdie\fP |
|
2384 into \f(CW*srccount\fP. |
|
2385 Source files defined in the statement program are ignored. |
|
2386 The given \f(CWdie\fP should have the tag \f(CWDW_TAG_compile_unit\fP. |
|
2387 The location pointed to by \f(CWsrcfiles\fP is set to point to a list |
|
2388 of pointers to null-terminated strings that name the source |
|
2389 files. |
|
2390 On a successful return from this function, each of the |
|
2391 strings returned should be individually free'd using \f(CWdwarf_dealloc()\fP |
|
2392 with the allocation type \f(CWDW_DLA_STRING\fP when no longer of |
|
2393 interest. |
|
2394 This should be followed by free-ing the list using |
|
2395 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_LIST\fP. |
|
2396 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2397 It returns \f(CWDW_DLV_NO_ENTRY\fP |
|
2398 if there is no |
|
2399 corresponding statement program (i.e., if there is no line information). |
|
2400 .in +2 |
|
2401 .DS |
|
2402 \f(CWDwarf_Signed cnt; |
|
2403 char **srcfiles; |
|
2404 int res; |
|
2405 |
|
2406 res = dwarf_srcfiles(somedie, &srcfiles,&cnt &error); |
|
2407 if (res == DW_DLV_OK) { |
|
2408 |
|
2409 for (i = 0; i < cnt; ++i) { |
|
2410 /* use srcfiles[i] */ |
|
2411 dwarf_dealloc(dbg, srcfiles[i], DW_DLA_STRING); |
|
2412 } |
|
2413 dwarf_dealloc(dbg, srcfiles, DW_DLA_LIST); |
|
2414 }\fP |
|
2415 .DE |
|
2416 .in -2 |
|
2417 .H 3 "Get information about a Single Table Line" |
|
2418 The following functions can be used on the \f(CWDwarf_Line\fP descriptors |
|
2419 returned by \f(CWdwarf_srclines()\fP to obtain information about the |
|
2420 source lines. |
|
2421 |
|
2422 .H 4 "dwarf_linebeginstatement()" |
|
2423 .DS |
|
2424 \f(CWint dwarf_linebeginstatement( |
|
2425 Dwarf_Line line, |
|
2426 Dwarf_Bool *return_bool, |
|
2427 Dwarf_Error *error)\fP |
|
2428 .DE |
|
2429 The function \f(CWdwarf_linebeginstatement()\fP returns |
|
2430 \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP |
|
2431 to |
|
2432 \fInon-zero\fP |
|
2433 (if \f(CWline\fP represents a line number entry that is marked as |
|
2434 beginning a statement). |
|
2435 or |
|
2436 \fIzero\fP ((if \f(CWline\fP represents a line number entry |
|
2437 that is not marked as beginning a statement). |
|
2438 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2439 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2440 |
|
2441 .P |
|
2442 .H 4 "dwarf_lineendsequence()" |
|
2443 .DS |
|
2444 \f(CWint dwarf_lineendsequence( |
|
2445 Dwarf_Line line, |
|
2446 Dwarf_Bool *return_bool, |
|
2447 Dwarf_Error *error)\fP |
|
2448 .DE |
|
2449 The function \f(CWdwarf_lineendsequence()\fP returns |
|
2450 \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP |
|
2451 \fInon-zero\fP |
|
2452 (in which case |
|
2453 \f(CWline\fP represents a line number entry that is marked as |
|
2454 ending a text sequence) |
|
2455 or |
|
2456 \fIzero\fP (in which case |
|
2457 \f(CWline\fP represents a line number entry |
|
2458 that is not marked as ending a text sequence). |
|
2459 A line number entry that is marked as |
|
2460 ending a text sequence is an entry with an address |
|
2461 one beyond the highest address used by the current |
|
2462 sequence of line table entries (that is, the table entry is |
|
2463 a DW_LNE_end_sequence entry (see the DWARF specification)). |
|
2464 .P |
|
2465 The function \f(CWdwarf_lineendsequence()\fP |
|
2466 returns \f(CWDW_DLV_ERROR\fP on error. |
|
2467 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2468 |
|
2469 .P |
|
2470 .H 4 "dwarf_lineno()" |
|
2471 .DS |
|
2472 \f(CWint dwarf_lineno( |
|
2473 Dwarf_Line line, |
|
2474 Dwarf_Unsigned * returned_lineno, |
|
2475 Dwarf_Error * error)\fP |
|
2476 .DE |
|
2477 The function \f(CWdwarf_lineno()\fP returns |
|
2478 \f(CWDW_DLV_OK\fP and sets \f(CW*return_lineno\fP to |
|
2479 the source statement line |
|
2480 number corresponding to the descriptor \f(CWline\fP. |
|
2481 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2482 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2483 |
|
2484 .P |
|
2485 .H 4 "dwarf_line_srcfileno()" |
|
2486 .DS |
|
2487 \f(CWint dwarf_line_srcfileno( |
|
2488 Dwarf_Line line, |
|
2489 Dwarf_Unsigned * returned_fileno, |
|
2490 Dwarf_Error * error)\fP |
|
2491 .DE |
|
2492 The function \f(CWdwarf_line_srcfileno()\fP returns |
|
2493 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_fileno\fP to |
|
2494 the source statement line |
|
2495 number corresponding to the descriptor \f(CWfile number\fP. |
|
2496 When the number returned thru \f(CW*returned_fileno\fP is zero it means |
|
2497 the file name is unknown (see the DWARF2/3 line table specification). |
|
2498 When the number returned thru \f(CW*returned_fileno\fP is non-zero |
|
2499 it is a file number: |
|
2500 subtract 1 from this file number |
|
2501 to get an |
|
2502 index into the array of strings returned by \f(CWdwarf_srcfiles()\fP |
|
2503 (verify the resulting index is in range for the array of strings |
|
2504 before indexing into the array of strings). |
|
2505 The file number may exceed the size of |
|
2506 the array of strings returned by \f(CWdwarf_srcfiles()\fP |
|
2507 because \f(CWdwarf_srcfiles()\fP does not return files names defined with |
|
2508 the \f(CWDW_DLE_define_file\fP operator. |
|
2509 The function \f(CWdwarf_line_srcfileno()\fP returns \f(CWDW_DLV_ERROR\fP on error. |
|
2510 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2511 |
|
2512 .P |
|
2513 .H 4 "dwarf_lineaddr()" |
|
2514 .DS |
|
2515 \f(CWint dwarf_lineaddr( |
|
2516 Dwarf_Line line, |
|
2517 Dwarf_Addr *return_lineaddr, |
|
2518 Dwarf_Error *error)\fP |
|
2519 .DE |
|
2520 The function \f(CWdwarf_lineaddr()\fP returns |
|
2521 \f(CWDW_DLV_OK\fP and sets \f(CW*return_lineaddr\fP to |
|
2522 the address associated |
|
2523 with the descriptor \f(CWline\fP. |
|
2524 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2525 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2526 |
|
2527 .P |
|
2528 .H 4 "dwarf_lineoff()" |
|
2529 .DS |
|
2530 \f(CWint dwarf_lineoff( |
|
2531 Dwarf_Line line, |
|
2532 Dwarf_Signed * return_lineoff, |
|
2533 Dwarf_Error *error)\fP |
|
2534 .DE |
|
2535 The function \f(CWdwarf_lineoff()\fP returns |
|
2536 \f(CWDW_DLV_OK\fP and sets \f(CW*return_lineoff\fP to |
|
2537 the column number at which |
|
2538 the statement represented by \f(CWline\fP begins. |
|
2539 It sets \f(CWreturn_lineoff\fP to \fI-1\fP |
|
2540 if the column number of the statement is not represented |
|
2541 (meaning the producer library call was given zero |
|
2542 as the column number). |
|
2543 .P |
|
2544 On error it returns \f(CWDW_DLV_ERROR\fP. |
|
2545 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2546 |
|
2547 .H 4 "dwarf_linesrc()" |
|
2548 .DS |
|
2549 \f(CWint dwarf_linesrc( |
|
2550 Dwarf_Line line, |
|
2551 char ** return_linesrc, |
|
2552 Dwarf_Error *error)\fP |
|
2553 .DE |
|
2554 The function \f(CWdwarf_linesrc()\fP returns |
|
2555 \f(CWDW_DLV_OK\fP and sets \f(CW*return_linesrc\fP to |
|
2556 a pointer to a |
|
2557 null-terminated string of characters that represents the name of the |
|
2558 source-file where \f(CWline\fP occurs. |
|
2559 It returns \f(CWDW_DLV_ERROR\fP on |
|
2560 error. |
|
2561 .P |
|
2562 If the applicable file name in the line table Statement Program Prolog |
|
2563 does not start with a '/' character |
|
2564 the string in \f(CWDW_AT_comp_dir\fP (if applicable and present) |
|
2565 or the applicable |
|
2566 directory name from the line Statement Program Prolog |
|
2567 is prepended to the |
|
2568 file name in the line table Statement Program Prolog |
|
2569 to make a full path. |
|
2570 .P |
|
2571 The storage pointed to by a successful return of |
|
2572 \f(CWdwarf_linesrc()\fP should be free'd using \f(CWdwarf_dealloc()\fP with |
|
2573 the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
2574 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2575 |
|
2576 .H 4 "dwarf_lineblock()" |
|
2577 .DS |
|
2578 \f(CWint dwarf_lineblock( |
|
2579 Dwarf_Line line, |
|
2580 Dwarf_Bool *return_bool, |
|
2581 Dwarf_Error *error)\fP |
|
2582 .DE |
|
2583 The function |
|
2584 \f(CWdwarf_lineblock()\fP returns |
|
2585 \f(CWDW_DLV_OK\fP and sets \f(CW*return_linesrc\fP to |
|
2586 non-zero (i.e. true)(if the line is marked as |
|
2587 beginning a basic block) |
|
2588 or zero (i.e. false) (if the line is marked as not |
|
2589 beginning a basic block). |
|
2590 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2591 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2592 |
|
2593 .\"#if 0 |
|
2594 .\".H 3 "Finding a Line Given A PC value" |
|
2595 .\"This is a 'higher level' (High-level) interface to line information. |
|
2596 .\" |
|
2597 .\".DS |
|
2598 .\"\f(CWint dwarf_pclines( |
|
2599 .\" Dwarf_Debug dbg, |
|
2600 .\" Dwarf_Addr pc, |
|
2601 .\" Dwarf_Line **linebuf, |
|
2602 .\" Dwarf_Signed slide, |
|
2603 .\" Dwarf_Signed *linecount, |
|
2604 .\" Dwarf_Error *error)\fP |
|
2605 .\".DE |
|
2606 .\"The function \f(CWdwarf_pclines()\fP places all line number descriptors |
|
2607 .\"that correspond to the value of \f(CWpc\fP into a single block and sets |
|
2608 .\"\f(CWlinebuf\fP to point to that block. A count of the number of |
|
2609 .\"\f(CWDwarf_Line\fP descriptors that are in this block is returned. For |
|
2610 .\"most cases, the count returned will be \fIone\fP, though it may be higher |
|
2611 .\"if optimizations such as common subexpression elimination result in multiple |
|
2612 .\"line number entries for a given value of \f(CWpc\fP. The \f(CWslide\fP |
|
2613 .\"argument specifies the direction to search for the nearest line number |
|
2614 .\"entry in the event that there is no line number entry that contains an |
|
2615 .\"exact match for \f(CWpc\fP. This argument may be one of: |
|
2616 .\"\f(CWDLS_BACKWARD\fP, \f(CWDLS_NOSLIDE\fP, \f(CWDLS_FORWARD\fP. |
|
2617 .\"\f(CWDW_DLV_NOCOUNT\fP is returned on error. On successful return, each |
|
2618 .\"line information structure pointed to by an entry in the block should be |
|
2619 .\"free'd using \f(CWdwarf_dealloc()\fP with the allocation type |
|
2620 .\"\f(CWDW_DLA_LINE\fP when no longer of interest. The block itself should |
|
2621 .\"be free'd using \f(CWdwarf_dealloc()\fP with the allocation type |
|
2622 .\"\f(CWDW_DLA_LIST\fP when no longer of interest. |
|
2623 .\"#endif |
|
2624 |
|
2625 .H 2 "Global Name Space Operations" |
|
2626 These operations operate on the .debug_pubnames section of the debugging |
|
2627 information. |
|
2628 |
|
2629 .H 3 "Debugger Interface Operations" |
|
2630 |
|
2631 .H 4 "dwarf_get_globals()" |
|
2632 .DS |
|
2633 \f(CWint dwarf_get_globals( |
|
2634 Dwarf_Debug dbg, |
|
2635 Dwarf_Global **globals, |
|
2636 Dwarf_Signed * return_count, |
|
2637 Dwarf_Error *error)\fP |
|
2638 .DE |
|
2639 The function \f(CWdwarf_get_globals()\fP returns |
|
2640 \f(CWDW_DLV_OK\fP and sets \f(CW*return_count\fP to |
|
2641 the count of pubnames |
|
2642 represented in the section containing pubnames i.e. .debug_pubnames. |
|
2643 It also stores at \f(CW*globals\fP, a pointer |
|
2644 to a list of \f(CWDwarf_Global\fP descriptors, one for each of the |
|
2645 pubnames in the .debug_pubnames section. |
|
2646 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2647 It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_pubnames |
|
2648 section does not exist. |
|
2649 |
|
2650 .P |
|
2651 On a successful return from |
|
2652 \f(CWdwarf_get_globals()\fP, the \f(CWDwarf_Global\fP |
|
2653 descriptors should be |
|
2654 free'd using \f(CWdwarf_globals_dealloc()\fP. |
|
2655 \f(CWdwarf_globals_dealloc()\fP is new as of July 15, 2005 |
|
2656 and is the preferred approach to freeing this memory.. |
|
2657 |
|
2658 .in +2 |
|
2659 .DS |
|
2660 \f(CWDwarf_Signed cnt; |
|
2661 Dwarf_Global *globs; |
|
2662 int res; |
|
2663 |
|
2664 res = dwarf_get_globals(dbg, &globs,&cnt, &error); |
|
2665 if (res == DW_DLV_OK) { |
|
2666 |
|
2667 for (i = 0; i < cnt; ++i) { |
|
2668 /* use globs[i] */ |
|
2669 } |
|
2670 dwarf_globals_dealloc(dbg, globs, cnt); |
|
2671 }\fP |
|
2672 .DE |
|
2673 .in -2 |
|
2674 |
|
2675 |
|
2676 .P |
|
2677 The following code is deprecated as of July 15, 2005 as it does not |
|
2678 free all relevant memory. |
|
2679 This approach still works as well as it ever did. |
|
2680 On a successful return from |
|
2681 \f(CWdwarf_get_globals()\fP, the \f(CWDwarf_Global\fP |
|
2682 descriptors should be individually |
|
2683 free'd using \f(CWdwarf_dealloc()\fP with the allocation type |
|
2684 \f(CWDW_DLA_GLOBAL_CONTEXT\fP, |
|
2685 (or |
|
2686 \f(CWDW_DLA_GLOBAL\fP, an older name, supported for compatibility) |
|
2687 followed by the deallocation of the list itself |
|
2688 with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are |
|
2689 no longer of interest. |
|
2690 |
|
2691 .in +2 |
|
2692 .DS |
|
2693 \f(CWDwarf_Signed cnt; |
|
2694 Dwarf_Global *globs; |
|
2695 int res; |
|
2696 |
|
2697 res = dwarf_get_globals(dbg, &globs,&cnt, &error); |
|
2698 if (res == DW_DLV_OK) { |
|
2699 |
|
2700 for (i = 0; i < cnt; ++i) { |
|
2701 /* use globs[i] */ |
|
2702 dwarf_dealloc(dbg, globs[i], DW_DLA_GLOBAL_CONTEXT); |
|
2703 } |
|
2704 dwarf_dealloc(dbg, globs, DW_DLA_LIST); |
|
2705 }\fP |
|
2706 .DE |
|
2707 .in -2 |
|
2708 |
|
2709 .H 4 "dwarf_globname()" |
|
2710 .DS |
|
2711 \f(CWint dwarf_globname( |
|
2712 Dwarf_Global global, |
|
2713 char ** return_name, |
|
2714 Dwarf_Error *error)\fP |
|
2715 .DE |
|
2716 The function \f(CWdwarf_globname()\fP returns |
|
2717 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to |
|
2718 a pointer to a |
|
2719 null-terminated string that names the pubname represented by the |
|
2720 \f(CWDwarf_Global\fP descriptor, \f(CWglobal\fP. |
|
2721 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2722 On a successful return from this function, the string should |
|
2723 be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type |
|
2724 \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
2725 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2726 |
|
2727 .H 4 "dwarf_global_die_offset()" |
|
2728 .DS |
|
2729 \f(CWint dwarf_global_die_offset( |
|
2730 Dwarf_Global global, |
|
2731 Dwarf_Off *return_offset, |
|
2732 Dwarf_Error *error)\fP |
|
2733 .DE |
|
2734 The function \f(CWdwarf_global_die_offset()\fP returns |
|
2735 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
2736 the offset in |
|
2737 the section containing DIE's, i.e. .debug_info, of the DIE representing |
|
2738 the pubname that is described by the \f(CWDwarf_Global\fP descriptor, |
|
2739 \f(CWglob\fP. |
|
2740 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2741 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2742 |
|
2743 .H 4 "dwarf_global_cu_offset()" |
|
2744 .DS |
|
2745 \f(CWint dwarf_global_cu_offset( |
|
2746 Dwarf_Global global, |
|
2747 Dwarf_Off *return_offset, |
|
2748 Dwarf_Error *error)\fP |
|
2749 .DE |
|
2750 The function \f(CWdwarf_global_cu_offset()\fP returns |
|
2751 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
2752 the offset in |
|
2753 the section containing DIE's, i.e. .debug_info, of the compilation-unit |
|
2754 header of the compilation-unit that contains the pubname described |
|
2755 by the \f(CWDwarf_Global\fP descriptor, \f(CWglobal\fP. |
|
2756 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2757 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2758 |
|
2759 .H 4 "dwarf_get_cu_die_offset_given_cu_header_offset()" |
|
2760 .DS |
|
2761 \f(CWint dwarf_get_cu_die_offset_given_cu_header_offset( |
|
2762 Dwarf_Debug dbg, |
|
2763 Dwarf_Off in_cu_header_offset, |
|
2764 Dwarf_Off * out_cu_die_offset, |
|
2765 Dwarf_Error *error)\fP |
|
2766 .DE |
|
2767 The function \f(CWdwarf_get_cu_die_offset_given_cu_header_offset()\fP |
|
2768 returns |
|
2769 \f(CWDW_DLV_OK\fP and sets \f(CW*out_cu_die_offset\fP to |
|
2770 the offset of the compilation-unit DIE given the |
|
2771 offset \f(CWin_cu_header_offset\fP of a compilation-unit header. |
|
2772 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2773 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2774 |
|
2775 |
|
2776 This effectively turns a compilation-unit-header offset |
|
2777 into a compilation-unit DIE offset (by adding the |
|
2778 size of the applicable CU header). |
|
2779 This function is also sometimes useful with the |
|
2780 \f(CWdwarf_weak_cu_offset()\fP, |
|
2781 \f(CWdwarf_func_cu_offset()\fP, |
|
2782 \f(CWdwarf_type_cu_offset()\fP, |
|
2783 and |
|
2784 \f(CWint dwarf_var_cu_offset()\fP |
|
2785 functions. |
|
2786 |
|
2787 \f(CWdwarf_get_cu_die_offset_given_cu_header_offset()\fP |
|
2788 added Rev 1.45, June, 2001. |
|
2789 |
|
2790 This function is declared as 'optional' in libdwarf.h |
|
2791 on IRIX systems so the _MIPS_SYMBOL_PRESENT |
|
2792 predicate may be used at run time to determine if the version of |
|
2793 libdwarf linked into an application has this function. |
|
2794 |
|
2795 .H 4 "dwarf_global_name_offsets()" |
|
2796 .DS |
|
2797 \f(CWint dwarf_global_name_offsets( |
|
2798 Dwarf_Global global, |
|
2799 char **return_name, |
|
2800 Dwarf_Off *die_offset, |
|
2801 Dwarf_Off *cu_offset, |
|
2802 Dwarf_Error *error)\fP |
|
2803 .DE |
|
2804 The function \f(CWdwarf_global_name_offsets()\fP returns |
|
2805 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to |
|
2806 a pointer to |
|
2807 a null-terminated string that gives the name of the pubname |
|
2808 described by the \f(CWDwarf_Global\fP descriptor \f(CWglobal\fP. |
|
2809 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2810 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2811 It also returns in the locations |
|
2812 pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets |
|
2813 of the DIE representing the |
|
2814 pubname, and the DIE |
|
2815 representing the compilation-unit containing the |
|
2816 pubname, respectively. |
|
2817 On a |
|
2818 successful return from \f(CWdwarf_global_name_offsets()\fP the storage |
|
2819 pointed to by \f(CWreturn_name\fP |
|
2820 should be free'd using \f(CWdwarf_dealloc()\fP, |
|
2821 with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
2822 |
|
2823 |
|
2824 .H 2 "DWARF3 Type Names Operations" |
|
2825 Section ".debug_pubtypes" is new in DWARF3. |
|
2826 .P |
|
2827 These functions operate on the .debug_pubtypes section of the debugging |
|
2828 information. The .debug_pubtypes section contains the names of file-scope |
|
2829 user-defined types, the offsets of the \f(CWDIE\fPs that represent the |
|
2830 definitions of those types, and the offsets of the compilation-units |
|
2831 that contain the definitions of those types. |
|
2832 |
|
2833 .H 3 "Debugger Interface Operations" |
|
2834 |
|
2835 .H 4 "dwarf_get_pubtypes()" |
|
2836 .DS |
|
2837 \f(CWint dwarf_get_pubtypes( |
|
2838 Dwarf_Debug dbg, |
|
2839 Dwarf_Type **types, |
|
2840 Dwarf_Signed *typecount, |
|
2841 Dwarf_Error *error)\fP |
|
2842 .DE |
|
2843 The function \f(CWdwarf_get_pubtypes()\fP returns |
|
2844 \f(CWDW_DLV_OK\fP and sets \f(CW*typecount\fP to |
|
2845 the count of user-defined |
|
2846 type names represented in the section containing user-defined type names, |
|
2847 i.e. .debug_pubtypes. |
|
2848 It also stores at \f(CW*types\fP, |
|
2849 a pointer to a list of \f(CWDwarf_Pubtype\fP descriptors, one for each of the |
|
2850 user-defined type names in the .debug_pubtypes section. |
|
2851 It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
2852 It returns \f(CWDW_DLV_NO_ENTRY\fP if |
|
2853 the .debug_pubtypes section does not exist. |
|
2854 |
|
2855 .P |
|
2856 On a successful |
|
2857 return from \f(CWdwarf_get_pubtypes()\fP, |
|
2858 the \f(CWDwarf_Type\fP descriptors should be |
|
2859 free'd using \f(CWdwarf_types_dealloc()\fP. |
|
2860 \f(CWdwarf_types_dealloc()\fP is used for both |
|
2861 \f(CWdwarf_get_pubtypes()\fP and \f(CWdwarf_get_types()\fP |
|
2862 as the data types are the same. |
|
2863 |
|
2864 .in +2 |
|
2865 .DS |
|
2866 \f(CWDwarf_Signed cnt; |
|
2867 Dwarf_Pubtype *types; |
|
2868 int res; |
|
2869 |
|
2870 res = dwarf_get_pubtypes(dbg, &types,&cnt, &error); |
|
2871 if (res == DW_DLV_OK) { |
|
2872 |
|
2873 for (i = 0; i < cnt; ++i) { |
|
2874 /* use types[i] */ |
|
2875 } |
|
2876 dwarf_types_dealloc(dbg, types, cnt); |
|
2877 }\fP |
|
2878 .DE |
|
2879 .in -2 |
|
2880 |
|
2881 .H 4 "dwarf_pubtypename()" |
|
2882 .DS |
|
2883 \f(CWint dwarf_pubtypename( |
|
2884 Dwarf_Pubtype type, |
|
2885 char **return_name, |
|
2886 Dwarf_Error *error)\fP |
|
2887 .DE |
|
2888 The function \f(CWdwarf_pubtypename()\fP returns |
|
2889 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to |
|
2890 a pointer to a |
|
2891 null-terminated string that names the user-defined type represented by the |
|
2892 \f(CWDwarf_Pubtype\fP descriptor, \f(CWtype\fP. |
|
2893 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2894 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2895 On a successful return from this function, the string should |
|
2896 be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type |
|
2897 \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
2898 |
|
2899 .H 4 "dwarf_pubtype_die_offset()" |
|
2900 .DS |
|
2901 \f(CWint dwarf_pubtype_die_offset( |
|
2902 Dwarf_Pubtype type, |
|
2903 Dwarf_Off *return_offset, |
|
2904 Dwarf_Error *error)\fP |
|
2905 .DE |
|
2906 The function \f(CWdwarf_pubtype_die_offset()\fP returns |
|
2907 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
2908 the offset in |
|
2909 the section containing DIE's, i.e. .debug_info, of the DIE representing |
|
2910 the user-defined type that is described by the \f(CWDwarf_Pubtype\fP |
|
2911 descriptor, \f(CWtype\fP. |
|
2912 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2913 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2914 |
|
2915 .H 4 "dwarf_pubtype_cu_offset()" |
|
2916 .DS |
|
2917 \f(CWint dwarf_pubtype_cu_offset( |
|
2918 Dwarf_Pubtype type, |
|
2919 Dwarf_Off *return_offset, |
|
2920 Dwarf_Error *error)\fP |
|
2921 .DE |
|
2922 The function \f(CWdwarf_pubtype_cu_offset()\fP returns |
|
2923 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
2924 the offset in |
|
2925 the section containing DIE's, i.e. .debug_info, of the compilation-unit |
|
2926 header of the compilation-unit that contains the user-defined type |
|
2927 described by the \f(CWDwarf_Pubtype\fP descriptor, \f(CWtype\fP. |
|
2928 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2929 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2930 |
|
2931 .H 4 "dwarf_pubtype_name_offsets()" |
|
2932 .DS |
|
2933 \f(CWint dwarf_pubtype_name_offsets( |
|
2934 Dwarf_Pubtype type, |
|
2935 char ** returned_name, |
|
2936 Dwarf_Off * die_offset, |
|
2937 Dwarf_Off * cu_offset, |
|
2938 Dwarf_Error *error)\fP |
|
2939 .DE |
|
2940 The function \f(CWdwarf_pubtype_name_offsets()\fP returns |
|
2941 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to |
|
2942 a pointer to |
|
2943 a null-terminated string that gives the name of the user-defined |
|
2944 type described by the \f(CWDwarf_Pubtype\fP descriptor \f(CWtype\fP. |
|
2945 It also returns in the locations |
|
2946 pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets |
|
2947 of the DIE representing the |
|
2948 user-defined type, and the DIE |
|
2949 representing the compilation-unit containing the |
|
2950 user-defined type, respectively. |
|
2951 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2952 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
2953 On a successful return from \f(CWdwarf_pubtype_name_offsets()\fP |
|
2954 the storage pointed to by \f(CWreturned_name\fP should |
|
2955 be free'd using |
|
2956 \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP |
|
2957 when no longer of interest. |
|
2958 |
|
2959 |
|
2960 .H 2 "User Defined Static Variable Names Operations" |
|
2961 This section is SGI specific and is not part of standard DWARF version 2. |
|
2962 .P |
|
2963 These functions operate on the .debug_varnames section of the debugging |
|
2964 information. The .debug_varnames section contains the names of file-scope |
|
2965 static variables, the offsets of the \f(CWDIE\fPs that represent the |
|
2966 definitions of those variables, and the offsets of the compilation-units |
|
2967 that contain the definitions of those variables. |
|
2968 .P |
|
2969 |
|
2970 |
|
2971 .H 2 "Weak Name Space Operations" |
|
2972 These operations operate on the .debug_weaknames section of the debugging |
|
2973 information. |
|
2974 .P |
|
2975 These operations are SGI specific, not part of standard DWARF. |
|
2976 .P |
|
2977 |
|
2978 .H 3 "Debugger Interface Operations" |
|
2979 |
|
2980 .H 4 "dwarf_get_weaks()" |
|
2981 .DS |
|
2982 \f(CWint dwarf_get_weaks( |
|
2983 Dwarf_Debug dbg, |
|
2984 Dwarf_Weak **weaks, |
|
2985 Dwarf_Signed *weak_count, |
|
2986 Dwarf_Error *error)\fP |
|
2987 .DE |
|
2988 The function \f(CWdwarf_get_weaks()\fP returns |
|
2989 \f(CWDW_DLV_OK\fP and sets \f(CW*weak_count\fP to |
|
2990 the count of weak names |
|
2991 represented in the section containing weak names i.e. .debug_weaknames. |
|
2992 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
2993 It returns \f(CWDW_DLV_NO_ENTRY\fP if the section does not exist. |
|
2994 It also stores in \f(CW*weaks\fP, a pointer to |
|
2995 a list of \f(CWDwarf_Weak\fP descriptors, one for each of the weak names |
|
2996 in the .debug_weaknames section. |
|
2997 |
|
2998 .P |
|
2999 On a successful return from this function, |
|
3000 the \f(CWDwarf_Weak\fP descriptors should be free'd using |
|
3001 \f(CWdwarf_weaks_dealloc()\fP when the data is no longer of |
|
3002 interest. \f(CWdwarf_weaks_dealloc()\fPis new as of July 15, 2005. |
|
3003 |
|
3004 .in +2 |
|
3005 .DS |
|
3006 \f(CWDwarf_Signed cnt; |
|
3007 Dwarf_Weak *weaks; |
|
3008 int res; |
|
3009 |
|
3010 res = dwarf_get_weaks(dbg, &weaks,&cnt, &error); |
|
3011 if (res == DW_DLV_OK) { |
|
3012 |
|
3013 for (i = 0; i < cnt; ++i) { |
|
3014 /* use weaks[i] */ |
|
3015 } |
|
3016 dwarf_weaks_dealloc(dbg, weaks, cnt); |
|
3017 }\fP |
|
3018 .DE |
|
3019 .in -2 |
|
3020 |
|
3021 |
|
3022 |
|
3023 .P |
|
3024 The following code is deprecated as of July 15, 2005 as it does not |
|
3025 free all relevant memory. |
|
3026 This approach still works as well as it ever did. |
|
3027 On a successful return from \f(CWdwarf_get_weaks()\fP |
|
3028 the \f(CWDwarf_Weak\fP descriptors should be individually free'd using |
|
3029 \f(CWdwarf_dealloc()\fP with the allocation type |
|
3030 \f(CWDW_DLA_WEAK_CONTEXT\fP, |
|
3031 (or |
|
3032 \f(CWDW_DLA_WEAK\fP, an older name, supported for compatibility) |
|
3033 followed by the deallocation of the list itself with the allocation type |
|
3034 \f(CWDW_DLA_LIST\fP when the descriptors are no longer of interest. |
|
3035 |
|
3036 .in +2 |
|
3037 .DS |
|
3038 \f(CWDwarf_Signed cnt; |
|
3039 Dwarf_Weak *weaks; |
|
3040 int res; |
|
3041 |
|
3042 res = dwarf_get_weaks(dbg, &weaks,&cnt, &error); |
|
3043 if (res == DW_DLV_OK) { |
|
3044 |
|
3045 for (i = 0; i < cnt; ++i) { |
|
3046 /* use weaks[i] */ |
|
3047 dwarf_dealloc(dbg, weaks[i], DW_DLA_WEAK_CONTEXT); |
|
3048 } |
|
3049 dwarf_dealloc(dbg, weaks, DW_DLA_LIST); |
|
3050 }\fP |
|
3051 .DE |
|
3052 .in -2 |
|
3053 |
|
3054 .H 4 "dwarf_weakname()" |
|
3055 .DS |
|
3056 \f(CWint dwarf_weakname( |
|
3057 Dwarf_Weak weak, |
|
3058 char ** return_name, |
|
3059 Dwarf_Error *error)\fP |
|
3060 .DE |
|
3061 The function \f(CWdwarf_weakname()\fP returns |
|
3062 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to |
|
3063 a pointer to a null-terminated |
|
3064 string that names the weak name represented by the |
|
3065 \f(CWDwarf_Weak\fP descriptor, \f(CWweak\fP. |
|
3066 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3067 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3068 On a successful return from this function, the string should |
|
3069 be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type |
|
3070 \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
3071 |
|
3072 .DS |
|
3073 \f(CWint dwarf_weak_die_offset( |
|
3074 Dwarf_Weak weak, |
|
3075 Dwarf_Off *return_offset, |
|
3076 Dwarf_Error *error)\fP |
|
3077 .DE |
|
3078 The function \f(CWdwarf_weak_die_offset()\fP returns |
|
3079 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in |
|
3080 the section containing DIE's, i.e. .debug_info, of the DIE representing |
|
3081 the weak name that is described by the \f(CWDwarf_Weak\fP descriptor, |
|
3082 \f(CWweak\fP. |
|
3083 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3084 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3085 |
|
3086 .H 4 "dwarf_weak_cu_offset()" |
|
3087 .DS |
|
3088 \f(CWint dwarf_weak_cu_offset( |
|
3089 Dwarf_Weak weak, |
|
3090 Dwarf_Off *return_offset, |
|
3091 Dwarf_Error *error)\fP |
|
3092 .DE |
|
3093 The function \f(CWdwarf_weak_cu_offset()\fP returns |
|
3094 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in |
|
3095 the section containing DIE's, i.e. .debug_info, of the compilation-unit |
|
3096 header of the compilation-unit that contains the weak name described |
|
3097 by the \f(CWDwarf_Weak\fP descriptor, \f(CWweak\fP. |
|
3098 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3099 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3100 |
|
3101 .H 4 "dwarf_weak_name_offsets()" |
|
3102 .DS |
|
3103 \f(CWint dwarf_weak_name_offsets( |
|
3104 Dwarf_Weak weak, |
|
3105 char ** weak_name, |
|
3106 Dwarf_Off *die_offset, |
|
3107 Dwarf_Off *cu_offset, |
|
3108 Dwarf_Error *error)\fP |
|
3109 .DE |
|
3110 The function \f(CWdwarf_weak_name_offsets()\fP returns |
|
3111 \f(CWDW_DLV_OK\fP and sets \f(CW*weak_name\fP to |
|
3112 a pointer to |
|
3113 a null-terminated string that gives the name of the weak name |
|
3114 described by the \f(CWDwarf_Weak\fP descriptor \f(CWweak\fP. |
|
3115 It also returns in the locations |
|
3116 pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets |
|
3117 of the DIE representing the |
|
3118 weakname, and the DIE |
|
3119 representing the compilation-unit containing the |
|
3120 weakname, respectively. |
|
3121 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3122 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3123 On a |
|
3124 successful return from \f(CWdwarf_weak_name_offsets()\fP the storage |
|
3125 pointed to by \f(CWweak_name\fP |
|
3126 should be free'd using \f(CWdwarf_dealloc()\fP, |
|
3127 with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
3128 |
|
3129 .H 2 "Static Function Names Operations" |
|
3130 This section is SGI specific and is not part of standard DWARF version 2. |
|
3131 .P |
|
3132 These function operate on the .debug_funcnames section of the debugging |
|
3133 information. The .debug_funcnames section contains the names of static |
|
3134 functions defined in the object, the offsets of the \f(CWDIE\fPs that |
|
3135 represent the definitions of the corresponding functions, and the offsets |
|
3136 of the start of the compilation-units that contain the definitions of |
|
3137 those functions. |
|
3138 |
|
3139 .H 3 "Debugger Interface Operations" |
|
3140 |
|
3141 .H 4 "dwarf_get_funcs()" |
|
3142 .DS |
|
3143 \f(CWint dwarf_get_funcs( |
|
3144 Dwarf_Debug dbg, |
|
3145 Dwarf_Func **funcs, |
|
3146 Dwarf_Signed *func_count, |
|
3147 Dwarf_Error *error)\fP |
|
3148 .DE |
|
3149 The function \f(CWdwarf_get_funcs()\fP returns |
|
3150 \f(CWDW_DLV_OK\fP and sets \f(CW*func_count\fP to |
|
3151 the count of static |
|
3152 function names represented in the section containing static function |
|
3153 names, i.e. .debug_funcnames. |
|
3154 It also |
|
3155 stores, at \f(CW*funcs\fP, a pointer to a list of \f(CWDwarf_Func\fP |
|
3156 descriptors, one for each of the static functions in the .debug_funcnames |
|
3157 section. |
|
3158 It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
3159 It returns \f(CWDW_DLV_NO_ENTRY\fP |
|
3160 if the .debug_funcnames section does not exist. |
|
3161 .P |
|
3162 On a successful return from \f(CWdwarf_get_funcs()\fP, |
|
3163 the \f(CWDwarf_Func\fP |
|
3164 descriptors should be free'd using \f(CWdwarf_funcs_dealloc()\fP. |
|
3165 \f(CWdwarf_funcs_dealloc()\fP is new as of July 15, 2005. |
|
3166 |
|
3167 .in +2 |
|
3168 .DS |
|
3169 \f(CWDwarf_Signed cnt; |
|
3170 Dwarf_Func *funcs; |
|
3171 int fres; |
|
3172 |
|
3173 fres = dwarf_get_funcs(dbg, &funcs, &error); |
|
3174 if (fres == DW_DLV_OK) { |
|
3175 |
|
3176 for (i = 0; i < cnt; ++i) { |
|
3177 /* use funcs[i] */ |
|
3178 } |
|
3179 dwarf_funcs_dealloc(dbg, funcs, cnt); |
|
3180 }\fP |
|
3181 .DE |
|
3182 .in -2 |
|
3183 |
|
3184 |
|
3185 .P |
|
3186 The following code is deprecated as of July 15, 2005 as it does not |
|
3187 free all relevant memory. |
|
3188 This approach still works as well as it ever did. |
|
3189 On a successful return from \f(CWdwarf_get_funcs()\fP, |
|
3190 the \f(CWDwarf_Func\fP |
|
3191 descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP |
|
3192 with the allocation type |
|
3193 \f(CWDW_DLA_FUNC_CONTEXT\fP, |
|
3194 (or |
|
3195 \f(CWDW_DLA_FUNC\fP, an older name, supported for compatibility) |
|
3196 followed by the deallocation |
|
3197 of the list itself with the allocation type \f(CWDW_DLA_LIST\fP when |
|
3198 the descriptors are no longer of interest. |
|
3199 |
|
3200 .in +2 |
|
3201 .DS |
|
3202 \f(CWDwarf_Signed cnt; |
|
3203 Dwarf_Func *funcs; |
|
3204 int fres; |
|
3205 |
|
3206 fres = dwarf_get_funcs(dbg, &funcs, &error); |
|
3207 if (fres == DW_DLV_OK) { |
|
3208 |
|
3209 for (i = 0; i < cnt; ++i) { |
|
3210 /* use funcs[i] */ |
|
3211 dwarf_dealloc(dbg, funcs[i], DW_DLA_FUNC_CONTEXT); |
|
3212 } |
|
3213 dwarf_dealloc(dbg, funcs, DW_DLA_LIST); |
|
3214 }\fP |
|
3215 .DE |
|
3216 .in -2 |
|
3217 |
|
3218 .H 4 "dwarf_funcname()" |
|
3219 .DS |
|
3220 \f(CWint dwarf_funcname( |
|
3221 Dwarf_Func func, |
|
3222 char ** return_name, |
|
3223 Dwarf_Error *error)\fP |
|
3224 .DE |
|
3225 The function \f(CWdwarf_funcname()\fP returns |
|
3226 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to |
|
3227 a pointer to a |
|
3228 null-terminated string that names the static function represented by the |
|
3229 \f(CWDwarf_Func\fP descriptor, \f(CWfunc\fP. |
|
3230 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3231 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3232 On a successful return from this function, the string should |
|
3233 be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type |
|
3234 \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
3235 |
|
3236 .H 4 "dwarf_func_die_offset()" |
|
3237 .DS |
|
3238 \f(CWint dwarf_func_die_offset( |
|
3239 Dwarf_Func func, |
|
3240 Dwarf_Off *return_offset, |
|
3241 Dwarf_Error *error)\fP |
|
3242 .DE |
|
3243 The function \f(CWdwarf_func_die_offset()\fP, returns |
|
3244 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
3245 the offset in |
|
3246 the section containing DIE's, i.e. .debug_info, of the DIE representing |
|
3247 the static function that is described by the \f(CWDwarf_Func\fP |
|
3248 descriptor, \f(CWfunc\fP. |
|
3249 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3250 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3251 |
|
3252 .H 4 "dwarf_func_cu_offset()" |
|
3253 .DS |
|
3254 \f(CWint dwarf_func_cu_offset( |
|
3255 Dwarf_Func func, |
|
3256 Dwarf_Off *return_offset, |
|
3257 Dwarf_Error *error)\fP |
|
3258 .DE |
|
3259 The function \f(CWdwarf_func_cu_offset()\fP returns |
|
3260 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
3261 the offset in |
|
3262 the section containing DIE's, i.e. .debug_info, of the compilation-unit |
|
3263 header of the |
|
3264 compilation-unit that contains the static function |
|
3265 described by the \f(CWDwarf_Func\fP descriptor, \f(CWfunc\fP. |
|
3266 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3267 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3268 |
|
3269 .H 4 "dwarf_func_name_offsets()" |
|
3270 .DS |
|
3271 \f(CWint dwarf_func_name_offsets( |
|
3272 Dwarf_Func func, |
|
3273 char **func_name, |
|
3274 Dwarf_Off *die_offset, |
|
3275 Dwarf_Off *cu_offset, |
|
3276 Dwarf_Error *error)\fP |
|
3277 .DE |
|
3278 The function \f(CWdwarf_func_name_offsets()\fP returns |
|
3279 \f(CWDW_DLV_OK\fP and sets \f(CW*func_name\fP to |
|
3280 a pointer to |
|
3281 a null-terminated string that gives the name of the static |
|
3282 function described by the \f(CWDwarf_Func\fP descriptor \f(CWfunc\fP. |
|
3283 It also returns in the locations |
|
3284 pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets |
|
3285 of the DIE representing the |
|
3286 static function, and the DIE |
|
3287 representing the compilation-unit containing the |
|
3288 static function, respectively. |
|
3289 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3290 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3291 On a successful return from \f(CWdwarf_func_name_offsets()\fP |
|
3292 the storage pointed to by \f(CWfunc_name\fP should be free'd using |
|
3293 \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP |
|
3294 when no longer of interest. |
|
3295 |
|
3296 .H 2 "User Defined Type Names Operations" |
|
3297 Section "debug_typenames" is SGI specific |
|
3298 and is not part of standard DWARF version 2. |
|
3299 (However, an identical section is part of DWARF version 3 |
|
3300 named ".debug_pubtypes", see \f(CWdwarf_get_pubtypes()\fP above.) |
|
3301 .P |
|
3302 These functions operate on the .debug_typenames section of the debugging |
|
3303 information. The .debug_typenames section contains the names of file-scope |
|
3304 user-defined types, the offsets of the \f(CWDIE\fPs that represent the |
|
3305 definitions of those types, and the offsets of the compilation-units |
|
3306 that contain the definitions of those types. |
|
3307 |
|
3308 .H 3 "Debugger Interface Operations" |
|
3309 |
|
3310 .H 4 "dwarf_get_types()" |
|
3311 .DS |
|
3312 \f(CWint dwarf_get_types( |
|
3313 Dwarf_Debug dbg, |
|
3314 Dwarf_Type **types, |
|
3315 Dwarf_Signed *typecount, |
|
3316 Dwarf_Error *error)\fP |
|
3317 .DE |
|
3318 The function \f(CWdwarf_get_types()\fP returns |
|
3319 \f(CWDW_DLV_OK\fP and sets \f(CW*typecount\fP to |
|
3320 the count of user-defined |
|
3321 type names represented in the section containing user-defined type names, |
|
3322 i.e. .debug_typenames. |
|
3323 It also stores at \f(CW*types\fP, |
|
3324 a pointer to a list of \f(CWDwarf_Type\fP descriptors, one for each of the |
|
3325 user-defined type names in the .debug_typenames section. |
|
3326 It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
3327 It returns \f(CWDW_DLV_NO_ENTRY\fP if |
|
3328 the .debug_typenames section does not exist. |
|
3329 |
|
3330 .P |
|
3331 |
|
3332 On a successful |
|
3333 return from \f(CWdwarf_get_types()\fP, |
|
3334 the \f(CWDwarf_Type\fP descriptors should be |
|
3335 free'd using \f(CWdwarf_types_dealloc()\fP. |
|
3336 \f(CWdwarf_types_dealloc()\fP is new as of July 15, 2005 |
|
3337 and frees all memory allocated by \f(CWdwarf_get_types()\fP. |
|
3338 |
|
3339 .in +2 |
|
3340 .DS |
|
3341 \f(CWDwarf_Signed cnt; |
|
3342 Dwarf_Type *types; |
|
3343 int res; |
|
3344 |
|
3345 res = dwarf_get_types(dbg, &types,&cnt, &error); |
|
3346 if (res == DW_DLV_OK) { |
|
3347 |
|
3348 for (i = 0; i < cnt; ++i) { |
|
3349 /* use types[i] */ |
|
3350 } |
|
3351 dwarf_types_dealloc(dbg, types, cnt); |
|
3352 }\fP |
|
3353 .DE |
|
3354 .in -2 |
|
3355 |
|
3356 |
|
3357 |
|
3358 .P |
|
3359 The following code is deprecated as of July 15, 2005 as it does not |
|
3360 free all relevant memory. |
|
3361 This approach still works as well as it ever did. |
|
3362 On a successful |
|
3363 return from \f(CWdwarf_get_types()\fP, |
|
3364 the \f(CWDwarf_Type\fP descriptors should be |
|
3365 individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type |
|
3366 \f(CWDW_DLA_TYPENAME_CONTEXT\fP, |
|
3367 (or |
|
3368 \f(CWDW_DLA_TYPENAME\fP, an older name, supported for compatibility) |
|
3369 followed by the deallocation of the list itself |
|
3370 with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no |
|
3371 longer of interest. |
|
3372 |
|
3373 .in +2 |
|
3374 .DS |
|
3375 \f(CWDwarf_Signed cnt; |
|
3376 Dwarf_Type *types; |
|
3377 int res; |
|
3378 |
|
3379 res = dwarf_get_types(dbg, &types,&cnt, &error); |
|
3380 if (res == DW_DLV_OK) { |
|
3381 |
|
3382 for (i = 0; i < cnt; ++i) { |
|
3383 /* use types[i] */ |
|
3384 dwarf_dealloc(dbg, types[i], DW_DLA_TYPENAME_CONTEXT); |
|
3385 } |
|
3386 dwarf_dealloc(dbg, types, DW_DLA_LIST); |
|
3387 }\fP |
|
3388 .DE |
|
3389 .in -2 |
|
3390 |
|
3391 .H 4 "dwarf_typename()" |
|
3392 .DS |
|
3393 \f(CWint dwarf_typename( |
|
3394 Dwarf_Type type, |
|
3395 char **return_name, |
|
3396 Dwarf_Error *error)\fP |
|
3397 .DE |
|
3398 The function \f(CWdwarf_typename()\fP returns |
|
3399 \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to |
|
3400 a pointer to a |
|
3401 null-terminated string that names the user-defined type represented by the |
|
3402 \f(CWDwarf_Type\fP descriptor, \f(CWtype\fP. |
|
3403 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3404 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3405 On a successful return from this function, the string should |
|
3406 be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type |
|
3407 \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
3408 |
|
3409 .H 4 "dwarf_type_die_offset()" |
|
3410 .DS |
|
3411 \f(CWint dwarf_type_die_offset( |
|
3412 Dwarf_Type type, |
|
3413 Dwarf_Off *return_offset, |
|
3414 Dwarf_Error *error)\fP |
|
3415 .DE |
|
3416 The function \f(CWdwarf_type_die_offset()\fP returns |
|
3417 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
3418 the offset in |
|
3419 the section containing DIE's, i.e. .debug_info, of the DIE representing |
|
3420 the user-defined type that is described by the \f(CWDwarf_Type\fP |
|
3421 descriptor, \f(CWtype\fP. |
|
3422 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3423 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3424 |
|
3425 .H 4 "dwarf_type_cu_offset()" |
|
3426 .DS |
|
3427 \f(CWint dwarf_type_cu_offset( |
|
3428 Dwarf_Type type, |
|
3429 Dwarf_Off *return_offset, |
|
3430 Dwarf_Error *error)\fP |
|
3431 .DE |
|
3432 The function \f(CWdwarf_type_cu_offset()\fP returns |
|
3433 \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to |
|
3434 the offset in |
|
3435 the section containing DIE's, i.e. .debug_info, of the compilation-unit |
|
3436 header of the compilation-unit that contains the user-defined type |
|
3437 described by the \f(CWDwarf_Type\fP descriptor, \f(CWtype\fP. |
|
3438 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3439 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3440 |
|
3441 .H 4 "dwarf_type_name_offsets()" |
|
3442 .DS |
|
3443 \f(CWint dwarf_type_name_offsets( |
|
3444 Dwarf_Type type, |
|
3445 char ** returned_name, |
|
3446 Dwarf_Off * die_offset, |
|
3447 Dwarf_Off * cu_offset, |
|
3448 Dwarf_Error *error)\fP |
|
3449 .DE |
|
3450 The function \f(CWdwarf_type_name_offsets()\fP returns |
|
3451 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to |
|
3452 a pointer to |
|
3453 a null-terminated string that gives the name of the user-defined |
|
3454 type described by the \f(CWDwarf_Type\fP descriptor \f(CWtype\fP. |
|
3455 It also returns in the locations |
|
3456 pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets |
|
3457 of the DIE representing the |
|
3458 user-defined type, and the DIE |
|
3459 representing the compilation-unit containing the |
|
3460 user-defined type, respectively. |
|
3461 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3462 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3463 On a successful return from \f(CWdwarf_type_name_offsets()\fP |
|
3464 the storage pointed to by \f(CWreturned_name\fP should |
|
3465 be free'd using |
|
3466 \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP |
|
3467 when no longer of interest. |
|
3468 |
|
3469 |
|
3470 .H 2 "User Defined Static Variable Names Operations" |
|
3471 This section is SGI specific and is not part of standard DWARF version 2. |
|
3472 .P |
|
3473 These functions operate on the .debug_varnames section of the debugging |
|
3474 information. The .debug_varnames section contains the names of file-scope |
|
3475 static variables, the offsets of the \f(CWDIE\fPs that represent the |
|
3476 definitions of those variables, and the offsets of the compilation-units |
|
3477 that contain the definitions of those variables. |
|
3478 .P |
|
3479 |
|
3480 .H 3 "Debugger Interface Operations" |
|
3481 |
|
3482 .H 4 "dwarf_get_vars()" |
|
3483 |
|
3484 .DS |
|
3485 \f(CWint dwarf_get_vars( |
|
3486 Dwarf_Debug dbg, |
|
3487 Dwarf_Var **vars, |
|
3488 Dwarf_Signed *var_count, |
|
3489 Dwarf_Error *error)\fP |
|
3490 .DE |
|
3491 The function \f(CWdwarf_get_vars()\fP returns |
|
3492 \f(CWDW_DLV_OK\fP and sets \f(CW*var_count\fP to |
|
3493 the count of file-scope |
|
3494 static variable names represented in the section containing file-scope |
|
3495 static variable names, i.e. .debug_varnames. |
|
3496 It also stores, at \f(CW*vars\fP, a pointer to a list of |
|
3497 \f(CWDwarf_Var\fP descriptors, one for each of the file-scope static |
|
3498 variable names in the .debug_varnames section. |
|
3499 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3500 It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_varnames section does |
|
3501 not exist. |
|
3502 |
|
3503 .P |
|
3504 The following is new as of July 15, 2005. |
|
3505 On a successful return |
|
3506 from \f(CWdwarf_get_vars()\fP, the \f(CWDwarf_Var\fP descriptors should be |
|
3507 free'd using \f(CWdwarf_vars_dealloc()\fP. |
|
3508 |
|
3509 .in +2 |
|
3510 .DS |
|
3511 \f(CWDwarf_Signed cnt; |
|
3512 Dwarf_Var *vars; |
|
3513 int res; |
|
3514 |
|
3515 res = dwarf_get_vars(dbg, &vars,&cnt &error); |
|
3516 if (res == DW_DLV_OK) { |
|
3517 |
|
3518 for (i = 0; i < cnt; ++i) { |
|
3519 /* use vars[i] */ |
|
3520 } |
|
3521 dwarf_vars_dealloc(dbg, vars, cnt); |
|
3522 }\fP |
|
3523 .DE |
|
3524 .in -2 |
|
3525 |
|
3526 .P |
|
3527 The following code is deprecated as of July 15, 2005 as it does not |
|
3528 free all relevant memory. |
|
3529 This approach still works as well as it ever did. |
|
3530 On a successful return |
|
3531 from \f(CWdwarf_get_vars()\fP, the \f(CWDwarf_Var\fP descriptors should be individually |
|
3532 free'd using \f(CWdwarf_dealloc()\fP with the allocation type |
|
3533 \f(CWDW_DLA_VAR_CONTEXT\fP, |
|
3534 (or |
|
3535 \f(CWDW_DLA_VAR\fP, an older name, supported for compatibility) |
|
3536 followed by the deallocation of the list itself with |
|
3537 the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no |
|
3538 longer of interest. |
|
3539 |
|
3540 .in +2 |
|
3541 .DS |
|
3542 \f(CWDwarf_Signed cnt; |
|
3543 Dwarf_Var *vars; |
|
3544 int res; |
|
3545 |
|
3546 res = dwarf_get_vars(dbg, &vars,&cnt &error); |
|
3547 if (res == DW_DLV_OK) { |
|
3548 |
|
3549 for (i = 0; i < cnt; ++i) { |
|
3550 /* use vars[i] */ |
|
3551 dwarf_dealloc(dbg, vars[i], DW_DLA_VAR_CONTEXT); |
|
3552 } |
|
3553 dwarf_dealloc(dbg, vars, DW_DLA_LIST); |
|
3554 }\fP |
|
3555 .DE |
|
3556 .in -2 |
|
3557 |
|
3558 .H 4 "dwarf_varname()" |
|
3559 .DS |
|
3560 \f(CWint dwarf_varname( |
|
3561 Dwarf_Var var, |
|
3562 char ** returned_name, |
|
3563 Dwarf_Error *error)\fP |
|
3564 .DE |
|
3565 The function \f(CWdwarf_varname()\fP returns |
|
3566 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to |
|
3567 a pointer to a |
|
3568 null-terminated string that names the file-scope static variable represented |
|
3569 by the \f(CWDwarf_Var\fP descriptor, \f(CWvar\fP. |
|
3570 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3571 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3572 On a successful return from this function, the string should |
|
3573 be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type |
|
3574 \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
3575 |
|
3576 .H 4 "dwarf_var_die_offset()" |
|
3577 .DS |
|
3578 \f(CWint dwarf_var_die_offset( |
|
3579 Dwarf_Var var, |
|
3580 Dwarf_Off *returned_offset, |
|
3581 Dwarf_Error *error)\fP |
|
3582 .DE |
|
3583 The function \f(CWdwarf_var_die_offset()\fP returns |
|
3584 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_offset\fP to |
|
3585 the offset in |
|
3586 the section containing DIE's, i.e. .debug_info, of the DIE representing |
|
3587 the file-scope static variable that is described by the \f(CWDwarf_Var\fP |
|
3588 descriptor, \f(CWvar\fP. |
|
3589 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3590 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3591 |
|
3592 .H 4 "dwarf_var_cu_offset()" |
|
3593 .DS |
|
3594 \f(CWint dwarf_var_cu_offset( |
|
3595 Dwarf_Var var, |
|
3596 Dwarf_Off *returned_offset, |
|
3597 Dwarf_Error *error)\fP |
|
3598 .DE |
|
3599 The function \f(CWdwarf_var_cu_offset()\fP returns |
|
3600 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_offset\fP to |
|
3601 the offset in |
|
3602 the section containing DIE's, i.e. .debug_info, of the compilation-unit |
|
3603 header of the compilation-unit that contains the file-scope static |
|
3604 variable described by the \f(CWDwarf_Var\fP descriptor, \f(CWvar\fP. |
|
3605 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3606 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3607 |
|
3608 .H 4 "dwarf_var_name_offsets()" |
|
3609 .DS |
|
3610 \f(CWint dwarf_var_name_offsets( |
|
3611 Dwarf_Var var, |
|
3612 char **returned_name, |
|
3613 Dwarf_Off *die_offset, |
|
3614 Dwarf_Off *cu_offset, |
|
3615 Dwarf_Error *error)\fP |
|
3616 .DE |
|
3617 The function \f(CWdwarf_var_name_offsets()\fP returns |
|
3618 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to |
|
3619 a pointer to |
|
3620 a null-terminated string that gives the name of the file-scope |
|
3621 static variable described by the \f(CWDwarf_Var\fP descriptor \f(CWvar\fP. |
|
3622 It also returns in the locations |
|
3623 pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets |
|
3624 of the DIE representing the |
|
3625 file-scope static variable, and the DIE |
|
3626 representing the compilation-unit containing the |
|
3627 file-scope static variable, respectively. |
|
3628 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
3629 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
3630 On a successful return from |
|
3631 \f(CWdwarf_var_name_offsets()\fP the storage pointed to by |
|
3632 \f(CWreturned_name\fP |
|
3633 should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation |
|
3634 type \f(CWDW_DLA_STRING\fP when no longer of interest. |
|
3635 |
|
3636 .H 2 "Macro Information Operations" |
|
3637 .H 3 "General Macro Operations" |
|
3638 .H 4 "dwarf_find_macro_value_start()" |
|
3639 .DS |
|
3640 \f(CWchar *dwarf_find_macro_value_start(char * macro_string);\fP |
|
3641 .DE |
|
3642 Given a macro string in the standard form defined in the DWARF |
|
3643 document ("name <space> value" or "name(args)<space>value") |
|
3644 this returns a pointer to the first byte of the macro value. |
|
3645 It does not alter the string pointed to by macro_string or copy |
|
3646 the string: it returns a pointer into the string whose |
|
3647 address was passed in. |
|
3648 .H 3 "Debugger Interface Macro Operations" |
|
3649 Macro information is accessed from the .debug_info section via the |
|
3650 DW_AT_macro_info attribute (whose value is an offset into .debug_macinfo). |
|
3651 .P |
|
3652 No Functions yet defined. |
|
3653 .H 3 "Low Level Macro Information Operations" |
|
3654 .H 4 "dwarf_get_macro_details()" |
|
3655 .DS |
|
3656 \f(CWint dwarf_get_macro_details(Dwarf_Debug /*dbg*/, |
|
3657 Dwarf_Off macro_offset, |
|
3658 Dwarf_Unsigned maximum_count, |
|
3659 Dwarf_Signed * entry_count, |
|
3660 Dwarf_Macro_Details ** details, |
|
3661 Dwarf_Error * err);\fP |
|
3662 .DE |
|
3663 \f(CWdwarf_get_macro_details()\fP |
|
3664 returns |
|
3665 \f(CWDW_DLV_OK\fP and sets |
|
3666 \f(CWentry_count\fP to the number of \f(CWdetails\fP records |
|
3667 returned through the \f(CWdetails\fP pointer. |
|
3668 The data returned thru \f(CWdetails\fP should be freed |
|
3669 by a call to \f(CWdwarf_dealloc()\fP with the allocation type |
|
3670 \f(CWDW_DLA_STRING\fP. |
|
3671 If \f(CWDW_DLV_OK\fP is returned, the \f(CWentry_count\fP will |
|
3672 be at least 1, since |
|
3673 a compilation unit with macro information but no macros will |
|
3674 have at least one macro data byte of 0. |
|
3675 .P |
|
3676 \f(CWdwarf_get_macro_details()\fP |
|
3677 begins at the \f(CWmacro_offset\fP offset you supply |
|
3678 and ends at the end of a compilation unit or at \f(CWmaximum_count\fP |
|
3679 detail records (whichever comes first). |
|
3680 If \f(CWmaximum_count\fP is 0, it is treated as if it were the maximum |
|
3681 possible unsigned integer. |
|
3682 .P |
|
3683 \f(CWdwarf_get_macro_details()\fP |
|
3684 attempts to set \f(CWdmd_fileindex\fP to the correct file in every |
|
3685 \f(CWdetails\fP record. If it is unable to do so (or whenever |
|
3686 the current file index is unknown, it sets \f(CWdmd_fileindex\fP |
|
3687 to -1. |
|
3688 .P |
|
3689 \f(CWdwarf_get_macro_details()\fP returns \f(CWDW_DLV_ERROR\fP on error. |
|
3690 It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no more |
|
3691 macro information at that \f(CWmacro_offset\fP. If \f(CWmacro_offset\fP |
|
3692 is passed in as 0, a \f(CWDW_DLV_NO_ENTRY\fP return means there is |
|
3693 no macro information. |
|
3694 .P |
|
3695 .in +2 |
|
3696 .DS |
|
3697 \f(CWDwarf_Unsigned max = 0; |
|
3698 Dwarf_Off cur_off = 0; |
|
3699 Dwarf_Signed count = 0; |
|
3700 Dwarf_Macro_Details *maclist; |
|
3701 int errv; |
|
3702 |
|
3703 /* loop thru all the compilation units macro info */ |
|
3704 while((errv = dwarf_macro_details(dbg, cur_off,max, |
|
3705 &count,&maclist,&error))== DW_DLV_OK) { |
|
3706 for (i = 0; i < count; ++i) { |
|
3707 /* use maclist[i] */ |
|
3708 } |
|
3709 cur_off = maclist[count-1].dmd_offset + 1; |
|
3710 dwarf_dealloc(dbg, maclist, DW_DLA_STRING); |
|
3711 }\fP |
|
3712 .DE |
|
3713 |
|
3714 |
|
3715 .H 2 "Low Level Frame Operations" |
|
3716 These functions provide information about stack frames to be |
|
3717 used to perform stack traces. The information is an abstraction |
|
3718 of a table with a row per instruction and a column per register |
|
3719 and a column for the canonical frame address (CFA, which corresponds |
|
3720 to the notion of a frame pointer), |
|
3721 as well as a column for the return address. |
|
3722 .P |
|
3723 From 1993-2006 the interface we'll here refer to as DWARF2 |
|
3724 made the CFA be a column in the matrix, but left |
|
3725 DW_FRAME_UNDEFINED_VAL, and DW_FRAME_SAME_VAL out of the matrix |
|
3726 (giving them high numbers). As of the DWARF3 interfaces |
|
3727 introduced in this document in April 2006, there are *two* |
|
3728 interfaces. |
|
3729 .P |
|
3730 The original still exists (see. |
|
3731 dwarf_get_fde_info_for_reg() and dwarf_get_fde_info_for_all_regs() below) |
|
3732 and works adequately for MIPS/IRIX DWARF2 and ABI/ISA sets |
|
3733 that are sufficiently similar (but the settings for non-MIPS |
|
3734 must be set into libdwarf.h and cannot be changed at runtime). |
|
3735 .P |
|
3736 A new interface set of dwarf_get_fde_info_for_reg3(), |
|
3737 dwarf_get_fde_info_for_cfa_reg3(), dwarf_get_fde_info_for_all_regs3() |
|
3738 dwarf_set_frame_rule_inital_value(), dwarf_set_frame_rule_table_size() |
|
3739 is more flexible |
|
3740 and should work for many more architectures |
|
3741 and the setting of DW_FRAME_CFA_COL and the size of |
|
3742 the table can be set at runtime. |
|
3743 .P |
|
3744 Each cell in the table contains one of the following: |
|
3745 |
|
3746 .AL |
|
3747 .LI |
|
3748 A register + offset(a)(b) |
|
3749 |
|
3750 .LI |
|
3751 A register(c)(d) |
|
3752 |
|
3753 |
|
3754 .LI |
|
3755 A marker (DW_FRAME_UNDEFINED_VAL) meaning \fIregister value undefined\fP |
|
3756 |
|
3757 .LI |
|
3758 A marker (DW_FRAME_SAME_VAL) meaning \fIregister value same as in caller\fP |
|
3759 .LE |
|
3760 .P |
|
3761 (a old DWARF2 interface) When the column is DW_FRAME_CFA_COL: the register |
|
3762 number is a real hardware register, not a reference |
|
3763 to DW_FRAME_CFA_COL, not DW_FRAME_UNDEFINED_VAL, |
|
3764 and not DW_FRAME_SAME_VAL. |
|
3765 The CFA rule value should be the stack pointer |
|
3766 plus offset 0 when no other value makes sense. |
|
3767 A value of DW_FRAME_SAME_VAL would |
|
3768 be semi-logical, but since the CFA is not a real register, |
|
3769 not really correct. |
|
3770 A value of DW_FRAME_UNDEFINED_VAL would imply |
|
3771 the CFA is undefined -- |
|
3772 this seems to be a useless notion, as |
|
3773 the CFA is a means to finding real registers, |
|
3774 so those real registers should be marked DW_FRAME_UNDEFINED_VAL, |
|
3775 and the CFA column content (whatever register it |
|
3776 specifies) becomes unreferenced by anything. |
|
3777 .P |
|
3778 (a new April 2006 DWARF2/3 interface): The CFA is |
|
3779 separately accessible and not part of the table. |
|
3780 The 'rule number' for the CFA is a number outside the table. |
|
3781 So the CFA is a marker, not a register number. |
|
3782 See DW_FRAME_CFA_COL3 in libdwarf.h and |
|
3783 dwarf_get_fde_info_for_cfa_reg3(). |
|
3784 .P |
|
3785 (b) When the column is not DW_FRAME_CFA_COL, the 'register' |
|
3786 will and must be DW_FRAME_CFA_COL, implying that |
|
3787 to get the final location for the column one must add |
|
3788 the offset here plus the DW_FRAME_CFA_COL rule value. |
|
3789 .P |
|
3790 (c) When the column is DW_FRAME_CFA_COL, then the register |
|
3791 number is (must be) a real hardware register . |
|
3792 If it were DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL |
|
3793 it would be a marker, not a register number. |
|
3794 .P |
|
3795 (d) When the column is not DW_FRAME_CFA_COL, the register |
|
3796 may be a hardware register. |
|
3797 It will not be DW_FRAME_CFA_COL. |
|
3798 .P |
|
3799 There is no 'column' for DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL. |
|
3800 |
|
3801 Figure \n(aX |
|
3802 is machine dependent and represents MIPS cpu register |
|
3803 assignments. |
|
3804 |
|
3805 .DS |
|
3806 .TS |
|
3807 center box, tab(:); |
|
3808 lfB lfB lfB |
|
3809 l c l. |
|
3810 NAME:value:PURPOSE |
|
3811 _ |
|
3812 DW_FRAME_CFA_COL:0:column used for CFA |
|
3813 DW_FRAME_REG1:1:integer regster 1 |
|
3814 DW_FRAME_REG2:2:integer register 2 |
|
3815 ---::obvious names and values here |
|
3816 DW_FRAME_REG30:30:integer register 30 |
|
3817 DW_FRAME_REG31:31:integer register 31 |
|
3818 DW_FRAME_FREG0:32:floating point register 0 |
|
3819 DW_FRAME_FREG1:33:floating point register 1 |
|
3820 ---::obvious names and values here |
|
3821 DW_FRAME_FREG30:62:floating point register 30 |
|
3822 DW_FRAME_FREG31:63:floating point register 31 |
|
3823 DW_FRAME_RA_COL:64:column recording ra |
|
3824 DW_FRAME_UNDEFINED_VAL:1034:register val undefined |
|
3825 DW_FRAME_SAME_VAL:1035:register same as in caller |
|
3826 .TE |
|
3827 |
|
3828 .FG "Frame Information Rule Assignments" |
|
3829 .DE |
|
3830 |
|
3831 .P |
|
3832 The following table shows SGI/MIPS specific |
|
3833 special cell values: these values mean |
|
3834 that the cell has the value \fIundefined\fP or \fIsame value\fP |
|
3835 respectively, rather than containing a \fIregister\fP or |
|
3836 \fIregister+offset\fP. |
|
3837 It assumes DW_FRAME_CFA_COL is a table rule, which |
|
3838 is not readily accomplished or sensible for some architectures. |
|
3839 .P |
|
3840 .DS |
|
3841 .TS |
|
3842 center box, tab(:); |
|
3843 lfB lfB lfB |
|
3844 l c l. |
|
3845 NAME:value:PURPOSE |
|
3846 _ |
|
3847 DW_FRAME_UNDEFINED_VAL:1034:means undefined value. |
|
3848 ::Not a column or register value |
|
3849 DW_FRAME_SAME_VAL:1035:means 'same value' as |
|
3850 ::caller had. Not a column or |
|
3851 ::register value |
|
3852 .TE |
|
3853 .FG "Frame Information Special Values" |
|
3854 .DE |
|
3855 |
|
3856 .P |
|
3857 The following table shows more general special cell values. |
|
3858 These values mean |
|
3859 that the cell register-number refers to the \fIcfa-register\fP or |
|
3860 \fIundefined-value\fP or \fIsame-value\fP |
|
3861 respectively, rather than referring to a \fIregister in the table\fP. |
|
3862 The generality arises from making DW_FRAME_CFA_COL3 be |
|
3863 outside the set of registers and making the cfa rule accessible |
|
3864 from outside the rule-table. |
|
3865 .P |
|
3866 .DS |
|
3867 .TS |
|
3868 center box, tab(:); |
|
3869 lfB lfB lfB |
|
3870 l c l. |
|
3871 NAME:value:PURPOSE |
|
3872 _ |
|
3873 DW_FRAME_UNDEFINED_VAL:1034:means undefined value. |
|
3874 ::Not a column or register value |
|
3875 DW_FRAME_SAME_VAL:1035:means 'same value' as |
|
3876 ::caller had. Not a column or |
|
3877 ::register value |
|
3878 DW_FRAME_CFA_COL3:1036:means 'cfa register'is referred to, |
|
3879 ::not a real register, not a column, but the cfa (the cfa |
|
3880 ::does have a value, but in the DWARF3 libdwarf interface |
|
3881 ::it does not have a 'real register number'). |
|
3882 .TE |
|
3883 .DE |
|
3884 .\"#if 0 |
|
3885 .\".P |
|
3886 .\"Since the cie and fde entries are not "organized" by anything |
|
3887 .\"outside of the .debug_frame section one must scan them all to |
|
3888 .\"find all entry addresses and lengths. Since there is one fde |
|
3889 .\"per function this can be a rather long list. |
|
3890 .\"#endif |
|
3891 |
|
3892 .P |
|
3893 .H 4 "dwarf_get_fde_list()" |
|
3894 .DS |
|
3895 \f(CWint dwarf_get_fde_list( |
|
3896 Dwarf_Debug dbg, |
|
3897 Dwarf_Cie **cie_data, |
|
3898 Dwarf_Signed *cie_element_count, |
|
3899 Dwarf_Fde **fde_data, |
|
3900 Dwarf_Signed *fde_element_count, |
|
3901 Dwarf_Error *error);\fP |
|
3902 .DE |
|
3903 \f(CWdwarf_get_fde_list()\fP stores a pointer to a list of |
|
3904 \f(CWDwarf_Cie\fP descriptors in \f(CW*cie_data\fP, and the |
|
3905 count of the number of descriptors in \f(CW*cie_element_count\fP. |
|
3906 There is a descriptor for each CIE in the .debug_frame section. |
|
3907 Similarly, it stores a pointer to a list of \f(CWDwarf_Fde\fP |
|
3908 descriptors in \f(CW*fde_data\fP, and the count of the number |
|
3909 of descriptors in \f(CW*fde_element_count\fP. There is one |
|
3910 descriptor per FDE in the .debug_frame section. |
|
3911 \f(CWdwarf_get_fde_list()\fP returns \f(CWDW_DLV_EROR\fP on error. |
|
3912 It returns \f(CWDW_DLV_NO_ENTRY\fP if it cannot find frame entries. |
|
3913 It returns \f(CWDW_DLV_OK\fP on a successful return. |
|
3914 .P |
|
3915 On successful return, structures pointed to by a |
|
3916 descriptor should be free'd using \f(CWdwarf_fde_cie_list_dealloc()\fP. |
|
3917 This dealloc approach is new as of July 15, 2005. |
|
3918 |
|
3919 .in +2 |
|
3920 .DS |
|
3921 \f(CWDwarf_Signed cnt; |
|
3922 Dwarf_Cie *cie_data; |
|
3923 Dwarf_Signed cie_count; |
|
3924 Dwarf_Fde *fde_data; |
|
3925 Dwarf_Signed fde_count; |
|
3926 int fres; |
|
3927 |
|
3928 fres = dwarf_get_fde_list(dbg,&cie_data,&cie_count, |
|
3929 &fde_data,&fde_count,&error); |
|
3930 if (fres == DW_DLV_OK) { |
|
3931 dwarf_fde_cie_list_dealloc(dbg, cie_data, cie_count, |
|
3932 fde_data,fde_count); |
|
3933 }\fP |
|
3934 .DE |
|
3935 .in -2 |
|
3936 |
|
3937 |
|
3938 |
|
3939 .P |
|
3940 The following code is deprecated as of July 15, 2005 as it does not |
|
3941 free all relevant memory. |
|
3942 This approach still works as well as it ever did. |
|
3943 .in +2 |
|
3944 .DS |
|
3945 \f(CWDwarf_Signed cnt; |
|
3946 Dwarf_Cie *cie_data; |
|
3947 Dwarf_Signed cie_count; |
|
3948 Dwarf_Fde *fde_data; |
|
3949 Dwarf_Signed fde_count; |
|
3950 int fres; |
|
3951 |
|
3952 fres = dwarf_get_fde_list(dbg,&cie_data,&cie_count, |
|
3953 &fde_data,&fde_count,&error); |
|
3954 if (fres == DW_DLV_OK) { |
|
3955 |
|
3956 for (i = 0; i < cie_count; ++i) { |
|
3957 /* use cie[i] */ |
|
3958 dwarf_dealloc(dbg, cie_data[i], DW_DLA_CIE); |
|
3959 } |
|
3960 for (i = 0; i < fde_count; ++i) { |
|
3961 /* use fde[i] */ |
|
3962 dwarf_dealloc(dbg, fde_data[i], DW_DLA_FDE); |
|
3963 } |
|
3964 dwarf_dealloc(dbg, cie_data, DW_DLA_LIST); |
|
3965 dwarf_dealloc(dbg, fde_data, DW_DLA_LIST); |
|
3966 }\fP |
|
3967 .DE |
|
3968 .in -2 |
|
3969 |
|
3970 .P |
|
3971 .H 4 "dwarf_get_fde_list_eh()" |
|
3972 .DS |
|
3973 \f(CWint dwarf_get_fde_list_eh( |
|
3974 Dwarf_Debug dbg, |
|
3975 Dwarf_Cie **cie_data, |
|
3976 Dwarf_Signed *cie_element_count, |
|
3977 Dwarf_Fde **fde_data, |
|
3978 Dwarf_Signed *fde_element_count, |
|
3979 Dwarf_Error *error);\fP |
|
3980 .DE |
|
3981 \f(CWdwarf_get_fde_list_eh()\fP is identical to |
|
3982 \f(CWdwarf_get_fde_list()\fP except that |
|
3983 \f(CWdwarf_get_fde_list_eh()\fP reads the GNU ecgs |
|
3984 section named .eh_frame (C++ exception handling information). |
|
3985 |
|
3986 \f(CWdwarf_get_fde_list_eh()\fP stores a pointer to a list of |
|
3987 \f(CWDwarf_Cie\fP descriptors in \f(CW*cie_data\fP, and the |
|
3988 count of the number of descriptors in \f(CW*cie_element_count\fP. |
|
3989 There is a descriptor for each CIE in the .debug_frame section. |
|
3990 Similarly, it stores a pointer to a list of \f(CWDwarf_Fde\fP |
|
3991 descriptors in \f(CW*fde_data\fP, and the count of the number |
|
3992 of descriptors in \f(CW*fde_element_count\fP. There is one |
|
3993 descriptor per FDE in the .debug_frame section. |
|
3994 \f(CWdwarf_get_fde_list()\fP returns \f(CWDW_DLV_EROR\fP on error. |
|
3995 It returns \f(CWDW_DLV_NO_ENTRY\fP if it cannot find |
|
3996 exception handling entries. |
|
3997 It returns \f(CWDW_DLV_OK\fP on a successful return. |
|
3998 |
|
3999 .P |
|
4000 On successful return, structures pointed to by a |
|
4001 descriptor should be free'd using \f(CWdwarf_fde_cie_list_dealloc()\fP. |
|
4002 This dealloc approach is new as of July 15, 2005. |
|
4003 |
|
4004 .in +2 |
|
4005 .DS |
|
4006 \f(CWDwarf_Signed cnt; |
|
4007 Dwarf_Cie *cie_data; |
|
4008 Dwarf_Signed cie_count; |
|
4009 Dwarf_Fde *fde_data; |
|
4010 Dwarf_Signed fde_count; |
|
4011 int fres; |
|
4012 |
|
4013 fres = dwarf_get_fde_list(dbg,&cie_data,&cie_count, |
|
4014 &fde_data,&fde_count,&error); |
|
4015 if (fres == DW_DLV_OK) { |
|
4016 dwarf_fde_cie_list_dealloc(dbg, cie_data, cie_count, |
|
4017 fde_data,fde_count); |
|
4018 }\fP |
|
4019 .DE |
|
4020 .in -2 |
|
4021 |
|
4022 |
|
4023 .P |
|
4024 .H 4 "dwarf_get_cie_of_fde()" |
|
4025 .DS |
|
4026 \f(CWint dwarf_get_cie_of_fde(Dwarf_Fde fde, |
|
4027 Dwarf_Cie *cie_returned, |
|
4028 Dwarf_Error *error);\fP |
|
4029 .DE |
|
4030 \f(CWdwarf_get_cie_of_fde()\fP stores a \f(CWDwarf_Cie\fP |
|
4031 into the \f(CWDwarf_Cie\fP that \f(CWcie_returned\fP points at. |
|
4032 |
|
4033 If one has called dwarf_get_fde_list and does not wish |
|
4034 to dwarf_dealloc() all the individual FDEs immediately, one |
|
4035 must also avoid dwarf_dealloc-ing the CIEs for those FDEs |
|
4036 not immediately dealloc'd. |
|
4037 Failing to observe this restriction will cause the FDE(s) not |
|
4038 dealloced to become invalid: an FDE contains (hidden in it) |
|
4039 a CIE pointer which will be be invalid (stale, pointing to freed memory) |
|
4040 if the CIE is dealloc'd. |
|
4041 The invalid CIE pointer internal to the FDE cannot be detected |
|
4042 as invalid by libdwarf. |
|
4043 If one later passes an FDE with a stale internal CIE pointer |
|
4044 to one of the routines taking an FDE as input the result will |
|
4045 be failure of the call (returning DW_DLV_ERROR) at best and |
|
4046 it is possible a coredump or worse will happpen (eventually). |
|
4047 |
|
4048 |
|
4049 \f(CWdwarf_get_cie_of_fde()\fP returns |
|
4050 \f(CWDW_DLV_OK\fP if it is successful (it will be |
|
4051 unless fde is the NULL pointer). |
|
4052 It returns \f(CWDW_DLV_ERROR\fP if the fde is invalid (NULL). |
|
4053 |
|
4054 .P |
|
4055 Each \f(CWDwarf_Fde\fP descriptor describes information about the |
|
4056 frame for a particular subroutine or function. |
|
4057 |
|
4058 \f(CWint dwarf_get_fde_for_die\fP is SGI/MIPS specific. |
|
4059 |
|
4060 .H 4 "dwarf_get_fde_for_die()" |
|
4061 .DS |
|
4062 \f(CWint dwarf_get_fde_for_die( |
|
4063 Dwarf_Debug dbg, |
|
4064 Dwarf_Die die, |
|
4065 Dwarf_Fde * return_fde, |
|
4066 Dwarf_Error *error)\fP |
|
4067 .DE |
|
4068 When it succeeds, |
|
4069 \f(CWdwarf_get_fde_for_die()\fP returns |
|
4070 \f(CWDW_DLV_OK\fP and sets \f(CW*return_fde\fP |
|
4071 to |
|
4072 a \f(CWDwarf_Fde\fP |
|
4073 descriptor representing frame information for the given \f(CWdie\fP. It |
|
4074 looks for the \f(CWDW_AT_MIPS_fde\fP attribute in the given \f(CWdie\fP. |
|
4075 If it finds it, is uses the value of the attribute as the offset in |
|
4076 the .debug_frame section where the FDE begins. |
|
4077 If there is no \f(CWDW_AT_MIPS_fde\fP it returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
4078 If there is an error it returns \f(CWDW_DLV_ERROR\fP. |
|
4079 |
|
4080 .H 4 "dwarf_get_fde_range()" |
|
4081 .DS |
|
4082 \f(CWint dwarf_get_fde_range( |
|
4083 Dwarf_Fde fde, |
|
4084 Dwarf_Addr *low_pc, |
|
4085 Dwarf_Unsigned *func_length, |
|
4086 Dwarf_Ptr *fde_bytes, |
|
4087 Dwarf_Unsigned *fde_byte_length, |
|
4088 Dwarf_Off *cie_offset, |
|
4089 Dwarf_Signed *cie_index, |
|
4090 Dwarf_Off *fde_offset, |
|
4091 Dwarf_Error *error);\fP |
|
4092 .DE |
|
4093 On success, |
|
4094 \f(CWdwarf_get_fde_range()\fP returns |
|
4095 \f(CWDW_DLV_OK\fP. |
|
4096 The location pointed to by \f(CWlow_pc\fP is set to the low pc value for |
|
4097 this function. |
|
4098 The location pointed to by \f(CWfunc_length\fP is |
|
4099 set to the length of the function in bytes. |
|
4100 This is essentially the |
|
4101 length of the text section for the function. |
|
4102 The location pointed |
|
4103 to by \f(CWfde_bytes\fP is set to the address where the FDE begins |
|
4104 in the .debug_frame section. |
|
4105 The location pointed to by |
|
4106 \f(CWfde_byte_length\fP is set to the length in bytes of the portion |
|
4107 of .debug_frame for this FDE. |
|
4108 This is the same as the value returned |
|
4109 by \f(CWdwarf_get_fde_range\fP. |
|
4110 The location pointed to by |
|
4111 \f(CWcie_offset\fP is set to the offset in the .debug_frame section |
|
4112 of the CIE used by this FDE. |
|
4113 The location pointed to by \f(CWcie_index\fP |
|
4114 is set to the index of the CIE used by this FDE. |
|
4115 The index is the |
|
4116 index of the CIE in the list pointed to by \f(CWcie_data\fP as set |
|
4117 by the function \f(CWdwarf_get_fde_list()\fP. |
|
4118 However, if the function |
|
4119 \f(CWdwarf_get_fde_for_die()\fP was used to obtain the given \f(CWfde\fP, |
|
4120 this index may not be correct. |
|
4121 The location pointed to by |
|
4122 \f(CWfde_offset\fP is set to the offset of the start of this FDE in |
|
4123 the .debug_frame section. |
|
4124 \f(CWdwarf_get_fde_range()\fP returns \f(CWDW_DLV_ERROR\fP on error. |
|
4125 |
|
4126 .H 4 "dwarf_get_cie_info()" |
|
4127 .DS |
|
4128 \f(CWint dwarf_get_cie_info( |
|
4129 Dwarf_Cie cie, |
|
4130 Dwarf_Unsigned *bytes_in_cie, |
|
4131 Dwarf_Small *version, |
|
4132 char **augmenter, |
|
4133 Dwarf_Unsigned *code_alignment_factor, |
|
4134 Dwarf_Signed *data_alignment_factor, |
|
4135 Dwarf_Half *return_address_register_rule, |
|
4136 Dwarf_Ptr *initial_instructions, |
|
4137 Dwarf_Unsigned *initial_instructions_length, |
|
4138 Dwarf_Error *error);\fP |
|
4139 .DE |
|
4140 \f(CWdwarf_get_cie_info()\fP is primarily for Internal-level Interface |
|
4141 consumers. |
|
4142 If successful, |
|
4143 it returns |
|
4144 \f(CWDW_DLV_OK\fP and sets \f(CW*bytes_in_cie\fP to |
|
4145 the number of bytes in the portion of the |
|
4146 frames section for the CIE represented by the given \f(CWDwarf_Cie\fP |
|
4147 descriptor, \f(CWcie\fP. |
|
4148 The other fields are directly taken from |
|
4149 the cie and returned, via the pointers to the caller. |
|
4150 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4151 |
|
4152 .H 4 "dwarf_get_fde_instr_bytes()" |
|
4153 .DS |
|
4154 \f(CWint dwarf_get_fde_instr_bytes( |
|
4155 Dwarf_Fde fde, |
|
4156 Dwarf_Ptr *outinstrs, |
|
4157 Dwarf_Unsigned *outlen, |
|
4158 Dwarf_Error *error);\fP |
|
4159 .DE |
|
4160 \f(CWdwarf_get_fde_instr_bytes()\fP returns |
|
4161 \f(CWDW_DLV_OK\fP and sets \f(CW*outinstrs\fP to |
|
4162 a pointer to a set of bytes which are the |
|
4163 actual frame instructions for this fde. |
|
4164 It also sets \f(CW*outlen\fP to the length, in |
|
4165 bytes, of the frame instructions. |
|
4166 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4167 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
4168 The intent is to allow low-level consumers like a dwarf-dumper |
|
4169 to print the bytes in some fashion. |
|
4170 The memory pointed to by \f(CWoutinstrs\fP |
|
4171 must not be changed and there |
|
4172 is nothing to free. |
|
4173 |
|
4174 .H 4 "dwarf_get_fde_info_for_reg()" |
|
4175 This interface is suitable for DWARF2 but is not |
|
4176 sufficient for DWARF3. See \f(CWint dwarf_get_fde_info_for_reg3\fP. |
|
4177 .DS |
|
4178 \f(CWint dwarf_get_fde_info_for_reg( |
|
4179 Dwarf_Fde fde, |
|
4180 Dwarf_Half table_column, |
|
4181 Dwarf_Addr pc_requested, |
|
4182 Dwarf_Signed *offset_relevant, |
|
4183 Dwarf_Signed *register_num, |
|
4184 Dwarf_Signed *offset, |
|
4185 Dwarf_Addr *row_pc, |
|
4186 Dwarf_Error *error);\fP |
|
4187 .DE |
|
4188 \f(CWdwarf_get_fde_info_for_reg()\fP returns |
|
4189 \f(CWDW_DLV_OK\fP and sets \f(CW*offset_relevant\fP to |
|
4190 non-zero if the offset is relevant for the |
|
4191 row specified by \f(CWpc_requested\fP and column specified by |
|
4192 \f(CWtable_column\fP, for the FDE specified by \f(CWfde\fP. |
|
4193 The |
|
4194 intent is to return the rule for the given pc value and register. |
|
4195 The location pointed to by \f(CWregister_num\fP is set to the register |
|
4196 value for the rule. |
|
4197 The location pointed to by \f(CWoffset\fP |
|
4198 is set to the offset value for the rule. |
|
4199 If offset is not relevant for this rule, \f(CW*offset_relevant\fP is |
|
4200 set to zero. |
|
4201 Since more than one pc |
|
4202 value will have rows with identical entries, the user may want to |
|
4203 know the earliest pc value after which the rules for all the columns |
|
4204 remained unchanged. |
|
4205 Recall that in the virtual table that the frame information |
|
4206 represents there may be one or more table rows with identical data |
|
4207 (each such table row at a different pc value). |
|
4208 Given a \f(CWpc_requested\fP which refers to a pc in such a group |
|
4209 of identical rows, |
|
4210 the location pointed to by \f(CWrow_pc\fP is set |
|
4211 to the lowest pc value |
|
4212 within the group of identical rows. |
|
4213 The value put in \f(CW*register_num\fP any of the |
|
4214 \f(CWDW_FRAME_*\fP table columns values specified in \f(CWlibdwarf.h\fP |
|
4215 or \f(CWdwarf.h\fP. |
|
4216 |
|
4217 \f(CWdwarf_get_fde_info_for_reg\fP returns \f(CWDW_DLV_ERROR\fP if there is an error. |
|
4218 |
|
4219 It is usable with either |
|
4220 \f(CWdwarf_get_fde_n()\fP or \f(CWdwarf_get_fde_at_pc()\fP. |
|
4221 |
|
4222 .H 4 "dwarf_get_fde_info_for_all_regs()" |
|
4223 .DS |
|
4224 \f(CWint dwarf_get_fde_info_for_all_regs( |
|
4225 Dwarf_Fde fde, |
|
4226 Dwarf_Addr pc_requested, |
|
4227 Dwarf_Regtable *reg_table, |
|
4228 Dwarf_Addr *row_pc, |
|
4229 Dwarf_Error *error);\fP |
|
4230 .DE |
|
4231 \f(CWdwarf_get_fde_info_for_all_regs()\fP returns |
|
4232 \f(CWDW_DLV_OK\fP and sets \f(CW*reg_table\fP for the row specified by |
|
4233 \f(CWpc_requested\fP for the FDE specified by \f(CWfde\fP. |
|
4234 .P |
|
4235 The intent is |
|
4236 to return the rules for decoding all the registers, given a pc value. |
|
4237 \f(CWreg_table\fP is an array of rules, one for each register specified in |
|
4238 \f(CWdwarf.h\fP. The rule for each register contains three items - |
|
4239 \f(CWdw_regnum\fP which denotes the register value for that rule, |
|
4240 \f(CWdw_offset\fP which denotes the offset value for that rule and |
|
4241 \f(CWdw_offset_relevant\fP which is set to zero if offset is not relevant |
|
4242 for that rule. See \f(CWdwarf_get_fde_info_fo_reg()\fP for a description |
|
4243 of \f(CWrow_pc\fP. |
|
4244 .P |
|
4245 \f(CWdwarf_get_fde_info_for_all_regs\fP returns \f(CWDW_DLV_ERROR\fP if there is an error. |
|
4246 .P |
|
4247 \f(CWint dwarf_get_fde_info_for_all_regs\fP is SGI/MIPS specific. |
|
4248 |
|
4249 |
|
4250 .H 4 "dwarf_set_frame_rule_table_size()" |
|
4251 .P |
|
4252 This allows consumers to set the size of the (internal to libdwarf) |
|
4253 rule table. It should be at least as large as the |
|
4254 number of real registers in the ABI which is to be read in |
|
4255 for the dwarf_get_fde_info_for_reg3() or dwarf_get_fde_info_for_all_regs3() |
|
4256 functions to work properly. |
|
4257 It must be less than the marker values |
|
4258 DW_FRAME_UNDEFINED_VAL, DW_FRAME_SAME_VAL, DW_FRAME_CFA_COL3. |
|
4259 .P |
|
4260 .DS |
|
4261 \f(CWDwarf_Half |
|
4262 dwarf_set_frame_rule_table_size(Dwarf_Debug dbg, |
|
4263 Dwarf_Half value);\fP |
|
4264 |
|
4265 .DE |
|
4266 \f(CWddwarf_set_frame_rule_table_size()\fP sets the |
|
4267 value \f(CWvalue\fP as the size of libdwarf-internal |
|
4268 rules tables of \f(CWdbg\fP. |
|
4269 The function returns |
|
4270 the previous value of the rules table size setting (taken from the |
|
4271 \f(CWdbg\fP structure). |
|
4272 |
|
4273 .H 4 "dwarf_set_frame_rule_inital_value()" |
|
4274 This allows consumers to set the initial value |
|
4275 for rows in the frame tables. By default it |
|
4276 is taken from libdwarf.h and is DW_FRAME_REG_INITIAL_VALUE |
|
4277 (which itself is either DW_FRAME_SAME_VAL or DW_FRAME_UNDEFINED_VAL). |
|
4278 The MIPS/IRIX default is DW_FRAME_SAME_VAL. |
|
4279 Comsumer code should set this appropriately and for |
|
4280 many architectures (but probably not MIPS) DW_FRAME_UNDEFINED_VAL is an |
|
4281 appropriate setting. |
|
4282 .DS |
|
4283 \f(CWDwarf_Half |
|
4284 dwarf_set_frame_rule_inital_value(Dwarf_Debug dbg, |
|
4285 Dwarf_Half value);\fP |
|
4286 |
|
4287 .DE |
|
4288 \f(CWdwarf_set_frame_rule_inital_value()\fP sets the |
|
4289 value \f(CWvalue\fP as the initial value for this \f(CWdbg\fP |
|
4290 when initializing rules tables. The function returns |
|
4291 the previous value of the initial setting (taken from the |
|
4292 \f(CWdbg\fP structure). |
|
4293 |
|
4294 |
|
4295 |
|
4296 .H 4 "dwarf_get_fde_info_for_reg3()" |
|
4297 This interface is suitable for DWARF3 and DWARF2. |
|
4298 It returns the values for a particular real register |
|
4299 (Not for the CFA register, see dwarf_get_fde_info_for_cfa_reg3() |
|
4300 below). |
|
4301 .DS |
|
4302 \f(CWint dwarf_get_fde_info_for_reg3( |
|
4303 Dwarf_Fde fde, |
|
4304 Dwarf_Half table_column, |
|
4305 Dwarf_Addr pc_requested, |
|
4306 Dwarf_Small *value_type, |
|
4307 Dwarf_Signed *offset_relevant, |
|
4308 Dwarf_Signed *register_num, |
|
4309 Dwarf_Signed *offset_or_block_len, |
|
4310 Dwarf_Ptr *block_ptr, |
|
4311 Dwarf_Addr *row_pc, |
|
4312 Dwarf_Error *error);\fP |
|
4313 .DE |
|
4314 \f(CWdwarf_get_fde_info_for_re3()\fP returns |
|
4315 \f(CWDW_DLV_OK\fP on success. |
|
4316 It sets \f(CW*value_type\fP |
|
4317 to one of DW_EXPR_OFFSET (0), |
|
4318 DW_EXPR_VAL_OFFSET(1), DW_EXPR_EXPRESSION(2) or |
|
4319 DW_EXPR_VAL_EXPRESSION(3). |
|
4320 On call, \f(CWtable_column\fP must be set to the |
|
4321 register number of a real register. Not |
|
4322 the cfa 'register' or DW_FRAME_SAME_VALUE or |
|
4323 DW_FRAME_UNDEFINED_VALUE. |
|
4324 |
|
4325 |
|
4326 if \f(CW*value_type\fP has the value DW_EXPR_OFFSET (0) then: |
|
4327 .in +4 |
|
4328 .P |
|
4329 It sets \f(CW*offset_relevant\fP to |
|
4330 non-zero if the offset is relevant for the |
|
4331 row specified by \f(CWpc_requested\fP and column specified by |
|
4332 \f(CWtable_column\fP or, for the FDE specified by \f(CWfde\fP. |
|
4333 In this case the \f(CW*register_num\fP will be set |
|
4334 to DW_FRAME_CFA_COL3. This is an offset(N) rule |
|
4335 as specified in the DWARF3/2 documents. |
|
4336 Adding the value of \f(CW*offset_or_block_len\fP |
|
4337 to the value of the CFA register gives the address |
|
4338 of a location holding the previous value of |
|
4339 register \f(CWtable_column\fP. |
|
4340 |
|
4341 .P |
|
4342 If offset is not relevant for this rule, \f(CW*offset_relevant\fP is |
|
4343 set to zero. \f(CW*register_num\fP will be set |
|
4344 to the number of the real register holding the value of |
|
4345 the \f(CWtable_column\fP register. |
|
4346 This is the register(R) rule as specifified in DWARF3/2 documents. |
|
4347 .P |
|
4348 The |
|
4349 intent is to return the rule for the given pc value and register. |
|
4350 The location pointed to by \f(CWregister_num\fP is set to the register |
|
4351 value for the rule. |
|
4352 The location pointed to by \f(CWoffset\fP |
|
4353 is set to the offset value for the rule. |
|
4354 Since more than one pc |
|
4355 value will have rows with identical entries, the user may want to |
|
4356 know the earliest pc value after which the rules for all the columns |
|
4357 remained unchanged. |
|
4358 Recall that in the virtual table that the frame information |
|
4359 represents there may be one or more table rows with identical data |
|
4360 (each such table row at a different pc value). |
|
4361 Given a \f(CWpc_requested\fP which refers to a pc in such a group |
|
4362 of identical rows, |
|
4363 the location pointed to by \f(CWrow_pc\fP is set |
|
4364 to the lowest pc value |
|
4365 within the group of identical rows. |
|
4366 |
|
4367 .in -4 |
|
4368 |
|
4369 .P |
|
4370 If \f(CW*value_type\fP has the value DW_EXPR_VAL_OFFSET (1) then: |
|
4371 .in +4 |
|
4372 This will be a val_offset(N) rule as specified in the |
|
4373 DWARF3/2 documents so \f(CW*offset_relevant\fP will |
|
4374 be non zero. |
|
4375 The calculation is identical to the DW_EXPR_OFFSET (0) |
|
4376 calculation with \f(CW*offset_relevant\fP non-zero, |
|
4377 but the value resulting is the actual \f(CWtable_column\fP |
|
4378 value (rather than the address where the value may be found). |
|
4379 .in -4 |
|
4380 .P |
|
4381 If \f(CW*value_type\fP has the value DW_EXPR_EXPRESSION (1) then: |
|
4382 .in +4 |
|
4383 \f(CW*offset_or_block_len\fP |
|
4384 is set to the length in bytes of a block of memory |
|
4385 with a DWARF expression in the block. |
|
4386 \f(CW*block_ptr\fP is set to point at the block of memory. |
|
4387 The consumer code should evaluate the block as |
|
4388 a DWARF-expression. The result is the address where |
|
4389 the previous value of the register may be found. |
|
4390 This is a DWARF3/2 expression(E) rule. |
|
4391 .in -4 |
|
4392 .P |
|
4393 If \f(CW*value_type\fP has the value DW_EXPR_VAL_EXPRESSION (1) then: |
|
4394 .in +4 |
|
4395 The calculation is exactly as for DW_EXPR_EXPRESSION (1) |
|
4396 but the result of the DWARF-expression evaluation is |
|
4397 the value of the \f(CWtable_column\fP (not |
|
4398 the address of the value). |
|
4399 This is a DWARF3/2 val_expression(E) rule. |
|
4400 .in -4 |
|
4401 |
|
4402 \f(CWdwarf_get_fde_info_for_reg\fP |
|
4403 returns \f(CWDW_DLV_ERROR\fP if there is an error and |
|
4404 if there is an error only the \f(CWerror\fP pointer is set, none |
|
4405 of the other output arguments are touched. |
|
4406 |
|
4407 It is usable with either |
|
4408 \f(CWdwarf_get_fde_n()\fP or \f(CWdwarf_get_fde_at_pc()\fP. |
|
4409 |
|
4410 |
|
4411 .H 4 "dwarf_get_fde_info_for_cfa_reg3()" |
|
4412 .DS |
|
4413 \f(CWint dwarf_get_fde_info_for_cfa_reg3(Dwarf_Fde fde, |
|
4414 Dwarf_Addr pc_requested, |
|
4415 Dwarf_Small * value_type, |
|
4416 Dwarf_Signed* offset_relevant, |
|
4417 Dwarf_Signed* register_num, |
|
4418 Dwarf_Signed* offset_or_block_len, |
|
4419 Dwarf_Ptr * block_ptr , |
|
4420 Dwarf_Addr * row_pc_out, |
|
4421 Dwarf_Error * error)\fP |
|
4422 .DE |
|
4423 .P |
|
4424 This is identical to \f(CWdwarf_get_fde_info_for_reg3()\fP |
|
4425 except the returned values are for the CFA rule. |
|
4426 So register number \f(CW*register_num\fP will be set |
|
4427 to a real register, not |
|
4428 DW_FRAME_CFA_COL3, DW_FRAME_SAME_VALUE, or |
|
4429 DW_FRAME_UNDEFINED_VALUE. |
|
4430 |
|
4431 |
|
4432 |
|
4433 .H 4 "dwarf_get_fde_info_for_all_regs3()" |
|
4434 .DS |
|
4435 \f(CWint dwarf_get_fde_info_for_all_regs3( |
|
4436 Dwarf_Fde fde, |
|
4437 Dwarf_Addr pc_requested, |
|
4438 Dwarf_Regtable3 *reg_table, |
|
4439 Dwarf_Addr *row_pc, |
|
4440 Dwarf_Error *error)\fP |
|
4441 .DE |
|
4442 \f(CWdwarf_get_fde_info_for_all_regs3()\fP returns |
|
4443 \f(CWDW_DLV_OK\fP and sets \f(CW*reg_table\fP |
|
4444 for the row specified by |
|
4445 \f(CWpc_requested\fP for the FDE specified by \f(CWfde\fP. |
|
4446 The intent is |
|
4447 to return the rules for decoding all the registers, given a pc |
|
4448 value. |
|
4449 \f(CWreg_table\fP is an array of rules, the |
|
4450 array size specifed by the caller. |
|
4451 plus a rule for the CFA. |
|
4452 The rule for the cfa returned in \f(CW*reg_table\fP |
|
4453 defines the CFA value at \f(CWpc_requested\fP |
|
4454 The rule for each |
|
4455 register contains several values that enable |
|
4456 the consumer to determine the previous value |
|
4457 of the register (see the earlier documentation of Dwarf_Regtable3). |
|
4458 \f(CWdwarf_get_fde_info_for_reg3()\fP and |
|
4459 the Dwarf_Regtable3 documentation above for a description of |
|
4460 the values for each row. |
|
4461 |
|
4462 \f(CWdwarf_get_fde_info_for_all_regs\fP returns \f(CWDW_DLV_ERROR\fP if there is an error. |
|
4463 |
|
4464 It's up to the caller to allocate space for |
|
4465 \f(CW*reg_table\fP and initialize it properly. |
|
4466 |
|
4467 |
|
4468 |
|
4469 .H 4 "dwarf_get_fde_n()" |
|
4470 .DS |
|
4471 \f(CWint dwarf_get_fde_n( |
|
4472 Dwarf_Fde *fde_data, |
|
4473 Dwarf_Unsigned fde_index, |
|
4474 Dwarf_Fde *returned_fde |
|
4475 Dwarf_Error *error)\fP |
|
4476 .DE |
|
4477 \f(CWdwarf_get_fde_n()\fP returns |
|
4478 \f(CWDW_DLV_OK\fP and sets \f(CWreturned_fde\fP to |
|
4479 the \f(CWDwarf_Fde\fP descriptor whose |
|
4480 index is \f(CWfde_index\fP in the table of \f(CWDwarf_Fde\fP descriptors |
|
4481 pointed to by \fPfde_data\fP. |
|
4482 The index starts with 0. |
|
4483 Returns \f(CWDW_DLV_NO_ENTRY\fP if the index does not |
|
4484 exist in the table of \f(CWDwarf_Fde\fP |
|
4485 descriptors. |
|
4486 Returns \f(CWDW_DLV_ERROR\fP if there is an error. |
|
4487 This function cannot be used unless |
|
4488 the block of \f(CWDwarf_Fde\fP descriptors has been created by a call to |
|
4489 \f(CWdwarf_get_fde_list()\fP. |
|
4490 |
|
4491 .H 4 "dwarf_get_fde_at_pc()" |
|
4492 .DS |
|
4493 \f(CWint dwarf_get_fde_at_pc( |
|
4494 Dwarf_Fde *fde_data, |
|
4495 Dwarf_Addr pc_of_interest, |
|
4496 Dwarf_Fde *returned_fde, |
|
4497 Dwarf_Addr *lopc, |
|
4498 Dwarf_Addr *hipc, |
|
4499 Dwarf_Error *error)\fP |
|
4500 .DE |
|
4501 \f(CWdwarf_get_fde_at_pc()\fP returns |
|
4502 \f(CWDW_DLV_OK\fP and sets \f(CWreturned_fde\fP to |
|
4503 a \f(CWDwarf_Fde\fP descriptor |
|
4504 for a function which contains the pc value specified by \f(CWpc_of_interest\fP. |
|
4505 In addition, it sets the locations pointed to |
|
4506 by \f(CWlopc\fP and \f(CWhipc\fP to the low address and the high address |
|
4507 covered by this FDE, respectively. |
|
4508 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4509 It returns \f(CWDW_DLV_NO_ENTRY\fP |
|
4510 if \f(CWpc_of_interest\fP is not in any of the |
|
4511 FDEs represented by the block of \f(CWDwarf_Fde\fP descriptors pointed |
|
4512 to by \f(CWfde_data\fP. |
|
4513 This function cannot be used unless |
|
4514 the block of \f(CWDwarf_Fde\fP descriptors has been created by a call to |
|
4515 \f(CWdwarf_get_fde_list()\fP. |
|
4516 |
|
4517 .H 4 "dwarf_expand_frame_instructions()" |
|
4518 .DS |
|
4519 \f(CWint dwarf_expand_frame_instructions( |
|
4520 Dwarf_Debug dbg, |
|
4521 Dwarf_Ptr instruction, |
|
4522 Dwarf_Unsigned i_length, |
|
4523 Dwarf_Frame_Op **returned_op_list, |
|
4524 Dwarf_Signed * returned_op_count, |
|
4525 Dwarf_Error *error);\fP |
|
4526 .DE |
|
4527 \f(CWdwarf_expand_frame_instructions()\fP is a High-level interface |
|
4528 function which expands a frame instruction byte stream into an |
|
4529 array of \f(CWDwarf_Frame_Op\fP structures. |
|
4530 To indicate success, it returns \f(CWDW_DLV_OK\fP. |
|
4531 The address where |
|
4532 the byte stream begins is specified by \f(CWinstruction\fP, and |
|
4533 the length of the byte stream is specified by \f(CWi_length\fP. |
|
4534 The location pointed to by \f(CWreturned_op_list\fP is set to |
|
4535 point to a table of |
|
4536 \f(CWreturned_op_count\fP |
|
4537 pointers to \f(CWDwarf_Frame_Op\fP which |
|
4538 contain the frame instructions in the byte stream. |
|
4539 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4540 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
4541 After a successful return, the |
|
4542 array of structures should be freed using |
|
4543 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_FRAME_BLOCK\fP |
|
4544 (when they are no longer of interest). |
|
4545 |
|
4546 .in +2 |
|
4547 .DS |
|
4548 \f(CWDwarf_Signed cnt; |
|
4549 Dwarf_Frame_Op *frameops; |
|
4550 Dwarf_Ptr instruction; |
|
4551 Dwarf_Unsigned len; |
|
4552 int res; |
|
4553 |
|
4554 res = expand_frame_instructions(dbg,instruction,len, &frameops,&cnt, &error); |
|
4555 if (res == DW_DLV_OK) { |
|
4556 |
|
4557 for (i = 0; i < cnt; ++i) { |
|
4558 /* use frameops[i] */ |
|
4559 } |
|
4560 dwarf_dealloc(dbg, frameops, DW_DLA_FRAME_BLOCK); |
|
4561 }\fP |
|
4562 .DE |
|
4563 .in -2 |
|
4564 .H 4 "dwarf_get_fde_exception_info()" |
|
4565 .DS |
|
4566 \f(CWint dwarf_get_fde_exception_info( |
|
4567 Dwarf_Fde fde, |
|
4568 Dwarf_Signed * offset_into_exception_tables, |
|
4569 Dwarf_Error * error); |
|
4570 .DE |
|
4571 \f(CWdwarf_get_fde_exception_info()\fP is an IRIX specific |
|
4572 function which returns an exception table signed offset |
|
4573 thru \f(CWoffset_into_exception_tables\fP. |
|
4574 The function never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
4575 If \f(CWDW_DLV_NO_ENTRY\fP is NULL the function returns |
|
4576 \f(CWDW_DLV_ERROR\fP. |
|
4577 For non-IRIX objects the offset returned will always be zero. |
|
4578 For non-C++ objects the offset returned will always be zero. |
|
4579 The meaning of the offset and the content of the tables |
|
4580 is not defined in this document. |
|
4581 The applicable CIE augmentation string (see above) |
|
4582 determines whether the value returned has meaning. |
|
4583 |
|
4584 .H 2 "Location Expression Evaluation" |
|
4585 |
|
4586 An "interpreter" which evaluates a location expression |
|
4587 is required in any debugger. There is no interface defined |
|
4588 here at this time. |
|
4589 |
|
4590 .P |
|
4591 One problem with defining an interface is that operations are |
|
4592 machine dependent: they depend on the interpretation of |
|
4593 register numbers and the methods of getting values from the |
|
4594 environment the expression is applied to. |
|
4595 |
|
4596 .P |
|
4597 It would be desirable to specify an interface. |
|
4598 |
|
4599 .H 3 "Location List Internal-level Interface" |
|
4600 |
|
4601 .H 4 "dwarf_get_loclist_entry()" |
|
4602 .DS |
|
4603 \f(CWint dwarf_get_loclist_entry( |
|
4604 Dwarf_Debug dbg, |
|
4605 Dwarf_Unsigned offset, |
|
4606 Dwarf_Addr *hipc_offset, |
|
4607 Dwarf_Addr *lopc_offset, |
|
4608 Dwarf_Ptr *data, |
|
4609 Dwarf_Unsigned *entry_len, |
|
4610 Dwarf_Unsigned *next_entry, |
|
4611 Dwarf_Error *error)\fP |
|
4612 .DE |
|
4613 The function reads |
|
4614 a location list entry starting at \f(CWoffset\fP and returns |
|
4615 through pointers (when successful) |
|
4616 the high pc \f(CWhipc_offset\fP, low pc |
|
4617 \f(CWlopc_offset\fP, a pointer to the location description data |
|
4618 \f(CWdata\fP, the length of the location description data |
|
4619 \f(CWentry_len\fP, and the offset of the next location description |
|
4620 entry \f(CWnext_entry\fP. |
|
4621 \f(CWdwarf_dwarf_get_loclist_entry()\fP returns |
|
4622 \f(CWDW_DLV_OK\fP if successful. |
|
4623 \f(CWDW_DLV_NO_ENTRY\fP is returned when the offset passed |
|
4624 in is beyond the end of the .debug_loc section (expected if |
|
4625 you start at offset zero and proceed thru all the entries). |
|
4626 \f(CWDW_DLV_ERROR\fP is returned on error. |
|
4627 .P |
|
4628 The \f(CWhipc_offset\fP, |
|
4629 low pc \f(CWlopc_offset\fP are offsets from the beginning of the |
|
4630 current procedure, not genuine pc values. |
|
4631 .in +2 |
|
4632 .DS |
|
4633 \f(CW |
|
4634 /* Looping thru the dwarf_loc section finding loclists: |
|
4635 an example. */ |
|
4636 int res; |
|
4637 Dwarf_Unsigned next_entry; |
|
4638 Dwarf_unsigned offset=0; |
|
4639 Dwarf_Addr hipc_off; |
|
4640 Dwarf_Addr lopc_off; |
|
4641 Dwarf_Ptr data; |
|
4642 Dwarf_Unsigned entry_len; |
|
4643 Dwarf_Unsigned next_entry; |
|
4644 Dwarf_Error err; |
|
4645 |
|
4646 for(;;) { |
|
4647 res = dwarf_get_loclist_entry(dbg,newoffset,&hipc_off, |
|
4648 &lowpc_off, &data, &entry_len,&next_entry,&err); |
|
4649 if (res == DW_DLV_OK) { |
|
4650 /* A valid entry. */ |
|
4651 newoffset = next_entry; |
|
4652 continue; |
|
4653 } else if (res ==DW_DLV_NO_ENTRY) { |
|
4654 /* Done! */ |
|
4655 break; |
|
4656 } else { |
|
4657 /* Error! */ |
|
4658 break; |
|
4659 } |
|
4660 |
|
4661 |
|
4662 } |
|
4663 }\fP |
|
4664 .DE |
|
4665 .in -2 |
|
4666 |
|
4667 |
|
4668 .H 2 "Abbreviations access" |
|
4669 These are Internal-level Interface functions. |
|
4670 Debuggers can ignore this. |
|
4671 |
|
4672 .H 3 "dwarf_get_abbrev()" |
|
4673 .DS |
|
4674 \f(CWint dwarf_get_abbrev( |
|
4675 Dwarf_Debug dbg, |
|
4676 Dwarf_Unsigned offset, |
|
4677 Dwarf_Abbrev *returned_abbrev, |
|
4678 Dwarf_Unsigned *length, |
|
4679 Dwarf_Unsigned *attr_count, |
|
4680 Dwarf_Error *error)\fP |
|
4681 .DE |
|
4682 The function \f(CWdwarf_get_abbrev()\fP returns |
|
4683 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_abbrev\fP to |
|
4684 \f(CWDwarf_Abbrev\fP |
|
4685 descriptor for an abbreviation at offset \f(CW*offset\fP in the abbreviations |
|
4686 section (i.e .debug_abbrev) on success. |
|
4687 The user is responsible for making sure that |
|
4688 a valid abbreviation begins at \f(CWoffset\fP in the abbreviations section. |
|
4689 The location pointed to by \f(CWlength\fP |
|
4690 is set to the length in bytes of the abbreviation in the abbreviations |
|
4691 section. |
|
4692 The location pointed to by \f(CWattr_count\fP is set to the |
|
4693 number of attributes in the abbreviation. |
|
4694 An abbreviation entry with a |
|
4695 length of 1 is the 0 byte of the last abbreviation entry of a compilation |
|
4696 unit. |
|
4697 \f(CWdwarf_get_abbrev()\fP returns \f(CWDW_DLV_ERROR\fP on error. |
|
4698 If the call succeeds, the storage pointed to |
|
4699 by \f(CW*returned_abbrev\fP |
|
4700 should be free'd, using \f(CWdwarf_dealloc()\fP with the |
|
4701 allocation type \f(CWDW_DLA_ABBREV\fP when no longer needed. |
|
4702 |
|
4703 |
|
4704 .H 3 "dwarf_get_abbrev_tag()" |
|
4705 .DS |
|
4706 \f(CWint dwarf_get_abbrev_tag( |
|
4707 Dwarf_abbrev abbrev, |
|
4708 Dwarf_Half *return_tag, |
|
4709 Dwarf_Error *error);\fP |
|
4710 .DE |
|
4711 If successful, |
|
4712 \f(CWdwarf_get_abbrev_tag()\fP returns |
|
4713 \f(CWDW_DLV_OK\fP and sets \f(CW*return_tag\fP to |
|
4714 the \fItag\fP of |
|
4715 the given abbreviation. |
|
4716 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4717 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
4718 |
|
4719 .H 3 "dwarf_get_abbrev_code()" |
|
4720 .DS |
|
4721 \f(CWint dwarf_get_abbrev_code( |
|
4722 Dwarf_abbrev abbrev, |
|
4723 Dwarf_Unsigned *return_code, |
|
4724 Dwarf_Error *error);\fP |
|
4725 .DE |
|
4726 If successful, |
|
4727 \f(CWdwarf_get_abbrev_code()\fP returns |
|
4728 \f(CWDW_DLV_OK\fP and sets \f(CW*return_code\fP to |
|
4729 the abbreviation code of |
|
4730 the given abbreviation. |
|
4731 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4732 It never returns \f(CWDW_DLV_NO_ENTRY\fP. |
|
4733 |
|
4734 .H 3 "dwarf_get_abbrev_children_flag()" |
|
4735 .DS |
|
4736 \f(CWint dwarf_get_abbrev_children_flag( |
|
4737 Dwarf_Abbrev abbrev, |
|
4738 Dwarf_Signed *returned_flag, |
|
4739 Dwarf_Error *error)\fP |
|
4740 .DE |
|
4741 The function \f(CWdwarf_get_abbrev_children_flag()\fP returns |
|
4742 \f(CWDW_DLV_OK\fP and sets \f(CWreturned_flag\fP to |
|
4743 \f(CWDW_children_no\fP (if the given abbreviation indicates that |
|
4744 a die with that abbreviation has no children) or |
|
4745 \f(CWDW_children_yes\fP (if the given abbreviation indicates that |
|
4746 a die with that abbreviation has a child). |
|
4747 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4748 |
|
4749 .H 3 "dwarf_get_abbrev_entry()" |
|
4750 .DS |
|
4751 \f(CWint dwarf_get_abbrev_entry( |
|
4752 Dwarf_Abbrev abbrev, |
|
4753 Dwarf_Signed index, |
|
4754 Dwarf_Half *attr_num, |
|
4755 Dwarf_Signed *form, |
|
4756 Dwarf_Off *offset, |
|
4757 Dwarf_Error *error)\fP |
|
4758 |
|
4759 .DE |
|
4760 If successful, |
|
4761 \f(CWdwarf_get_abbrev_entry()\fP returns |
|
4762 \f(CWDW_DLV_OK\fP and sets \f(CW*attr_num\fP to the attribute code of |
|
4763 the attribute |
|
4764 whose index is specified by \f(CWindex\fP in the given abbreviation. |
|
4765 The index starts at 0. |
|
4766 The location pointed to by \f(CWform\fP is set |
|
4767 to the form of the attribute. |
|
4768 The location pointed to by \f(CWoffset\fP |
|
4769 is set to the byte offset of the attribute in the abbreviations section. |
|
4770 It returns \f(CWDW_DLV_NO_ENTRY\fP if the index specified is outside |
|
4771 the range of attributes in this abbreviation. |
|
4772 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4773 |
|
4774 .H 2 "String Section Operations" |
|
4775 The .debug_str section contains only strings. Debuggers need |
|
4776 never use this interface: it is only for debugging problems with |
|
4777 the string section itself. |
|
4778 |
|
4779 .H 3 "dwarf_get_str()" |
|
4780 .DS |
|
4781 \f(CWint dwarf_get_str( |
|
4782 Dwarf_Debug dbg, |
|
4783 Dwarf_Off offset, |
|
4784 char **string, |
|
4785 Dwarf_Signed *returned_str_len, |
|
4786 Dwarf_Error *error)\fP |
|
4787 .DE |
|
4788 The function \f(CWdwarf_get_str()\fP returns |
|
4789 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_str_len\fP to |
|
4790 the length of |
|
4791 the string, not counting the null terminator, that begins at the offset |
|
4792 specified by \f(CWoffset\fP in the .debug_str section. |
|
4793 The location |
|
4794 pointed to by \f(CWstring\fP is set to a pointer to this string. |
|
4795 The next string in the .debug_str |
|
4796 section begins at the previous \f(CWoffset\fP + 1 + \f(CW*returned_str_len\fP. |
|
4797 A zero-length string is NOT the end of the section. |
|
4798 If there is no .debug_str section, \f(CWDW_DLV_NO_ENTRY\fP is returned. |
|
4799 If there is an error, \f(CWDW_DLV_ERROR\fP is returned. |
|
4800 If we are at the end of the section (that is, \f(CWoffset\fP |
|
4801 is one past the end of the section) \f(CWDW_DLV_NO_ENTRY\fP is returned. |
|
4802 If the \f(CWoffset\fP is some other too-large value then |
|
4803 \f(CWDW_DLV_ERROR\fP is returned. |
|
4804 |
|
4805 .H 2 "Address Range Operations" |
|
4806 These functions provide information about address ranges. Address |
|
4807 ranges map ranges of pc values to the corresponding compilation-unit |
|
4808 die that covers the address range. |
|
4809 |
|
4810 .H 3 "dwarf_get_aranges()" |
|
4811 .DS |
|
4812 \f(CWint dwarf_get_aranges( |
|
4813 Dwarf_Debug dbg, |
|
4814 Dwarf_Arange **aranges, |
|
4815 Dwarf_Signed * returned_arange_count, |
|
4816 Dwarf_Error *error)\fP |
|
4817 .DE |
|
4818 The function \f(CWdwarf_get_aranges()\fP returns |
|
4819 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_arange_count\fP to |
|
4820 the count of the |
|
4821 number of address ranges in the .debug_aranges section. |
|
4822 It sets |
|
4823 \f(CW*aranges\fP to point to a block of \f(CWDwarf_Arange\fP |
|
4824 descriptors, one for each address range. |
|
4825 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4826 It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no .debug_aranges |
|
4827 section. |
|
4828 |
|
4829 .in +2 |
|
4830 .DS |
|
4831 \f(CWDwarf_Signed cnt; |
|
4832 Dwarf_Arange *arang; |
|
4833 int res; |
|
4834 |
|
4835 res = dwarf_get_aranges(dbg, &arang,&cnt, &error); |
|
4836 if (res == DW_DLV_OK) { |
|
4837 |
|
4838 for (i = 0; i < cnt; ++i) { |
|
4839 /* use arang[i] */ |
|
4840 dwarf_dealloc(dbg, arang[i], DW_DLA_ARANGE); |
|
4841 } |
|
4842 dwarf_dealloc(dbg, arang, DW_DLA_LIST); |
|
4843 }\fP |
|
4844 .DE |
|
4845 .in -2 |
|
4846 |
|
4847 |
|
4848 .DS |
|
4849 \f(CWint dwarf_get_arange( |
|
4850 Dwarf_Arange *aranges, |
|
4851 Dwarf_Unsigned arange_count, |
|
4852 Dwarf_Addr address, |
|
4853 Dwarf_Arange *returned_arange, |
|
4854 Dwarf_Error *error);\fP |
|
4855 .DE |
|
4856 The function \f(CWdwarf_get_arange()\fP takes as input a pointer |
|
4857 to a block of \f(CWDwarf_Arange\fP pointers, and a count of the |
|
4858 number of descriptors in the block. |
|
4859 It then searches for the |
|
4860 descriptor that covers the given \f(CWaddress\fP. |
|
4861 If it finds |
|
4862 one, it returns |
|
4863 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_arange\fP to |
|
4864 the descriptor. |
|
4865 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4866 It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no .debug_aranges |
|
4867 entry covering that address. |
|
4868 |
|
4869 |
|
4870 .H 3 "dwarf_get_cu_die_offset()" |
|
4871 .DS |
|
4872 \f(CWint dwarf_get_cu_die_offset( |
|
4873 Dwarf_Arange arange, |
|
4874 Dwarf_Off *returned_cu_die_offset, |
|
4875 Dwarf_Error *error);\fP |
|
4876 .DE |
|
4877 The function \f(CWdwarf_get_cu_die_offset()\fP takes a |
|
4878 \f(CWDwarf_Arange\fP descriptor as input, and |
|
4879 if successful returns |
|
4880 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_cu_die_offset\fP to |
|
4881 the offset |
|
4882 in the .debug_info section of the compilation-unit DIE for the |
|
4883 compilation-unit represented by the given address range. |
|
4884 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4885 |
|
4886 .H 3 "dwarf_get_arange_cu_header_offset()" |
|
4887 .DS |
|
4888 \f(CWint dwarf_get_arange_cu_header_offset( |
|
4889 Dwarf_Arange arange, |
|
4890 Dwarf_Off *returned_cu_header_offset, |
|
4891 Dwarf_Error *error)\fP |
|
4892 .DE |
|
4893 The function \f(CWdwarf_get_arange_cu_header_offset()\fP takes a |
|
4894 \f(CWDwarf_Arange\fP descriptor as input, and |
|
4895 if successful returns |
|
4896 \f(CWDW_DLV_OK\fP and sets \f(CW*returned_cu_header_offset\fP to |
|
4897 the offset |
|
4898 in the .debug_info section of the compilation-unit header for the |
|
4899 compilation-unit represented by the given address range. |
|
4900 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4901 |
|
4902 This function added Rev 1.45, June, 2001. |
|
4903 |
|
4904 This function is declared as 'optional' in libdwarf.h |
|
4905 on IRIX systems so the _MIPS_SYMBOL_PRESENT |
|
4906 predicate may be used at run time to determine if the version of |
|
4907 libdwarf linked into an application has this function. |
|
4908 |
|
4909 |
|
4910 |
|
4911 .H 3 "dwarf_get_arange_info()" |
|
4912 .DS |
|
4913 \f(CWint dwarf_get_arange_info( |
|
4914 Dwarf_Arange arange, |
|
4915 Dwarf_Addr *start, |
|
4916 Dwarf_Unsigned *length, |
|
4917 Dwarf_Off *cu_die_offset, |
|
4918 Dwarf_Error *error)\fP |
|
4919 .DE |
|
4920 The function \f(CWdwarf_get_arange_info()\fP returns |
|
4921 \f(CWDW_DLV_OK\fP |
|
4922 and |
|
4923 stores the starting value of the address range in the location pointed |
|
4924 to by \f(CWstart\fP, the length of the address range in the location |
|
4925 pointed to by \f(CWlength\fP, and the offset in the .debug_info section |
|
4926 of the compilation-unit DIE for the compilation-unit represented by the |
|
4927 address range. |
|
4928 It returns \f(CWDW_DLV_ERROR\fP on error. |
|
4929 |
|
4930 .H 2 "General Low Level Operations" |
|
4931 This function is low-level and intended for use only |
|
4932 by programs such as dwarf-dumpers. |
|
4933 |
|
4934 .H 3 "dwarf_get_address_size()" |
|
4935 .DS |
|
4936 \f(CWint dwarf_get_address_size(Dwarf_Debug dbg, |
|
4937 Dwarf_Half *addr_size, |
|
4938 Dwarf_Error *error)\fP |
|
4939 .DE |
|
4940 The function \f(CWdwarf_get_address_size()\fP |
|
4941 returns \f(CWDW_DLV_OK\fP on success and sets |
|
4942 the \f(CW*addr_size\fP |
|
4943 to the size in bytes of an address. |
|
4944 In case of error, it returns \f(CWDW_DLV_ERROR\fP |
|
4945 and does not set \f(CW*addr_size\fP. |
|
4946 |
|
4947 |
|
4948 .H 2 "Utility Operations" |
|
4949 These functions aid in the management of errors encountered when using |
|
4950 functions in the \fIlibdwarf\fP library and releasing memory allocated |
|
4951 as a result of a \fIlibdwarf\fP operation. |
|
4952 |
|
4953 .H 3 "dwarf_errno()" |
|
4954 .DS |
|
4955 \f(CWDwarf_Unsigned dwarf_errno( |
|
4956 Dwarf_Error error)\fP |
|
4957 .DE |
|
4958 The function \f(CWdwarf_errno()\fP returns the error number corresponding |
|
4959 to the error specified by \f(CWerror\fP. |
|
4960 |
|
4961 .H 3 "dwarf_errmsg()" |
|
4962 .DS |
|
4963 \f(CWconst char* dwarf_errmsg( |
|
4964 Dwarf_Error error)\fP |
|
4965 .DE |
|
4966 The function \f(CWdwarf_errmsg()\fP returns a pointer to a |
|
4967 null-terminated error message string corresponding to the error specified by |
|
4968 \f(CWerror\fP. |
|
4969 The string returned by \f(CWdwarf_errmsg()\fP |
|
4970 should not be deallocated using \f(CWdwarf_dealloc()\fP. |
|
4971 |
|
4972 .P |
|
4973 The set of errors |
|
4974 enumerated in Figure \n(aX below were defined in Dwarf 1. |
|
4975 These errors are not used by the current implementation |
|
4976 of Dwarf 2. |
|
4977 .DS |
|
4978 .TS |
|
4979 center box, tab(:); |
|
4980 lfB lfB |
|
4981 l l. |
|
4982 SYMBOLIC NAME:DESCRIPTION |
|
4983 _ |
|
4984 DW_DLE_NE:No error (0) |
|
4985 DW_DLE_VMM:Version of DWARF information newer than libdwarf |
|
4986 DW_DLE_MAP:Memory map failure |
|
4987 DW_DLE_LEE:Propagation of libelf error |
|
4988 DW_DLE_NDS:No debug section |
|
4989 DW_DLE_NLS:No line section |
|
4990 DW_DLE_ID:Requested information not associated with descriptor |
|
4991 DW_DLE_IOF:I/O failure |
|
4992 DW_DLE_MAF:Memory allocation failure |
|
4993 DW_DLE_IA:Invalid argument |
|
4994 DW_DLE_MDE:Mangled debugging entry |
|
4995 DW_DLE_MLE:Mangled line number entry |
|
4996 DW_DLE_FNO:File descriptor does not refer to an open file |
|
4997 DW_DLE_FNR:File is not a regular file |
|
4998 DW_DLE_FWA:File is opened with wrong access |
|
4999 DW_DLE_NOB:File is not an object file |
|
5000 DW_DLE_MOF:Mangled object file header |
|
5001 DW_DLE_EOLL:End of location list entries |
|
5002 DW_DLE_NOLL:No location list section |
|
5003 DW_DLE_BADOFF:Invalid offset |
|
5004 DW_DLE_EOS:End of section |
|
5005 DW_DLE_ATRUNC:Abbreviations section appears truncated |
|
5006 DW_DLE_BADBITC:Address size passed to dwarf bad |
|
5007 .TE |
|
5008 .FG "List of Dwarf Error Codes" |
|
5009 .DE |
|
5010 |
|
5011 The set of errors returned by SGI \f(CWLibdwarf\fP functions |
|
5012 is listed below. |
|
5013 Some of the errors are SGI specific. |
|
5014 |
|
5015 .DS |
|
5016 .TS |
|
5017 center box, tab(:); |
|
5018 lfB lfB |
|
5019 l l. |
|
5020 SYMBOLIC NAME:DESCRIPTION |
|
5021 _ |
|
5022 DW_DLE_DBG_ALLOC:Could not allocate Dwarf_Debug struct |
|
5023 DW_DLE_FSTAT_ERROR:Error in fstat()-ing object |
|
5024 DW_DLE_FSTAT_MODE_ERROR:Error in mode of object file |
|
5025 DW_DLE_INIT_ACCESS_WRONG:Incorrect access to dwarf_init() |
|
5026 DW_DLE_ELF_BEGIN_ERROR:Error in elf_begin() on object |
|
5027 DW_DLE_ELF_GETEHDR_ERROR:Error in elf_getehdr() on object |
|
5028 DW_DLE_ELF_GETSHDR_ERROR:Error in elf_getshdr() on object |
|
5029 DW_DLE_ELF_STRPTR_ERROR:Error in elf_strptr() on object |
|
5030 DW_DLE_DEBUG_INFO_DUPLICATE:Multiple .debug_info sections |
|
5031 DW_DLE_DEBUG_INFO_NULL:No data in .debug_info section |
|
5032 DW_DLE_DEBUG_ABBREV_DUPLICATE:Multiple .debug_abbrev sections |
|
5033 DW_DLE_DEBUG_ABBREV_NULL:No data in .debug_abbrev section |
|
5034 DW_DLE_DEBUG_ARANGES_DUPLICATE:Multiple .debug_arange sections |
|
5035 DW_DLE_DEBUG_ARANGES_NULL:No data in .debug_arange section |
|
5036 DW_DLE_DEBUG_LINE_DUPLICATE:Multiple .debug_line sections |
|
5037 DW_DLE_DEBUG_LINE_NULL:No data in .debug_line section |
|
5038 DW_DLE_DEBUG_LOC_DUPLICATE:Multiple .debug_loc sections |
|
5039 DW_DLE_DEBUG_LOC_NULL:No data in .debug_loc section |
|
5040 DW_DLE_DEBUG_MACINFO_DUPLICATE:Multiple .debug_macinfo sections |
|
5041 DW_DLE_DEBUG_MACINFO_NULL:No data in .debug_macinfo section |
|
5042 DW_DLE_DEBUG_PUBNAMES_DUPLICATE:Multiple .debug_pubnames sections |
|
5043 DW_DLE_DEBUG_PUBNAMES_NULL:No data in .debug_pubnames section |
|
5044 DW_DLE_DEBUG_STR_DUPLICATE:Multiple .debug_str sections |
|
5045 DW_DLE_DEBUG_STR_NULL:No data in .debug_str section |
|
5046 DW_DLE_CU_LENGTH_ERROR:Length of compilation-unit bad |
|
5047 DW_DLE_VERSION_STAMP_ERROR:Incorrect Version Stamp |
|
5048 DW_DLE_ABBREV_OFFSET_ERROR:Offset in .debug_abbrev bad |
|
5049 DW_DLE_ADDRESS_SIZE_ERROR:Size of addresses in target bad |
|
5050 DW_DLE_DEBUG_INFO_PTR_NULL:Pointer into .debug_info in DIE null |
|
5051 DW_DLE_DIE_NULL:Null Dwarf_Die |
|
5052 DW_DLE_STRING_OFFSET_BAD:Offset in .debug_str bad |
|
5053 DW_DLE_DEBUG_LINE_LENGTH_BAD:Length of .debug_line segment bad |
|
5054 DW_DLE_LINE_PROLOG_LENGTH_BAD:Length of .debug_line prolog bad |
|
5055 DW_DLE_LINE_NUM_OPERANDS_BAD:Number of operands to line instr bad |
|
5056 DW_DLE_LINE_SET_ADDR_ERROR:Error in DW_LNE_set_address instruction |
|
5057 DW_DLE_LINE_EXT_OPCODE_BAD:Error in DW_EXTENDED_OPCODE instruction |
|
5058 DW_DLE_DWARF_LINE_NULL:Null Dwarf_line argument |
|
5059 DW_DLE_INCL_DIR_NUM_BAD:Error in included directory for given line |
|
5060 DW_DLE_LINE_FILE_NUM_BAD:File number in .debug_line bad |
|
5061 DW_DLE_ALLOC_FAIL:Failed to allocate required structs |
|
5062 DW_DLE_DBG_NULL:Null Dwarf_Debug argument |
|
5063 DW_DLE_DEBUG_FRAME_LENGTH_BAD:Error in length of frame |
|
5064 DW_DLE_FRAME_VERSION_BAD:Bad version stamp for frame |
|
5065 DW_DLE_CIE_RET_ADDR_REG_ERROR:Bad register specified for return address |
|
5066 DW_DLE_FDE_NULL:Null Dwarf_Fde argument |
|
5067 DW_DLE_FDE_DBG_NULL:No Dwarf_Debug associated with FDE |
|
5068 DW_DLE_CIE_NULL:Null Dwarf_Cie argument |
|
5069 DW_DLE_CIE_DBG_NULL:No Dwarf_Debug associated with CIE |
|
5070 DW_DLE_FRAME_TABLE_COL_BAD:Bad column in frame table specified |
|
5071 .TE |
|
5072 .FG "List of Dwarf 2 Error Codes (continued)" |
|
5073 .DE |
|
5074 |
|
5075 .DS |
|
5076 .TS |
|
5077 center box, tab(:); |
|
5078 lfB lfB |
|
5079 l l. |
|
5080 SYMBOLIC NAME:DESCRIPTION |
|
5081 _ |
|
5082 DW_DLE_PC_NOT_IN_FDE_RANGE:PC requested not in address range of FDE |
|
5083 DW_DLE_CIE_INSTR_EXEC_ERROR:Error in executing instructions in CIE |
|
5084 DW_DLE_FRAME_INSTR_EXEC_ERROR:Error in executing instructions in FDE |
|
5085 DW_DLE_FDE_PTR_NULL:Null Pointer to Dwarf_Fde specified |
|
5086 DW_DLE_RET_OP_LIST_NULL:No location to store pointer to Dwarf_Frame_Op |
|
5087 DW_DLE_LINE_CONTEXT_NULL:Dwarf_Line has no context |
|
5088 DW_DLE_DBG_NO_CU_CONTEXT:dbg has no CU context for dwarf_siblingof() |
|
5089 DW_DLE_DIE_NO_CU_CONTEXT:Dwarf_Die has no CU context |
|
5090 DW_DLE_FIRST_DIE_NOT_CU:First DIE in CU not DW_TAG_compilation_unit |
|
5091 DW_DLE_NEXT_DIE_PTR_NULL:Error in moving to next DIE in .debug_info |
|
5092 DW_DLE_DEBUG_FRAME_DUPLICATE:Multiple .debug_frame sections |
|
5093 DW_DLE_DEBUG_FRAME_NULL:No data in .debug_frame section |
|
5094 DW_DLE_ABBREV_DECODE_ERROR:Error in decoding abbreviation |
|
5095 DW_DLE_DWARF_ABBREV_NULL:Null Dwarf_Abbrev specified |
|
5096 DW_DLE_ATTR_NULL:Null Dwarf_Attribute specified |
|
5097 DW_DLE_DIE_BAD:DIE bad |
|
5098 DW_DLE_DIE_ABBREV_BAD:No abbreviation found for code in DIE |
|
5099 DW_DLE_ATTR_FORM_BAD:Inappropriate attribute form for attribute |
|
5100 DW_DLE_ATTR_NO_CU_CONTEXT:No CU context for Dwarf_Attribute struct |
|
5101 DW_DLE_ATTR_FORM_SIZE_BAD:Size of block in attribute value bad |
|
5102 DW_DLE_ATTR_DBG_NULL:No Dwarf_Debug for Dwarf_Attribute struct |
|
5103 DW_DLE_BAD_REF_FORM:Inappropriate form for reference attribute |
|
5104 DW_DLE_ATTR_FORM_OFFSET_BAD:Offset reference attribute outside current CU |
|
5105 DW_DLE_LINE_OFFSET_BAD:Offset of lines for current CU outside .debug_line |
|
5106 DW_DLE_DEBUG_STR_OFFSET_BAD:Offset into .debug_str past its end |
|
5107 DW_DLE_STRING_PTR_NULL:Pointer to pointer into .debug_str NULL |
|
5108 DW_DLE_PUBNAMES_VERSION_ERROR:Version stamp of pubnames incorrect |
|
5109 DW_DLE_PUBNAMES_LENGTH_BAD:Read pubnames past end of .debug_pubnames |
|
5110 DW_DLE_GLOBAL_NULL:Null Dwarf_Global specified |
|
5111 DW_DLE_GLOBAL_CONTEXT_NULL:No context for Dwarf_Global given |
|
5112 DW_DLE_DIR_INDEX_BAD:Error in directory index read |
|
5113 DW_DLE_LOC_EXPR_BAD:Bad operator read for location expression |
|
5114 DW_DLE_DIE_LOC_EXPR_BAD:Expected block value for attribute not found |
|
5115 DW_DLE_OFFSET_BAD:Offset for next compilation-unit in .debug_info bad |
|
5116 DW_DLE_MAKE_CU_CONTEXT_FAIL:Could not make CU context |
|
5117 DW_DLE_ARANGE_OFFSET_BAD:Offset into .debug_info in .debug_aranges bad |
|
5118 DW_DLE_SEGMENT_SIZE_BAD:Segment size should be 0 for MIPS processors |
|
5119 DW_DLE_ARANGE_LENGTH_BAD:Length of arange section in .debug_arange bad |
|
5120 DW_DLE_ARANGE_DECODE_ERROR:Aranges do not end at end of .debug_aranges |
|
5121 DW_DLE_ARANGES_NULL:NULL pointer to Dwarf_Arange specified |
|
5122 DW_DLE_ARANGE_NULL:NULL Dwarf_Arange specified |
|
5123 DW_DLE_NO_FILE_NAME:No file name for Dwarf_Line struct |
|
5124 DW_DLE_NO_COMP_DIR:No Compilation directory for compilation-unit |
|
5125 DW_DLE_CU_ADDRESS_SIZE_BAD:CU header address size not match Elf class |
|
5126 DW_DLE_ELF_GETIDENT_ERROR:Error in elf_getident() on object |
|
5127 DW_DLE_NO_AT_MIPS_FDE:DIE does not have DW_AT_MIPS_fde attribute |
|
5128 DW_DLE_NO_CIE_FOR_FDE:No CIE specified for FDE |
|
5129 DW_DLE_DIE_ABBREV_LIST_NULL:No abbreviation for the code in DIE found |
|
5130 DW_DLE_DEBUG_FUNCNAMES_DUPLICATE:Multiple .debug_funcnames sections |
|
5131 DW_DLE_DEBUG_FUNCNAMES_NULL:No data in .debug_funcnames section |
|
5132 .TE |
|
5133 .FG "List of Dwarf 2 Error Codes (continued)" |
|
5134 .DE |
|
5135 |
|
5136 .DS |
|
5137 .TS |
|
5138 center box, tab(:); |
|
5139 lfB lfB |
|
5140 l l. |
|
5141 SYMBOLIC NAME:DESCRIPTION |
|
5142 _ |
|
5143 DW_DLE_DEBUG_FUNCNAMES_VERSION_ERROR:Version stamp in .debug_funcnames bad |
|
5144 DW_DLE_DEBUG_FUNCNAMES_LENGTH_BAD:Length error in reading .debug_funcnames |
|
5145 DW_DLE_FUNC_NULL:NULL Dwarf_Func specified |
|
5146 DW_DLE_FUNC_CONTEXT_NULL:No context for Dwarf_Func struct |
|
5147 DW_DLE_DEBUG_TYPENAMES_DUPLICATE:Multiple .debug_typenames sections |
|
5148 DW_DLE_DEBUG_TYPENAMES_NULL:No data in .debug_typenames section |
|
5149 DW_DLE_DEBUG_TYPENAMES_VERSION_ERROR:Version stamp in .debug_typenames bad |
|
5150 DW_DLE_DEBUG_TYPENAMES_LENGTH_BAD:Length error in reading .debug_typenames |
|
5151 DW_DLE_TYPE_NULL:NULL Dwarf_Type specified |
|
5152 DW_DLE_TYPE_CONTEXT_NULL:No context for Dwarf_Type given |
|
5153 DW_DLE_DEBUG_VARNAMES_DUPLICATE:Multiple .debug_varnames sections |
|
5154 DW_DLE_DEBUG_VARNAMES_NULL:No data in .debug_varnames section |
|
5155 DW_DLE_DEBUG_VARNAMES_VERSION_ERROR:Version stamp in .debug_varnames bad |
|
5156 DW_DLE_DEBUG_VARNAMES_LENGTH_BAD:Length error in reading .debug_varnames |
|
5157 DW_DLE_VAR_NULL:NULL Dwarf_Var specified |
|
5158 DW_DLE_VAR_CONTEXT_NULL:No context for Dwarf_Var given |
|
5159 DW_DLE_DEBUG_WEAKNAMES_DUPLICATE:Multiple .debug_weaknames section |
|
5160 DW_DLE_DEBUG_WEAKNAMES_NULL:No data in .debug_varnames section |
|
5161 DW_DLE_DEBUG_WEAKNAMES_VERSION_ERROR:Version stamp in .debug_varnames bad |
|
5162 DW_DLE_DEBUG_WEAKNAMES_LENGTH_BAD:Length error in reading .debug_weaknames |
|
5163 DW_DLE_WEAK_NULL:NULL Dwarf_Weak specified |
|
5164 DW_DLE_WEAK_CONTEXT_NULL:No context for Dwarf_Weak given |
|
5165 .TE |
|
5166 .FG "List of Dwarf 2 Error Codes" |
|
5167 .DE |
|
5168 |
|
5169 This list of errors is not necessarily complete; |
|
5170 additional errors |
|
5171 might be added when functionality to create debugging information |
|
5172 entries are added to \fIlibdwarf\fP and by the implementors of |
|
5173 \fIlibdwarf\fP to describe internal errors not addressed by the |
|
5174 above list. |
|
5175 Some of the above errors may be unused. |
|
5176 Errors may not have the same meaning in different implementations. |
|
5177 |
|
5178 .H 3 "dwarf_seterrhand()" |
|
5179 .DS |
|
5180 \f(CWDwarf_Handler dwarf_seterrhand( |
|
5181 Dwarf_Debug dbg, |
|
5182 Dwarf_Handler errhand)\fP |
|
5183 .DE |
|
5184 The function \f(CWdwarf_seterrhand()\fP replaces the error handler |
|
5185 (see \f(CWdwarf_init()\fP) with \f(CWerrhand\fP. The old error handler |
|
5186 is returned. This function is currently unimplemented. |
|
5187 |
|
5188 .H 3 "dwarf_seterrarg()" |
|
5189 .DS |
|
5190 \f(CWDwarf_Ptr dwarf_seterrarg( |
|
5191 Dwarf_Debug dbg, |
|
5192 Dwarf_Ptr errarg)\fP |
|
5193 .DE |
|
5194 The function \f(CWdwarf_seterrarg()\fP replaces the pointer to the |
|
5195 error handler communication area (see \f(CWdwarf_init()\fP) with |
|
5196 \f(CWerrarg\fP. A pointer to the old area is returned. This |
|
5197 function is currently unimplemented. |
|
5198 |
|
5199 .H 3 "dwarf_dealloc()" |
|
5200 .DS |
|
5201 \f(CWvoid dwarf_dealloc( |
|
5202 Dwarf_Debug dbg, |
|
5203 void* space, |
|
5204 Dwarf_Unsigned type)\fP |
|
5205 .DE |
|
5206 The function \f(CWdwarf_dealloc\fP frees the dynamic storage pointed |
|
5207 to by \f(CWspace\fP, and allocated to the given \f(CWDwarf_Debug\fP. |
|
5208 The argument \f(CWtype\fP is an integer code that specifies the allocation |
|
5209 type of the region pointed to by the \f(CWspace\fP. Refer to section |
|
5210 4 for details on \fIlibdwarf\fP memory management. |
|
5211 |
|
5212 .SK |
|
5213 .S |
|
5214 .TC 1 1 4 |
|
5215 .CS |