\." \." the following line may be removed if the ff ligature works on your machine .lg 0 \." set up heading formats .ds HF 3 3 3 3 3 2 2 .ds HP +2 +2 +1 +0 +0 .nr Hs 5 .nr Hb 5 \." ============================================== \." Put current date in the following at each rev .ds vE rev 1.65, 03 July 2007 \." ============================================== \." ============================================== .ds | | .ds ~ ~ .ds ' ' .if t .ds Cw \&\f(CW .if n .ds Cw \fB .de Cf \" Place every other arg in Cw font, beginning with first .if \\n(.$=1 \&\*(Cw\\$1\fP .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2 .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4 .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6 .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8 .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\ *(Cw .. .nr Cl 4 .SA 1 .TL A Consumer Library Interface to DWARF .AF "" .AU "David Anderson" .PF "'\*(vE'- \\\\nP -''" .AS 1 This document describes an interface to a library of functions .FS UNIX is a registered trademark of UNIX System Laboratories, Inc. in the United States and other countries. .FE to access DWARF debugging information entries and DWARF line number information (and other DWARF2/3 information). It does not make recommendations as to how the functions described in this document should be implemented nor does it suggest possible optimizations. .P The document is oriented to reading DWARF version 2 and version 3. There are certain sections which are SGI-specific (those are clearly identified in the document). .P \*(vE .AE .MT 4 .H 1 "INTRODUCTION" This document describes an interface to \fIlibdwarf\fP, a library of functions to provide access to DWARF debugging information records, DWARF line number information, DWARF address range and global names information, weak names information, DWARF frame description information, DWARF static function names, DWARF static variables, and DWARF type information. .P The document has long mentioned the "Unix International Programming Languages Special Interest Group" (PLSIG), under whose auspices the DWARF committtee was formed around 1991. "Unix International" was disbanded in the 1990's and no longer exists. .P The DWARF committee published DWARF2 July 27, 1993. .P In the mid 1990's this document and the library it describes (which the committee never endorsed, having decided not to endorse or approve any particular library interface) was made available on the internet by Silcon Graphics, Inc. .P In 2005 the DWARF committee began an affiliation with FreeStandards.org. In 2007 FreeStandards.org merged with The Linux Foundation. The DWARF committee dropped its affiliation with FreeStandards.org in 2007 and established the dwarfstd.org website. See "http://www.dwarfstd.org" for current information on standardization activities and a copy of the standard. .H 2 "Copyright" Copyright 1993-2006 Silicon Graphics, Inc. Copyright 2007 David Anderson. Permission is hereby granted to copy or republish or use any or all of this document without restriction except that when publishing more than a small amount of the document please acknowledge Silicon Graphics, Inc and David Anderson. This document is distributed in the hope that it would be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .P .H 2 "Purpose and Scope" The purpose of this document is to document a library of functions to access DWARF debugging information. There is no effort made in this document to address the creation of these records as those issues are addressed separately (see "A Producer Library Interface to DWARF"). .P Additionally, the focus of this document is the functional interface, and as such, implementation as well as optimization issues are intentionally ignored. .H 2 "Document History" .P A document was written about 1991 which had similar layout and interfaces. Written by people from Hal Corporation, That document described a library for reading DWARF1. The authors distributed paper copies to the committee with the clearly expressed intent to propose the document as a supported interface definition. The committee decided not to pursue a library definition. .P SGI wrote the document you are now reading in 1993 with a similar layout and content and organization, but it was complete document rewrite with the intent to read DWARF2 (the DWARF version then in existence). The intent was (and is) to also cover future revisions of DWARF. All the function interfaces were changed in 1994 to uniformly return a simple integer success-code (see DW_DLV_OK etc), generally following the recomendations in the chapter titled "Candy Machine Interfaces" of "Writing Solid Code", a book by Steve Maguire (published by Microsoft Press). .H 2 "Definitions" DWARF debugging information entries (DIEs) are the segments of information placed in the \f(CW.debug_*\fP sections by compilers, assemblers, and linkage editors that, in conjunction with line number entries, are necessary for symbolic source-level debugging. Refer to the latest "\fIDWARF Debugging Information Format\fP" from www.dwarfstd.org for a more complete description of these entries. .P This document adopts all the terms and definitions in "\fIDWARF Debugging Information Format\fP" versions 2 and 3. It originally focused on the implementation at Silicon Graphics, Inc., but now attempts to be more generally useful. .H 2 "Overview" The remaining sections of this document describe the proposed interface to \f(CWlibdwarf\fP, first by describing the purpose of additional types defined by the interface, followed by descriptions of the available operations. This document assumes you are thoroughly familiar with the information contained in the \fIDWARF Debugging Information Format\fP document. .P We separate the functions into several categories to emphasize that not all consumers want to use all the functions. We call the categories Debugger, Internal-level, High-level, and Miscellaneous not because one is more important than another but as a way of making the rather large set of function calls easier to understand. .P Unless otherwise specified, all functions and structures should be taken as being designed for Debugger consumers. .P The Debugger Interface of this library is intended to be used by debuggers. The interface is low-level (close to dwarf) but suppresses irrelevant detail. A debugger will want to absorb all of some sections at startup and will want to see little or nothing of some sections except at need. And even then will probably want to absorb only the information in a single compilation unit at a time. A debugger does not care about implementation details of the library. .P The Internal-level Interface is for a DWARF prettyprinter and checker. A thorough prettyprinter will want to know all kinds of internal things (like actual FORM numbers and actual offsets) so it can check for appropriate structure in the DWARF data and print (on request) all that internal information for human users and libdwarf authors and compiler-writers. Calls in this interface provide data a debugger does not care about. .P The High-level Interface is for higher level access (it's not really a high level interface!). Programs such as disassemblers will want to be able to display relevant information about functions and line numbers without having to invest too much effort in looking at DWARF. .P The miscellaneous interface is just what is left over: the error handler functions. .P The following is a brief mention of the changes in this libdwarf from the libdwarf draft for DWARF Version 1 and recent changes. .H 2 "Items Changed" .P Added support for various DWARF3 features, but primarily a new frame-information interface tailorable at run-time to more than a single ABI. See dwarf_set_frame_rule_inital_value() and dwarf_set_frame_rule_table_size(). See also dwarf_get_fde_info_for_reg3() and dwarf_get_fde_info_for_cfa_reg3(). (April 2006) .P Added support for DWARF3 .debug_pubtypes section. Corrected various leaks (revising dealloc() calls, adding new functions) and corrected dwarf_formstring() documentation. .P Added dwarf_srclines_dealloc() as the previous deallocation method documented for data returned by dwarf_srclines() was incapable of freeing all the allocated storage (14 July 2005). .P dwarf_nextglob(), dwarf_globname(), and dwarf_globdie() were all changed to operate on the items in the .debug_pubnames section. .P All functions were modified to return solely an error code. Data is returned through pointer arguments. This makes writing safe and correct library-using-code far easier. For justification for this approach, see the book by Steve Maguire titled "Writing Solid Code" at your bookstore. .H 2 "Items Removed" .P Dwarf_Type was removed since types are no longer special. .P dwarf_typeof() was removed since types are no longer special. .P Dwarf_Ellist was removed since element lists no longer are a special format. .P Dwarf_Bounds was removed since bounds have been generalized. .P dwarf_nextdie() was replaced by dwarf_next_cu_header() to reflect the real way DWARF is organized. The dwarf_nextdie() was only useful for getting to compilation unit beginnings, so it does not seem harmful to remove it in favor of a more direct function. .P dwarf_childcnt() is removed on grounds that no good use was apparent. .P dwarf_prevline() and dwarf_nextline() were removed on grounds this is better left to a debugger to do. Similarly, dwarf_dieline() was removed. .P dwarf_is1stline() was removed as it was not meaningful for the revised DWARF line operations. .P Any libdwarf implementation might well decide to support all the removed functionality and to retain the DWARF Version 1 meanings of that functionality. This would be difficult because the original libdwarf draft specification used traditional C library interfaces which confuse the values returned by successful calls with exceptional conditions like failures and 'no more data' indications. .H 2 "Revision History" .VL 15 .LI "March 93" Work on DWARF2 SGI draft begins .LI "June 94" The function returns are changed to return an error/success code only. .LI "April 2006: Support for DWARF3 consumer operations is close to completion. .LE .H 1 "Types Definitions" .H 2 "General Description" The \fIlibdwarf.h\fP header file contains typedefs and preprocessor definitions of types and symbolic names used to reference objects of \fIlibdwarf\fP. The types defined by typedefs contained in \fIlibdwarf.h\fP all use the convention of adding \f(CWDwarf_\fP as a prefix and can be placed in three categories: .BL .LI Scalar types : The scalar types defined in \fIlibdwarf.h\fP are defined primarily for notational convenience and identification. Depending on the individual definition, they are interpreted as a value, a pointer, or as a flag. .LI Aggregate types : Some values can not be represented by a single scalar type; they must be represented by a collection of, or as a union of, scalar and/or aggregate types. .LI Opaque types : The complete definition of these types is intentionally omitted; their use is as handles for query operations, which will yield either an instance of another opaque type to be used in another query, or an instance of a scalar or aggregate type, which is the actual result. .P .H 2 "Scalar Types" The following are the defined by \fIlibdwarf.h\fP: .DS \f(CW typedef int Dwarf_Bool; typedef unsigned long long Dwarf_Off; typedef unsigned long long Dwarf_Unsigned; typedef unsigned short Dwarf_Half; typedef unsigned char Dwarf_Small; typedef signed long long Dwarf_Signed; typedef unsigned long long Dwarf_Addr; typedef void *Dwarf_Ptr; typedef void (*Dwarf_Handler)(Dwarf_Error *error, Dwarf_Ptr errarg); .DE .nr aX \n(Fg+1 Dwarf_Ptr is an address for use by the host program calling the library, not for representing pc-values/addresses within the target object file. Dwarf_Addr is for pc-values within the target object file. The sample scalar type assignments above are for a \fIlibdwarf.h\fP that can read and write 32-bit or 64-bit binaries on a 32-bit or 64-bit host machine. The types must be defined appropriately for each implementation of libdwarf. A description of these scalar types in the SGI/MIPS environment is given in Figure \n(aX. .DS .TS center box, tab(:); lfB lfB lfB lfB l c c l. NAME:SIZE:ALIGNMENT:PURPOSE _ Dwarf_Bool:4:4:Boolean states Dwarf_Off:8:8:Unsigned file offset Dwarf_Unsigned:8:8:Unsigned large integer Dwarf_Half:2:2:Unsigned medium integer Dwarf_Small:1:1:Unsigned small integer Dwarf_Signed:8:8:Signed large integer Dwarf_Addr:8:8:Program address :::(target program) Dwarf_Ptr:4|8:4|8:Dwarf section pointer :::(host program) Dwarf_Handler:4|8:4|8:Pointer to :::error handler function .TE .FG "Scalar Types" .DE .H 2 "Aggregate Types" The following aggregate types are defined by \fIlibdwarf.h\fP: \f(CWDwarf_Loc\fP, \f(CWDwarf_Locdesc\fP, \f(CWDwarf_Block\fP, \f(CWDwarf_Frame_Op\fP. \f(CWDwarf_Regtable\fP. \f(CWDwarf_Regtable3\fP. While most of \f(CWlibdwarf\fP acts on or returns simple values or opaque pointer types, this small set of structures seems useful. .H 3 "Location Record" The \f(CWDwarf_Loc\fP type identifies a single atom of a location description or a location expression. .DS \f(CWtypedef struct { Dwarf_Small lr_atom; Dwarf_Unsigned lr_number; Dwarf_Unsigned lr_number2; Dwarf_Unsigned lr_offset; } Dwarf_Loc;\fP .DE The \f(CWlr_atom\fP identifies the atom corresponding to the \f(CWDW_OP_*\fP definition in \fIdwarf.h\fP and it represents the operation to be performed in order to locate the item in question. .P The \f(CWlr_number\fP field is the operand to be used in the calculation specified by the \f(CWlr_atom\fP field; not all atoms use this field. Some atom operations imply signed numbers so it is necessary to cast this to a \f(CWDwarf_Signed\fP type for those operations. .P The \f(CWlr_number2\fP field is the second operand specified by the \f(CWlr_atom\fP field; only \f(CWDW_OP_BREGX\fP has this field. Some atom operations imply signed numbers so it may be necessary to cast this to a \f(CWDwarf_Signed\fP type for those operations. .P The \f(CWlr_offset\fP field is the byte offset (within the block the location record came from) of the atom specified by the \f(CWlr_atom\fP field. This is set on all atoms. This is useful for operations \f(CWDW_OP_SKIP\fP and \f(CWDW_OP_BRA\fP. .H 3 "Location Description" The \f(CWDwarf_Locdesc\fP type represents an ordered list of \f(CWDwarf_Loc\fP records used in the calculation to locate an item. Note that in many cases, the location can only be calculated at runtime of the associated program. .DS \f(CWtypedef struct { Dwarf_Addr ld_lopc; Dwarf_Addr ld_hipc; Dwarf_Unsigned ld_cents; Dwarf_Loc* ld_s; } Dwarf_Locdesc;\fP .DE The \f(CWld_lopc\fP and \f(CWld_hipc\fP fields provide an address range for which this location descriptor is valid. Both of these fields are set to \fIzero\fP if the location descriptor is valid throughout the scope of the item it is associated with. These addresses are virtual memory addresses, not offsets-from-something. The virtual memory addresses do not account for dso movement (none of the pc values from libdwarf do that, it is up to the consumer to do that). .P The \f(CWld_cents\fP field contains a count of the number of \f(CWDwarf_Loc\fP entries pointed to by the \f(CWld_s\fP field. .P The \f(CWld_s\fP field points to an array of \f(CWDwarf_Loc\fP records. .H 3 "Data Block" .SP The \f(CWDwarf_Block\fP type is used to contain the value of an attribute whose form is either \f(CWDW_FORM_block1\fP, \f(CWDW_FORM_block2\fP, \f(CWDW_FORM_block4\fP, \f(CWDW_FORM_block8\fP, or \f(CWDW_FORM_block\fP. Its intended use is to deliver the value for an attribute of any of these forms. .DS \f(CWtypedef struct { Dwarf_Unsigned bl_len; Dwarf_Ptr bl_data; } Dwarf_Block;\fP .DE .P The \f(CWbl_len\fP field contains the length in bytes of the data pointed to by the \f(CWbl_data\fP field. .P The \f(CWbl_data\fP field contains a pointer to the uninterpreted data. Since we use a \f(CWDwarf_Ptr\fP here one must copy the pointer to some other type (typically an \f(CWunsigned char *\fP) so one can add increments to index through the data. The data pointed to by \f(CWbl_data\fP is not necessarily at any useful alignment. .H 3 "Frame Operation Codes: DWARF 2" This interface is adequate for DWARF2 but not for DWARF3. A separate interface usable for DWARF3 and for DWARF2 is described below. .P The DWARF2 \f(CWDwarf_Frame_Op\fP type is used to contain the data of a single instruction of an instruction-sequence of low-level information from the section containing frame information. This is ordinarily used by Internal-level Consumers trying to print everything in detail. .DS \f(CWtypedef struct { Dwarf_Small fp_base_op; Dwarf_Small fp_extended_op; Dwarf_Half fp_register; Dwarf_Signed fp_offset; Dwarf_Offset fp_instr_offset; } Dwarf_Frame_Op; .DE \f(CWfp_base_op\fP is the 2-bit basic op code. \f(CWfp_extended_op\fP is the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an extended op code) and is zero otherwise. .P \f(CWfp_register\fP is any (or the first) register value as defined in the \f(CWCall Frame Instruction Encodings\fP figure in the \f(CWdwarf\fP document. If not used with the Op it is 0. .P \f(CWfp_offset\fP is the address, delta, offset, or second register as defined in the \f(CWCall Frame Instruction Encodings\fP figure in the \f(CWdwarf\fP document. If this is an \f(CWaddress\fP then the value should be cast to \f(CW(Dwarf_Addr)\fP before being used. In any implementation this field *must* be as large as the larger of Dwarf_Signed and Dwarf_Addr for this to work properly. If not used with the op it is 0. .P \f(CWfp_instr_offset\fP is the byte_offset (within the instruction stream of the frame instructions) of this operation. It starts at 0 for a given frame descriptor. .H 3 "Frame Regtable: DWARF 2" This interface is adequate for DWARF2 but not for DWARF3. A separate interface usable for DWARF3 and for DWARF2 is described below. .P The \f(CWDwarf_Regtable\fP type is used to contain the register-restore information for all registers at a given PC value. Normally used by debuggers. .DS /* DW_REG_TABLE_SIZE must reflect the number of registers *(DW_FRAME_LAST_REG_NUM) as defined in dwarf.h */ #define DW_REG_TABLE_SIZE \f(CWtypedef struct { struct { Dwarf_Small dw_offset_relevant; Dwarf_Half dw_regnum; Dwarf_Addr dw_offset; } rules[DW_REG_TABLE_SIZE]; } Dwarf_Regtable;\fP .DE .P The array is indexed by register number. The field values for each index are described next. For clarity we describe the field values for index rules[M] (M being any legal array element index). .P \f(CWdw_offset_relevant\fP is non-zero to indicate the \f(CWdw_offset\fP field is meaningful. If zero then the \f(CWdw_offset\fP is zero and should be ignored. .P \f(CWdw_regnum \fPis the register number\fP applicable. If \f(CWdw_offset_relevant\fP is zero, then this is the register number of the register containing the value for register M. If \f(CWdw_offset_relevant\fP is non-zero, then this is the register number of the register to use as a base (M may be DW_FRAME_CFA_COL, for example) and the \f(CWdw_offset\fP value applies. The value of register M is therefore the value of register \f(CWdw_regnum\vP . .P \f(CWdw_offset\fP should be ignored if \f(CWdw_offset_relevant\fP is zero. If \f(CWdw_offset_relevant\fP is non-zero, then the consumer code should add the value to the value of the register \f(CWdw_regnum\fP to produce the value. .H 3 "Frame Operation Codes: DWARF 3 (and DWARF2)" This interface is adequate for DWARF3 and for DWARF2. It is new in libdwarf in April 2006. .P The DWARF2 \f(CWDwarf_Frame_Op3\fP type is used to contain the data of a single instruction of an instruction-sequence of low-level information from the section containing frame information. This is ordinarily used by Internal-level Consumers trying to print everything in detail. .DS \f(CWtypedef struct { Dwarf_Small fp_base_op; Dwarf_Small fp_extended_op; Dwarf_Half fp_register; /* Value may be signed, depends on op. Any applicable data_alignment_factor has not been applied, this is the raw offset. */ Dwarf_Unsigned fp_offset_or_block_len; Dwarf_Small *fp_expr_block; Dwarf_Off fp_instr_offset; } Dwarf_Frame_Op3;\fP .DE \f(CWfp_base_op\fP is the 2-bit basic op code. \f(CWfp_extended_op\fP is the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an extended op code) and is zero otherwise. .P \f(CWfp_register\fP is any (or the first) register value as defined in the \f(CWCall Frame Instruction Encodings\fP figure in the \f(CWdwarf\fP document. If not used with the Op it is 0. .P \f(CWfp_offset_or_block_len\fP is the address, delta, offset, or second register as defined in the \f(CWCall Frame Instruction Encodings\fP figure in the \f(CWdwarf\fP document. Or (depending on the op, it may be the length of the dwarf-expression block pointed to by \f(CWfp_expr_block\fP. If this is an \f(CWaddress\fP then the value should be cast to \f(CW(Dwarf_Addr)\fP before being used. In any implementation this field *must* be as large as the larger of Dwarf_Signed and Dwarf_Addr for this to work properly. If not used with the op it is 0. .P \f(CWfp_expr_block\fP (if applicable to the op) points to a dwarf-expression block whch is \f(CWfp_offset_or_block_len\fP bytes long. .P \f(CWfp_instr_offset\fP is the byte_offset (within the instruction stream of the frame instructions) of this operation. It starts at 0 for a given frame descriptor. .H 3 "Frame Regtable: DWARF 3" This interface is adequate for DWARF3 and for DWARF2. It is new in libdwarf as of April 2006. .P The \f(CWDwarf_Regtable3\fP type is used to contain the register-restore information for all registers at a given PC value. Normally used by debuggers. .DS \f(CWtypedef struct Dwarf_Regtable_Entry3_s { Dwarf_Small dw_offset_relevant; Dwarf_Small dw_value_type; Dwarf_Half dw_regnum; Dwarf_Unsigned dw_offset_or_block_len; Dwarf_Ptr dw_block_ptr; }Dwarf_Regtable_Entry3; typedef struct Dwarf_Regtable3_s { struct Dwarf_Regtable_Entry3_s rt3_cfa_rule; Dwarf_Half rt3_reg_table_size; struct Dwarf_Regtable_Entry3_s * rt3_rules; } Dwarf_Regtable3;\fP .DE .P The array is indexed by register number. The field values for each index are described next. For clarity we describe the field values for index rules[M] (M being any legal array element index). (DW_FRAME_CFA_COL3 DW_FRAME_SAME_VAL, DW_FRAME_UNDEFINED_VAL are not legal array indexes, nor is any index < 0 or > rt3_reg_table_size); The caller of routines using this struct must create data space for rt3_reg_table_size entries of struct Dwarf_Regtable_Entry3_s and arrange that rt3_rules points to that space and that rt3_reg_table_size is set correctly. The caller need not (but may) initialize the contents of the rt3_cfa_rule or the rt3_rules array. The following applies to each rt3_rules rule M: .P .in +4 \f(CWdw_regnum\fP is the register number applicable. If \f(CWdw_regnum\fP is DW_FRAME_UNDEFINED_VAL, then the register I has undefined value. If \f(CWdw_regnum\fP is DW_FRAME_SAME_VAL, then the register I has the same value as in the previous frame. .P If \f(CWdw_regnum\fP is neither of these two, then the following apply: .P .P \f(CWdw_value_type\fP determines the meaning of the other fields. It is one of DW_EXPR_OFFSET (0), DW_EXPR_VAL_OFFSET(1), DW_EXPR_EXPRESSION(2) or DW_EXPR_VAL_EXPRESSION(3). .P If \f(CWdw_value_type\fP is DW_EXPR_OFFSET (0) then this is as in DWARF2 and the offset(N) rule or the register(R) rule of the DWARF3 and DWARF2 document applies. The value is either: .in +4 If \f(CWdw_offset_relevant\fP is non-zero, then \f(CWdw_regnum\fP is effectively ignored but must be identical to DW_FRAME_CFA_COL3 and the \f(CWdw_offset\fP value applies. The value of register M is therefore the value of CFA plus the value of \f(CWdw_offset\fP. The result of the calculation is the address in memory where the value of register M resides. This is the offset(N) rule of the DWARF2 and DWARF3 documents. .P \f(CWdw_offset_relevant\fP is zero it indicates the \f(CWdw_offset\fP field is not meaningful. The value of register M is the value currently in register \f(CWdw_regnum\fP (the value DW_FRAME_CFA_COL3 must not appear, only real registers). This is the register(R) rule of the DWARF3 spec. .in -4 .P If \f(CWdw_value_type\fP is DW_EXPR_OFFSET (1) then this is the the val_offset(N) rule of the DWARF3 spec applies. The calculation is identical to that of DW_EXPR_OFFSET (0) but the value is interpreted as the value of register M (rather than the address where register M's value is stored). .P If \f(CWdw_value_type\fP is DW_EXPR_EXPRESSION (2) then this is the the expression(E) rule of the DWARF3 document. .P .in +4 \f(CWdw_offset_or_block_len\fP is the length in bytes of the in-memory block pointed at by \f(CWdw_block_ptr\fP. \f(CWdw_block_ptr\fP is a DWARF expression. Evaluate that expression and the result is the address where the previous value of register M is found. .in -4 .P If \f(CWdw_value_type\fP is DW_EXPR_VAL_EXPRESSION (3) then this is the the val_expression(E) rule of the DWARF3 spec. .P .in +4 \f(CWdw_offset_or_block_len\fP is the length in bytes of the in-memory block pointed at by \f(CWdw_block_ptr\fP. \f(CWdw_block_ptr\fP is a DWARF expression. Evaluate that expression and the result is the previous value of register M. .in -4 .P The rule \f(CWrt3_cfa_rule\fP is the current value of the CFA. It is interpreted exactly like any register M rule (as described just above) except that \f(CWdw_regnum\fP cannot be CW_FRAME_CFA_REG3 or DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL but must be a real register number. .in -4 .H 3 "Macro Details Record" The \f(CWDwarf_Macro_Details\fP type gives information about a single entry in the .debug.macinfo section. .DS \f(CWstruct Dwarf_Macro_Details_s { Dwarf_Off dmd_offset; Dwarf_Small dmd_type; Dwarf_Signed dmd_lineno; Dwarf_Signed dmd_fileindex; char * dmd_macro; }; typedef struct Dwarf_Macro_Details_s Dwarf_Macro_Details; .DE .P \f(CWdmd_offset\fP is the byte offset, within the .debug_macinfo section, of this macro information. .P \f(CWdmd_type\fP is the type code of this macro info entry (or 0, the type code indicating that this is the end of macro information entries for a compilation unit. See \f(CWDW_MACINFO_define\fP, etc in the DWARF document. .P \f(CWdmd_lineno\fP is the line number where this entry was found, or 0 if there is no applicable line number. .P \f(CWdmd_fileindex\fP is the file index of the file involved. This is only guaranteed meaningful on a \f(CWDW_MACINFO_start_file\fP \f(CWdmd_type\fP. Set to -1 if unknown (see the functional interface for more details). .P \f(CWdmd_macro\fP is the applicable string. For a \f(CWDW_MACINFO_define\fP this is the macro name and value. For a \f(CWDW_MACINFO_undef\fP, or this is the macro name. For a \f(CWDW_MACINFO_vendor_ext\fP this is the vendor-defined string value. For other \f(CWdmd_type\fPs this is 0. .H 2 "Opaque Types" The opaque types declared in \fIlibdwarf.h\fP are used as descriptors for queries against DWARF information stored in various debugging sections. Each time an instance of an opaque type is returned as a result of a \fIlibdwarf\fP operation (\f(CWDwarf_Debug\fP excepted), it should be free'd, using \f(CWdwarf_dealloc()\fP when it is no longer of use (read the following documentation for details, as in at least one case there is a special routine provided for deallocation and \f(CWdwarf_dealloc()\fP is not directly called: see \f(CWdwarf_srclines()\fP). Some functions return a number of instances of an opaque type in a block, by means of a pointer to the block and a count of the number of opaque descriptors in the block: see the function description for deallocation rules for such functions. The list of opaque types defined in \fIlibdwarf.h\fP that are pertinent to the Consumer Library, and their intended use is described below. .DS \f(CWtypedef struct Dwarf_Debug_s* Dwarf_Debug;\fP .DE An instance of the \f(CWDwarf_Debug\fP type is created as a result of a successful call to \f(CWdwarf_init()\fP, or \f(CWdwarf_elf_init()\fP, and is used as a descriptor for subsequent access to most \f(CWlibdwarf\fP functions on that object. The storage pointed to by this descriptor should be not be free'd, using the \f(CWdwarf_dealloc()\fP function. Instead free it with \f(CWdwarf_finish()\fP. .P .DS \f(CWtypedef struct Dwarf_Die_s* Dwarf_Die;\fP .DE An instance of a \f(CWDwarf_Die\fP type is returned from a successful call to the \f(CWdwarf_siblingof()\fP, \f(CWdwarf_child\fP, or \f(CWdwarf_offdie()\fP function, and is used as a descriptor for queries about information related to that DIE. The storage pointed to by this descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_DIE\fP when no longer needed. .DS \f(CWtypedef struct Dwarf_Line_s* Dwarf_Line;\fP .DE Instances of \f(CWDwarf_Line\fP type are returned from a successful call to the \f(CWdwarf_srclines()\fP function, and are used as descriptors for queries about source lines. The storage pointed to by these descriptors should be individually free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_LINE\fP when no longer needed. .DS \f(CWtypedef struct Dwarf_Global_s* Dwarf_Global;\fP .DE Instances of \f(CWDwarf_Global\fP type are returned from a successful call to the \f(CWdwarf_get_globals()\fP function, and are used as descriptors for queries about global names (pubnames). .DS \f(CWtypedef struct Dwarf_Weak_s* Dwarf_Weak;\fP .DE Instances of \f(CWDwarf_Weak\fP type are returned from a successful call to the SGI-specific \f(CWdwarf_get_weaks()\fP function, and are used as descriptors for queries about weak names. The storage pointed to by these descriptors should be individually free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_WEAK_CONTEXT\fP (or \f(CWDW_DLA_WEAK\fP, an older name, supported for compatibility) when no longer needed. .DS \f(CWtypedef struct Dwarf_Func_s* Dwarf_Func;\fP .DE Instances of \f(CWDwarf_Func\fP type are returned from a successful call to the SGI-specific \f(CWdwarf_get_funcs()\fP function, and are used as descriptors for queries about static function names. .DS \f(CWtypedef struct Dwarf_Type_s* Dwarf_Type;\fP .DE Instances of \f(CWDwarf_Type\fP type are returned from a successful call to the SGI-specific \f(CWdwarf_get_types()\fP function, and are used as descriptors for queries about user defined types. .DS \f(CWtypedef struct Dwarf_Var_s* Dwarf_Var;\fP .DE Instances of \f(CWDwarf_Var\fP type are returned from a successful call to the SGI-specific \f(CWdwarf_get_vars()\fP function, and are used as descriptors for queries about static variables. .DS \f(CWtypedef struct Dwarf_Error_s* Dwarf_Error;\fP .DE This descriptor points to a structure that provides detailed information about errors detected by \f(CWlibdwarf\fP. Users typically provide a location for \f(CWlibdwarf\fP to store this descriptor for the user to obtain more information about the error. The storage pointed to by this descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ERROR\fP when no longer needed. .DS \f(CWtypedef struct Dwarf_Attribute_s* Dwarf_Attribute;\fP .DE Instances of \f(CWDwarf_Attribute\fP type are returned from a successful call to the \f(CWdwarf_attrlist()\fP, or \f(CWdwarf_attr()\fP functions, and are used as descriptors for queries about attribute values. The storage pointed to by this descriptor should be individually free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ATTR\fP when no longer needed. .DS \f(CWtypedef struct Dwarf_Abbrev_s* Dwarf_Abbrev;\fP .DE An instance of a \f(CWDwarf_Abbrev\fP type is returned from a successful call to \f(CWdwarf_get_abbrev()\fP, and is used as a descriptor for queries about abbreviations in the .debug_abbrev section. The storage pointed to by this descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ABBREV\fP when no longer needed. .DS \f(CWtypedef struct Dwarf_Fde_s* Dwarf_Fde;\fP .DE Instances of \f(CWDwarf_Fde\fP type are returned from a successful call to the \f(CWdwarf_get_fde_list()\fP, \f(CWdwarf_get_fde_for_die()\fP, or \f(CWdwarf_get_fde_at_pc()\fP functions, and are used as descriptors for queries about frames descriptors. .DS \f(CWtypedef struct Dwarf_Cie_s* Dwarf_Cie;\fP .DE Instances of \f(CWDwarf_Cie\fP type are returned from a successful call to the \f(CWdwarf_get_fde_list()\fP function, and are used as descriptors for queries about information that is common to several frames. .DS \f(CWtypedef struct Dwarf_Arange_s* Dwarf_Arange;\fP .DE Instances of \f(CWDwarf_Arange\fP type are returned from successful calls to the \f(CWdwarf_get_aranges()\fP, or \f(CWdwarf_get_arange()\fP functions, and are used as descriptors for queries about address ranges. The storage pointed to by this descriptor should be individually free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ARANGE\fP when no longer needed. .H 1 "Error Handling" The method for detection and disposition of error conditions that arise during access of debugging information via \fIlibdwarf\fP is consistent across all \fIlibdwarf\fP functions that are capable of producing an error. This section describes the method used by \fIlibdwarf\fP in notifying client programs of error conditions. .P Most functions within \fIlibdwarf\fP accept as an argument a pointer to a \f(CWDwarf_Error\fP descriptor where a \f(CWDwarf_Error\fP descriptor is stored if an error is detected by the function. Routines in the client program that provide this argument can query the \f(CWDwarf_Error\fP descriptor to determine the nature of the error and perform appropriate processing. .P A client program can also specify a function to be invoked upon detection of an error at the time the library is initialized (see \f(CWdwarf_init()\fP). When a \fIlibdwarf\fP routine detects an error, this function is called with two arguments: a code indicating the nature of the error and a pointer provided by the client at initialization (again see \f(CWdwarf_init()\fP). This pointer argument can be used to relay information between the error handler and other routines of the client program. A client program can specify or change both the error handling function and the pointer argument after initialization using \f(CWdwarf_seterrhand()\fP and \f(CWdwarf_seterrarg()\fP. .P In the case where \fIlibdwarf\fP functions are not provided a pointer to a \f(CWDwarf_Error\fP descriptor, and no error handling function was provided at initialization, \fIlibdwarf\fP functions terminate execution by calling \f(CWabort(3C)\fP. .P The following lists the processing steps taken upon detection of an error: .AL 1 .LI Check the \f(CWerror\fP argument; if not a \fINULL\fP pointer, allocate and initialize a \f(CWDwarf_Error\fP descriptor with information describing the error, place this descriptor in the area pointed to by \f(CWerror\fP, and return a value indicating an error condition. .LI If an \f(CWerrhand\fP argument was provided to \f(CWdwarf_init()\fP at initialization, call \f(CWerrhand()\fP passing it the error descriptor and the value of the \f(CWerrarg\fP argument provided to \f(CWdwarf_init()\fP. If the error handling function returns, return a value indicating an error condition. .LI Terminate program execution by calling \f(CWabort(3C)\fP. .LE .SP In all cases, it is clear from the value returned from a function that an error occurred in executing the function, since DW_DLV_ERROR is returned. .P As can be seen from the above steps, the client program can provide an error handler at initialization, and still provide an \f(CWerror\fP argument to \fIlibdwarf\fP functions when it is not desired to have the error handler invoked. .P If a \f(CWlibdwarf\fP function is called with invalid arguments, the behaviour is undefined. In particular, supplying a \f(CWNULL\fP pointer to a \f(CWlibdwarf\fP function (except where explicitly permitted), or pointers to invalid addresses or uninitialized data causes undefined behaviour; the return value in such cases is undefined, and the function may fail to invoke the caller supplied error handler or to return a meaningful error number. Implementations also may abort execution for such cases. .P .H 2 "Returned values in the functional interface" Values returned by \f(CWlibdwarf\fP functions to indicate success and errors .nr aX \n(Fg+1 are enumerated in Figure \n(aX. The \f(CWDW_DLV_NO_ENTRY\fP case is useful for functions need to indicate that while there was no data to return there was no error either. For example, \f(CWdwarf_siblingof()\fP may return \f(CWDW_DLV_NO_ENTRY\fP to indicate that that there was no sibling to return. .DS .TS center box, tab(:); lfB cfB lfB l c l. SYMBOLIC NAME:VALUE:MEANING _ DW_DLV_ERROR:1:Error DW_DLV_OK:0:Successful call DW_DLV_NO_ENTRY:-1:No applicable value .TE .FG "Error Indications" .DE .P Each function in the interface that returns a value returns one of the integers in the above figure. .P If \f(CWDW_DLV_ERROR\fP is returned and a pointer to a \f(CWDwarf_Error\fP pointer is passed to the function, then a Dwarf_Error handle is returned thru the pointer. No other pointer value in the interface returns a value. After the \f(CWDwarf_Error\fP is no longer of interest, a \f(CWdwarf_dealloc(dbg,dw_err,DW_DLA_ERROR)\fP on the error pointer is appropriate to free any space used by the error information. .P If \f(CWDW_DLV_NO_ENTRY\fP is returned no pointer value in the interface returns a value. .P If \f(CWDW_DLV_OK\fP is returned the \f(CWDwarf_Error\fP pointer, if supplied, is not touched, but any other values to be returned through pointers are returned. In this case calls (depending on the exact function returning the error) to \f(CWdwarf_dealloc()\fP may be appropriate once the particular pointer returned is no longer of interest. .P Pointers passed to allow values to be returned thru them are uniformly the last pointers in each argument list. .P All the interface functions are defined from the point of view of the writer-of-the-library (as is traditional for UN*X library documentation), not from the point of view of the user of the library. The caller might code: .P .DS Dwarf_Line line; Dwarf_Signed ret_loff; Dwarf_Error err; int retval = dwarf_lineoff(line,&ret_loff,&err); .DE for the function defined as .P .DS int dwarf_lineoff(Dwarf_Line line,Dwarf_Signed *return_lineoff, Dwarf_Error* err); .DE and this document refers to the function as returning the value thru *err or *return_lineoff or uses the phrase "returns in the location pointed to by err". Sometimes other similar phrases are used. .H 1 "Memory Management" Several of the functions that comprise \fIlibdwarf\fP return pointers (opaque descriptors) to structures that have been dynamically allocated by the library. To aid in the management of dynamic memory, the function \f(CWdwarf_dealloc()\fP is provided to free storage allocated as a result of a call to a \fIlibdwarf\fP function. This section describes the strategy that should be taken by a client program in managing dynamic storage. .H 2 "Read-only Properties" All pointers (opaque descriptors) returned by or as a result of a \fIlibdwarf Consumer Library\fP call should be assumed to point to read-only memory. The results are undefined for \fIlibdwarf\fP clients that attempt to write to a region pointed to by a value returned by a \fIlibdwarf Consumer Library\fP call. .H 2 "Storage Deallocation" See the section "Returned values in the functional interface", above, for the general rules where calls to \f(CWdwarf_dealloc()\fP is appropriate. .P In some cases the pointers returned by a \fIlibdwarf\fP call are pointers to data which is not free-able. The library knows from the allocation type provided to it whether the space is freeable or not and will not free inappropriately when \f(CWdwarf_dealloc()\fP is called. So it is vital that \f(CWdwarf_dealloc()\fP be called with the proper allocation type. .P For most storage allocated by \fIlibdwarf\fP, the client can free the storage for reuse by calling \f(CWdwarf_dealloc()\fP, providing it with the \f(CWDwarf_Debug\fP descriptor specifying the object for which the storage was allocated, a pointer to the area to be free-ed, and an identifier that specifies what the pointer points to (the allocation type). For example, to free a \f(CWDwarf_Die die\fP belonging the the object represented by \f(CWDwarf_Debug dbg\fP, allocated by a call to \f(CWdwarf_siblingof()\fP, the call to \f(CWdwarf_dealloc()\fP would be: .DS \f(CWdwarf_dealloc(dbg, die, DW_DLA_DIE);\fP .DE To free storage allocated in the form of a list of pointers (opaque descriptors), each member of the list should be deallocated, followed by deallocation of the actual list itself. The following code fragment uses an invocation of \f(CWdwarf_attrlist()\fP as an example to illustrate a technique that can be used to free storage from any \fIlibdwarf\fP routine that returns a list: .DS \f(CWDwarf_Unsigned atcnt; Dwarf_Attribute *atlist; int errv; errv = dwarf_attrlist(somedie, &atlist,&atcnt, &error); if (errv == DW_DLV_OK) { for (i = 0; i < atcnt; ++i) { /* use atlist[i] */ dwarf_dealloc(dbg, atlist[i], DW_DLA_ATTR); } dwarf_dealloc(dbg, atlist, DW_DLA_LIST); }\fP .DE The \f(CWDwarf_Debug\fP returned from \f(CWdwarf_init()\fP or \f(CWdwarf_elf_init()\fP cannot be free'd using \f(CWdwarf_dealloc()\fP. The function \f(CWdwarf_finish()\fP will deallocate all dynamic storage associated with an instance of a \f(CWDwarf_Debug\fP type. In particular, it will deallocate all dynamically allocated space associated with the \f(CWDwarf_Debug\fP descriptor, and finally make the descriptor invalid. An \f(CWDwarf_Error\fP returned from \f(CWdwarf_init()\fP or \f(CWdwarf_elf_init()\fP in case of a failure cannot be free'd using \f(CWdwarf_dealloc()\fP. The only way to free the \f(CWDwarf_Error\fP from either of those calls is to use \f2free(3)\fP directly. Every \f(CWDwarf_Error\fP must be free'd by \f(CWdwarf_dealloc()\fP except those returned by \f(CWdwarf_init()\fP or \f(CWdwarf_elf_init()\fP. .P The codes that identify the storage pointed to in calls to .nr aX \n(Fg+1 \f(CWdwarf_dealloc()\fP are described in figure \n(aX. .DS .TS center box, tab(:); lfB lfB l l. IDENTIFIER:USED TO FREE _ DW_DLA_STRING : char* DW_DLA_LOC : Dwarf_Loc DW_DLA_LOCDESC : Dwarf_Locdesc DW_DLA_ELLIST : Dwarf_Ellist (not used) DW_DLA_BOUNDS : Dwarf_Bounds (not used) DW_DLA_BLOCK : Dwarf_Block DW_DLA_DEBUG : Dwarf_Debug (do not use) DW_DLA_DIE : Dwarf_Die DW_DLA_LINE : Dwarf_Line DW_DLA_ATTR : Dwarf_Attribute DW_DLA_TYPE : Dwarf_Type (not used) DW_DLA_SUBSCR : Dwarf_Subscr (not used) DW_DLA_GLOBAL_CONTEXT : Dwarf_Global DW_DLA_ERROR : Dwarf_Error DW_DLA_LIST : a list of opaque descriptors DW_DLA_LINEBUF : Dwarf_Line* (not used) DW_DLA_ARANGE : Dwarf_Arange DW_DLA_ABBREV : Dwarf_Abbrev DW_DLA_FRAME_OP : Dwarf_Frame_Op DW_DLA_CIE : Dwarf_Cie DW_DLA_FDE : Dwarf_Fde DW_DLA_LOC_BLOCK : Dwarf_Loc Block DW_DLA_FRAME_BLOCK : Dwarf_Frame Block (not used) DW_DLA_FUNC_CONTEXT : Dwarf_Func DW_DLA_TYPENAME_CONTEXT : Dwarf_Type DW_DLA_VAR_CONTEXT : Dwarf_Var DW_DLA_WEAK_CONTEXT : Dwarf_Weak DW_DLA_PUBTYPES_CONTEXT : Dwarf_Pubtype .TE .FG "Allocation/Deallocation Identifiers" .DE .P .H 1 "Functional Interface" This section describes the functions available in the \fIlibdwarf\fP library. Each function description includes its definition, followed by one or more paragraph describing the function's operation. .P The following sections describe these functions. .H 2 "Initialization Operations" These functions are concerned with preparing an object file for subsequent access by the functions in \fIlibdwarf\fP and with releasing allocated resources when access is complete. .H 3 "dwarf_init()" .DS \f(CWint dwarf_init( int fd, Dwarf_Unsigned access, Dwarf_Handler errhand, Dwarf_Ptr errarg, Dwarf_Debug * dbg, Dwarf_Error *error)\fP .DE When it returns \f(CWDW_DLV_OK\fP, the function \f(CWdwarf_init()\fP returns thru \f(CWdbg\fP a \f(CWDwarf_Debug\fP descriptor that represents a handle for accessing debugging records associated with the open file descriptor \f(CWfd\fP. \f(CWDW_DLV_NO_ENTRY\fP is returned if the object does not contain DWARF debugging information. \f(CWDW_DLV_ERROR\fP is returned if an error occurred. The \f(CWaccess\fP argument indicates what access is allowed for the section. The \f(CWDW_DLC_READ\fP parameter is valid for read access (only read access is defined or discussed in this document). The \f(CWerrhand\fP argument is a pointer to a function that will be invoked whenever an error is detected as a result of a \fIlibdwarf\fP operation. The \f(CWerrarg\fP argument is passed as an argument to the \f(CWerrhand\fP function. The file descriptor associated with the \f(CWfd\fP argument must refer to an ordinary file (i.e. not a pipe, socket, device, /proc entry, etc.), be opened with the at least as much permission as specified by the \f(CWaccess\fP argument, and cannot be closed or used as an argument to any system calls by the client until after \f(CWdwarf_finish()\fP is called. The seek position of the file associated with \f(CWfd\fP is undefined upon return of \f(CWdwarf_init()\fP. With SGI IRIX, by default it is allowed that the app \f(CWclose()\fP \f(CWfd\fP immediately after calling \f(CWdwarf_init()\fP, but that is not a portable approach (that it works is an accidental side effect of the fact that SGI IRIX uses \f(CWELF_C_READ_MMAP\fP in its hidden internal call to \f(CWelf_begin()\fP). The portable approach is to consider that \f(CWfd\fP must be left open till after the corresponding dwarf_finish() call has returned. Since \f(CWdwarf_init()\fP uses the same error handling processing as other \fIlibdwarf\fP functions (see \fIError Handling\fP above), client programs will generally supply an \f(CWerror\fP parameter to bypass the default actions during initialization unless the default actions are appropriate. .H 3 "dwarf_elf_init()" .DS \f(CWint dwarf_elf_init( Elf * elf_file_pointer, Dwarf_Unsigned access, Dwarf_Handler errhand, Dwarf_Ptr errarg, Dwarf_Debug * dbg, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_elf_init()\fP is identical to \f(CWdwarf_init()\fP except that an open \f(CWElf *\fP pointer is passed instead of a file descriptor. In systems supporting \f(CWELF\fP object files this may be more space or time-efficient than using \f(CWdwarf_init()\fP. The client is allowed to use the \f(CWElf *\fP pointer for its own purposes without restriction during the time the \f(CWDwarf_Debug\fP is open, except that the client should not \f(CWelf_end()\fP the pointer till after \f(CWdwarf_finish\fP is called. .H 3 "dwarf_get_elf()" .DS \f(CWint dwarf_get_elf( Dwarf_Debug dbg, Elf ** elf, Dwarf_Error *error)\fP .DE When it returns \f(CWDW_DLV_OK\fP, the function \f(CWdwarf_get_elf()\fP returns thru the pointer \f(CWelf\fP the \f(CWElf *\fP handle used to access the object represented by the \f(CWDwarf_Debug\fP descriptor \f(CWdbg\fP. It returns \f(CWDW_DLV_ERROR\fP on error. Because \f(CWint dwarf_init()\fP opens an Elf descriptor on its fd and \f(CWdwarf_finish()\fP does not close that descriptor, an app should use \f(CWdwarf_get_elf\fP and should call \f(CWelf_end\fP with the pointer returned thru the \f(CWElf**\fP handle created by \f(CWint dwarf_init()\fP. This function is not meaningful for a system that does not use the Elf format for objects. .H 3 "dwarf_finish()" .DS \f(CWint dwarf_finish( Dwarf_Debug dbg, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_finish()\fP releases all \fILibdwarf\fP internal resources associated with the descriptor \f(CWdbg\fP, and invalidates \f(CWdbg\fP. It returns \f(CWDW_DLV_ERROR\fP if there is an error during the finishing operation. It returns \f(CWDW_DLV_OK\fP for a successful operation. Because \f(CWint dwarf_init()\fP opens an Elf descriptor on its fd and \f(CWdwarf_finish()\fP does not close that descriptor, an app should use \f(CWdwarf_get_elf\fP and should call \f(CWelf_end\fP with the pointer returned thru the \f(CWElf**\fP handle created by \f(CWint dwarf_init()\fP. .H 2 "Debugging Information Entry Delivery Operations" These functions are concerned with accessing debugging information entries. .H 3 "Debugging Information Entry Debugger Delivery Operations" .H 3 "dwarf_next_cu_header()" .DS \f(CWint dwarf_next_cu_header( Dwarf_debug dbg, Dwarf_Unsigned *cu_header_length, Dwarf_Half *version_stamp, Dwarf_Unsigned *abbrev_offset, Dwarf_Half *address_size, Dwarf_Unsigned *next_cu_header, Dwarf_Error *error); .DE The function \f(CWdwarf_next_cu_header()\fP returns \f(CWDW_DLV_ERROR\fP if it fails, and \f(CWDW_DLV_OK\fP if it succeeds. .P If it succeeds, \f(CW*next_cu_header\fP is set to the offset in the .debug_info section of the next compilation-unit header if it succeeds. On reading the last compilation-unit header in the .debug_info section it contains the size of the .debug_info section. The next call to \f(CWdwarf_next_cu_header()\fP returns \f(CWDW_DLV_NO_ENTRY\fP without reading a compilation-unit or setting \f(CW*next_cu_header\fP. Subsequent calls to \f(CWdwarf_next_cu_header()\fP repeat the cycle by reading the first compilation-unit and so on. .P The other values returned through pointers are the values in the compilation-unit header. If any of \f(CWcu_header_length\fP, \f(CWversion_stamp\fP, \f(CWabbrev_offset\fP, or \f(CWaddress_size\fP is \f(CWNULL\fP, the argument is ignored (meaning it is not an error to provide a \f(CWNULL\fP pointer). .H 3 "dwarf_siblingof()" .DS \f(CWint dwarf_siblingof( Dwarf_Debug dbg, Dwarf_Die die, Dwarf_Die *return_sib, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_siblingof()\fP returns \f(CWDW_DLV_ERROR\fP and sets the \f(CWerror\fP pointer on error. If there is no sibling it returns \f(CWDW_DLV_NO_ENTRY\fP. When it succeeds, \f(CWdwarf_siblingof()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_sib\fP to the \f(CWDwarf_Die\fP descriptor of the sibling of \f(CWdie\fP. If \f(CWdie\fP is \fINULL\fP, the \f(CWDwarf_Die\fP descriptor of the first die in the compilation-unit is returned. This die has the \f(CWDW_TAG_compile_unit\fP tag. .H 3 "dwarf_child()" .DS \f(CWint dwarf_child( Dwarf_Die die, Dwarf_Die *return_kid, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_child()\fP returns \f(CWDW_DLV_ERROR\fP and sets the \f(CWerror\fP die on error. If there is no child it returns \f(CWDW_DLV_NO_ENTRY\fP. When it succeeds, \f(CWdwarf_child()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_kid\fP to the \f(CWDwarf_Die\fP descriptor of the first child of \f(CWdie\fP. The function \f(CWdwarf_siblingof()\fP can be used with the return value of \f(CWdwarf_child()\fP to access the other children of \f(CWdie\fP. .H 3 "dwarf_offdie()" .DS \f(CWint dwarf_offdie( Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Die *return_die, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_offdie()\fP returns \f(CWDW_DLV_ERROR\fP and sets the \f(CWerror\fP die on error. When it succeeds, \f(CWdwarf_offdie()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_die\fP to the the \f(CWDwarf_Die\fP descriptor of the debugging information entry at \f(CWoffset\fP in the section containing debugging information entries i.e the .debug_info section. A return of \f(CWDW_DLV_NO_ENTRY\fP means that the \f(CWoffset\fP in the section is of a byte containing all 0 bits, indicating that there is no abbreviation code. Meaning this 'die offset' is not the offset of a real die, but is instead an offset of a null die, a padding die, or of some random zero byte: this should not be returned in normal use. It is the user's responsibility to make sure that \f(CWoffset\fP is the start of a valid debugging information entry. The result of passing it an invalid offset could be chaos. .\"#if 0 .\".H 3 "Debugging Entry Delivery High-level Operations" .\"The following "higher level" operations are typically not used by .\"debuggers or DWARF prettyprinters. A disassembler (for example) .\"might find them useful. .\" .\".DS .\"\f(CWDwarf_Die dwarf_pcfile( .\" Dwarf_Debug dbg, .\" Dwarf_Addr pc, .\" Dwarf_Error *error)\fP .\".DE .\"The function \f(CWdwarf_pcfile()\fP returns the \f(CWDwarf_Die\fP .\"descriptor of the compilation unit debugging information entry that .\"contains the address of \f(CWpc\fP. It returns \fINULL\fP if no .\"entry exists or an error occurred. Currently compilation unit .\"debugging information entries are defined as those having a tag of: .\"\f(CWDW_TAG_compile_unit\fP. This function is currently unimplemented. .\" .\".DS .\"\f(CWDwarf_Die dwarf_pcsubr( .\" Dwarf_Debug dbg, .\" Dwarf_Addr pc, .\" Dwarf_Error *error)\fP .\".DE .\"The function .\"\f(CWdwarf_pcsubr()\fP returns the \f(CWDwarf_Die\fP descriptor of the .\"subroutine debugging entry that contains the address of \f(CWpc\fP. It .\"returns \fINULL\fP if no entry exists or an error occurred. Currently .\"subroutine debugging information entries are defined as those having a .\"tag of: \f(CWDW_TAG_subprogram\fP, or \f(CWTAG_inlined_subroutine\fP. .\"This function is currently unimplemented. .\" .\".DS .\"\f(CWDwarf_Die dwarf_pcscope( .\" Dwarf_Debug dbg, .\" Dwarf_Addr pc, .\" Dwarf_Error *error)\fP .\".DE .\"The function .\"\f(CWdwarf_pcscope()\fP returns the \f(CWDwarf_Die\fP descriptor for .\"the debugging information entry that represents the innermost enclosing .\"scope containing \f(CWpc\fP, or \fINULL\fP if no entry exists or an .\"error occurred. Debugging information entries that represent a \fIscope\fP .\"are those containing a low pc attribute and either a high pc or byte .\"size attribute that delineates a range. For example: a debugging information .\"entry for a lexical block is considered one having a scope whereas a .\"debugging information entry for a label is not. This function is .\"currently unimplemented. .\"#endif .H 2 "Debugging Information Entry Query Operations" These queries return specific information about debugging information entries or a descriptor that can be used on subsequent queries when given a \f(CWDwarf_Die\fP descriptor. Note that some operations are specific to debugging information entries that are represented by a \f(CWDwarf_Die\fP descriptor of a specific type. For example, not all debugging information entries contain an attribute having a name, so consequently, a call to \f(CWdwarf_diename()\fP using a \f(CWDwarf_Die\fP descriptor that does not have a name attribute will return \f(CWDW_DLV_NO_ENTRY\fP. This is not an error, i.e. calling a function that needs a specific attribute is not an error for a die that does not contain that specific attribute. .P There are several methods that can be used to obtain the value of an attribute in a given die: .AL 1 .LI Call \f(CWdwarf_hasattr()\fP to determine if the debugging information entry has the attribute of interest prior to issuing the query for information about the attribute. .LI Supply an \f(CWerror\fP argument, and check its value after the call to a query indicates an unsuccessful return, to determine the nature of the problem. The \f(CWerror\fP argument will indicate whether an error occurred, or the specific attribute needed was missing in that die. .LI Arrange to have an error handling function invoked upon detection of an error (see \f(CWdwarf_init()\fP). .LI Call \f(CWdwarf_attrlist()\fP and iterate through the returned list of attributes, dealing with each one as appropriate. .LE .P .H 3 "dwarf_tag()" .DS \f(CWint dwarf_tag( Dwarf_Die die, Dwarf_Half *tagval, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_tag()\fP returns the \fItag\fP of \f(CWdie\fP thru the pointer \f(CWtagval\fP if it succeeds. It returns \f(CWDW_DLV_OK\fP if it succeeds. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_dieoffset()" .DS \f(CWint dwarf_dieoffset( Dwarf_Die die, Dwarf_Off * return_offset, Dwarf_Error *error)\fP .DE When it succeeds, the function \f(CWdwarf_dieoffset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the position of \f(CWdie\fP in the section containing debugging information entries (the \f(CWreturn_offset\fP is a section-relative offset). In other words, it sets \f(CWreturn_offset\fP to the offset of the start of the debugging information entry described by \f(CWdie\fP in the section containing die's i.e .debug_info. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_die_CU_offset()" .DS \f(CWint dwarf_die_CU_offset( Dwarf_Die die, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_die_CU_offset()\fP is similar to \f(CWdwarf_dieoffset()\fP, except that it puts the offset of the DIE represented by the \f(CWDwarf_Die\fP \f(CWdie\fP, from the start of the compilation-unit that it belongs to rather than the start of .debug_info (the \f(CWreturn_offset\fP is a CU-relative offset). .H 3 "dwarf_diename()" .DS \f(CWint dwarf_diename( Dwarf_Die die, char ** return_name, Dwarf_Error *error)\fP .DE When it succeeds, the function \f(CWdwarf_diename()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string of characters that represents the name attribute of \f(CWdie\fP. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not have a name attribute. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. The storage pointed to by a successful return of \f(CWdwarf_diename()\fP should be free'd using the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest (see \f(CWdwarf_dealloc()\fP). .H 3 "dwarf_attrlist()" .DS \f(CWint dwarf_attrlist( Dwarf_Die die, Dwarf_Attribute** attrbuf, Dwarf_Signed *attrcount, Dwarf_Error *error)\fP .DE When it returns \f(CWDW_DLV_OK\fP, the function \f(CWdwarf_attrlist()\fP sets \f(CWattrbuf\fP to point to an array of \f(CWDwarf_Attribute\fP descriptors corresponding to each of the attributes in die, and returns the number of elements in the array thru \f(CWattrcount\fP. \f(CWDW_DLV_NO_ENTRY\fP is returned if the count is zero (no \f(CWattrbuf\fP is allocated in this case). \f(CWDW_DLV_ERROR\fP is returned on error. On a successful return from \f(CWdwarf_attrlist()\fP, each of the \f(CWDwarf_Attribute\fP descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ATTR\fP, followed by free-ing the list pointed to by \f(CW*attrbuf\fP using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_LIST\fP, when no longer of interest (see \f(CWdwarf_dealloc()\fP). Freeing the attrlist: .in +2 .DS \f(CWDwarf_Unsigned atcnt; Dwarf_Attribute *atlist; int errv; errv = dwarf_attrlist(somedie, &atlist,&atcnt, &error); if (errv == DW_DLV_OK) { for (i = 0; i < atcnt; ++i) { /* use atlist[i] */ dwarf_dealloc(dbg, atlist[i], DW_DLA_ATTR); } dwarf_dealloc(dbg, atlist, DW_DLA_LIST); }\fP .DE .in -2 .P .H 3 "dwarf_hasattr()" .DS \f(CWint dwarf_hasattr( Dwarf_Die die, Dwarf_Half attr, Dwarf_Bool *return_bool, Dwarf_Error *error)\fP .DE When it succeeds, the function \f(CWdwarf_hasattr()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP to \fInon-zero\fP if \f(CWdie\fP has the attribute \f(CWattr\fP and \fIzero\fP otherwise. If it fails, it returns \f(CWDW_DLV_ERROR\fP. .H 3 "dwarf_attr()" .DS \f(CWint dwarf_attr( Dwarf_Die die, Dwarf_Half attr, Dwarf_Attribute *return_attr, Dwarf_Error *error)\fP .DE When it returns \f(CWDW_DLV_OK\fP, the function \f(CWdwarf_attr()\fP sets \f(CW*return_attr\fP to the \f(CWDwarf_Attribute\fP descriptor of \f(CWdie\fP having the attribute \f(CWattr\fP. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWattr\fP is not contained in \f(CWdie\fP. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .\"#if 0 .\".DS .\"\f(CWDwarf_Locdesc* dwarf_stringlen( .\" Dwarf_Die die, .\" Dwarf_Error *error)\fP .\".DE .\"The function \f(CWdwarf_stringlen()\fP returns a pointer to a .\"\f(CWDwarf_Locdesc\fP with one Locdesc entry that when evaluated, .\"yields the length of the string represented by \f(CWdie\fP. It .\"returns \f(CWNULL\fP if \f(CWdie\fP does not contain a string length .\"attribute or the string length attribute is not a location-description .\"or an error occurred. The address range of the list is set to 0 thru .\"the highest possible address if a loclist pointer is returned. The .\"storage pointed to by a successful return of \f(CWdwarf_stringlen()\fP .\"should be free'd when no longer of interest (see \f(CWdwarf_dealloc()\fP). .\"This function is currently unimplemented. .\"#endif .\"#if 0 .\".DS .\"\f(CWDwarf_Signed dwarf_subscrcnt( .\" Dwarf_Die die, .\" Dwarf_Error *error)\fP .\".DE .\"The function \f(CWdwarf_subscrcnt()\fP returns the number of subscript .\"die's that are owned by the array type represented by \f(CWdie\fP. It .\"returns \f(CWDW_DLV_NOCOUNT\fP on error. This function is currently .\"unimplemented. .\" .\".DS .\"\f(CWDwarf_Die dwarf_nthsubscr( .\" Dwarf_Die die, .\" Dwarf_Unsigned ssndx, .\" Dwarf_Error *error)\fP .\".DE .\"The function \f(CWdwarf_nthsubscr()\fP returns a \f(CWDwarf_Die\fP .\"descriptor that describes the \f(CWssndx\fP subscript of the array .\"type debugging information entry represented by \f(CWdie\fP, where .\"\fI1\fP is the first member. It returns \fINULL\fP if \f(CWdie\fP .\"does not have an \f(CWssndx\fP subscript, or an error occurred. .\"This function is currently unimplemented. .\"#endif .H 3 "dwarf_lowpc()" .DS \f(CWint dwarf_lowpc( Dwarf_Die die, Dwarf_Addr * return_lowpc, Dwarf_Error * error)\fP .DE The function \f(CWdwarf_lowpc()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_lowpc\fP to the low program counter value associated with the \f(CWdie\fP descriptor if \f(CWdie\fP represents a debugging information entry with this attribute. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not have this attribute. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .H 3 "dwarf_highpc()" .DS \f(CWint dwarf_highpc( Dwarf_Die die, Dwarf_Addr * return_highpc, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_highpc()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_highpc\fP the high program counter value associated with the \f(CWdie\fP descriptor if \f(CWdie\fP represents a debugging information entry with this attribute. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not have this attribute. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .H 3 "dwarf_bytesize()" .DS \f(CWDwarf_Signed dwarf_bytesize( Dwarf_Die die, Dwarf_Unsigned *return_size, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_bytesize()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_size\fP to the number of bytes needed to contain an instance of the aggregate debugging information entry represented by \f(CWdie\fP. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not contain the byte size attribute \f(CWDW_AT_byte_size\fP. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .\"#if 0 .\".DS .\"\f(CWDwarf_Bool dwarf_isbitfield( .\" Dwarf_Die die, .\" Dwarf_Error *error)\fP .\".DE .\"The function \f(CWdwarf_isbitfield()\fP returns \fInon-zero\fP if .\"\f(CWdie\fP is a descriptor for a debugging information entry that .\"represents a bit field member. It returns \fIzero\fP if \f(CWdie\fP .\"is not associated with a bit field member. This function is currently .\"unimplemented. .\"#endif .H 3 "dwarf_bitsize()" .DS \f(CWint dwarf_bitsize( Dwarf_Die die, Dwarf_Unsigned *return_size, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_bitsize()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_size\fP to the number of bits occupied by the bit field value that is an attribute of the given die. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not contain the bit size attribute \f(CWDW_AT_bit_size\fP. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .H 3 "dwarf_bitoffset()" .DS \f(CWint dwarf_bitoffset( Dwarf_Die die, Dwarf_Unsigned *return_size, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_bitoffset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_size\fP to the number of bits to the left of the most significant bit of the bit field value. This bit offset is not necessarily the net bit offset within the structure or class , since \f(CWDW_AT_data_member_location\fP may give a byte offset to this \f(CWDIE\fP and the bit offset returned through the pointer does not include the bits in the byte offset. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not contain the bit offset attribute \f(CWDW_AT_bit_offset\fP. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .H 3 "dwarf_srclang()" .DS \f(CWint dwarf_srclang( Dwarf_Die die, Dwarf_Unsigned *return_lang, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_srclang()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_lang\fP to a code indicating the source language of the compilation unit represented by the descriptor \f(CWdie\fP. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not represent a source file debugging information entry (i.e. contain the attribute \f(CWDW_AT_language\fP). It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .H 3 "dwarf_arrayorder()" .DS \f(CWint dwarf_arrayorder( Dwarf_Die die, Dwarf_Unsigned *return_order, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_arrayorder()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_order\fP a code indicating the ordering of the array represented by the descriptor \f(CWdie\fP. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWdie\fP does not contain the array order attribute \f(CWDW_AT_ordering\fP. It returns \f(CWDW_DLV_ERROR\fP if an error occurred. .H 2 "Attribute Form Queries" Based on the attribute's form, these operations are concerned with returning uninterpreted attribute data. Since it is not always obvious from the return value of these functions if an error occurred, one should always supply an \f(CWerror\fP parameter or have arranged to have an error handling function invoked (see \f(CWdwarf_init()\fP) to determine the validity of the returned value and the nature of any errors that may have occurred. A \f(CWDwarf_Attribute\fP descriptor describes an attribute of a specific die. Thus, each \f(CWDwarf_Attribute\fP descriptor is implicitly associated with a specific die. .H 3 "dwarf_hasform()" .DS \f(CWnt dwarf_hasform( Dwarf_Attribute attr, Dwarf_Half form, Dwarf_Bool *return_hasform, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_hasform()\fP returns \f(CWDW_DLV_OK\fP and and puts a \fInon-zero\fP value in the \f(CW*return_hasform\fP boolean if the attribute represented by the \f(CWDwarf_Attribute\fP descriptor \f(CWattr\fP has the attribute form \f(CWform\fP. If the attribute does not have that form \fIzero\fP is put into \f(CW*return_hasform\fP. \f(CWDW_DLV_ERROR\fP is returned on error. .H 3 "dwarf_whatform()" .DS \f(CWint dwarf_whatform( Dwarf_Attribute attr, Dwarf_Half *return_form, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_whatform()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_form\fP to the attribute form code of the attribute represented by the \f(CWDwarf_Attribute\fP descriptor \f(CWattr\fP. It returns \f(CWDW_DLV_ERROR\fP on error. An attribute using DW_FORM_indirect effectively has two forms. This function returns the 'final' form for \f(CWDW_FORM_indirect\fP, not the \f(CWDW_FORM_indirect\fP itself. This function is what most applications will want to call. .H 3 "dwarf_whatform_direct()" .DS \f(CWint dwarf_whatform_direct( Dwarf_Attribute attr, Dwarf_Half *return_form, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_whatform_direct()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_form\fP to the attribute form code of the attribute represented by the \f(CWDwarf_Attribute\fP descriptor \f(CWattr\fP. It returns \f(CWDW_DLV_ERROR\fP on error. An attribute using \f(CWDW_FORM_indirect\fP effectively has two forms. This returns the form 'directly' in the initial form field. So when the form field is \f(CWDW_FORM_indirect\fP this call returns the \f(CWDW_FORM_indirect\fP form, which is sometimes useful for dump utilities. .H 3 "dwarf_whatattr()" .DS \f(CWint dwarf_whatattr( Dwarf_Attribute attr, Dwarf_Half *return_attr, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_whatattr()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_attr\fP to the attribute code represented by the \f(CWDwarf_Attribute\fP descriptor \f(CWattr\fP. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_formref()" .DS \f(CWint dwarf_formref( Dwarf_Attribute attr, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_formref()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the CU-relative offset represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWREFERENCE\fP class. \f(CWattr\fP must be a CU-local reference, not form \f(CWDW_FORM_ref_addr\fP. It is an error for the form to not belong to this class or to be form \f(CWDW_FORM_ref_addr\fP. It returns \f(CWDW_DLV_ERROR\fP on error. See also \f(CWdwarf_global_formref\fP below. .H 3 "dwarf_global_formref()" .DS \f(CWint dwarf_global_formref( Dwarf_Attribute attr, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_global_formref()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the .debug_info-section-relative offset represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWREFERENCE\fP class. \f(CWattr\fP can be any legal \f(CWREFERENCE\fP class form including \f(CWDW_FORM_ref_addr\fP. It is an error for the form to not belong to this class. It returns \f(CWDW_DLV_ERROR\fP on error. See also \f(CWdwarf_formref\fP above. .H 3 "dwarf_formaddr()" .DS \f(CWint dwarf_formaddr( Dwarf_Attribute attr, Dwarf_Addr * return_addr, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_formaddr()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_addr\fP to the address represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWADDRESS\fP class. It is an error for the form to not belong to this class. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_formflag()" .DS \f(CWint dwarf_formflag( Dwarf_Attribute attr, Dwarf_Bool * return_bool, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_formflag()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP \f(CW1\fP (i.e. true) (if the attribute has a non-zero value) or \f(CW0\fP (i.e. false) (if the attribute has a zero value). It returns \f(CWDW_DLV_ERROR\fP on error or if the \f(CWattr\fP does not have form flag. .H 3 "dwarf_formudata()" .DS \f(CWint dwarf_formudata( Dwarf_Attribute attr, Dwarf_Unsigned * return_uvalue, Dwarf_Error * error)\fP .DE The function \f(CWdwarf_formudata()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_uvalue\fP to the \f(CWDwarf_Unsigned\fP value of the attribute represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWCONSTANT\fP class. It is an error for the form to not belong to this class. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_formsdata()" .DS \f(CWint dwarf_formsdata( Dwarf_Attribute attr, Dwarf_Signed * return_svalue, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_formsdata()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_svalue\fP to the \f(CWDwarf_Signed\fP value of the attribute represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWCONSTANT\fP class. It is an error for the form to not belong to this class. If the size of the data attribute referenced is smaller than the size of the \f(CWDwarf_Signed\fP type, its value is sign extended. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_formblock()" .DS \f(CWint dwarf_formblock( Dwarf_Attribute attr, Dwarf_Block ** return_block, Dwarf_Error * error)\fP .DE The function \f(CWdwarf_formblock()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_block\fP to a pointer to a \f(CWDwarf_Block\fP structure containing the value of the attribute represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWBLOCK\fP class. It is an error for the form to not belong to this class. The storage pointed to by a successful return of \f(CWdwarf_formblock()\fP should be free'd using the allocation type \f(CWDW_DLA_BLOCK\fP, when no longer of interest (see \f(CWdwarf_dealloc()\fP). It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_formstring()" .DS \f(CWint dwarf_formstring( Dwarf_Attribute attr, char ** return_string, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_formstring()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_string\fP to a pointer to a null-terminated string containing the value of the attribute represented by the descriptor \f(CWattr\fP if the form of the attribute belongs to the \f(CWSTRING\fP class. It is an error for the form to not belong to this class. The storage pointed to by a successful return of \f(CWdwarf_formstring()\fP should not be free'd. The pointer points into existing DWARF memory and the pointer becomes stale/invalid after a call to \f(CWdwarf_finish\fP. \f(CWdwarf_formstring()\fP returns \f(CWDW_DLV_ERROR\fP on error. .H 4 "dwarf_loclist_n()" .DS \f(CWint dwarf_loclist_n( Dwarf_Attribute attr, Dwarf_Locdesc ***llbuf, Dwarf_Signed *listlen, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_loclist_n()\fP sets \f(CW*llbuf\fP to point to an array of \f(CWDwarf_Locdesc\fP pointers corresponding to each of the location expressions in a location list, and sets \f(CW*listlen\fP to the number of elements in the array and returns \f(CWDW_DLV_OK\fP if the attribute is appropriate. .P This is the preferred function for Dwarf_Locdesc as it is the interface allowing access to an entire loclist. (use of \f(CWdwarf_loclist_n()\fP is suggested as the better interface, though \f(CWdwarf_loclist()\fP is still supported.) .P If the attribute is a reference to a location list (DW_FORM_data4 or DW_FORM_data8) the location list entries are used to fill in all the fields of the \f(CWDwarf_Locdesc\fP(s) returned. .P If the attribute is a location description (DW_FORM_block2 or DW_FORM_block4) then some of the \f(CWDwarf_Locdesc\fP values of the single \f(CWDwarf_Locdesc\fP record are set to 'sensible' but arbitrary values. Specifically, ld_lopc is set to 0 and ld_hipc is set to all-bits-on. And \f(CW*listlen\fP is set to 1. .P It returns \f(CWDW_DLV_ERROR\fP on error. \f(CWdwarf_loclist_n()\fP works on \f(CWDW_AT_location\fP, \f(CWDW_AT_data_member_location\fP, \f(CWDW_AT_vtable_elem_location\fP, \f(CWDW_AT_string_length\fP, \f(CWDW_AT_use_location\fP, and \f(CWDW_AT_return_addr\fP attributes. .P Storage allocated by a successful call of \f(CWdwarf_loclist_n()\fP should be deallocated when no longer of interest (see \f(CWdwarf_dealloc()\fP). The block of \f(CWDwarf_Loc\fP structs pointed to by the \f(CWld_s\fP field of each \f(CWDwarf_Locdesc\fP structure should be deallocated with the allocation type \f(CWDW_DLA_LOC_BLOCK\fP. and the \f(CWllbuf[]\fP space pointed to should be deallocated with allocation type \f(CWDW_DLA_LOCDESC\fP. This should be followed by deallocation of the \f(CWllbuf\fP using the allocation type \f(CWDW_DLA_LIST\fP. .in +2 .DS \f(CWDwarf_Signed lcnt; Dwarf_Locdesc **llbuf; int lres; lres = dwarf_loclist_n(someattr, &llbuf,&lcnt &error); if (lres == DW_DLV_OK) { for (i = 0; i < lcnt; ++i) { /* use llbuf[i] */ dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK); dwarf_dealloc(dbg,llbuf[i], DW_DLA_LOCDESC); } dwarf_dealloc(dbg, llbuf, DW_DLA_LIST); }\fP .DE .in -2 .P .H 4 "dwarf_loclist()" .DS \f(CWint dwarf_loclist( Dwarf_Attribute attr, Dwarf_Locdesc **llbuf, Dwarf_Signed *listlen, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_loclist()\fP sets \f(CW*llbuf\fP to point to a \f(CWDwarf_Locdesc\fP pointer for the single location expression it can return. It sets \f(CW*listlen\fP to 1. and returns \f(CWDW_DLV_OK\fP if the attribute is appropriate. .P It is less flexible than \f(CWdwarf_loclist_n()\fP in that \f(CWdwarf_loclist()\fP can handle a maximum of one location expression, not a full location list. If a location-list is present it returns only the first location-list entry location description. Use \f(CWdwarf_loclist_n()\fP instead. .P It returns \f(CWDW_DLV_ERROR\fP on error. \f(CWdwarf_loclist()\fP works on \f(CWDW_AT_location\fP, \f(CWDW_AT_data_member_location\fP, \f(CWDW_AT_vtable_elem_location\fP, \f(CWDW_AT_string_length\fP, \f(CWDW_AT_use_location\fP, and \f(CWDW_AT_return_addr\fP attributes. .P Storage allocated by a successful call of \f(CWdwarf_loclist()\fP should be deallocated when no longer of interest (see \f(CWdwarf_dealloc()\fP). The block of \f(CWDwarf_Loc\fP structs pointed to by the \f(CWld_s\fP field of each \f(CWDwarf_Locdesc\fP structure should be deallocated with the allocation type \f(CWDW_DLA_LOC_BLOCK\fP. This should be followed by deallocation of the \f(CWllbuf\fP using the allocation type \f(CWDW_DLA_LOCDESC\fP. .in +2 .DS \f(CWDwarf_Signed lcnt; Dwarf_Locdesc *llbuf; int lres; lres = dwarf_loclist(someattr, &llbuf,&lcnt,&error); if (lres == DW_DLV_OK) { /* lcnt is always 1, (and has always been 1) */ */ /* Use llbuf here. */ dwarf_dealloc(dbg, llbuf->ld_s, DW_DLA_LOC_BLOCK); dwarf_dealloc(dbg, llbuf, DW_DLA_LOCDESC); /* Earlier version. * for (i = 0; i < lcnt; ++i) { * /* use llbuf[i] */ * * /* Deallocate Dwarf_Loc block of llbuf[i] */ * dwarf_dealloc(dbg, llbuf[i].ld_s, DW_DLA_LOC_BLOCK); * } * dwarf_dealloc(dbg, llbuf, DW_DLA_LOCDESC); */ }\fP .DE .in -2 .P .H 4 "dwarf_loclist_from_expr()" .DS \f(CWint dwarf_loclist_from_expr( Dwarf_Ptr bytes_in, Dwarf_Unsigned bytes_len, Dwarf_Locdesc **llbuf, Dwarf_Signed *listlen, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_loclist_from_expr()\fP sets \f(CW*llbuf\fP to point to a \f(CWDwarf_Locdesc\fP pointer for the single location expression which is pointed to by \f(CW*bytes_in\fP (whose length is \f(CW*bytes_len\fP). It sets \f(CW*listlen\fP to 1. and returns \f(CWDW_DLV_OK\fP if decoding is successful. Some sources of bytes of expressions are dwarf expressions in frame operations like \f(CWDW_CFA_def_cfa_expression\fP, \f(CWDW_CFA_expression\fP, and \f(CWDW_CFA_val_expression\fP. .P It returns \f(CWDW_DLV_ERROR\fP on error. .P Storage allocated by a successful call of \f(CWdwarf_loclist_from_expr()\fP should be deallocated when no longer of interest (see \f(CWdwarf_dealloc()\fP). The block of \f(CWDwarf_Loc\fP structs pointed to by the \f(CWld_s\fP field of each \f(CWDwarf_Locdesc\fP structure should be deallocated with the allocation type \f(CWDW_DLA_LOC_BLOCK\fP. This should be followed by deallocation of the \f(CWllbuf\fP using the allocation type \f(CWDW_DLA_LOCDESC\fP. .in +2 .DS \f(CWDwarf_Signed lcnt; Dwarf_Locdesc *llbuf; int lres; /* Example with an empty buffer here. */ Dwarf_Ptr data = ""; Dwarf_Unsigned len = 0; lres = dwarf_loclist_from_expr(data,len, &llbuf,&lcnt, &error); if (lres == DW_DLV_OK) { /* lcnt is always 1 */ /* Use llbuf here.*/ dwarf_dealloc(dbg, llbuf->ld_s, DW_DLA_LOC_BLOCK); dwarf_dealloc(dbg, llbuf, DW_DLA_LOCDESC); }\fP .DE .in -2 .P .P .H 2 "Line Number Operations" These functions are concerned with accessing line number entries, mapping debugging information entry objects to their corresponding source lines, and providing a mechanism for obtaining information about line number entries. Although, the interface talks of "lines" what is really meant is "statements". In case there is more than one statement on the same line, there will be at least one descriptor per statement, all with the same line number. If column number is also being represented they will have the column numbers of the start of the statements also represented. .P There can also be more than one Dwarf_Line per statement. For example, if a file is preprocessed by a language translator, this could result in translator output showing 2 or more sets of line numbers per translated line of output. .H 3 "Get A Set of Lines" The function returns information about every source line for a particular compilation-unit. The compilation-unit is specified by the corresponding die. .H 4 "dwarf_srclines()" .DS \f(CWint dwarf_srclines( Dwarf_Die die, Dwarf_Line **linebuf, Dwarf_Signed *linecount, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_srclines()\fP places all line number descriptors for a single compilation unit into a single block, sets \f(CW*linebuf\fP to point to that block, sets \f(CW*linecount\fP to the number of descriptors in this block and returns \f(CWDW_DLV_OK\fP. The compilation-unit is indicated by the given \f(CWdie\fP which must be a compilation-unit die. It returns \f(CWDW_DLV_ERROR\fP on error. On successful return, line number information should be free'd using \f(CWdwarf_srclines_dealloc()\fP when no longer of interest. .P .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Line *linebuf; int sres; sres = dwarf_srclines(somedie, &linebuf,&cnt, &error); if (sres == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use linebuf[i] */ } dwarf_srclines_dealloc(dbg, linebuf, cnt); }\fP .DE .in -2 .P The following dealloc code (the only documented method before July 2005) still works, but does not completely free all data allocated. The \f(CWdwarf_srclines_dealloc()\fP routine was created to fix the problem of incomplete deallocation. .P .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Line *linebuf; int sres; sres = dwarf_srclines(somedie, &linebuf,&cnt, &error); if (sres == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use linebuf[i] */ dwarf_dealloc(dbg, linebuf[i], DW_DLA_LINE); } dwarf_dealloc(dbg, linebuf, DW_DLA_LIST); }\fP .DE .in -2 .H 3 "Get the set of Source File Names" The function returns the names of the source files that have contributed to the compilation-unit represented by the given DIE. Only the source files named in the statement program prologue are returned. .DS \f(CWint dwarf_srcfiles( Dwarf_Die die, char ***srcfiles, Dwarf_Signed *srccount, Dwarf_Error *error)\fP .DE When it succeeds \f(CWdwarf_srcfiles()\fP returns \f(CWDW_DLV_OK\fP and puts the number of source files named in the statement program prologue indicated by the given \f(CWdie\fP into \f(CW*srccount\fP. Source files defined in the statement program are ignored. The given \f(CWdie\fP should have the tag \f(CWDW_TAG_compile_unit\fP. The location pointed to by \f(CWsrcfiles\fP is set to point to a list of pointers to null-terminated strings that name the source files. On a successful return from this function, each of the strings returned should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. This should be followed by free-ing the list using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_LIST\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no corresponding statement program (i.e., if there is no line information). .in +2 .DS \f(CWDwarf_Signed cnt; char **srcfiles; int res; res = dwarf_srcfiles(somedie, &srcfiles,&cnt &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use srcfiles[i] */ dwarf_dealloc(dbg, srcfiles[i], DW_DLA_STRING); } dwarf_dealloc(dbg, srcfiles, DW_DLA_LIST); }\fP .DE .in -2 .H 3 "Get information about a Single Table Line" The following functions can be used on the \f(CWDwarf_Line\fP descriptors returned by \f(CWdwarf_srclines()\fP to obtain information about the source lines. .H 4 "dwarf_linebeginstatement()" .DS \f(CWint dwarf_linebeginstatement( Dwarf_Line line, Dwarf_Bool *return_bool, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_linebeginstatement()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP to \fInon-zero\fP (if \f(CWline\fP represents a line number entry that is marked as beginning a statement). or \fIzero\fP ((if \f(CWline\fP represents a line number entry that is not marked as beginning a statement). It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .P .H 4 "dwarf_lineendsequence()" .DS \f(CWint dwarf_lineendsequence( Dwarf_Line line, Dwarf_Bool *return_bool, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_lineendsequence()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_bool\fP \fInon-zero\fP (in which case \f(CWline\fP represents a line number entry that is marked as ending a text sequence) or \fIzero\fP (in which case \f(CWline\fP represents a line number entry that is not marked as ending a text sequence). A line number entry that is marked as ending a text sequence is an entry with an address one beyond the highest address used by the current sequence of line table entries (that is, the table entry is a DW_LNE_end_sequence entry (see the DWARF specification)). .P The function \f(CWdwarf_lineendsequence()\fP returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .P .H 4 "dwarf_lineno()" .DS \f(CWint dwarf_lineno( Dwarf_Line line, Dwarf_Unsigned * returned_lineno, Dwarf_Error * error)\fP .DE The function \f(CWdwarf_lineno()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_lineno\fP to the source statement line number corresponding to the descriptor \f(CWline\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .P .H 4 "dwarf_line_srcfileno()" .DS \f(CWint dwarf_line_srcfileno( Dwarf_Line line, Dwarf_Unsigned * returned_fileno, Dwarf_Error * error)\fP .DE The function \f(CWdwarf_line_srcfileno()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_fileno\fP to the source statement line number corresponding to the descriptor \f(CWfile number\fP. When the number returned thru \f(CW*returned_fileno\fP is zero it means the file name is unknown (see the DWARF2/3 line table specification). When the number returned thru \f(CW*returned_fileno\fP is non-zero it is a file number: subtract 1 from this file number to get an index into the array of strings returned by \f(CWdwarf_srcfiles()\fP (verify the resulting index is in range for the array of strings before indexing into the array of strings). The file number may exceed the size of the array of strings returned by \f(CWdwarf_srcfiles()\fP because \f(CWdwarf_srcfiles()\fP does not return files names defined with the \f(CWDW_DLE_define_file\fP operator. The function \f(CWdwarf_line_srcfileno()\fP returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .P .H 4 "dwarf_lineaddr()" .DS \f(CWint dwarf_lineaddr( Dwarf_Line line, Dwarf_Addr *return_lineaddr, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_lineaddr()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_lineaddr\fP to the address associated with the descriptor \f(CWline\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .P .H 4 "dwarf_lineoff()" .DS \f(CWint dwarf_lineoff( Dwarf_Line line, Dwarf_Signed * return_lineoff, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_lineoff()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_lineoff\fP to the column number at which the statement represented by \f(CWline\fP begins. It sets \f(CWreturn_lineoff\fP to \fI-1\fP if the column number of the statement is not represented (meaning the producer library call was given zero as the column number). .P On error it returns \f(CWDW_DLV_ERROR\fP. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_linesrc()" .DS \f(CWint dwarf_linesrc( Dwarf_Line line, char ** return_linesrc, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_linesrc()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_linesrc\fP to a pointer to a null-terminated string of characters that represents the name of the source-file where \f(CWline\fP occurs. It returns \f(CWDW_DLV_ERROR\fP on error. .P If the applicable file name in the line table Statement Program Prolog does not start with a '/' character the string in \f(CWDW_AT_comp_dir\fP (if applicable and present) or the applicable directory name from the line Statement Program Prolog is prepended to the file name in the line table Statement Program Prolog to make a full path. .P The storage pointed to by a successful return of \f(CWdwarf_linesrc()\fP should be free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_lineblock()" .DS \f(CWint dwarf_lineblock( Dwarf_Line line, Dwarf_Bool *return_bool, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_lineblock()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_linesrc\fP to non-zero (i.e. true)(if the line is marked as beginning a basic block) or zero (i.e. false) (if the line is marked as not beginning a basic block). It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .\"#if 0 .\".H 3 "Finding a Line Given A PC value" .\"This is a 'higher level' (High-level) interface to line information. .\" .\".DS .\"\f(CWint dwarf_pclines( .\" Dwarf_Debug dbg, .\" Dwarf_Addr pc, .\" Dwarf_Line **linebuf, .\" Dwarf_Signed slide, .\" Dwarf_Signed *linecount, .\" Dwarf_Error *error)\fP .\".DE .\"The function \f(CWdwarf_pclines()\fP places all line number descriptors .\"that correspond to the value of \f(CWpc\fP into a single block and sets .\"\f(CWlinebuf\fP to point to that block. A count of the number of .\"\f(CWDwarf_Line\fP descriptors that are in this block is returned. For .\"most cases, the count returned will be \fIone\fP, though it may be higher .\"if optimizations such as common subexpression elimination result in multiple .\"line number entries for a given value of \f(CWpc\fP. The \f(CWslide\fP .\"argument specifies the direction to search for the nearest line number .\"entry in the event that there is no line number entry that contains an .\"exact match for \f(CWpc\fP. This argument may be one of: .\"\f(CWDLS_BACKWARD\fP, \f(CWDLS_NOSLIDE\fP, \f(CWDLS_FORWARD\fP. .\"\f(CWDW_DLV_NOCOUNT\fP is returned on error. On successful return, each .\"line information structure pointed to by an entry in the block should be .\"free'd using \f(CWdwarf_dealloc()\fP with the allocation type .\"\f(CWDW_DLA_LINE\fP when no longer of interest. The block itself should .\"be free'd using \f(CWdwarf_dealloc()\fP with the allocation type .\"\f(CWDW_DLA_LIST\fP when no longer of interest. .\"#endif .H 2 "Global Name Space Operations" These operations operate on the .debug_pubnames section of the debugging information. .H 3 "Debugger Interface Operations" .H 4 "dwarf_get_globals()" .DS \f(CWint dwarf_get_globals( Dwarf_Debug dbg, Dwarf_Global **globals, Dwarf_Signed * return_count, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_globals()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_count\fP to the count of pubnames represented in the section containing pubnames i.e. .debug_pubnames. It also stores at \f(CW*globals\fP, a pointer to a list of \f(CWDwarf_Global\fP descriptors, one for each of the pubnames in the .debug_pubnames section. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_pubnames section does not exist. .P On a successful return from \f(CWdwarf_get_globals()\fP, the \f(CWDwarf_Global\fP descriptors should be free'd using \f(CWdwarf_globals_dealloc()\fP. \f(CWdwarf_globals_dealloc()\fP is new as of July 15, 2005 and is the preferred approach to freeing this memory.. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Global *globs; int res; res = dwarf_get_globals(dbg, &globs,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use globs[i] */ } dwarf_globals_dealloc(dbg, globs, cnt); }\fP .DE .in -2 .P The following code is deprecated as of July 15, 2005 as it does not free all relevant memory. This approach still works as well as it ever did. On a successful return from \f(CWdwarf_get_globals()\fP, the \f(CWDwarf_Global\fP descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_GLOBAL_CONTEXT\fP, (or \f(CWDW_DLA_GLOBAL\fP, an older name, supported for compatibility) followed by the deallocation of the list itself with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no longer of interest. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Global *globs; int res; res = dwarf_get_globals(dbg, &globs,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use globs[i] */ dwarf_dealloc(dbg, globs[i], DW_DLA_GLOBAL_CONTEXT); } dwarf_dealloc(dbg, globs, DW_DLA_LIST); }\fP .DE .in -2 .H 4 "dwarf_globname()" .DS \f(CWint dwarf_globname( Dwarf_Global global, char ** return_name, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_globname()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string that names the pubname represented by the \f(CWDwarf_Global\fP descriptor, \f(CWglobal\fP. It returns \f(CWDW_DLV_ERROR\fP on error. On a successful return from this function, the string should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_global_die_offset()" .DS \f(CWint dwarf_global_die_offset( Dwarf_Global global, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_global_die_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the DIE representing the pubname that is described by the \f(CWDwarf_Global\fP descriptor, \f(CWglob\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_global_cu_offset()" .DS \f(CWint dwarf_global_cu_offset( Dwarf_Global global, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_global_cu_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the compilation-unit header of the compilation-unit that contains the pubname described by the \f(CWDwarf_Global\fP descriptor, \f(CWglobal\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_get_cu_die_offset_given_cu_header_offset()" .DS \f(CWint dwarf_get_cu_die_offset_given_cu_header_offset( Dwarf_Debug dbg, Dwarf_Off in_cu_header_offset, Dwarf_Off * out_cu_die_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_cu_die_offset_given_cu_header_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*out_cu_die_offset\fP to the offset of the compilation-unit DIE given the offset \f(CWin_cu_header_offset\fP of a compilation-unit header. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. This effectively turns a compilation-unit-header offset into a compilation-unit DIE offset (by adding the size of the applicable CU header). This function is also sometimes useful with the \f(CWdwarf_weak_cu_offset()\fP, \f(CWdwarf_func_cu_offset()\fP, \f(CWdwarf_type_cu_offset()\fP, and \f(CWint dwarf_var_cu_offset()\fP functions. \f(CWdwarf_get_cu_die_offset_given_cu_header_offset()\fP added Rev 1.45, June, 2001. This function is declared as 'optional' in libdwarf.h on IRIX systems so the _MIPS_SYMBOL_PRESENT predicate may be used at run time to determine if the version of libdwarf linked into an application has this function. .H 4 "dwarf_global_name_offsets()" .DS \f(CWint dwarf_global_name_offsets( Dwarf_Global global, char **return_name, Dwarf_Off *die_offset, Dwarf_Off *cu_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_global_name_offsets()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string that gives the name of the pubname described by the \f(CWDwarf_Global\fP descriptor \f(CWglobal\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. It also returns in the locations pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets of the DIE representing the pubname, and the DIE representing the compilation-unit containing the pubname, respectively. On a successful return from \f(CWdwarf_global_name_offsets()\fP the storage pointed to by \f(CWreturn_name\fP should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 2 "DWARF3 Type Names Operations" Section ".debug_pubtypes" is new in DWARF3. .P These functions operate on the .debug_pubtypes section of the debugging information. The .debug_pubtypes section contains the names of file-scope user-defined types, the offsets of the \f(CWDIE\fPs that represent the definitions of those types, and the offsets of the compilation-units that contain the definitions of those types. .H 3 "Debugger Interface Operations" .H 4 "dwarf_get_pubtypes()" .DS \f(CWint dwarf_get_pubtypes( Dwarf_Debug dbg, Dwarf_Type **types, Dwarf_Signed *typecount, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_pubtypes()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*typecount\fP to the count of user-defined type names represented in the section containing user-defined type names, i.e. .debug_pubtypes. It also stores at \f(CW*types\fP, a pointer to a list of \f(CWDwarf_Pubtype\fP descriptors, one for each of the user-defined type names in the .debug_pubtypes section. It returns \f(CWDW_DLV_NOCOUNT\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_pubtypes section does not exist. .P On a successful return from \f(CWdwarf_get_pubtypes()\fP, the \f(CWDwarf_Type\fP descriptors should be free'd using \f(CWdwarf_types_dealloc()\fP. \f(CWdwarf_types_dealloc()\fP is used for both \f(CWdwarf_get_pubtypes()\fP and \f(CWdwarf_get_types()\fP as the data types are the same. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Pubtype *types; int res; res = dwarf_get_pubtypes(dbg, &types,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use types[i] */ } dwarf_types_dealloc(dbg, types, cnt); }\fP .DE .in -2 .H 4 "dwarf_pubtypename()" .DS \f(CWint dwarf_pubtypename( Dwarf_Pubtype type, char **return_name, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_pubtypename()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string that names the user-defined type represented by the \f(CWDwarf_Pubtype\fP descriptor, \f(CWtype\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from this function, the string should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 4 "dwarf_pubtype_die_offset()" .DS \f(CWint dwarf_pubtype_die_offset( Dwarf_Pubtype type, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_pubtype_die_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the DIE representing the user-defined type that is described by the \f(CWDwarf_Pubtype\fP descriptor, \f(CWtype\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_pubtype_cu_offset()" .DS \f(CWint dwarf_pubtype_cu_offset( Dwarf_Pubtype type, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_pubtype_cu_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the compilation-unit header of the compilation-unit that contains the user-defined type described by the \f(CWDwarf_Pubtype\fP descriptor, \f(CWtype\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_pubtype_name_offsets()" .DS \f(CWint dwarf_pubtype_name_offsets( Dwarf_Pubtype type, char ** returned_name, Dwarf_Off * die_offset, Dwarf_Off * cu_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_pubtype_name_offsets()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to a pointer to a null-terminated string that gives the name of the user-defined type described by the \f(CWDwarf_Pubtype\fP descriptor \f(CWtype\fP. It also returns in the locations pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets of the DIE representing the user-defined type, and the DIE representing the compilation-unit containing the user-defined type, respectively. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from \f(CWdwarf_pubtype_name_offsets()\fP the storage pointed to by \f(CWreturned_name\fP should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 2 "User Defined Static Variable Names Operations" This section is SGI specific and is not part of standard DWARF version 2. .P These functions operate on the .debug_varnames section of the debugging information. The .debug_varnames section contains the names of file-scope static variables, the offsets of the \f(CWDIE\fPs that represent the definitions of those variables, and the offsets of the compilation-units that contain the definitions of those variables. .P .H 2 "Weak Name Space Operations" These operations operate on the .debug_weaknames section of the debugging information. .P These operations are SGI specific, not part of standard DWARF. .P .H 3 "Debugger Interface Operations" .H 4 "dwarf_get_weaks()" .DS \f(CWint dwarf_get_weaks( Dwarf_Debug dbg, Dwarf_Weak **weaks, Dwarf_Signed *weak_count, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_weaks()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*weak_count\fP to the count of weak names represented in the section containing weak names i.e. .debug_weaknames. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if the section does not exist. It also stores in \f(CW*weaks\fP, a pointer to a list of \f(CWDwarf_Weak\fP descriptors, one for each of the weak names in the .debug_weaknames section. .P On a successful return from this function, the \f(CWDwarf_Weak\fP descriptors should be free'd using \f(CWdwarf_weaks_dealloc()\fP when the data is no longer of interest. \f(CWdwarf_weaks_dealloc()\fPis new as of July 15, 2005. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Weak *weaks; int res; res = dwarf_get_weaks(dbg, &weaks,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use weaks[i] */ } dwarf_weaks_dealloc(dbg, weaks, cnt); }\fP .DE .in -2 .P The following code is deprecated as of July 15, 2005 as it does not free all relevant memory. This approach still works as well as it ever did. On a successful return from \f(CWdwarf_get_weaks()\fP the \f(CWDwarf_Weak\fP descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_WEAK_CONTEXT\fP, (or \f(CWDW_DLA_WEAK\fP, an older name, supported for compatibility) followed by the deallocation of the list itself with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no longer of interest. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Weak *weaks; int res; res = dwarf_get_weaks(dbg, &weaks,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use weaks[i] */ dwarf_dealloc(dbg, weaks[i], DW_DLA_WEAK_CONTEXT); } dwarf_dealloc(dbg, weaks, DW_DLA_LIST); }\fP .DE .in -2 .H 4 "dwarf_weakname()" .DS \f(CWint dwarf_weakname( Dwarf_Weak weak, char ** return_name, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_weakname()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string that names the weak name represented by the \f(CWDwarf_Weak\fP descriptor, \f(CWweak\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from this function, the string should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .DS \f(CWint dwarf_weak_die_offset( Dwarf_Weak weak, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_weak_die_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the DIE representing the weak name that is described by the \f(CWDwarf_Weak\fP descriptor, \f(CWweak\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_weak_cu_offset()" .DS \f(CWint dwarf_weak_cu_offset( Dwarf_Weak weak, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_weak_cu_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the compilation-unit header of the compilation-unit that contains the weak name described by the \f(CWDwarf_Weak\fP descriptor, \f(CWweak\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_weak_name_offsets()" .DS \f(CWint dwarf_weak_name_offsets( Dwarf_Weak weak, char ** weak_name, Dwarf_Off *die_offset, Dwarf_Off *cu_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_weak_name_offsets()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*weak_name\fP to a pointer to a null-terminated string that gives the name of the weak name described by the \f(CWDwarf_Weak\fP descriptor \f(CWweak\fP. It also returns in the locations pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets of the DIE representing the weakname, and the DIE representing the compilation-unit containing the weakname, respectively. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from \f(CWdwarf_weak_name_offsets()\fP the storage pointed to by \f(CWweak_name\fP should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 2 "Static Function Names Operations" This section is SGI specific and is not part of standard DWARF version 2. .P These function operate on the .debug_funcnames section of the debugging information. The .debug_funcnames section contains the names of static functions defined in the object, the offsets of the \f(CWDIE\fPs that represent the definitions of the corresponding functions, and the offsets of the start of the compilation-units that contain the definitions of those functions. .H 3 "Debugger Interface Operations" .H 4 "dwarf_get_funcs()" .DS \f(CWint dwarf_get_funcs( Dwarf_Debug dbg, Dwarf_Func **funcs, Dwarf_Signed *func_count, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_funcs()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*func_count\fP to the count of static function names represented in the section containing static function names, i.e. .debug_funcnames. It also stores, at \f(CW*funcs\fP, a pointer to a list of \f(CWDwarf_Func\fP descriptors, one for each of the static functions in the .debug_funcnames section. It returns \f(CWDW_DLV_NOCOUNT\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_funcnames section does not exist. .P On a successful return from \f(CWdwarf_get_funcs()\fP, the \f(CWDwarf_Func\fP descriptors should be free'd using \f(CWdwarf_funcs_dealloc()\fP. \f(CWdwarf_funcs_dealloc()\fP is new as of July 15, 2005. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Func *funcs; int fres; fres = dwarf_get_funcs(dbg, &funcs, &error); if (fres == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use funcs[i] */ } dwarf_funcs_dealloc(dbg, funcs, cnt); }\fP .DE .in -2 .P The following code is deprecated as of July 15, 2005 as it does not free all relevant memory. This approach still works as well as it ever did. On a successful return from \f(CWdwarf_get_funcs()\fP, the \f(CWDwarf_Func\fP descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_FUNC_CONTEXT\fP, (or \f(CWDW_DLA_FUNC\fP, an older name, supported for compatibility) followed by the deallocation of the list itself with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no longer of interest. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Func *funcs; int fres; fres = dwarf_get_funcs(dbg, &funcs, &error); if (fres == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use funcs[i] */ dwarf_dealloc(dbg, funcs[i], DW_DLA_FUNC_CONTEXT); } dwarf_dealloc(dbg, funcs, DW_DLA_LIST); }\fP .DE .in -2 .H 4 "dwarf_funcname()" .DS \f(CWint dwarf_funcname( Dwarf_Func func, char ** return_name, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_funcname()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string that names the static function represented by the \f(CWDwarf_Func\fP descriptor, \f(CWfunc\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from this function, the string should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 4 "dwarf_func_die_offset()" .DS \f(CWint dwarf_func_die_offset( Dwarf_Func func, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_func_die_offset()\fP, returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the DIE representing the static function that is described by the \f(CWDwarf_Func\fP descriptor, \f(CWfunc\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_func_cu_offset()" .DS \f(CWint dwarf_func_cu_offset( Dwarf_Func func, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_func_cu_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the compilation-unit header of the compilation-unit that contains the static function described by the \f(CWDwarf_Func\fP descriptor, \f(CWfunc\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_func_name_offsets()" .DS \f(CWint dwarf_func_name_offsets( Dwarf_Func func, char **func_name, Dwarf_Off *die_offset, Dwarf_Off *cu_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_func_name_offsets()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*func_name\fP to a pointer to a null-terminated string that gives the name of the static function described by the \f(CWDwarf_Func\fP descriptor \f(CWfunc\fP. It also returns in the locations pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets of the DIE representing the static function, and the DIE representing the compilation-unit containing the static function, respectively. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from \f(CWdwarf_func_name_offsets()\fP the storage pointed to by \f(CWfunc_name\fP should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 2 "User Defined Type Names Operations" Section "debug_typenames" is SGI specific and is not part of standard DWARF version 2. (However, an identical section is part of DWARF version 3 named ".debug_pubtypes", see \f(CWdwarf_get_pubtypes()\fP above.) .P These functions operate on the .debug_typenames section of the debugging information. The .debug_typenames section contains the names of file-scope user-defined types, the offsets of the \f(CWDIE\fPs that represent the definitions of those types, and the offsets of the compilation-units that contain the definitions of those types. .H 3 "Debugger Interface Operations" .H 4 "dwarf_get_types()" .DS \f(CWint dwarf_get_types( Dwarf_Debug dbg, Dwarf_Type **types, Dwarf_Signed *typecount, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_types()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*typecount\fP to the count of user-defined type names represented in the section containing user-defined type names, i.e. .debug_typenames. It also stores at \f(CW*types\fP, a pointer to a list of \f(CWDwarf_Type\fP descriptors, one for each of the user-defined type names in the .debug_typenames section. It returns \f(CWDW_DLV_NOCOUNT\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_typenames section does not exist. .P On a successful return from \f(CWdwarf_get_types()\fP, the \f(CWDwarf_Type\fP descriptors should be free'd using \f(CWdwarf_types_dealloc()\fP. \f(CWdwarf_types_dealloc()\fP is new as of July 15, 2005 and frees all memory allocated by \f(CWdwarf_get_types()\fP. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Type *types; int res; res = dwarf_get_types(dbg, &types,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use types[i] */ } dwarf_types_dealloc(dbg, types, cnt); }\fP .DE .in -2 .P The following code is deprecated as of July 15, 2005 as it does not free all relevant memory. This approach still works as well as it ever did. On a successful return from \f(CWdwarf_get_types()\fP, the \f(CWDwarf_Type\fP descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_TYPENAME_CONTEXT\fP, (or \f(CWDW_DLA_TYPENAME\fP, an older name, supported for compatibility) followed by the deallocation of the list itself with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no longer of interest. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Type *types; int res; res = dwarf_get_types(dbg, &types,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use types[i] */ dwarf_dealloc(dbg, types[i], DW_DLA_TYPENAME_CONTEXT); } dwarf_dealloc(dbg, types, DW_DLA_LIST); }\fP .DE .in -2 .H 4 "dwarf_typename()" .DS \f(CWint dwarf_typename( Dwarf_Type type, char **return_name, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_typename()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_name\fP to a pointer to a null-terminated string that names the user-defined type represented by the \f(CWDwarf_Type\fP descriptor, \f(CWtype\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from this function, the string should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 4 "dwarf_type_die_offset()" .DS \f(CWint dwarf_type_die_offset( Dwarf_Type type, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_type_die_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the DIE representing the user-defined type that is described by the \f(CWDwarf_Type\fP descriptor, \f(CWtype\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_type_cu_offset()" .DS \f(CWint dwarf_type_cu_offset( Dwarf_Type type, Dwarf_Off *return_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_type_cu_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the compilation-unit header of the compilation-unit that contains the user-defined type described by the \f(CWDwarf_Type\fP descriptor, \f(CWtype\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_type_name_offsets()" .DS \f(CWint dwarf_type_name_offsets( Dwarf_Type type, char ** returned_name, Dwarf_Off * die_offset, Dwarf_Off * cu_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_type_name_offsets()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to a pointer to a null-terminated string that gives the name of the user-defined type described by the \f(CWDwarf_Type\fP descriptor \f(CWtype\fP. It also returns in the locations pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets of the DIE representing the user-defined type, and the DIE representing the compilation-unit containing the user-defined type, respectively. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from \f(CWdwarf_type_name_offsets()\fP the storage pointed to by \f(CWreturned_name\fP should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 2 "User Defined Static Variable Names Operations" This section is SGI specific and is not part of standard DWARF version 2. .P These functions operate on the .debug_varnames section of the debugging information. The .debug_varnames section contains the names of file-scope static variables, the offsets of the \f(CWDIE\fPs that represent the definitions of those variables, and the offsets of the compilation-units that contain the definitions of those variables. .P .H 3 "Debugger Interface Operations" .H 4 "dwarf_get_vars()" .DS \f(CWint dwarf_get_vars( Dwarf_Debug dbg, Dwarf_Var **vars, Dwarf_Signed *var_count, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_vars()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*var_count\fP to the count of file-scope static variable names represented in the section containing file-scope static variable names, i.e. .debug_varnames. It also stores, at \f(CW*vars\fP, a pointer to a list of \f(CWDwarf_Var\fP descriptors, one for each of the file-scope static variable names in the .debug_varnames section. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if the .debug_varnames section does not exist. .P The following is new as of July 15, 2005. On a successful return from \f(CWdwarf_get_vars()\fP, the \f(CWDwarf_Var\fP descriptors should be free'd using \f(CWdwarf_vars_dealloc()\fP. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Var *vars; int res; res = dwarf_get_vars(dbg, &vars,&cnt &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use vars[i] */ } dwarf_vars_dealloc(dbg, vars, cnt); }\fP .DE .in -2 .P The following code is deprecated as of July 15, 2005 as it does not free all relevant memory. This approach still works as well as it ever did. On a successful return from \f(CWdwarf_get_vars()\fP, the \f(CWDwarf_Var\fP descriptors should be individually free'd using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_VAR_CONTEXT\fP, (or \f(CWDW_DLA_VAR\fP, an older name, supported for compatibility) followed by the deallocation of the list itself with the allocation type \f(CWDW_DLA_LIST\fP when the descriptors are no longer of interest. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Var *vars; int res; res = dwarf_get_vars(dbg, &vars,&cnt &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use vars[i] */ dwarf_dealloc(dbg, vars[i], DW_DLA_VAR_CONTEXT); } dwarf_dealloc(dbg, vars, DW_DLA_LIST); }\fP .DE .in -2 .H 4 "dwarf_varname()" .DS \f(CWint dwarf_varname( Dwarf_Var var, char ** returned_name, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_varname()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to a pointer to a null-terminated string that names the file-scope static variable represented by the \f(CWDwarf_Var\fP descriptor, \f(CWvar\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from this function, the string should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 4 "dwarf_var_die_offset()" .DS \f(CWint dwarf_var_die_offset( Dwarf_Var var, Dwarf_Off *returned_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_var_die_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the DIE representing the file-scope static variable that is described by the \f(CWDwarf_Var\fP descriptor, \f(CWvar\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_var_cu_offset()" .DS \f(CWint dwarf_var_cu_offset( Dwarf_Var var, Dwarf_Off *returned_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_var_cu_offset()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_offset\fP to the offset in the section containing DIE's, i.e. .debug_info, of the compilation-unit header of the compilation-unit that contains the file-scope static variable described by the \f(CWDwarf_Var\fP descriptor, \f(CWvar\fP. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 4 "dwarf_var_name_offsets()" .DS \f(CWint dwarf_var_name_offsets( Dwarf_Var var, char **returned_name, Dwarf_Off *die_offset, Dwarf_Off *cu_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_var_name_offsets()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_name\fP to a pointer to a null-terminated string that gives the name of the file-scope static variable described by the \f(CWDwarf_Var\fP descriptor \f(CWvar\fP. It also returns in the locations pointed to by \f(CWdie_offset\fP, and \f(CWcu_offset\fP, the offsets of the DIE representing the file-scope static variable, and the DIE representing the compilation-unit containing the file-scope static variable, respectively. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. On a successful return from \f(CWdwarf_var_name_offsets()\fP the storage pointed to by \f(CWreturned_name\fP should be free'd using \f(CWdwarf_dealloc()\fP, with the allocation type \f(CWDW_DLA_STRING\fP when no longer of interest. .H 2 "Macro Information Operations" .H 3 "General Macro Operations" .H 4 "dwarf_find_macro_value_start()" .DS \f(CWchar *dwarf_find_macro_value_start(char * macro_string);\fP .DE Given a macro string in the standard form defined in the DWARF document ("name value" or "name(args)value") this returns a pointer to the first byte of the macro value. It does not alter the string pointed to by macro_string or copy the string: it returns a pointer into the string whose address was passed in. .H 3 "Debugger Interface Macro Operations" Macro information is accessed from the .debug_info section via the DW_AT_macro_info attribute (whose value is an offset into .debug_macinfo). .P No Functions yet defined. .H 3 "Low Level Macro Information Operations" .H 4 "dwarf_get_macro_details()" .DS \f(CWint dwarf_get_macro_details(Dwarf_Debug /*dbg*/, Dwarf_Off macro_offset, Dwarf_Unsigned maximum_count, Dwarf_Signed * entry_count, Dwarf_Macro_Details ** details, Dwarf_Error * err);\fP .DE \f(CWdwarf_get_macro_details()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CWentry_count\fP to the number of \f(CWdetails\fP records returned through the \f(CWdetails\fP pointer. The data returned thru \f(CWdetails\fP should be freed by a call to \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_STRING\fP. If \f(CWDW_DLV_OK\fP is returned, the \f(CWentry_count\fP will be at least 1, since a compilation unit with macro information but no macros will have at least one macro data byte of 0. .P \f(CWdwarf_get_macro_details()\fP begins at the \f(CWmacro_offset\fP offset you supply and ends at the end of a compilation unit or at \f(CWmaximum_count\fP detail records (whichever comes first). If \f(CWmaximum_count\fP is 0, it is treated as if it were the maximum possible unsigned integer. .P \f(CWdwarf_get_macro_details()\fP attempts to set \f(CWdmd_fileindex\fP to the correct file in every \f(CWdetails\fP record. If it is unable to do so (or whenever the current file index is unknown, it sets \f(CWdmd_fileindex\fP to -1. .P \f(CWdwarf_get_macro_details()\fP returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no more macro information at that \f(CWmacro_offset\fP. If \f(CWmacro_offset\fP is passed in as 0, a \f(CWDW_DLV_NO_ENTRY\fP return means there is no macro information. .P .in +2 .DS \f(CWDwarf_Unsigned max = 0; Dwarf_Off cur_off = 0; Dwarf_Signed count = 0; Dwarf_Macro_Details *maclist; int errv; /* loop thru all the compilation units macro info */ while((errv = dwarf_macro_details(dbg, cur_off,max, &count,&maclist,&error))== DW_DLV_OK) { for (i = 0; i < count; ++i) { /* use maclist[i] */ } cur_off = maclist[count-1].dmd_offset + 1; dwarf_dealloc(dbg, maclist, DW_DLA_STRING); }\fP .DE .H 2 "Low Level Frame Operations" These functions provide information about stack frames to be used to perform stack traces. The information is an abstraction of a table with a row per instruction and a column per register and a column for the canonical frame address (CFA, which corresponds to the notion of a frame pointer), as well as a column for the return address. .P From 1993-2006 the interface we'll here refer to as DWARF2 made the CFA be a column in the matrix, but left DW_FRAME_UNDEFINED_VAL, and DW_FRAME_SAME_VAL out of the matrix (giving them high numbers). As of the DWARF3 interfaces introduced in this document in April 2006, there are *two* interfaces. .P The original still exists (see. dwarf_get_fde_info_for_reg() and dwarf_get_fde_info_for_all_regs() below) and works adequately for MIPS/IRIX DWARF2 and ABI/ISA sets that are sufficiently similar (but the settings for non-MIPS must be set into libdwarf.h and cannot be changed at runtime). .P A new interface set of dwarf_get_fde_info_for_reg3(), dwarf_get_fde_info_for_cfa_reg3(), dwarf_get_fde_info_for_all_regs3() dwarf_set_frame_rule_inital_value(), dwarf_set_frame_rule_table_size() is more flexible and should work for many more architectures and the setting of DW_FRAME_CFA_COL and the size of the table can be set at runtime. .P Each cell in the table contains one of the following: .AL .LI A register + offset(a)(b) .LI A register(c)(d) .LI A marker (DW_FRAME_UNDEFINED_VAL) meaning \fIregister value undefined\fP .LI A marker (DW_FRAME_SAME_VAL) meaning \fIregister value same as in caller\fP .LE .P (a old DWARF2 interface) When the column is DW_FRAME_CFA_COL: the register number is a real hardware register, not a reference to DW_FRAME_CFA_COL, not DW_FRAME_UNDEFINED_VAL, and not DW_FRAME_SAME_VAL. The CFA rule value should be the stack pointer plus offset 0 when no other value makes sense. A value of DW_FRAME_SAME_VAL would be semi-logical, but since the CFA is not a real register, not really correct. A value of DW_FRAME_UNDEFINED_VAL would imply the CFA is undefined -- this seems to be a useless notion, as the CFA is a means to finding real registers, so those real registers should be marked DW_FRAME_UNDEFINED_VAL, and the CFA column content (whatever register it specifies) becomes unreferenced by anything. .P (a new April 2006 DWARF2/3 interface): The CFA is separately accessible and not part of the table. The 'rule number' for the CFA is a number outside the table. So the CFA is a marker, not a register number. See DW_FRAME_CFA_COL3 in libdwarf.h and dwarf_get_fde_info_for_cfa_reg3(). .P (b) When the column is not DW_FRAME_CFA_COL, the 'register' will and must be DW_FRAME_CFA_COL, implying that to get the final location for the column one must add the offset here plus the DW_FRAME_CFA_COL rule value. .P (c) When the column is DW_FRAME_CFA_COL, then the register number is (must be) a real hardware register . If it were DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL it would be a marker, not a register number. .P (d) When the column is not DW_FRAME_CFA_COL, the register may be a hardware register. It will not be DW_FRAME_CFA_COL. .P There is no 'column' for DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL. Figure \n(aX is machine dependent and represents MIPS cpu register assignments. .DS .TS center box, tab(:); lfB lfB lfB l c l. NAME:value:PURPOSE _ DW_FRAME_CFA_COL:0:column used for CFA DW_FRAME_REG1:1:integer regster 1 DW_FRAME_REG2:2:integer register 2 ---::obvious names and values here DW_FRAME_REG30:30:integer register 30 DW_FRAME_REG31:31:integer register 31 DW_FRAME_FREG0:32:floating point register 0 DW_FRAME_FREG1:33:floating point register 1 ---::obvious names and values here DW_FRAME_FREG30:62:floating point register 30 DW_FRAME_FREG31:63:floating point register 31 DW_FRAME_RA_COL:64:column recording ra DW_FRAME_UNDEFINED_VAL:1034:register val undefined DW_FRAME_SAME_VAL:1035:register same as in caller .TE .FG "Frame Information Rule Assignments" .DE .P The following table shows SGI/MIPS specific special cell values: these values mean that the cell has the value \fIundefined\fP or \fIsame value\fP respectively, rather than containing a \fIregister\fP or \fIregister+offset\fP. It assumes DW_FRAME_CFA_COL is a table rule, which is not readily accomplished or sensible for some architectures. .P .DS .TS center box, tab(:); lfB lfB lfB l c l. NAME:value:PURPOSE _ DW_FRAME_UNDEFINED_VAL:1034:means undefined value. ::Not a column or register value DW_FRAME_SAME_VAL:1035:means 'same value' as ::caller had. Not a column or ::register value .TE .FG "Frame Information Special Values" .DE .P The following table shows more general special cell values. These values mean that the cell register-number refers to the \fIcfa-register\fP or \fIundefined-value\fP or \fIsame-value\fP respectively, rather than referring to a \fIregister in the table\fP. The generality arises from making DW_FRAME_CFA_COL3 be outside the set of registers and making the cfa rule accessible from outside the rule-table. .P .DS .TS center box, tab(:); lfB lfB lfB l c l. NAME:value:PURPOSE _ DW_FRAME_UNDEFINED_VAL:1034:means undefined value. ::Not a column or register value DW_FRAME_SAME_VAL:1035:means 'same value' as ::caller had. Not a column or ::register value DW_FRAME_CFA_COL3:1036:means 'cfa register'is referred to, ::not a real register, not a column, but the cfa (the cfa ::does have a value, but in the DWARF3 libdwarf interface ::it does not have a 'real register number'). .TE .DE .\"#if 0 .\".P .\"Since the cie and fde entries are not "organized" by anything .\"outside of the .debug_frame section one must scan them all to .\"find all entry addresses and lengths. Since there is one fde .\"per function this can be a rather long list. .\"#endif .P .H 4 "dwarf_get_fde_list()" .DS \f(CWint dwarf_get_fde_list( Dwarf_Debug dbg, Dwarf_Cie **cie_data, Dwarf_Signed *cie_element_count, Dwarf_Fde **fde_data, Dwarf_Signed *fde_element_count, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_fde_list()\fP stores a pointer to a list of \f(CWDwarf_Cie\fP descriptors in \f(CW*cie_data\fP, and the count of the number of descriptors in \f(CW*cie_element_count\fP. There is a descriptor for each CIE in the .debug_frame section. Similarly, it stores a pointer to a list of \f(CWDwarf_Fde\fP descriptors in \f(CW*fde_data\fP, and the count of the number of descriptors in \f(CW*fde_element_count\fP. There is one descriptor per FDE in the .debug_frame section. \f(CWdwarf_get_fde_list()\fP returns \f(CWDW_DLV_EROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if it cannot find frame entries. It returns \f(CWDW_DLV_OK\fP on a successful return. .P On successful return, structures pointed to by a descriptor should be free'd using \f(CWdwarf_fde_cie_list_dealloc()\fP. This dealloc approach is new as of July 15, 2005. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Cie *cie_data; Dwarf_Signed cie_count; Dwarf_Fde *fde_data; Dwarf_Signed fde_count; int fres; fres = dwarf_get_fde_list(dbg,&cie_data,&cie_count, &fde_data,&fde_count,&error); if (fres == DW_DLV_OK) { dwarf_fde_cie_list_dealloc(dbg, cie_data, cie_count, fde_data,fde_count); }\fP .DE .in -2 .P The following code is deprecated as of July 15, 2005 as it does not free all relevant memory. This approach still works as well as it ever did. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Cie *cie_data; Dwarf_Signed cie_count; Dwarf_Fde *fde_data; Dwarf_Signed fde_count; int fres; fres = dwarf_get_fde_list(dbg,&cie_data,&cie_count, &fde_data,&fde_count,&error); if (fres == DW_DLV_OK) { for (i = 0; i < cie_count; ++i) { /* use cie[i] */ dwarf_dealloc(dbg, cie_data[i], DW_DLA_CIE); } for (i = 0; i < fde_count; ++i) { /* use fde[i] */ dwarf_dealloc(dbg, fde_data[i], DW_DLA_FDE); } dwarf_dealloc(dbg, cie_data, DW_DLA_LIST); dwarf_dealloc(dbg, fde_data, DW_DLA_LIST); }\fP .DE .in -2 .P .H 4 "dwarf_get_fde_list_eh()" .DS \f(CWint dwarf_get_fde_list_eh( Dwarf_Debug dbg, Dwarf_Cie **cie_data, Dwarf_Signed *cie_element_count, Dwarf_Fde **fde_data, Dwarf_Signed *fde_element_count, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_fde_list_eh()\fP is identical to \f(CWdwarf_get_fde_list()\fP except that \f(CWdwarf_get_fde_list_eh()\fP reads the GNU ecgs section named .eh_frame (C++ exception handling information). \f(CWdwarf_get_fde_list_eh()\fP stores a pointer to a list of \f(CWDwarf_Cie\fP descriptors in \f(CW*cie_data\fP, and the count of the number of descriptors in \f(CW*cie_element_count\fP. There is a descriptor for each CIE in the .debug_frame section. Similarly, it stores a pointer to a list of \f(CWDwarf_Fde\fP descriptors in \f(CW*fde_data\fP, and the count of the number of descriptors in \f(CW*fde_element_count\fP. There is one descriptor per FDE in the .debug_frame section. \f(CWdwarf_get_fde_list()\fP returns \f(CWDW_DLV_EROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if it cannot find exception handling entries. It returns \f(CWDW_DLV_OK\fP on a successful return. .P On successful return, structures pointed to by a descriptor should be free'd using \f(CWdwarf_fde_cie_list_dealloc()\fP. This dealloc approach is new as of July 15, 2005. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Cie *cie_data; Dwarf_Signed cie_count; Dwarf_Fde *fde_data; Dwarf_Signed fde_count; int fres; fres = dwarf_get_fde_list(dbg,&cie_data,&cie_count, &fde_data,&fde_count,&error); if (fres == DW_DLV_OK) { dwarf_fde_cie_list_dealloc(dbg, cie_data, cie_count, fde_data,fde_count); }\fP .DE .in -2 .P .H 4 "dwarf_get_cie_of_fde()" .DS \f(CWint dwarf_get_cie_of_fde(Dwarf_Fde fde, Dwarf_Cie *cie_returned, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_cie_of_fde()\fP stores a \f(CWDwarf_Cie\fP into the \f(CWDwarf_Cie\fP that \f(CWcie_returned\fP points at. If one has called dwarf_get_fde_list and does not wish to dwarf_dealloc() all the individual FDEs immediately, one must also avoid dwarf_dealloc-ing the CIEs for those FDEs not immediately dealloc'd. Failing to observe this restriction will cause the FDE(s) not dealloced to become invalid: an FDE contains (hidden in it) a CIE pointer which will be be invalid (stale, pointing to freed memory) if the CIE is dealloc'd. The invalid CIE pointer internal to the FDE cannot be detected as invalid by libdwarf. If one later passes an FDE with a stale internal CIE pointer to one of the routines taking an FDE as input the result will be failure of the call (returning DW_DLV_ERROR) at best and it is possible a coredump or worse will happpen (eventually). \f(CWdwarf_get_cie_of_fde()\fP returns \f(CWDW_DLV_OK\fP if it is successful (it will be unless fde is the NULL pointer). It returns \f(CWDW_DLV_ERROR\fP if the fde is invalid (NULL). .P Each \f(CWDwarf_Fde\fP descriptor describes information about the frame for a particular subroutine or function. \f(CWint dwarf_get_fde_for_die\fP is SGI/MIPS specific. .H 4 "dwarf_get_fde_for_die()" .DS \f(CWint dwarf_get_fde_for_die( Dwarf_Debug dbg, Dwarf_Die die, Dwarf_Fde * return_fde, Dwarf_Error *error)\fP .DE When it succeeds, \f(CWdwarf_get_fde_for_die()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_fde\fP to a \f(CWDwarf_Fde\fP descriptor representing frame information for the given \f(CWdie\fP. It looks for the \f(CWDW_AT_MIPS_fde\fP attribute in the given \f(CWdie\fP. If it finds it, is uses the value of the attribute as the offset in the .debug_frame section where the FDE begins. If there is no \f(CWDW_AT_MIPS_fde\fP it returns \f(CWDW_DLV_NO_ENTRY\fP. If there is an error it returns \f(CWDW_DLV_ERROR\fP. .H 4 "dwarf_get_fde_range()" .DS \f(CWint dwarf_get_fde_range( Dwarf_Fde fde, Dwarf_Addr *low_pc, Dwarf_Unsigned *func_length, Dwarf_Ptr *fde_bytes, Dwarf_Unsigned *fde_byte_length, Dwarf_Off *cie_offset, Dwarf_Signed *cie_index, Dwarf_Off *fde_offset, Dwarf_Error *error);\fP .DE On success, \f(CWdwarf_get_fde_range()\fP returns \f(CWDW_DLV_OK\fP. The location pointed to by \f(CWlow_pc\fP is set to the low pc value for this function. The location pointed to by \f(CWfunc_length\fP is set to the length of the function in bytes. This is essentially the length of the text section for the function. The location pointed to by \f(CWfde_bytes\fP is set to the address where the FDE begins in the .debug_frame section. The location pointed to by \f(CWfde_byte_length\fP is set to the length in bytes of the portion of .debug_frame for this FDE. This is the same as the value returned by \f(CWdwarf_get_fde_range\fP. The location pointed to by \f(CWcie_offset\fP is set to the offset in the .debug_frame section of the CIE used by this FDE. The location pointed to by \f(CWcie_index\fP is set to the index of the CIE used by this FDE. The index is the index of the CIE in the list pointed to by \f(CWcie_data\fP as set by the function \f(CWdwarf_get_fde_list()\fP. However, if the function \f(CWdwarf_get_fde_for_die()\fP was used to obtain the given \f(CWfde\fP, this index may not be correct. The location pointed to by \f(CWfde_offset\fP is set to the offset of the start of this FDE in the .debug_frame section. \f(CWdwarf_get_fde_range()\fP returns \f(CWDW_DLV_ERROR\fP on error. .H 4 "dwarf_get_cie_info()" .DS \f(CWint dwarf_get_cie_info( Dwarf_Cie cie, Dwarf_Unsigned *bytes_in_cie, Dwarf_Small *version, char **augmenter, Dwarf_Unsigned *code_alignment_factor, Dwarf_Signed *data_alignment_factor, Dwarf_Half *return_address_register_rule, Dwarf_Ptr *initial_instructions, Dwarf_Unsigned *initial_instructions_length, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_cie_info()\fP is primarily for Internal-level Interface consumers. If successful, it returns \f(CWDW_DLV_OK\fP and sets \f(CW*bytes_in_cie\fP to the number of bytes in the portion of the frames section for the CIE represented by the given \f(CWDwarf_Cie\fP descriptor, \f(CWcie\fP. The other fields are directly taken from the cie and returned, via the pointers to the caller. It returns \f(CWDW_DLV_ERROR\fP on error. .H 4 "dwarf_get_fde_instr_bytes()" .DS \f(CWint dwarf_get_fde_instr_bytes( Dwarf_Fde fde, Dwarf_Ptr *outinstrs, Dwarf_Unsigned *outlen, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_fde_instr_bytes()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*outinstrs\fP to a pointer to a set of bytes which are the actual frame instructions for this fde. It also sets \f(CW*outlen\fP to the length, in bytes, of the frame instructions. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. The intent is to allow low-level consumers like a dwarf-dumper to print the bytes in some fashion. The memory pointed to by \f(CWoutinstrs\fP must not be changed and there is nothing to free. .H 4 "dwarf_get_fde_info_for_reg()" This interface is suitable for DWARF2 but is not sufficient for DWARF3. See \f(CWint dwarf_get_fde_info_for_reg3\fP. .DS \f(CWint dwarf_get_fde_info_for_reg( Dwarf_Fde fde, Dwarf_Half table_column, Dwarf_Addr pc_requested, Dwarf_Signed *offset_relevant, Dwarf_Signed *register_num, Dwarf_Signed *offset, Dwarf_Addr *row_pc, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_fde_info_for_reg()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*offset_relevant\fP to non-zero if the offset is relevant for the row specified by \f(CWpc_requested\fP and column specified by \f(CWtable_column\fP, for the FDE specified by \f(CWfde\fP. The intent is to return the rule for the given pc value and register. The location pointed to by \f(CWregister_num\fP is set to the register value for the rule. The location pointed to by \f(CWoffset\fP is set to the offset value for the rule. If offset is not relevant for this rule, \f(CW*offset_relevant\fP is set to zero. Since more than one pc value will have rows with identical entries, the user may want to know the earliest pc value after which the rules for all the columns remained unchanged. Recall that in the virtual table that the frame information represents there may be one or more table rows with identical data (each such table row at a different pc value). Given a \f(CWpc_requested\fP which refers to a pc in such a group of identical rows, the location pointed to by \f(CWrow_pc\fP is set to the lowest pc value within the group of identical rows. The value put in \f(CW*register_num\fP any of the \f(CWDW_FRAME_*\fP table columns values specified in \f(CWlibdwarf.h\fP or \f(CWdwarf.h\fP. \f(CWdwarf_get_fde_info_for_reg\fP returns \f(CWDW_DLV_ERROR\fP if there is an error. It is usable with either \f(CWdwarf_get_fde_n()\fP or \f(CWdwarf_get_fde_at_pc()\fP. .H 4 "dwarf_get_fde_info_for_all_regs()" .DS \f(CWint dwarf_get_fde_info_for_all_regs( Dwarf_Fde fde, Dwarf_Addr pc_requested, Dwarf_Regtable *reg_table, Dwarf_Addr *row_pc, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_fde_info_for_all_regs()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*reg_table\fP for the row specified by \f(CWpc_requested\fP for the FDE specified by \f(CWfde\fP. .P The intent is to return the rules for decoding all the registers, given a pc value. \f(CWreg_table\fP is an array of rules, one for each register specified in \f(CWdwarf.h\fP. The rule for each register contains three items - \f(CWdw_regnum\fP which denotes the register value for that rule, \f(CWdw_offset\fP which denotes the offset value for that rule and \f(CWdw_offset_relevant\fP which is set to zero if offset is not relevant for that rule. See \f(CWdwarf_get_fde_info_fo_reg()\fP for a description of \f(CWrow_pc\fP. .P \f(CWdwarf_get_fde_info_for_all_regs\fP returns \f(CWDW_DLV_ERROR\fP if there is an error. .P \f(CWint dwarf_get_fde_info_for_all_regs\fP is SGI/MIPS specific. .H 4 "dwarf_set_frame_rule_table_size()" .P This allows consumers to set the size of the (internal to libdwarf) rule table. It should be at least as large as the number of real registers in the ABI which is to be read in for the dwarf_get_fde_info_for_reg3() or dwarf_get_fde_info_for_all_regs3() functions to work properly. It must be less than the marker values DW_FRAME_UNDEFINED_VAL, DW_FRAME_SAME_VAL, DW_FRAME_CFA_COL3. .P .DS \f(CWDwarf_Half dwarf_set_frame_rule_table_size(Dwarf_Debug dbg, Dwarf_Half value);\fP .DE \f(CWddwarf_set_frame_rule_table_size()\fP sets the value \f(CWvalue\fP as the size of libdwarf-internal rules tables of \f(CWdbg\fP. The function returns the previous value of the rules table size setting (taken from the \f(CWdbg\fP structure). .H 4 "dwarf_set_frame_rule_inital_value()" This allows consumers to set the initial value for rows in the frame tables. By default it is taken from libdwarf.h and is DW_FRAME_REG_INITIAL_VALUE (which itself is either DW_FRAME_SAME_VAL or DW_FRAME_UNDEFINED_VAL). The MIPS/IRIX default is DW_FRAME_SAME_VAL. Comsumer code should set this appropriately and for many architectures (but probably not MIPS) DW_FRAME_UNDEFINED_VAL is an appropriate setting. .DS \f(CWDwarf_Half dwarf_set_frame_rule_inital_value(Dwarf_Debug dbg, Dwarf_Half value);\fP .DE \f(CWdwarf_set_frame_rule_inital_value()\fP sets the value \f(CWvalue\fP as the initial value for this \f(CWdbg\fP when initializing rules tables. The function returns the previous value of the initial setting (taken from the \f(CWdbg\fP structure). .H 4 "dwarf_get_fde_info_for_reg3()" This interface is suitable for DWARF3 and DWARF2. It returns the values for a particular real register (Not for the CFA register, see dwarf_get_fde_info_for_cfa_reg3() below). .DS \f(CWint dwarf_get_fde_info_for_reg3( Dwarf_Fde fde, Dwarf_Half table_column, Dwarf_Addr pc_requested, Dwarf_Small *value_type, Dwarf_Signed *offset_relevant, Dwarf_Signed *register_num, Dwarf_Signed *offset_or_block_len, Dwarf_Ptr *block_ptr, Dwarf_Addr *row_pc, Dwarf_Error *error);\fP .DE \f(CWdwarf_get_fde_info_for_re3()\fP returns \f(CWDW_DLV_OK\fP on success. It sets \f(CW*value_type\fP to one of DW_EXPR_OFFSET (0), DW_EXPR_VAL_OFFSET(1), DW_EXPR_EXPRESSION(2) or DW_EXPR_VAL_EXPRESSION(3). On call, \f(CWtable_column\fP must be set to the register number of a real register. Not the cfa 'register' or DW_FRAME_SAME_VALUE or DW_FRAME_UNDEFINED_VALUE. if \f(CW*value_type\fP has the value DW_EXPR_OFFSET (0) then: .in +4 .P It sets \f(CW*offset_relevant\fP to non-zero if the offset is relevant for the row specified by \f(CWpc_requested\fP and column specified by \f(CWtable_column\fP or, for the FDE specified by \f(CWfde\fP. In this case the \f(CW*register_num\fP will be set to DW_FRAME_CFA_COL3. This is an offset(N) rule as specified in the DWARF3/2 documents. Adding the value of \f(CW*offset_or_block_len\fP to the value of the CFA register gives the address of a location holding the previous value of register \f(CWtable_column\fP. .P If offset is not relevant for this rule, \f(CW*offset_relevant\fP is set to zero. \f(CW*register_num\fP will be set to the number of the real register holding the value of the \f(CWtable_column\fP register. This is the register(R) rule as specifified in DWARF3/2 documents. .P The intent is to return the rule for the given pc value and register. The location pointed to by \f(CWregister_num\fP is set to the register value for the rule. The location pointed to by \f(CWoffset\fP is set to the offset value for the rule. Since more than one pc value will have rows with identical entries, the user may want to know the earliest pc value after which the rules for all the columns remained unchanged. Recall that in the virtual table that the frame information represents there may be one or more table rows with identical data (each such table row at a different pc value). Given a \f(CWpc_requested\fP which refers to a pc in such a group of identical rows, the location pointed to by \f(CWrow_pc\fP is set to the lowest pc value within the group of identical rows. .in -4 .P If \f(CW*value_type\fP has the value DW_EXPR_VAL_OFFSET (1) then: .in +4 This will be a val_offset(N) rule as specified in the DWARF3/2 documents so \f(CW*offset_relevant\fP will be non zero. The calculation is identical to the DW_EXPR_OFFSET (0) calculation with \f(CW*offset_relevant\fP non-zero, but the value resulting is the actual \f(CWtable_column\fP value (rather than the address where the value may be found). .in -4 .P If \f(CW*value_type\fP has the value DW_EXPR_EXPRESSION (1) then: .in +4 \f(CW*offset_or_block_len\fP is set to the length in bytes of a block of memory with a DWARF expression in the block. \f(CW*block_ptr\fP is set to point at the block of memory. The consumer code should evaluate the block as a DWARF-expression. The result is the address where the previous value of the register may be found. This is a DWARF3/2 expression(E) rule. .in -4 .P If \f(CW*value_type\fP has the value DW_EXPR_VAL_EXPRESSION (1) then: .in +4 The calculation is exactly as for DW_EXPR_EXPRESSION (1) but the result of the DWARF-expression evaluation is the value of the \f(CWtable_column\fP (not the address of the value). This is a DWARF3/2 val_expression(E) rule. .in -4 \f(CWdwarf_get_fde_info_for_reg\fP returns \f(CWDW_DLV_ERROR\fP if there is an error and if there is an error only the \f(CWerror\fP pointer is set, none of the other output arguments are touched. It is usable with either \f(CWdwarf_get_fde_n()\fP or \f(CWdwarf_get_fde_at_pc()\fP. .H 4 "dwarf_get_fde_info_for_cfa_reg3()" .DS \f(CWint dwarf_get_fde_info_for_cfa_reg3(Dwarf_Fde fde, Dwarf_Addr pc_requested, Dwarf_Small * value_type, Dwarf_Signed* offset_relevant, Dwarf_Signed* register_num, Dwarf_Signed* offset_or_block_len, Dwarf_Ptr * block_ptr , Dwarf_Addr * row_pc_out, Dwarf_Error * error)\fP .DE .P This is identical to \f(CWdwarf_get_fde_info_for_reg3()\fP except the returned values are for the CFA rule. So register number \f(CW*register_num\fP will be set to a real register, not DW_FRAME_CFA_COL3, DW_FRAME_SAME_VALUE, or DW_FRAME_UNDEFINED_VALUE. .H 4 "dwarf_get_fde_info_for_all_regs3()" .DS \f(CWint dwarf_get_fde_info_for_all_regs3( Dwarf_Fde fde, Dwarf_Addr pc_requested, Dwarf_Regtable3 *reg_table, Dwarf_Addr *row_pc, Dwarf_Error *error)\fP .DE \f(CWdwarf_get_fde_info_for_all_regs3()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*reg_table\fP for the row specified by \f(CWpc_requested\fP for the FDE specified by \f(CWfde\fP. The intent is to return the rules for decoding all the registers, given a pc value. \f(CWreg_table\fP is an array of rules, the array size specifed by the caller. plus a rule for the CFA. The rule for the cfa returned in \f(CW*reg_table\fP defines the CFA value at \f(CWpc_requested\fP The rule for each register contains several values that enable the consumer to determine the previous value of the register (see the earlier documentation of Dwarf_Regtable3). \f(CWdwarf_get_fde_info_for_reg3()\fP and the Dwarf_Regtable3 documentation above for a description of the values for each row. \f(CWdwarf_get_fde_info_for_all_regs\fP returns \f(CWDW_DLV_ERROR\fP if there is an error. It's up to the caller to allocate space for \f(CW*reg_table\fP and initialize it properly. .H 4 "dwarf_get_fde_n()" .DS \f(CWint dwarf_get_fde_n( Dwarf_Fde *fde_data, Dwarf_Unsigned fde_index, Dwarf_Fde *returned_fde Dwarf_Error *error)\fP .DE \f(CWdwarf_get_fde_n()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CWreturned_fde\fP to the \f(CWDwarf_Fde\fP descriptor whose index is \f(CWfde_index\fP in the table of \f(CWDwarf_Fde\fP descriptors pointed to by \fPfde_data\fP. The index starts with 0. Returns \f(CWDW_DLV_NO_ENTRY\fP if the index does not exist in the table of \f(CWDwarf_Fde\fP descriptors. Returns \f(CWDW_DLV_ERROR\fP if there is an error. This function cannot be used unless the block of \f(CWDwarf_Fde\fP descriptors has been created by a call to \f(CWdwarf_get_fde_list()\fP. .H 4 "dwarf_get_fde_at_pc()" .DS \f(CWint dwarf_get_fde_at_pc( Dwarf_Fde *fde_data, Dwarf_Addr pc_of_interest, Dwarf_Fde *returned_fde, Dwarf_Addr *lopc, Dwarf_Addr *hipc, Dwarf_Error *error)\fP .DE \f(CWdwarf_get_fde_at_pc()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CWreturned_fde\fP to a \f(CWDwarf_Fde\fP descriptor for a function which contains the pc value specified by \f(CWpc_of_interest\fP. In addition, it sets the locations pointed to by \f(CWlopc\fP and \f(CWhipc\fP to the low address and the high address covered by this FDE, respectively. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if \f(CWpc_of_interest\fP is not in any of the FDEs represented by the block of \f(CWDwarf_Fde\fP descriptors pointed to by \f(CWfde_data\fP. This function cannot be used unless the block of \f(CWDwarf_Fde\fP descriptors has been created by a call to \f(CWdwarf_get_fde_list()\fP. .H 4 "dwarf_expand_frame_instructions()" .DS \f(CWint dwarf_expand_frame_instructions( Dwarf_Debug dbg, Dwarf_Ptr instruction, Dwarf_Unsigned i_length, Dwarf_Frame_Op **returned_op_list, Dwarf_Signed * returned_op_count, Dwarf_Error *error);\fP .DE \f(CWdwarf_expand_frame_instructions()\fP is a High-level interface function which expands a frame instruction byte stream into an array of \f(CWDwarf_Frame_Op\fP structures. To indicate success, it returns \f(CWDW_DLV_OK\fP. The address where the byte stream begins is specified by \f(CWinstruction\fP, and the length of the byte stream is specified by \f(CWi_length\fP. The location pointed to by \f(CWreturned_op_list\fP is set to point to a table of \f(CWreturned_op_count\fP pointers to \f(CWDwarf_Frame_Op\fP which contain the frame instructions in the byte stream. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. After a successful return, the array of structures should be freed using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_FRAME_BLOCK\fP (when they are no longer of interest). .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Frame_Op *frameops; Dwarf_Ptr instruction; Dwarf_Unsigned len; int res; res = expand_frame_instructions(dbg,instruction,len, &frameops,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use frameops[i] */ } dwarf_dealloc(dbg, frameops, DW_DLA_FRAME_BLOCK); }\fP .DE .in -2 .H 4 "dwarf_get_fde_exception_info()" .DS \f(CWint dwarf_get_fde_exception_info( Dwarf_Fde fde, Dwarf_Signed * offset_into_exception_tables, Dwarf_Error * error); .DE \f(CWdwarf_get_fde_exception_info()\fP is an IRIX specific function which returns an exception table signed offset thru \f(CWoffset_into_exception_tables\fP. The function never returns \f(CWDW_DLV_NO_ENTRY\fP. If \f(CWDW_DLV_NO_ENTRY\fP is NULL the function returns \f(CWDW_DLV_ERROR\fP. For non-IRIX objects the offset returned will always be zero. For non-C++ objects the offset returned will always be zero. The meaning of the offset and the content of the tables is not defined in this document. The applicable CIE augmentation string (see above) determines whether the value returned has meaning. .H 2 "Location Expression Evaluation" An "interpreter" which evaluates a location expression is required in any debugger. There is no interface defined here at this time. .P One problem with defining an interface is that operations are machine dependent: they depend on the interpretation of register numbers and the methods of getting values from the environment the expression is applied to. .P It would be desirable to specify an interface. .H 3 "Location List Internal-level Interface" .H 4 "dwarf_get_loclist_entry()" .DS \f(CWint dwarf_get_loclist_entry( Dwarf_Debug dbg, Dwarf_Unsigned offset, Dwarf_Addr *hipc_offset, Dwarf_Addr *lopc_offset, Dwarf_Ptr *data, Dwarf_Unsigned *entry_len, Dwarf_Unsigned *next_entry, Dwarf_Error *error)\fP .DE \f(CWdwarf_dwarf_get_loclist_entry()\fP returns \f(CWDW_DLV_OK\fP if successful. \f(CWDW_DLV_NO_ENTRY\fP is returned when the offset passed in is beyond the end of the .debug_loc section (expected if you start at offset zero and proceed thru all the entries). \f(CWDW_DLV_ERROR\fP is returned on error. The function reads a location list entry starting at \f(CWoffset\fP and returns through pointers (when successful) the high pc \f(CWhipc_offset\fP, low pc \f(CWlopc_offset\fP, a pointer to the location description data \f(CWdata\fP, the length of the location description data \f(CWentry_len\fP, and the offset of the next location description entry \f(CWnext_entry\fP. .P The \f(CWhipc_offset\fP, low pc \f(CWlopc_offset\fP are offsets from the beginning of the current procedure, not genuine pc values. .H 2 "Abbreviations access" These are Internal-level Interface functions. Debuggers can ignore this. .H 3 "dwarf_get_abbrev()" .DS \f(CWint dwarf_get_abbrev( Dwarf_Debug dbg, Dwarf_Unsigned offset, Dwarf_Abbrev *returned_abbrev, Dwarf_Unsigned *length, Dwarf_Unsigned *attr_count, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_abbrev()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_abbrev\fP to \f(CWDwarf_Abbrev\fP descriptor for an abbreviation at offset \f(CW*offset\fP in the abbreviations section (i.e .debug_abbrev) on success. The user is responsible for making sure that a valid abbreviation begins at \f(CWoffset\fP in the abbreviations section. The location pointed to by \f(CWlength\fP is set to the length in bytes of the abbreviation in the abbreviations section. The location pointed to by \f(CWattr_count\fP is set to the number of attributes in the abbreviation. An abbreviation entry with a length of 1 is the 0 byte of the last abbreviation entry of a compilation unit. \f(CWdwarf_get_abbrev()\fP returns \f(CWDW_DLV_ERROR\fP on error. If the call succeeds, the storage pointed to by \f(CW*returned_abbrev\fP should be free'd, using \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ABBREV\fP when no longer needed. .H 3 "dwarf_get_abbrev_tag()" .DS \f(CWint dwarf_get_abbrev_tag( Dwarf_abbrev abbrev, Dwarf_Half *return_tag, Dwarf_Error *error);\fP .DE If successful, \f(CWdwarf_get_abbrev_tag()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_tag\fP to the \fItag\fP of the given abbreviation. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 3 "dwarf_get_abbrev_code()" .DS \f(CWint dwarf_get_abbrev_code( Dwarf_abbrev abbrev, Dwarf_Unsigned *return_code, Dwarf_Error *error);\fP .DE If successful, \f(CWdwarf_get_abbrev_code()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*return_code\fP to the abbreviation code of the given abbreviation. It returns \f(CWDW_DLV_ERROR\fP on error. It never returns \f(CWDW_DLV_NO_ENTRY\fP. .H 3 "dwarf_get_abbrev_children_flag()" .DS \f(CWint dwarf_get_abbrev_children_flag( Dwarf_Abbrev abbrev, Dwarf_Signed *returned_flag, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_abbrev_children_flag()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CWreturned_flag\fP to \f(CWDW_children_no\fP (if the given abbreviation indicates that a die with that abbreviation has no children) or \f(CWDW_children_yes\fP (if the given abbreviation indicates that a die with that abbreviation has a child). It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_get_abbrev_entry()" .DS \f(CWint dwarf_get_abbrev_entry( Dwarf_Abbrev abbrev, Dwarf_Signed index, Dwarf_Half *attr_num, Dwarf_Signed *form, Dwarf_Off *offset, Dwarf_Error *error)\fP .DE If successful, \f(CWdwarf_get_abbrev_entry()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*attr_num\fP to the attribute code of the attribute whose index is specified by \f(CWindex\fP in the given abbreviation. The index starts at 0. The location pointed to by \f(CWform\fP is set to the form of the attribute. The location pointed to by \f(CWoffset\fP is set to the byte offset of the attribute in the abbreviations section. It returns \f(CWDW_DLV_NO_ENTRY\fP if the index specified is outside the range of attributes in this abbreviation. It returns \f(CWDW_DLV_ERROR\fP on error. .H 2 "String Section Operations" The .debug_str section contains only strings. Debuggers need never use this interface: it is only for debugging problems with the string section itself. .H 3 "dwarf_get_str()" .DS \f(CWint dwarf_get_str( Dwarf_Debug dbg, Dwarf_Off offset, char **string, Dwarf_Signed *returned_str_len, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_str()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_str_len\fP to the length of the string, not counting the null terminator, that begins at the offset specified by \f(CWoffset\fP in the .debug_str section. The location pointed to by \f(CWstring\fP is set to a pointer to this string. The next string in the .debug_str section begins at the previous \f(CWoffset\fP + 1 + \f(CW*returned_str_len\fP. A zero-length string is NOT the end of the section. If there is no .debug_str section, \f(CWDW_DLV_NO_ENTRY\fP is returned. If there is an error, \f(CWDW_DLV_ERROR\fP is returned. If we are at the end of the section (that is, \f(CWoffset\fP is one past the end of the section) \f(CWDW_DLV_NO_ENTRY\fP is returned. If the \f(CWoffset\fP is some other too-large value then \f(CWDW_DLV_ERROR\fP is returned. .H 2 "Address Range Operations" These functions provide information about address ranges. Address ranges map ranges of pc values to the corresponding compilation-unit die that covers the address range. .H 3 "dwarf_get_aranges()" .DS \f(CWint dwarf_get_aranges( Dwarf_Debug dbg, Dwarf_Arange **aranges, Dwarf_Signed * returned_arange_count, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_aranges()\fP returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_arange_count\fP to the count of the number of address ranges in the .debug_aranges section. It sets \f(CW*aranges\fP to point to a block of \f(CWDwarf_Arange\fP descriptors, one for each address range. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no .debug_aranges section. .in +2 .DS \f(CWDwarf_Signed cnt; Dwarf_Arange *arang; int res; res = dwarf_get_aranges(dbg, &arang,&cnt, &error); if (res == DW_DLV_OK) { for (i = 0; i < cnt; ++i) { /* use arang[i] */ dwarf_dealloc(dbg, arang[i], DW_DLA_ARANGE); } dwarf_dealloc(dbg, arang, DW_DLA_LIST); }\fP .DE .in -2 .DS \f(CWint dwarf_get_arange( Dwarf_Arange *aranges, Dwarf_Unsigned arange_count, Dwarf_Addr address, Dwarf_Arange *returned_arange, Dwarf_Error *error);\fP .DE The function \f(CWdwarf_get_arange()\fP takes as input a pointer to a block of \f(CWDwarf_Arange\fP pointers, and a count of the number of descriptors in the block. It then searches for the descriptor that covers the given \f(CWaddress\fP. If it finds one, it returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_arange\fP to the descriptor. It returns \f(CWDW_DLV_ERROR\fP on error. It returns \f(CWDW_DLV_NO_ENTRY\fP if there is no .debug_aranges entry covering that address. .H 3 "dwarf_get_cu_die_offset()" .DS \f(CWint dwarf_get_cu_die_offset( Dwarf_Arange arange, Dwarf_Off *returned_cu_die_offset, Dwarf_Error *error);\fP .DE The function \f(CWdwarf_get_cu_die_offset()\fP takes a \f(CWDwarf_Arange\fP descriptor as input, and if successful returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_cu_die_offset\fP to the offset in the .debug_info section of the compilation-unit DIE for the compilation-unit represented by the given address range. It returns \f(CWDW_DLV_ERROR\fP on error. .H 3 "dwarf_get_arange_cu_header_offset()" .DS \f(CWint dwarf_get_arange_cu_header_offset( Dwarf_Arange arange, Dwarf_Off *returned_cu_header_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_arange_cu_header_offset()\fP takes a \f(CWDwarf_Arange\fP descriptor as input, and if successful returns \f(CWDW_DLV_OK\fP and sets \f(CW*returned_cu_header_offset\fP to the offset in the .debug_info section of the compilation-unit header for the compilation-unit represented by the given address range. It returns \f(CWDW_DLV_ERROR\fP on error. This function added Rev 1.45, June, 2001. This function is declared as 'optional' in libdwarf.h on IRIX systems so the _MIPS_SYMBOL_PRESENT predicate may be used at run time to determine if the version of libdwarf linked into an application has this function. .H 3 "dwarf_get_arange_info()" .DS \f(CWint dwarf_get_arange_info( Dwarf_Arange arange, Dwarf_Addr *start, Dwarf_Unsigned *length, Dwarf_Off *cu_die_offset, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_arange_info()\fP returns \f(CWDW_DLV_OK\fP and stores the starting value of the address range in the location pointed to by \f(CWstart\fP, the length of the address range in the location pointed to by \f(CWlength\fP, and the offset in the .debug_info section of the compilation-unit DIE for the compilation-unit represented by the address range. It returns \f(CWDW_DLV_ERROR\fP on error. .H 2 "General Low Level Operations" This function is low-level and intended for use only by programs such as dwarf-dumpers. .H 3 "dwarf_get_address_size()" .DS \f(CWint dwarf_get_address_size(Dwarf_Debug dbg, Dwarf_Half *addr_size, Dwarf_Error *error)\fP .DE The function \f(CWdwarf_get_address_size()\fP returns \f(CWDW_DLV_OK\fP on success and sets the \f(CW*addr_size\fP to the size in bytes of an address. In case of error, it returns \f(CWDW_DLV_ERROR\fP and does not set \f(CW*addr_size\fP. .H 2 "Utility Operations" These functions aid in the management of errors encountered when using functions in the \fIlibdwarf\fP library and releasing memory allocated as a result of a \fIlibdwarf\fP operation. .H 3 "dwarf_errno()" .DS \f(CWDwarf_Unsigned dwarf_errno( Dwarf_Error error)\fP .DE The function \f(CWdwarf_errno()\fP returns the error number corresponding to the error specified by \f(CWerror\fP. .H 3 "dwarf_errmsg()" .DS \f(CWconst char* dwarf_errmsg( Dwarf_Error error)\fP .DE The function \f(CWdwarf_errmsg()\fP returns a pointer to a null-terminated error message string corresponding to the error specified by \f(CWerror\fP. The string returned by \f(CWdwarf_errmsg()\fP should not be deallocated using \f(CWdwarf_dealloc()\fP. .P The set of errors enumerated in Figure \n(aX below were defined in Dwarf 1. These errors are not used by the current implementation of Dwarf 2. .DS .TS center box, tab(:); lfB lfB l l. SYMBOLIC NAME:DESCRIPTION _ DW_DLE_NE:No error (0) DW_DLE_VMM:Version of DWARF information newer than libdwarf DW_DLE_MAP:Memory map failure DW_DLE_LEE:Propagation of libelf error DW_DLE_NDS:No debug section DW_DLE_NLS:No line section DW_DLE_ID:Requested information not associated with descriptor DW_DLE_IOF:I/O failure DW_DLE_MAF:Memory allocation failure DW_DLE_IA:Invalid argument DW_DLE_MDE:Mangled debugging entry DW_DLE_MLE:Mangled line number entry DW_DLE_FNO:File descriptor does not refer to an open file DW_DLE_FNR:File is not a regular file DW_DLE_FWA:File is opened with wrong access DW_DLE_NOB:File is not an object file DW_DLE_MOF:Mangled object file header DW_DLE_EOLL:End of location list entries DW_DLE_NOLL:No location list section DW_DLE_BADOFF:Invalid offset DW_DLE_EOS:End of section DW_DLE_ATRUNC:Abbreviations section appears truncated DW_DLE_BADBITC:Address size passed to dwarf bad .TE .FG "List of Dwarf Error Codes" .DE The set of errors returned by SGI \f(CWLibdwarf\fP functions is listed below. Some of the errors are SGI specific. .DS .TS center box, tab(:); lfB lfB l l. SYMBOLIC NAME:DESCRIPTION _ DW_DLE_DBG_ALLOC:Could not allocate Dwarf_Debug struct DW_DLE_FSTAT_ERROR:Error in fstat()-ing object DW_DLE_FSTAT_MODE_ERROR:Error in mode of object file DW_DLE_INIT_ACCESS_WRONG:Incorrect access to dwarf_init() DW_DLE_ELF_BEGIN_ERROR:Error in elf_begin() on object DW_DLE_ELF_GETEHDR_ERROR:Error in elf_getehdr() on object DW_DLE_ELF_GETSHDR_ERROR:Error in elf_getshdr() on object DW_DLE_ELF_STRPTR_ERROR:Error in elf_strptr() on object DW_DLE_DEBUG_INFO_DUPLICATE:Multiple .debug_info sections DW_DLE_DEBUG_INFO_NULL:No data in .debug_info section DW_DLE_DEBUG_ABBREV_DUPLICATE:Multiple .debug_abbrev sections DW_DLE_DEBUG_ABBREV_NULL:No data in .debug_abbrev section DW_DLE_DEBUG_ARANGES_DUPLICATE:Multiple .debug_arange sections DW_DLE_DEBUG_ARANGES_NULL:No data in .debug_arange section DW_DLE_DEBUG_LINE_DUPLICATE:Multiple .debug_line sections DW_DLE_DEBUG_LINE_NULL:No data in .debug_line section DW_DLE_DEBUG_LOC_DUPLICATE:Multiple .debug_loc sections DW_DLE_DEBUG_LOC_NULL:No data in .debug_loc section DW_DLE_DEBUG_MACINFO_DUPLICATE:Multiple .debug_macinfo sections DW_DLE_DEBUG_MACINFO_NULL:No data in .debug_macinfo section DW_DLE_DEBUG_PUBNAMES_DUPLICATE:Multiple .debug_pubnames sections DW_DLE_DEBUG_PUBNAMES_NULL:No data in .debug_pubnames section DW_DLE_DEBUG_STR_DUPLICATE:Multiple .debug_str sections DW_DLE_DEBUG_STR_NULL:No data in .debug_str section DW_DLE_CU_LENGTH_ERROR:Length of compilation-unit bad DW_DLE_VERSION_STAMP_ERROR:Incorrect Version Stamp DW_DLE_ABBREV_OFFSET_ERROR:Offset in .debug_abbrev bad DW_DLE_ADDRESS_SIZE_ERROR:Size of addresses in target bad DW_DLE_DEBUG_INFO_PTR_NULL:Pointer into .debug_info in DIE null DW_DLE_DIE_NULL:Null Dwarf_Die DW_DLE_STRING_OFFSET_BAD:Offset in .debug_str bad DW_DLE_DEBUG_LINE_LENGTH_BAD:Length of .debug_line segment bad DW_DLE_LINE_PROLOG_LENGTH_BAD:Length of .debug_line prolog bad DW_DLE_LINE_NUM_OPERANDS_BAD:Number of operands to line instr bad DW_DLE_LINE_SET_ADDR_ERROR:Error in DW_LNE_set_address instruction DW_DLE_LINE_EXT_OPCODE_BAD:Error in DW_EXTENDED_OPCODE instruction DW_DLE_DWARF_LINE_NULL:Null Dwarf_line argument DW_DLE_INCL_DIR_NUM_BAD:Error in included directory for given line DW_DLE_LINE_FILE_NUM_BAD:File number in .debug_line bad DW_DLE_ALLOC_FAIL:Failed to allocate required structs DW_DLE_DBG_NULL:Null Dwarf_Debug argument DW_DLE_DEBUG_FRAME_LENGTH_BAD:Error in length of frame DW_DLE_FRAME_VERSION_BAD:Bad version stamp for frame DW_DLE_CIE_RET_ADDR_REG_ERROR:Bad register specified for return address DW_DLE_FDE_NULL:Null Dwarf_Fde argument DW_DLE_FDE_DBG_NULL:No Dwarf_Debug associated with FDE DW_DLE_CIE_NULL:Null Dwarf_Cie argument DW_DLE_CIE_DBG_NULL:No Dwarf_Debug associated with CIE DW_DLE_FRAME_TABLE_COL_BAD:Bad column in frame table specified .TE .FG "List of Dwarf 2 Error Codes (continued)" .DE .DS .TS center box, tab(:); lfB lfB l l. SYMBOLIC NAME:DESCRIPTION _ DW_DLE_PC_NOT_IN_FDE_RANGE:PC requested not in address range of FDE DW_DLE_CIE_INSTR_EXEC_ERROR:Error in executing instructions in CIE DW_DLE_FRAME_INSTR_EXEC_ERROR:Error in executing instructions in FDE DW_DLE_FDE_PTR_NULL:Null Pointer to Dwarf_Fde specified DW_DLE_RET_OP_LIST_NULL:No location to store pointer to Dwarf_Frame_Op DW_DLE_LINE_CONTEXT_NULL:Dwarf_Line has no context DW_DLE_DBG_NO_CU_CONTEXT:dbg has no CU context for dwarf_siblingof() DW_DLE_DIE_NO_CU_CONTEXT:Dwarf_Die has no CU context DW_DLE_FIRST_DIE_NOT_CU:First DIE in CU not DW_TAG_compilation_unit DW_DLE_NEXT_DIE_PTR_NULL:Error in moving to next DIE in .debug_info DW_DLE_DEBUG_FRAME_DUPLICATE:Multiple .debug_frame sections DW_DLE_DEBUG_FRAME_NULL:No data in .debug_frame section DW_DLE_ABBREV_DECODE_ERROR:Error in decoding abbreviation DW_DLE_DWARF_ABBREV_NULL:Null Dwarf_Abbrev specified DW_DLE_ATTR_NULL:Null Dwarf_Attribute specified DW_DLE_DIE_BAD:DIE bad DW_DLE_DIE_ABBREV_BAD:No abbreviation found for code in DIE DW_DLE_ATTR_FORM_BAD:Inappropriate attribute form for attribute DW_DLE_ATTR_NO_CU_CONTEXT:No CU context for Dwarf_Attribute struct DW_DLE_ATTR_FORM_SIZE_BAD:Size of block in attribute value bad DW_DLE_ATTR_DBG_NULL:No Dwarf_Debug for Dwarf_Attribute struct DW_DLE_BAD_REF_FORM:Inappropriate form for reference attribute DW_DLE_ATTR_FORM_OFFSET_BAD:Offset reference attribute outside current CU DW_DLE_LINE_OFFSET_BAD:Offset of lines for current CU outside .debug_line DW_DLE_DEBUG_STR_OFFSET_BAD:Offset into .debug_str past its end DW_DLE_STRING_PTR_NULL:Pointer to pointer into .debug_str NULL DW_DLE_PUBNAMES_VERSION_ERROR:Version stamp of pubnames incorrect DW_DLE_PUBNAMES_LENGTH_BAD:Read pubnames past end of .debug_pubnames DW_DLE_GLOBAL_NULL:Null Dwarf_Global specified DW_DLE_GLOBAL_CONTEXT_NULL:No context for Dwarf_Global given DW_DLE_DIR_INDEX_BAD:Error in directory index read DW_DLE_LOC_EXPR_BAD:Bad operator read for location expression DW_DLE_DIE_LOC_EXPR_BAD:Expected block value for attribute not found DW_DLE_OFFSET_BAD:Offset for next compilation-unit in .debug_info bad DW_DLE_MAKE_CU_CONTEXT_FAIL:Could not make CU context DW_DLE_ARANGE_OFFSET_BAD:Offset into .debug_info in .debug_aranges bad DW_DLE_SEGMENT_SIZE_BAD:Segment size should be 0 for MIPS processors DW_DLE_ARANGE_LENGTH_BAD:Length of arange section in .debug_arange bad DW_DLE_ARANGE_DECODE_ERROR:Aranges do not end at end of .debug_aranges DW_DLE_ARANGES_NULL:NULL pointer to Dwarf_Arange specified DW_DLE_ARANGE_NULL:NULL Dwarf_Arange specified DW_DLE_NO_FILE_NAME:No file name for Dwarf_Line struct DW_DLE_NO_COMP_DIR:No Compilation directory for compilation-unit DW_DLE_CU_ADDRESS_SIZE_BAD:CU header address size not match Elf class DW_DLE_ELF_GETIDENT_ERROR:Error in elf_getident() on object DW_DLE_NO_AT_MIPS_FDE:DIE does not have DW_AT_MIPS_fde attribute DW_DLE_NO_CIE_FOR_FDE:No CIE specified for FDE DW_DLE_DIE_ABBREV_LIST_NULL:No abbreviation for the code in DIE found DW_DLE_DEBUG_FUNCNAMES_DUPLICATE:Multiple .debug_funcnames sections DW_DLE_DEBUG_FUNCNAMES_NULL:No data in .debug_funcnames section .TE .FG "List of Dwarf 2 Error Codes (continued)" .DE .DS .TS center box, tab(:); lfB lfB l l. SYMBOLIC NAME:DESCRIPTION _ DW_DLE_DEBUG_FUNCNAMES_VERSION_ERROR:Version stamp in .debug_funcnames bad DW_DLE_DEBUG_FUNCNAMES_LENGTH_BAD:Length error in reading .debug_funcnames DW_DLE_FUNC_NULL:NULL Dwarf_Func specified DW_DLE_FUNC_CONTEXT_NULL:No context for Dwarf_Func struct DW_DLE_DEBUG_TYPENAMES_DUPLICATE:Multiple .debug_typenames sections DW_DLE_DEBUG_TYPENAMES_NULL:No data in .debug_typenames section DW_DLE_DEBUG_TYPENAMES_VERSION_ERROR:Version stamp in .debug_typenames bad DW_DLE_DEBUG_TYPENAMES_LENGTH_BAD:Length error in reading .debug_typenames DW_DLE_TYPE_NULL:NULL Dwarf_Type specified DW_DLE_TYPE_CONTEXT_NULL:No context for Dwarf_Type given DW_DLE_DEBUG_VARNAMES_DUPLICATE:Multiple .debug_varnames sections DW_DLE_DEBUG_VARNAMES_NULL:No data in .debug_varnames section DW_DLE_DEBUG_VARNAMES_VERSION_ERROR:Version stamp in .debug_varnames bad DW_DLE_DEBUG_VARNAMES_LENGTH_BAD:Length error in reading .debug_varnames DW_DLE_VAR_NULL:NULL Dwarf_Var specified DW_DLE_VAR_CONTEXT_NULL:No context for Dwarf_Var given DW_DLE_DEBUG_WEAKNAMES_DUPLICATE:Multiple .debug_weaknames section DW_DLE_DEBUG_WEAKNAMES_NULL:No data in .debug_varnames section DW_DLE_DEBUG_WEAKNAMES_VERSION_ERROR:Version stamp in .debug_varnames bad DW_DLE_DEBUG_WEAKNAMES_LENGTH_BAD:Length error in reading .debug_weaknames DW_DLE_WEAK_NULL:NULL Dwarf_Weak specified DW_DLE_WEAK_CONTEXT_NULL:No context for Dwarf_Weak given .TE .FG "List of Dwarf 2 Error Codes" .DE This list of errors is not necessarily complete; additional errors might be added when functionality to create debugging information entries are added to \fIlibdwarf\fP and by the implementors of \fIlibdwarf\fP to describe internal errors not addressed by the above list. Some of the above errors may be unused. Errors may not have the same meaning in different implementations. .H 3 "dwarf_seterrhand()" .DS \f(CWDwarf_Handler dwarf_seterrhand( Dwarf_Debug dbg, Dwarf_Handler errhand)\fP .DE The function \f(CWdwarf_seterrhand()\fP replaces the error handler (see \f(CWdwarf_init()\fP) with \f(CWerrhand\fP. The old error handler is returned. This function is currently unimplemented. .H 3 "dwarf_seterrarg()" .DS \f(CWDwarf_Ptr dwarf_seterrarg( Dwarf_Debug dbg, Dwarf_Ptr errarg)\fP .DE The function \f(CWdwarf_seterrarg()\fP replaces the pointer to the error handler communication area (see \f(CWdwarf_init()\fP) with \f(CWerrarg\fP. A pointer to the old area is returned. This function is currently unimplemented. .H 3 "dwarf_dealloc()" .DS \f(CWvoid dwarf_dealloc( Dwarf_Debug dbg, void* space, Dwarf_Unsigned type)\fP .DE The function \f(CWdwarf_dealloc\fP frees the dynamic storage pointed to by \f(CWspace\fP, and allocated to the given \f(CWDwarf_Debug\fP. The argument \f(CWtype\fP is an integer code that specifies the allocation type of the region pointed to by the \f(CWspace\fP. Refer to section 4 for details on \fIlibdwarf\fP memory management. .SK .S .TC 1 1 4 .CS