--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/elf4rom/libs/dwarf-20071209/libdwarf/libdwarf2.1.mm Fri Jan 15 09:07:44 2010 +0000
@@ -0,0 +1,5215 @@
+\."
+\." 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.66, 04 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 <fill in size here, 66 for MIPS/IRIX>
+\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 <space> value" or "name(args)<space>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
+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.
+\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.
+.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.
+.in +2
+.DS
+\f(CW
+/* Looping thru the dwarf_loc section finding loclists:
+ an example. */
+int res;
+Dwarf_Unsigned next_entry;
+Dwarf_unsigned offset=0;
+Dwarf_Addr hipc_off;
+Dwarf_Addr lopc_off;
+Dwarf_Ptr data;
+Dwarf_Unsigned entry_len;
+Dwarf_Unsigned next_entry;
+Dwarf_Error err;
+
+ for(;;) {
+ res = dwarf_get_loclist_entry(dbg,newoffset,&hipc_off,
+ &lowpc_off, &data, &entry_len,&next_entry,&err);
+ if (res == DW_DLV_OK) {
+ /* A valid entry. */
+ newoffset = next_entry;
+ continue;
+ } else if (res ==DW_DLV_NO_ENTRY) {
+ /* Done! */
+ break;
+ } else {
+ /* Error! */
+ break;
+ }
+
+
+ }
+}\fP
+.DE
+.in -2
+
+
+.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