MCL/sf/adapt/qemu: comparison tools/elf4rom/libs/dwarf-20071209/libdwarf/libdwarf2p.1.mm

equal deleted inserted replaced

-:1af5c1be89f8
+:92d87f2e53c2
+\." $Revision: 1.12 $
+\." $Date: 2002/01/14 23:40:11 $
+\."
+\."
+\." 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.20, 4 Sep 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 3
+.SA 1
+.TL
+A Producer Library Interface to DWARF
+.AF ""
+.AU "David Anderson"
+.PF "'\*(vE '- \\\\nP -''"
+.AS 1
+This document describes an interface to a library of functions
+to create DWARF debugging information entries and DWARF line number
+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 creating DWARF version 2.
+Support for creating DWARF3 is intended but such support
+is not yet fully present.
+.P
+\*(vE
+.AE
+.MT 4
+.H 1 "INTRODUCTION"
+This document describes an interface to \f(CWlibdwarf\fP, a
+library of functions to provide creation of DWARF debugging information
+records, DWARF line number information, DWARF address range and
+pubnames information, weak names information, and DWARF frame description
+information.
+.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.
+.H 2 "Purpose and Scope"
+The purpose of this document is to propose a library of functions to
+create DWARF debugging information.  Reading (consuming) of such records
+is discussed in a separate document.
+The functions in this document have mostly been implemented at
+Silicon Graphics
+and are being used by the code generator to provide debugging information.
+Some functions (and support for some extensions) were provided
+by Sun Microsystems.
+.P
+The focus of this document is the functional interface,
+and as such, implementation and optimization issues are
+intentionally ignored.
+.P
+Error handling, error codes, and certain \f(CWLibdwarf\fP codes are discussed
+in the "\fIA Consumer Library Interface to DWARF\fP", which should
+be read (or at least skimmed) before reading this document.
+.P
+However the general style of functions here
+in the producer librar is rather C-traditional
+with various types as return values (quite different
+from the consumer library interfaces).   The style
+generally follows the style of the original DWARF1 reader
+proposed as an interface to DWARF.
+When the style of the reader interfaces was changed (1994) in the
+dwarf reader ( See the "Document History"
+section of "A Consumer Library Interface to DWARF")
+the interfaces here were not changed as it seemed like
+too much of a change for the two applications then using
+the interface!  So this interface remains in the traditional C style
+of returning various data types with various (somewhat inconsistent)
+means of indicating failure.
+.H 2 "Document History"
+This document originally prominently referenced
+"UNIX International Programming Languages Special Interest Group "
+(PLSIG).
+Both  UNIX International and the
+affiliated  Programming Languages Special Interest Group
+are defunct
+(UNIX is a registered trademark of UNIX System Laboratories, Inc.
+in the United States and other countries).
+Nothing except the general interface style is actually
+related to anything shown to the PLSIG
+(this document was open sourced with libdwarf in the mid 1990's).
+.P
+See "http://www.dwarfstd.org" for information on current
+DWARF standards and committee activities.
+.H 2 "Definitions"
+DWARF debugging information entries (DIEs) are the segments of information
+placed in the \f(CW.debug_info\fP  and related
+sections by compilers, assemblers, and linkage
+editors that, in conjunction with line number entries, are necessary for
+symbolic source-level debugging.
+Refer to the document
+"\fIDWARF Debugging Information Format\fP" from UI PLSIG for a more complete
+description of these entries.
+.P
+This document adopts all the terms and definitions in
+"\fIDWARF Debugging Information Format\fP" version 2.
+and the "\fIA Consumer Library Interface to DWARF\fP".
+.P
+In addition, this document refers to Elf, the ATT/USL System V
+Release 4 object format.
+This is because the library was first developed for that object
+format.
+Hopefully the functions defined here can easily be
+applied to other object formats.
+.H 2 "Overview"
+The remaining sections of this document describe a proposed producer
+(compiler or assembler) interface to \fILibdwarf\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, and
+"\fIA Consumer Library Interface to DWARF\fP".
+.P
+The interface necessarily knows a little bit about the object format
+(which is assumed to be Elf).  We make an attempt to make this knowledge
+as limited as possible.  For example, \fILibdwarf\fP does not do the
+writing of object data to the disk.  The producer program does that.
+.H 2 "Revision History"
+.VL 15
+.LI "March 1993"
+Work on dwarf2 sgi producer draft begins
+.LI "March 1999"
+Adding a function to allow any number of trips
+thru the dwarf_get_section_bytes() call.
+.LI "April 10 1999"
+Added support for assembler text output of dwarf
+(as when the output must pass thru an assembler).
+Revamped internals for better performance and
+simpler provision for differences in ABI.
+.LI "Sep 1, 1999"
+Added support for little- and cross- endian
+debug info creation.
+.LI "May 7  2007"
+This library interface now cleans up, deallocating
+all memory it uses (the application simply calls
+dwarf_producer_finish(dbg)).
+.LE
+.H 1 "Type 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 \fI Libdwarf \fP .
+The types defined by typedefs contained in \fI libdwarf.h\fP
+all use the convention of adding \fI Dwarf_ \fP
+as a prefix to
+indicate that they refer to objects used by Libdwarf.
+The prefix \fI Dwarf_P_\fP is used for objects
+referenced by the \fI Libdwarf\fP
+Producer when there are similar but distinct
+objects used by the Consumer.
+.H 2 "Namespace issues"
+Application programs should avoid creating names
+beginning with
+\f(CWDwarf_\fP
+\f(CWdwarf_\fP
+or
+\f(CWDW_\fP
+as these are reserved to dwarf and libdwarf.
+.H 1 "libdwarf and Elf and relocations"
+Much of the description below presumes that Elf is the object
+format in use.
+The library is probably usable with other object formats
+that allow arbitrary sections to be created.
+.H 2 "binary or assembler output"
+With
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+(see below)
+it is assumed that the calling app will simply
+write the streams and relocations directly into
+an Elf file, without going thru an assembler.
+With
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+the calling app must either
+A) generate binary relocation streams and write
+the generated debug information streams and
+the relocation streams direct to an elf file
+or
+B) generate assembler output text for an assembler
+to read and produce an object file.
+With case B) the libdwarf-calling application must
+use the relocation information to change
+points of each binary stream into references to
+symbolic names.
+It is necessary for the assembler to be
+willing to accept and generate relocations
+for references from arbitrary byte boundaries.
+For example:
+.sp
+.nf
+.in +4
+.data 0a0bcc    #producing 3 bytes of data.
+.word mylabel   #producing a reference
+.word endlabel - startlable #producing absolute length
+.in -4
+.fi
+.sp
+.H 2 "libdwarf relationship to Elf"
+When the documentation below refers to 'an elf section number'
+it is really only dependent on getting (via the callback
+function passed by the caller of
+\f(CWdwarf_producer_init()\fP)
+a sequence of integers back (with 1 as the lowest).
+When the documentation below refers to 'an Elf symbol index'
+it is really dependent on
+Elf symbol numbers
+only if
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+are being generated (see below).
+With
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+the library is generating Elf relocations
+and the section numbers in binary form so
+the section numbers and symbol indices must really
+be Elf (or elf-like) numbers.
+With
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+the values passed as symbol indexes can be any
+integer set or even pointer set.
+All that libdwarf assumes is that where values
+are unique they get unique values.
+Libdwarf does not generate any kind of symbol table
+from the numbers and does not check their
+uniqueness or lack thereof.
+.H 2 "libdwarf and relocations"
+With
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+libdwarf creates binary streams of debug information
+and arrays of relocation information describing
+the necessary relocation.
+The Elf section numbers and symbol numbers appear
+nowhere in the binary streams. Such appear
+only in the relocation information and the passed-back
+information from calls requesting the relocation information.
+As a consequence, the 'symbol indices' can be
+any pointer or integer value as the caller must
+arrange that the output deal with relocations.
+With
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+all the relocations are directly created by libdwarf
+as binary streams (libdwarf only creates the streams
+in memory,
+it does not write them to disk).
+.H 2 "symbols, addresses, and offsets"
+The following applies to calls that
+pass in symbol indices, addresses, and offsets, such
+as
+\f(CWdwarf_add_AT_targ_address() \fP
+\f(CWdwarf_add_arange_b()\fP
+and
+\f(CWdwarf_add_frame_fde_b()\fP.
+With
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+a passed in address is one of:
+a) a section offset and the (non-global) symbol index of
+a section symbol.
+b) A symbol index (global symbol) and a zero offset.
+With \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+the same approach can be used, or, instead,
+a passed in address may be
+c) a symbol handle and an offset.
+In this case, since it is up to the calling app to
+generate binary relocations (if appropriate)
+or to turn the binary stream into
+a text stream (for input to an assembler, if appropriate)
+the application has complete control of the interpretation
+of the symbol handles.
+.H 1 "Memory Management"
+Several of the functions that comprise the \fILibdwarf\fP
+producer interface dynamically allocate values and some
+return pointers to those spaces.
+The dynamically allocated spaces
+can not be reclaimed  (and must
+not be freed)  except by \f(CWdwarf_producer_finish(dbg)\fP.
+All data for a particular \f(CWDwarf_P_Debug\fP descriptor
+is separate from the data for any other
+\f(CWDwarf_P_Debug\fP descriptor in use in the library-calling
+application.
+.H 2 "Read-only Properties"
+All pointers returned by or as a result of a \fILibdwarf\fP call should
+be assumed to point to read-only memory.
+Except as defined by this document, the results are undefined for
+\fILibdwarf\fP clients that attempt to write to a region pointed to by a
+return value from a \fILibdwarf\fP call.
+.H 2 "Storage Deallocation"
+Calling \f(CWdwarf_producer_finish(dbg)\fP frees all the space, and
+invalidates all pointers returned from \f(CWLibdwarf\fP functions on
+or descended from \f(CWdbg\fP).
+.H 1 "Functional Interface"
+This section describes the functions available in the \fILibdwarf\fP
+library.  Each function description includes its definition, followed
+by a paragraph describing the function's operation.
+.P
+The functions may be categorized into groups:
+\fIinitialization and termination operations\fP,
+\fIdebugging information entry creation\fP,
+\fIElf section callback function\fP,
+\fIattribute creation\fP,
+\fIexpression creation\fP,
+\fIline number creation\fP,
+\fIfast-access (aranges) creation\fP,
+\fIfast-access (pubnames) creation\fP,
+\fIfast-access (weak names) creation\fP,
+\fImacro information creation\fP,
+\fIlow level (.debug_frame) creation\fP,
+and
+\fIlocation list (.debug_loc) creation\fP.
+.P
+The following sections describe these functions.
+.H 2 "Initialization and Termination Operations"
+These functions setup \f(CWLibdwarf\fP to accumulate debugging information
+for an object, usually a compilation-unit, provided by the producer.
+The actual addition of information is done by functions in the other
+sections of this document.  Once all the information has been added,
+functions from this section are used to transform the information to
+appropriate byte streams, and help to write out the byte streams to
+disk.
+Typically then, a producer application
+would create a \f(CWDwarf_P_Debug\fP
+descriptor to gather debugging information for a particular
+compilation-unit using \f(CWdwarf_producer_init()\fP.
+The producer application would
+use this \f(CWDwarf_P_Debug\fP descriptor to accumulate debugging
+information for this object using functions from other sections of
+this document.
+Once all the information had been added, it would
+call \f(CWdwarf_transform_to_disk_form()\fP to convert the accumulated
+information into byte streams in accordance with the \f(CWDWARF\fP
+standard.
+The application would then repeatedly call
+\f(CWdwarf_get_section_bytes()\fP
+for each of the \f(CW.debug_*\fP created.
+This gives the producer
+information about the data bytes to be written to disk.
+At this point,
+the producer would release all resource used by \f(CWLibdwarf\fP for
+this object by calling \f(CWdwarf_producer_finish()\fP.
+It is also possible to create assembler-input character streams
+from the byte streams created by this library.
+This feature requires slightly different interfaces than
+direct binary output.
+The details are mentioned in the text.
+.H 3 "dwarf_producer_init()"
+.DS
+\f(CWDwarf_P_Debug dwarf_producer_init(
+Dwarf_Unsigned flags,
+Dwarf_Callback_Func func,
+Dwarf_Handler errhand,
+Dwarf_Ptr errarg,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_producer_init() \fP returns a new
+\f(CWDwarf_P_Debug\fP descriptor that can be used to add \f(CWDwarf\fP
+information to the object.
+On error it returns \f(CWDW_DLV_BADADDR\fP.
+\f(CWflags\fP determine whether the target object is 64-bit or 32-bit.
+\f(CWfunc\fP is a pointer to a function called-back from \f(CWLibdwarf\fP
+whenever \f(CWLibdwarf\fP needs to create a new object section (as it will
+for each .debug_* section and related relocation section).
+\f(CWerrhand\fP
+is a pointer to a function that will be used for handling errors detected
+by \f(CWLibdwarf\fP.  \f(CWerrarg\fP is the default error argument used
+by the function pointed to by \f(CWerrhand\fP.
+.P
+The \f(CWflags\fP
+values are as follows:
+.in +4
+\f(CWDW_DLC_WRITE\fP
+is required.
+The values
+\f(CWDW_DLC_READ\fP
+\f(CWDW_DLC_RDWR\fP
+are not supported by the producer and must not be passed.
+If
+\f(CWDW_DLC_SIZE_64\fP
+is not OR'd into \f(CWflags\fP
+then
+\f(CWDW_DLC_SIZE_32\fP
+is assumed.
+Oring in both is an error.
+If
+\f(CWDW_DLC_ISA_IA64\fP
+is not OR'd into \f(CWflags\fP
+then
+\f(CWDW_DLC_ISA_MIPS\fP
+is assumed.
+Oring in both is an error.
+If
+\f(CWDW_DLC_TARGET_BIGENDIAN\fP
+is not OR'd into \f(CWflags\fP
+then
+endianness the same as the host is assumed.
+If
+\f(CWDW_DLC_TARGET_LITTLEENDIAN\fP
+is not OR'd into \f(CWflags\fP
+then
+endianness the same as the host is assumed.
+If both
+\f(CWDW_DLC_TARGET_LITTLEENDIAN\fP
+and
+\f(CWDW_DLC_TARGET_BIGENDIAN\fP
+are or-d in it is an error.
+Either one of two output forms is specifiable:
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+or
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP .
+The default is
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP .
+The
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+are relocations in a binary stream (as used
+in a MIPS Elf object).
+The
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+are the same relocations but expressed in an
+array of structures defined by libdwarf,
+which the caller of the relevant function
+(see below) must deal with appropriately.
+This method of expressing relocations allows
+the producer-application to easily produce
+assembler text output of debugging information.
+If
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+is OR'd into \f(CWflags\fP
+then relocations are returned not as streams
+but thru an array of structures.
+.in -4
+.P
+The function \f(CWfunc\fP
+must be provided by the user of this library.
+Its prototype is:
+.DS
+\f(CWtypedef int (*Dwarf_Callback_Func)(
+char* name,
+int                 size,
+Dwarf_Unsigned      type,
+Dwarf_Unsigned      flags,
+Dwarf_Unsigned      link,
+Dwarf_Unsigned      info,
+int*                sect_name_index,
+int*                error) \fP
+.DE
+For each section in the object file that \f(CWlibdwarf\fP
+needs to create, it calls this function once, passing in
+the section \f(CWname\fP, the section \f(CWtype\fP,
+the section \f(CWflags\fP, the \f(CWlink\fP field, and
+the \f(CWinfo\fP field.
+For an Elf object file these values
+should be appropriate Elf section header values.
+For example, for relocation callbacks, the \f(CWlink\fP
+field is supposed to be set (by the app) to the index
+of the symtab section (the link field passed thru the
+callback must be ignored by the app).
+And, for relocation callbacks, the \f(CWinfo\fP field
+is passed as the elf section number of the section
+the relocations apply to.
+On success
+the user function should return the Elf section number of the
+newly created Elf section.
+.P
+On success, the function should also set the integer
+pointed to by \f(CWsect_name_index\fP to the
+Elf symbol number assigned in the Elf symbol table of the
+new Elf section.
+This symbol number is needed with relocations
+dependent on the relocation of this new section.
+Because "int *" is not guaranteed to work with elf 'symbols'
+that are really pointers,
+It is better to use the
+\f(CWdwarf_producer_init_b()\fP
+interface.
+.P
+For example, the \f(CW.debug_line\fP section's third
+data element (in a compilation unit) is the offset from the
+beginning of the \f(CW.debug_info\fP section of the compilation
+unit entry for this \f(CW.debug_line\fP set.
+The relocation entry in \f(CW.rel.debug_line\fP
+for this offset
+must have the relocation symbol index of the
+symbol \f(CW.debug_info\fP  returned
+by the callback of that section-creation through
+the pointer \f(CWsect_name_index\fP.
+.P
+On failure, the function should return -1 and set the \f(CWerror\fP
+integer to an error code.
+.P
+Nothing in libdwarf actually depends on the section index
+returned being a real Elf section.
+The Elf section is simply useful for generating relocation
+records.
+Similarly, the Elf symbol table index returned thru
+the \f(CWsect_name_index\fP must simply be an index
+that can be used in relocations against this section.
+The application will probably want to note the
+values passed to this function in some form, even if
+no Elf file is being produced.
+.H 3 "dwarf_producer_init_b()"
+.DS
+\f(CWDwarf_P_Debug dwarf_producer_init_b(
+Dwarf_Unsigned flags,
+Dwarf_Callback_Func_b func,
+Dwarf_Handler errhand,
+Dwarf_Ptr errarg,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_producer_init_b() \fP
+is the same as \f(CWdwarf_producer_init() \fP
+except that the callback function uses
+Dwarf_Unsigned rather than int as the
+type of the symbol-index returned to libdwarf
+thru the pointer argument (see below).
+.P
+The \f(CWflags\fP
+values are as follows:
+.in +4
+\f(CWDW_DLC_WRITE\fP
+is required.
+The values
+\f(CWDW_DLC_READ\fP
+\f(CWDW_DLC_RDWR\fP
+are not supported by the producer and must not be passed.
+If
+\f(CWDW_DLC_SIZE_64\fP
+is not OR'd into \f(CWflags\fP
+then
+\f(CWDW_DLC_SIZE_32\fP
+is assumed.
+Oring in both is an error.
+If
+\f(CWDW_DLC_ISA_IA64\fP
+is not OR'd into \f(CWflags\fP
+then
+\f(CWDW_DLC_ISA_MIPS\fP
+is assumed.
+Oring in both is an error.
+Either one of two output forms are specifiable:
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+or
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP .
+\f(CWdwarf_producer_init_b() \fP
+is usable with
+either output form.
+Either one of two output forms is specifiable:
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+or
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP .
+The default is
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP .
+The
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+are relocations in a binary stream (as used
+in a MIPS Elf object).
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+are OR'd into flags
+to cause
+the same relocations to be expressed in an
+array of structures defined by libdwarf,
+which the caller of the relevant function
+(see below) must deal with appropriately.
+This method of expressing relocations allows
+the producer-application to easily produce
+assembler text output of debugging information.
+.in -4
+.P
+The function \f(CWfunc\fP
+must be provided by the user of this library.
+Its prototype is:
+.DS
+\f(CWtypedef int (*Dwarf_Callback_Func_b)(
+char* name,
+int                 size,
+Dwarf_Unsigned      type,
+Dwarf_Unsigned      flags,
+Dwarf_Unsigned      link,
+Dwarf_Unsigned      info,
+Dwarf_Unsigned*     sect_name_index,
+int*                error) \fP
+.DE
+For each section in the object file that \f(CWlibdwarf\fP
+needs to create, it calls this function once, passing in
+the section \f(CWname\fP, the section \f(CWtype\fP,
+the section \f(CWflags\fP, the \f(CWlink\fP field, and
+the \f(CWinfo\fP field.  For an Elf object file these values
+should be appropriate Elf section header values.
+For example, for relocation callbacks, the \f(CWlink\fP
+field is supposed to be set (by the app) to the index
+of the symtab section (the link field passed thru the
+callback must be ignored by the app).
+And, for relocation callbacks, the \f(CWinfo\fP field
+is passed as the elf section number of the section
+the relocations apply to.
+On success
+the user function should return the Elf section number of the
+newly created Elf section.
+.P
+On success, the function should also set the integer
+pointed to by \f(CWsect_name_index\fP to the
+Elf symbol number assigned in the Elf symbol table of the
+new Elf section.
+This symbol number is needed with relocations
+dependent on the relocation of this new section.
+.P
+For example, the \f(CW.debug_line\fP section's third
+data element (in a compilation unit) is the offset from the
+beginning of the \f(CW.debug_info\fP section of the compilation
+unit entry for this \f(CW.debug_line\fP set.
+The relocation entry in \f(CW.rel.debug_line\fP
+for this offset
+must have the relocation symbol index of the
+symbol \f(CW.debug_info\fP  returned
+by the callback of that section-creation through
+the pointer \f(CWsect_name_index\fP.
+.P
+On failure, the function should return -1 and set the \f(CWerror\fP
+integer to an error code.
+.P
+Nothing in libdwarf actually depends on the section index
+returned being a real Elf section.
+The Elf section is simply useful for generating relocation
+records.
+Similarly, the Elf symbol table index returned thru
+the \f(CWsect_name_index\fP must simply be an index
+that can be used in relocations against this section.
+The application will probably want to note the
+values passed to this function in some form, even if
+no Elf file is being produced.
+Note that the \f(CWDwarf_Callback_Func_b() \fP form
+passes back the sect_name_index as a Dwarf_Unsigned.
+This is guaranteed large enough to hold a pointer.
+(the other functional interfaces have versions with
+the 'symbol index' as a Dwarf_Unsigned too. See below).
+If \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+is in use, then the symbol index is simply an arbitrary
+value (from the point of view of libdwarf) so the
+caller can put anything in it:
+a normal elf symbol index,
+a pointer to a struct (with arbitrary contents)
+(the caller must cast to/from Dwarf_Unsigned
+as appropriate),
+or some other kind of pointer or value.
+The values show up in the
+output of \f(CWdwarf_get_relocation_info()\fP
+(described below) and are not emitted anywhere else.
+.H 3 "dwarf_transform_to_disk_form()"
+.DS
+\f(CWDwarf_Signed dwarf_transform_to_disk_form(
+Dwarf_P_Debug dbg,
+Dwarf_Error* error) \fP
+.DE
+The function \f(CWdwarf_transform_to_disk_form() \fP does the actual
+conversion of the \f(CWDwarf\fP information provided so far, to the
+form that is
+normally written out as \f(CWElf\fP sections.
+In other words,
+once all DWARF information has been passed to \f(CWLibdwarf\fP, call
+\f(CWdwarf_transform_to_disk_form() \fP to transform all the accumulated
+data into byte streams.
+This includes turning relocation information
+into byte streams (and possibly relocation arrays).
+This function does not write anything to disk.  If
+successful, it returns a count of the number of \f(CWElf\fP sections
+ready to be retrieved (and, normally, written to disk).
+In case of error, it returns
+\f(CWDW_DLV_NOCOUNT\fP.
+.H 3 "dwarf_get_section_bytes()"
+.DS
+\f(CWDwarf_Ptr dwarf_get_section_bytes(
+Dwarf_P_Debug dbg,
+Dwarf_Signed dwarf_section,
+Dwarf_Signed *elf_section_index,
+Dwarf_Unsigned *length,
+Dwarf_Error* error)\fP
+.DE
+The function \f(CWdwarf_get_section_bytes() \fP must be called repetitively,
+with the index \f(CWdwarf_section\fP starting at 0 and continuing for the
+number of sections
+returned by \f(CWdwarf_transform_to_disk_form() \fP.
+It returns \f(CWNULL\fP to indicate that there are no more sections of
+\f(CWDwarf\fP information.
+For each non-NULL return, the return value
+points to \f(CW*length\fP bytes of data that are normally
+added to the output
+object in \f(CWElf\fP section \f(CW*elf_section\fP by the producer application.
+It is illegal to call these in any order other than 0 thru N-1 where
+N is the number of dwarf sections
+returned by \f(CWdwarf_transform_to_disk_form() \fP.
+The \f(CWdwarf_section\fP
+number is actually ignored: the data is returned as if the
+caller passed in the correct dwarf_section numbers in the
+required sequence.
+The \f(CWerror\fP argument is not used.
+.P
+There is no requirement that the section bytes actually
+be written to an elf file.
+For example, consider the .debug_info section and its
+relocation section (the call back function would resulted in
+assigning 'section' numbers and the link field to tie these
+together (.rel.debug_info would have a link to .debug_info).
+One could examine the relocations, split the .debug_info
+data at relocation boundaries, emit byte streams (in hex)
+as assembler output, and at each relocation point,
+emit an assembler directive with a symbol name for the assembler.
+Examining the relocations is awkward though.
+It is much better to use \f(CWdwarf_get_section_relocation_info() \fP
+.P
+The memory space of the section byte stream is freed
+by the \f(CWdwarf_producer_finish() \fP call
+(or would be if the \f(CWdwarf_producer_finish() \fP
+was actually correct), along
+with all the other space in use with that Dwarf_P_Debug.
+.H 3 "dwarf_get_relocation_info_count()"
+.DS
+\f(CWint  dwarf_get_relocation_info_count(
+Dwarf_P_Debug dbg,
+Dwarf_Unsigned *count_of_relocation_sections ,
+	int            *drd_buffer_version,
+Dwarf_Error* error)\fP
+.DE
+The function \f(CWdwarf_get_relocation_info() \fP
+returns, thru  the pointer \f(CWcount_of_relocation_sections\fP, the
+number of times that \f(CWdwarf_get_relocation_info() \fP
+should be called.
+The function \f(CWdwarf_get_relocation_info() \fP
+returns DW_DLV_OK if the call was successful (the
+\f(CWcount_of_relocation_sections\fP is therefore meaningful,
+though \f(CWcount_of_relocation_sections\fP
+could be zero).
+\f(CW*drd_buffer_version\fP
+is the value 2.
+If the structure pointed to by
+the \f(CW*reldata_buffer\fP
+changes this number will change.
+The application should verify that the number is
+the version it understands (that it matches
+the value of DWARF_DRD_BUFFER_VERSION (from libdwarf.h)).
+The value 1 version was never used in production
+MIPS libdwarf (version 1 did exist in source).
+It returns DW_DLV_NO_ENTRY if
+\f(CWcount_of_relocation_sections\fP is not meaningful
+because \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP was not
+passed in the
+\f(CWdwarf_producer_init() \fP
+(or
+\f(CWdwarf_producer_init_b() \fP ) call.
+It returns DW_DLV_ERROR if there was an error,
+in which case
+\f(CWcount_of_relocation_sections\fP is not meaningful.
+.H 3 "dwarf_get_relocation_info()"
+.DS
+\f(CWint dwarf_get_relocation_info(
+Dwarf_P_Debug dbg,
+Dwarf_Signed *elf_section_index,
+	Dwarf_Signed *elf_section_index_link,
+Dwarf_Unsigned *relocation_buffer_count,
+	Dwarf_Relocation_Data *reldata_buffer,
+Dwarf_Error* error)\fP
+.DE
+The function \f(CWdwarf_get_relocation_info() \fP
+should normally be called repetitively,
+for the number of relocation sections that
+\f(CWdwarf_get_relocation_info_count() \fP
+indicated exist.
+It returns \f(CWDW_DLV_OK\fP to indicate that
+valid values are returned thru the pointer arguments.
+The \f(CWerror\fP argument is not set.
+It returns DW_DLV_NO_ENTRY if there are no entries
+(the count of relocation arrays is zero.).
+The \f(CWerror\fP argument is not set.
+It returns \f(CWDW_DLV_ERROR\fP if there is an error.
+Calling \f(CWdwarf_get_relocation_info() \fP
+more than the number of times indicated by
+\f(CWdwarf_get_relocation_info_count() \fP
+(without an intervening call to
+\f(CWdwarf_reset_section_bytes() \fP )
+results in a return of \f(CWDW_DLV_ERROR\fP once past
+the valid count.
+The \f(CWerror\fP argument is set to indicate the error.
+Now consider the returned-thru-pointer values for
+\f(CWDW_DLV_OK\fP .
+\f(CW*elf_section_index\fP
+is the 'elf section index' of the section implied by
+this group of relocations.
+\f(CW*elf_section_index_link\fP
+is the section index of the section that these
+relocations apply to.
+\f(CW*relocation_buffer_count\fP
+is the number of array entries of relocation information
+in the array pointed to by
+\f(CW*reldata_buffer\fP .
+\f(CW*reldata_buffer\fP
+points to an array of 'struct Dwarf_Relocation_Data_s'
+structures.
+The version 2 array information is as follows:
+.nf
+enum Dwarf_Rel_Type {dwarf_drt_none,
+dwarf_drt_data_reloc,
+dwarf_drt_segment_rel,
+dwarf_drt_first_of_length_pair,
+dwarf_drt_second_of_length_pair
+};
+typedef struct Dwarf_Relocation_Data_s  * Dwarf_Relocation_Data;
+struct Dwarf_Relocation_Data_s {
+unsigned char        drd_type;   /* contains Dwarf_Rel_Type */
+	unsigned char        drd_length; /* typically 4 or 8 */
+Dwarf_Unsigned       drd_offset; /* where the data to reloc is */
+Dwarf_Unsigned       drd_symbol_index;
+};
+.fi
+The \f(CWDwarf_Rel_Type\fP enum is encoded (via casts if necessary)
+into the single unsigned char \f(CWdrd_type\fP field to control
+the space used for this information (keep the space to 1 byte).
+The unsigned char \f(CWdrd_length\fP field
+holds the size in bytes of the field to be relocated.
+So for elf32 object formats with 32 bit apps, \f(CWdrd_length\fP
+will be 4.  For objects with MIPS -64 contents,
+\f(CWdrd_length\fP will be 8.
+For some dwarf 64 bit environments, such as ia64, \f(CWdrd_length\fP
+is 4 for some relocations (file offsets, for example)
+and 8 for others (run time
+addresses, for example).
+If \f(CWdrd_type\fP is \f(CWdwarf_drt_none\fP, this is an unused slot
+and it should be ignored.
+If \f(CWdrd_type\fP is \f(CWdwarf_drt_data_reloc\fP
+this is an ordinary relocation.
+The relocation type means either
+(R_MIPS_64) or (R_MIPS_32) (or the like for
+the particular ABI.
+f(CWdrd_length\fP gives the length of the field to be relocated.
+\f(CWdrd_offset\fP is an offset (of the
+value to be relocated) in
+the section this relocation stuff is linked to.
+\f(CWdrd_symbol_index\fP is the symbol index (if elf symbol
+indices were provided) or the handle to arbitrary
+information (if that is what the caller passed in
+to the relocation-creating dwarf calls) of the symbol
+that the relocation is relative to.
+When \f(CWdrd_type\fP is \f(CWdwarf_drt_first_of_length_pair\fP
+the next data record will be \f(CWdrt_second_of_length_pair\fP
+and the \f(CWdrd_offset\fP of the two data records will match.
+The relevant 'offset' in the section this reloc applies to
+should contain a symbolic pair like
+.nf
+.in +4
+.word    second_symbol - first_symbol
+.in -4
+.fi
+to generate a length.
+\f(CWdrd_length\fP gives the length of the field to be relocated.
+\f(CWdrt_segment_rel\fP means (R_MIPS_SCN_DISP)
+is the real relocation (R_MIPS_SCN_DISP applies to
+exception tables and this part may need further work).
+\f(CWdrd_length\fP gives the length of the field to be relocated.
+.P
+The memory space of the section byte stream is freed
+by the \f(CWdwarf_producer_finish() \fP call
+(or would be if the \f(CWdwarf_producer_finish() \fP
+was actually correct), along
+with all the other space in use with that Dwarf_P_Debug.
+.H 3 "dwarf_reset_section_bytes()"
+.DS
+\f(CWvoid dwarf_reset_section_bytes(
+Dwarf_P_Debug dbg
+) \fP
+.DE
+The function \f(CWdwarf_reset_section_bytes() \fP
+is used to reset the internal information so that
+\f(CWdwarf_get_section_bytes() \fP will begin (on the next
+call) at the initial dwarf section again.
+It also resets so that calls to
+\f(CWdwarf_get_relocation_info() \fP
+will begin again at the initial array of relocation information.
+Some dwarf producers need to be able to run thru
+the \f(CWdwarf_get_section_bytes()\fP
+and/or
+the \f(CWdwarf_get_relocation_info()\fP
+calls more than once and this call makes additional
+passes possible.
+The set of Dwarf_Ptr values returned is identical to the
+set returned by the first pass.
+It is acceptable to call this before finishing a pass
+of \f(CWdwarf_get_section_bytes()\fP
+or
+\f(CWdwarf_get_relocation_info()\fP
+calls.
+No errors are possible as this just resets some
+internal pointers.
+It is unwise to call this before
+\f(CWdwarf_transform_to_disk_form() \fP has been called.
+.P
+.H 3 "dwarf_producer_finish()"
+.DS
+\f(CWDwarf_Unsigned dwarf_producer_finish(
+Dwarf_P_Debug dbg,
+Dwarf_Error* error) \fP
+.DE
+The function \f(CWdwarf_producer_finish() \fP should be called after all
+the bytes of data have been copied somewhere
+(normally the bytes are written to disk).
+It frees all dynamic space
+allocated for \f(CWdbg\fP, include space for the structure pointed to by
+\f(CWdbg\fP.
+This should not be called till the data have been
+copied or written
+to disk or are no longer of interest.
+It returns non-zero if successful, and \f(CWDW_DLV_NOCOUNT\fP
+if there is an error.
+.H 2 "Debugging Information Entry Creation"
+The functions in this section add new \f(CWDIE\fPs to the object,
+and also the relationships among the \f(CWDIE\fP to be specified
+by linking them up as parents, children, left or right siblings
+of each other.
+In addition, there is a function that marks the
+root of the graph thus created.
+.H 3 "dwarf_add_die_to_debug()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_die_to_debug(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die first_die,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_die_to_debug() \fP indicates to \f(CWLibdwarf\fP
+the root \f(CWDIE\fP of the \f(CWDIE\fP graph that has been built so
+far.
+It is intended to mark the compilation-unit \f(CWDIE\fP for the
+object represented by \f(CWdbg\fP.
+The root \f(CWDIE\fP is specified
+by \f(CWfirst_die\fP.
+It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_new_die()"
+.DS
+\f(CWDwarf_P_Die dwarf_new_die(
+Dwarf_P_Debug dbg,
+Dwarf_Tag new_tag,
+Dwarf_P_Die parent,
+Dwarf_P_Die child,
+Dwarf_P_Die left_sibling,
+Dwarf_P_Die right_sibling,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_new_die() \fP creates a new \f(CWDIE\fP with
+its parent, child, left sibling, and right sibling \f(CWDIE\fPs
+specified by \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP,
+and \f(CWright_sibling\fP, respectively.
+There is no requirement
+that all of these \f(CWDIE\fPs be specified, i.e. any of these
+descriptors may be \f(CWNULL\fP.
+If none is specified, this will
+be an isolated \f(CWDIE\fP.
+A \f(CWDIE\fP is
+transformed to disk form by \f(CWdwarf_transform_to_disk_form() \fP
+only if there is a path from
+the \f(CWDIE\fP specified by \f(CWdwarf_add_die_to_debug\fP to it.
+This function returns \f(CWDW_DLV_BADADDR\fP on error.
+\f(CWnew_tag\fP is the tag which is given to the new \f(CWDIE\fP.
+\f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP, and
+\f(CWright_sibling\fP are pointers to establish links to existing
+\f(CWDIE\fPs.  Only one of \f(CWparent\fP, \f(CWchild\fP,
+\f(CWleft_sibling\fP, and \f(CWright_sibling\fP may be non-NULL.
+If \f(CWparent\fP (\f(CWchild\fP) is given, the \f(CWDIE\fP is
+linked into the list after (before) the \f(CWDIE\fP pointed to.
+If \f(CWleft_sibling\fP (\f(CWright_sibling\fP) is given, the
+\f(CWDIE\fP is linked into the list after (before) the \f(CWDIE\fP
+pointed to.
+To add attributes to the new \f(CWDIE\fP, use the \f(CWAttribute Creation\fP
+functions defined in the next section.
+.H 3 "dwarf_die_link()"
+.DS
+\f(CWDwarf_P_Die dwarf_die_link(
+Dwarf_P_Die die,
+Dwarf_P_Die parent,
+Dwarf_P_Die child,
+Dwarf_P_Die left-sibling,
+Dwarf_P_Die right_sibling,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_die_link() \fP links an existing \f(CWDIE\fP
+described by the given \f(CWdie\fP to other existing \f(CWDIE\fPs.
+The given \f(CWdie\fP can be linked to a parent \f(CWDIE\fP, a child
+\f(CWDIE\fP, a left sibling \f(CWDIE\fP, or a right sibling \f(CWDIE\fP
+by specifying non-NULL \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP,
+and \f(CWright_sibling\fP \f(CWDwarf_P_Die\fP descriptors.
+It returns
+the given \f(CWDwarf_P_Die\fP descriptor, \f(CWdie\fP, on success,
+and \f(CWDW_DLV_BADADDR\fP on error.
+Only one of \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP,
+and \f(CWright_sibling\fP may be non-NULL.
+If \f(CWparent\fP
+(\f(CWchild\fP) is given, the \f(CWDIE\fP is linked into the list
+after (before) the \f(CWDIE\fP pointed to.
+If \f(CWleft_sibling\fP
+(\f(CWright_sibling\fP) is given, the \f(CWDIE\fP is linked into
+the list after (before) the \f(CWDIE\fP pointed to.
+Non-NULL links
+overwrite the corresponding links the given \f(CWdie\fP may have
+had before the call to \f(CWdwarf_die_link() \fP.
+.H 2 "Attribute Creation"
+The functions in this section add attributes to a \f(CWDIE\fP.
+These functions return a \f(CWDwarf_P_Attribute\fP descriptor
+that represents the attribute added to the given \f(CWDIE\fP.
+In most cases the return value is only useful to determine if
+an error occurred.
+Some of the attributes have values that are relocatable.
+They
+need a symbol with respect to which the linker will perform
+relocation.
+This symbol is specified by means of an index into
+the Elf symbol table for the object
+(of course, the symbol index can be more general than an index).
+.H 3 "dwarf_add_AT_location_expr()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_location_expr(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_P_Expr loc_expr,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_location_expr() \fP adds the attribute
+specified by \f(CWattr\fP to the \f(CWDIE\fP descriptor given by
+\f(CWownerdie\fP.  The attribute should be one that has a location
+expression as its value.  The location expression that is the value
+is represented by the \f(CWDwarf_P_Expr\fP descriptor \f(CWloc_expr\fP.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+given, on success.  On error it returns \f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_name()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_name(
+Dwarf_P_Die ownerdie,
+char *name,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_name() \fP adds the string specified
+by \f(CWname\fP as the value of the \f(CWDW_AT_name\fP attribute
+for the given \f(CWDIE\fP, \f(CWownerdie\fP.  It returns the
+\f(CWDwarf_P_attribute\fP descriptor for the \f(CWDW_AT_name\fP
+attribute on success.  On error, it returns \f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_comp_dir()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_comp_dir(
+Dwarf_P_Die ownerdie,
+char *current_working_directory,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_comp_dir() \fP adds the string given by
+\f(CWcurrent_working_directory\fP as the value of the \f(CWDW_AT_comp_dir\fP
+attribute for the \f(CWDIE\fP described by the given \f(CWownerdie\fP.
+It returns the \f(CWDwarf_P_Attribute\fP for this attribute on success.
+On error, it returns \f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_producer()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_producer(
+Dwarf_P_Die ownerdie,
+char *producer_string,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_producer() \fP adds the string given by
+\f(CWproducer_string\fP as the value of the \f(CWDW_AT_producer\fP
+attribute for the \f(CWDIE\fP given by \f(CWownerdie\fP.  It returns
+the \f(CWDwarf_P_Attribute\fP descriptor representing this attribute
+on success.  On error, it returns \f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_const_value_signedint()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_const_value_signedint(
+Dwarf_P_Die ownerdie,
+Dwarf_Signed signed_value,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_const_value_signedint() \fP adds the
+given \f(CWDwarf_Signed\fP value \f(CWsigned_value\fP as the value
+of the \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP
+described by the given \f(CWownerdie\fP.  It returns the
+\f(CWDwarf_P_Attribute\fP descriptor for this attribute on success.
+On error, it returns \f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_const_value_unsignedint()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_const_value_unsignedint(
+Dwarf_P_Die ownerdie,
+Dwarf_Unsigned unsigned_value,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_const_value_unsignedint() \fP adds the
+given \f(CWDwarf_Unsigned\fP value \f(CWunsigned_value\fP as the value
+of the \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP described
+by the given \f(CWownerdie\fP.  It returns the \f(CWDwarf_P_Attribute\fP
+descriptor for this attribute on success.  On error, it returns
+\f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_const_value_string()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_const_value_string(
+Dwarf_P_Die ownerdie,
+char *string_value,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_const_value_string() \fP adds the
+string value given by \f(CWstring_value\fP as the value of the
+\f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP described
+by the given \f(CWownerdie\fP.  It returns the \f(CWDwarf_P_Attribute\fP
+descriptor for this attribute on success.  On error, it returns
+\f(CWDW_DLV_BADADDR\fP.
+.H 3 "dwarf_add_AT_targ_address()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_targ_address(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Unsigned pc_value,
+Dwarf_Signed sym_index,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_targ_address() \fP adds an attribute that
+belongs to the "address" class to the die specified by \f(CWownerdie\fP.
+The attribute is specified by \f(CWattr\fP, and the object that the
+\f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The relocatable
+address that is the value of the attribute is specified by \f(CWpc_value\fP.
+The symbol to be used for relocation is specified by the \f(CWsym_index\fP,
+which is the index of the symbol in the Elf symbol table.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+on success, and \f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_AT_targ_address_b()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_targ_address_b(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Unsigned pc_value,
+Dwarf_Unsigned sym_index,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_targ_address_b() \fP
+is identical to \f(CWdwarf_add_AT_targ_address_b() \fP
+except that \f(CWsym_index() \fP is guaranteed to
+be large enough that it can contain a pointer to
+arbitrary data (so the caller can pass in a real elf
+symbol index, an arbitrary number, or a pointer
+to arbitrary data).
+The ability to pass in a pointer thru \f(CWsym_index() \fP
+is only usable with
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP.
+The \f(CWpc_value\fP
+is put into the section stream output and
+the \f(CWsym_index\fP is applied to the relocation
+information.
+Do not use this function for attr \f(CWDW_AT_high_pc\fP
+if the value to be recorded is an offset (not a pc)
+[ use \f(CWdwarf_add_AT_unsigned_const()\fP  (for example)
+instead].
+.H 3 "dwarf_add_AT_dataref()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_dataref(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Unsigned pc_value,
+Dwarf_Unsigned sym_index,
+Dwarf_Error *error) \fP
+.DE
+This is very similar to \f(CWdwarf_add_AT_targ_address_b() \fP
+but results in a different FORM (results in DW_FORM_data4
+or DW_FORM_data8).
+Useful for adding relocatable addresses in location lists.
+\f(CWsym_index() \fP is guaranteed to
+be large enough that it can contain a pointer to
+arbitrary data (so the caller can pass in a real elf
+symbol index, an arbitrary number, or a pointer
+to arbitrary data).
+The ability to pass in a pointer thru \f(CWsym_index() \fP
+is only usable with
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP.
+The \f(CWpc_value\fP
+is put into the section stream output and
+the \f(CWsym_index\fP is applied to the relocation
+information.
+Do not use this function for \f(CWDW_AT_high_pc\fP, use
+\f(CWdwarf_add_AT_unsigned_const()\fP  [ (for example)
+if the value to be recorded is
+an offset of \f(CWDW_AT_low_pc\fP]
+or \f(CWdwarf_add_AT_targ_address_b()\fP [ if the value
+to be recorded is an address].
+.H 3 "dwarf_add_AT_ref_address()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_ref_address(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Unsigned pc_value,
+Dwarf_Unsigned sym_index,
+Dwarf_Error *error) \fP
+.DE
+This is very similar to \f(CWdwarf_add_AT_targ_address_b() \fP
+but results in a different FORM (results in \f(CWDW_FORM_ref_addr\fP
+being generated).
+Useful for  \f(CWDW_AT_type\fP and \f(CWDW_AT_import\fP attributes.
+\f(CWsym_index() \fP is guaranteed to
+be large enough that it can contain a pointer to
+arbitrary data (so the caller can pass in a real elf
+symbol index, an arbitrary number, or a pointer
+to arbitrary data).
+The ability to pass in a pointer thru \f(CWsym_index() \fP
+is only usable with
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP.
+The \f(CWpc_value\fP
+is put into the section stream output and
+the \f(CWsym_index\fP is applied to the relocation
+information.
+Do not use this function for \f(CWDW_AT_high_pc\fP.
+.H 3 "dwarf_add_AT_unsigned_const()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_unsigned_const(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Unsigned value,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_unsigned_const() \fP adds an attribute
+with a \f(CWDwarf_Unsigned\fP value belonging to the "constant" class,
+to the \f(CWDIE\fP specified by \f(CWownerdie\fP.  The object that
+the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The attribute
+is specified by \f(CWattr\fP, and its value is specified by \f(CWvalue\fP.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+on success, and \f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_AT_signed_const()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_signed_const(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Signed value,
+Dwarf_Error *error) \fP
+.DE
+The function \f(CWdwarf_add_AT_signed_const() \fP adds an attribute
+with a \f(CWDwarf_Signed\fP value belonging to the "constant" class,
+to the \f(CWDIE\fP specified by \f(CWownerdie\fP.  The object that
+the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The attribute
+is specified by \f(CWattr\fP, and its value is specified by \f(CWvalue\fP.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+on success, and \f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_AT_reference()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_reference(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_P_Die otherdie,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_AT_reference()\fP adds an attribute
+with a value that is a reference to another \f(CWDIE\fP in the
+same compilation-unit to the \f(CWDIE\fP specified by \f(CWownerdie\fP.
+The object that the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.
+The attribute is specified by \f(CWattr\fP, and the other \f(CWDIE\fP
+being referred to is specified by \f(CWotherdie\fP.
+This cannot generate DW_FORM_ref_addr references to
+\f(CWDIE\fPs in other compilation units.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+on success, and \f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_AT_flag()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_flag(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+Dwarf_Small flag,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_AT_flag()\fP adds an attribute with
+a \f(CWDwarf_Small\fP value belonging to the "flag" class, to the
+\f(CWDIE\fP specified by \f(CWownerdie\fP.  The object that the
+\f(CWDIE\fP belongs to is specified by \f(CWdbg\fP.  The attribute
+is specified by \f(CWattr\fP, and its value is specified by \f(CWflag\fP.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+on success, and \f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_AT_string()"
+.DS
+\f(CWDwarf_P_Attribute dwarf_add_AT_string(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die ownerdie,
+Dwarf_Half attr,
+char *string,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_AT_string()\fP adds an attribute with a
+value that is a character string to the \f(CWDIE\fP specified by
+\f(CWownerdie\fP.  The object that the \f(CWDIE\fP belongs to is
+specified by \f(CWdbg\fP.  The attribute is specified by \f(CWattr\fP,
+and its value is pointed to by \f(CWstring\fP.
+It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute
+on success, and \f(CWDW_DLV_BADADDR\fP on error.
+.H 2 "Expression Creation"
+The following functions are used to convert location expressions into
+blocks so that attributes with values that are location expressions
+can store their values as a \f(CWDW_FORM_blockn\fP value.  This is for
+both .debug_info and .debug_loc expression blocks.
+To create an expression, first call \f(CWdwarf_new_expr()\fP to get
+a \f(CWDwarf_P_Expr\fP descriptor that can be used to build up the
+block containing the location expression.  Then insert the parts of
+the expression in prefix order (exactly the order they would be
+interpreted in in an expression interpreter).  The bytes of the
+expression are then built-up as specified by the user.
+.H 3 "dwarf_new_expr()"
+.DS
+\f(CWDwarf_Expr dwarf_new_expr(
+Dwarf_P_Debug dbg,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_new_expr()\fP creates a new expression area
+in which a location expression stream can be created.  It returns
+a \f(CWDwarf_P_Expr\fP descriptor that can be used to add operators
+to build up a location expression.  It returns \f(CWNULL\fP on error.
+.H 3 "dwarf_add_expr_gen()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_expr_gen(
+Dwarf_P_Expr expr,
+Dwarf_Small opcode,
+Dwarf_Unsigned val1,
+Dwarf_Unsigned val2,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_expr_gen()\fP takes an operator specified
+by \f(CWopcode\fP, along with up to 2 operands specified by \f(CWval1\fP,
+and \f(CWval2\fP, converts it into the \f(CWDwarf\fP representation and
+appends the bytes to the byte stream being assembled for the location
+expression represented by \f(CWexpr\fP.  The first operand, if present,
+to \f(CWopcode\fP is in \f(CWval1\fP, and the second operand, if present,
+is in \f(CWval2\fP.  Both the operands may actually be signed or unsigned
+depending on \f(CWopcode\fP.  It returns the number of bytes in the byte
+stream for \f(CWexpr\fP currently generated, i.e. after the addition of
+\f(CWopcode\fP.  It returns \f(CWDW_DLV_NOCOUNT\fP on error.
+The function \f(CWdwarf_add_expr_gen()\fP works for all opcodes except
+those that have a target address as an operand.  This is because it does
+not set up a relocation record that is needed when target addresses are
+involved.
+.H 3 "dwarf_add_expr_addr()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_expr_addr(
+Dwarf_P_Expr expr,
+Dwarf_Unsigned address,
+Dwarf_Signed sym_index,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_expr_addr()\fP is used to add the
+\f(CWDW_OP_addr\fP opcode to the location expression represented
+by the given \f(CWDwarf_P_Expr\fP descriptor, \f(CWexpr\fP.  The
+value of the relocatable address is given by \f(CWaddress\fP.
+The symbol to be used for relocation is given by \f(CWsym_index\fP,
+which is the index of the symbol in the Elf symbol table.  It returns
+the number of bytes in the byte stream for \f(CWexpr\fP currently
+generated, i.e. after the addition of the \f(CWDW_OP_addr\fP operator.
+It returns \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_add_expr_addr_b()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_expr_addr_b(
+Dwarf_P_Expr expr,
+Dwarf_Unsigned address,
+Dwarf_Unsigned sym_index,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_expr_addr_f()\fP is
+identical to \f(CWdwarf_add_expr_addr()\fP
+except that \f(CWsym_index() \fP is guaranteed to
+be large enough that it can contain a pointer to
+arbitrary data (so the caller can pass in a real elf
+symbol index, an arbitrary number, or a pointer
+to arbitrary data).
+The ability to pass in a pointer thru \f(CWsym_index() \fP
+is only usable with
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP.
+.H 3 "dwarf_expr_current_offset()"
+.DS
+\f(CWDwarf_Unsigned dwarf_expr_current_offset(
+Dwarf_P_Expr expr,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_expr_current_offset()\fP returns the number
+of bytes currently in the byte stream for the location expression
+represented by the given \fCW(Dwarf_P_Expr\fP descriptor, \f(CWexpr\fP.
+It returns \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_expr_into_block()"
+.DS
+\f(CWDwarf_Addr dwarf_expr_into_block(
+Dwarf_P_Expr expr,
+Dwarf_Unsigned *length,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_expr_into_block()\fP returns the address
+of the start of the byte stream generated for the location expression
+represented by the given \f(CWDwarf_P_Expr\fP descriptor, \f(CWexpr\fP.
+The length of the byte stream is returned in the location pointed to
+by \f(CWlength\fP.  It returns \f(CWDW_DLV_BADADDR\fP on error.
+.H 2 "Line Number Operations"
+These are operations on the .debug_line section.
+They provide
+information about instructions in the program and the source
+lines the instruction come from.
+Typically, code is generated
+in contiguous blocks, which may then be relocated as contiguous
+blocks.
+To make the provision of relocation information more
+efficient, the information is recorded in such a manner that only
+the address of the start of the block needs to be relocated.
+This is done by providing the address of the first instruction
+in a block using the function \f(CWdwarf_lne_set_address()\fP.
+Information about the instructions in the block are then added
+using the function \f(CWdwarf_add_line_entry()\fP, which specifies
+offsets from the address of the first instruction.
+The end of
+a contiguous block is indicated by calling the function
+\f(CWdwarf_lne_end_sequence()\fP.
+.P
+Line number operations do not support
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP.
+.H 3 "dwarf_add_line_entry()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_line_entry(
+Dwarf_P_Debug dbg,
+Dwarf_Unsigned file_index,
+Dwarf_Addr code_offset,
+Dwarf_Unsigned lineno,
+Dwarf_Signed column_number,
+Dwarf_Bool is_source_stmt_begin,
+Dwarf_Bool is_basic_block_begin,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_line_entry()\fP adds an entry to the
+section containing information about source lines.
+It specifies
+in \f(CWcode_offset\fP, the offset from the address set using
+\f(CWdwarfdwarf_lne_set_address()\fP, of the address of the first
+instruction in a contiguous block.
+The source file that gave rise
+to the instruction is specified by \f(CWfile_index\fP, the source
+line number is specified by \f(CWlineno\fP, and the source column
+number is specified by \f(CWcolumn_number\fP
+(column numbers begin at 1)
+(if the source column is unknown, specify 0).
+\f(CWfile_index\fP
+is the index of the source file in a list of source files which is
+built up using the function \f(CWdwarf_add_file_decl()\fP.
+\f(CWis_source_stmt_begin\fP is a boolean flag that is true only if
+the instruction at \f(CWcode_address\fP is the first instruction in
+the sequence generated for the source line at \f(CWlineno\fP.  Similarly,
+\f(CWis_basic_block_begin\fP is a boolean flag that is true only if
+the instruction at \f(CWcode_address\fP is the first instruction of
+a basic block.
+It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_lne_set_address()"
+.DS
+\f(CWDwarf_Unsigned dwarf_lne_set_address(
+Dwarf_P_Debug dbg,
+Dwarf_Addr offs,
+Dwarf_Unsigned symidx,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_lne_set_address()\fP sets the target address
+at which a contiguous block of instructions begin.  Information about
+the instructions in the block is added to .debug_line using calls to
+\f(CWdwarfdwarf_add_line_entry()\fP which specifies the offset of each
+instruction in the block relative to the start of the block.  This is
+done so that a single relocation record can be used to obtain the final
+target address of every instruction in the block.
+The relocatable address of the start of the block of instructions is
+specified by \f(CWoffs\fP.  The symbol used to relocate the address
+is given by \f(CWsymidx\fP, which is normally the index of the symbol in the
+Elf symbol table.
+It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_lne_end_sequence()"
+.DS
+\f(CWDwarf_Unsigned dwarf_lne_end_sequence(
+Dwarf_P_Debug dbg,
+	Dwarf_Addr    address;
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_lne_end_sequence()\fP indicates the end of a
+contiguous block of instructions.
+\f(CWaddress()\fP
+should be just higher than the end of the last address in the
+sequence of instructions.
+block of instructions, a call to \f(CWdwarf_lne_set_address()\fP will
+have to be made to set the address of the start of the target address
+of the block, followed by calls to \f(CWdwarf_add_line_entry()\fP for
+each of the instructions in the block.
+It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_add_directory_decl()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_directory_decl(
+Dwarf_P_Debug dbg,
+char *name,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_directory_decl()\fP adds the string
+specified by \f(CWname\fP to the list of include directories in
+the statement program prologue of the .debug_line section.
+The
+string should therefore name a directory from which source files
+have been used to create the present object.
+It returns the index of the string just added, in the list of include
+directories for the object.
+This index is then used to refer to this
+string.
+It returns \f(CWDW_DLV_NOCOUNT\fP on error.
+.H 3 "dwarf_add_file_decl()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_file_decl(
+Dwarf_P_Debug dbg,
+char *name,
+Dwarf_Unsigned dir_idx,
+Dwarf_Unsigned time_mod,
+Dwarf_Unsigned length,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_file_decl()\fP adds the name of a source
+file that contributed to the present object.
+The name of the file is
+specified by \f(CWname\fP (which must not be the empty string
+or a null pointer, it must point to
+a string with length greater than 0).
+In case the name is not a fully-qualified
+pathname, it is prefixed with the name of the directory specified by
+\f(CWdir_idx\fP.
+\f(CWdir_idx\fP is the index of the directory to be
+prefixed in the list builtup using \f(CWdwarf_add_directory_decl()\fP.
+\f(CWtime_mod\fP gives the time at which the file was last modified,
+and \f(CWlength\fP gives the length of the file in bytes.
+It returns the index of the source file in the list built up so far
+using this function, on success.  This index can then be used to
+refer to this source file in calls to \f(CWdwarf_add_line_entry()\fP.
+On error, it returns \f(CWDW_DLV_NOCOUNT\fP.
+.H 2 "Fast Access (aranges) Operations"
+These functions operate on the .debug_aranges section.
+.H 3 "dwarf_add_arange()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_arange(
+Dwarf_P_Debug dbg,
+Dwarf_Addr begin_address,
+Dwarf_Unsigned length,
+Dwarf_Signed symbol_index,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_arange()\fP adds another address range
+to be added to the section
+containing address range information, .debug_aranges.
+The relocatable start address of the range is
+specified by \f(CWbegin_address\fP, and the length of the address
+range is specified by \f(CWlength\fP.
+The relocatable symbol to be
+used to relocate the start of the address range is specified by
+\f(CWsymbol_index\fP, which is normally
+the index of the symbol in the Elf
+symbol table.
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 3 "dwarf_add_arange_b()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_arange_b(
+Dwarf_P_Debug dbg,
+Dwarf_Addr begin_address,
+Dwarf_Unsigned length,
+Dwarf_Unsigned symbol_index,
+	Dwarf_Unsigned end_symbol_index,
+	Dwarf_Addr     offset_from_end_symbol,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_arange_b()\fP adds another address range
+to be added to the section containing
+address range information, .debug_aranges.
+If
+\f(CWend_symbol_index is not zero\fP
+we are using two symbols to create a length
+(must be \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP to be useful)
+.sp
+.in +2
+\f(CWbegin_address\fP
+is the offset from the symbol specified by
+\f(CWsymbol_index\fP .
+\f(CWoffset_from_end_symbol\fP
+is the offset from the symbol specified by
+\f(CWend_symbol_index\fP.
+\f(CWlength\fP is ignored.
+This begin-end pair will be show up in the
+relocation array returned by
+\f(CWdwarf_get_relocation_info() \fP
+as a
+\f(CWdwarf_drt_first_of_length_pair\fP
+and
+\f(CWdwarf_drt_second_of_length_pair\fP
+pair of relocation records.
+The consuming application will turn that pair into
+something conceptually identical to
+.sp
+.nf
+.in +4
+.word end_symbol + offset_from_end - \\
+( start_symbol + begin_address)
+.in -4
+.fi
+.sp
+The reason offsets are allowed on the begin and end symbols
+is to allow the caller to re-use existing labels
+when the labels are available
+and the corresponding offset is known
+(economizing on the number of labels in use).
+The  'offset_from_end - begin_address'
+will actually be in the binary stream, not the relocation
+record, so the app processing the relocation array
+must read that stream value into (for example)
+net_offset and actually emit something like
+.sp
+.nf
+.in +4
+.word end_symbol - start_symbol + net_offset
+.in -4
+.fi
+.sp
+.in -2
+If
+\f(CWend_symbol_index\fP is zero
+we must be given a length
+(either
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+or
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+):
+.sp
+.in +2
+The relocatable start address of the range is
+specified by \f(CWbegin_address\fP, and the length of the address
+range is specified by \f(CWlength\fP.
+The relocatable symbol to be
+used to relocate the start of the address range is specified by
+\f(CWsymbol_index\fP, which is normally
+the index of the symbol in the Elf
+symbol table.
+The
+\f(CWoffset_from_end_symbol\fP
+is ignored.
+.in -2
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 2 "Fast Access (pubnames) Operations"
+These functions operate on the .debug_pubnames section.
+.sp
+.H 3 "dwarf_add_pubname()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_pubname(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die die,
+char *pubname_name,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_pubname()\fP adds the pubname specified
+by \f(CWpubname_name\fP to the section containing pubnames, i.e.
+.debug_pubnames.  The \f(CWDIE\fP that represents the function
+being named is specified by \f(CWdie\fP.
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 2 "Fast Access (weak names) Operations"
+These functions operate on the .debug_weaknames section.
+.H 3 "dwarf_add_weakname()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_weakname(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die die,
+char *weak_name,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_weakname()\fP adds the weak name specified
+by \f(CWweak_name\fP to the section containing weak names, i.e.
+.debug_weaknames.  The \f(CWDIE\fP that represents the function
+being named is specified by \f(CWdie\fP.
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 2 "Static Function Names Operations"
+The .debug_funcnames section contains the names of static function
+names defined in the object, and also the offsets of the \f(CWDIE\fPs
+that represent the definitions of the functions in the .debug_info
+section.
+.H 3 "dwarf_add_funcname()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_funcname(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die die,
+char *func_name,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_funcname()\fP adds the name of a static
+function specified by \f(CWfunc_name\fP to the section containing the
+names of static functions defined in the object represented by \f(CWdbg\fP.
+The \f(CWDIE\fP that represents the definition of the function is
+specified by \f(CWdie\fP.
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 2 "File-scope User-defined Type Names Operations"
+The .debug_typenames section contains the names of file-scope
+user-defined types in the given object, and also the offsets
+of the \f(CWDIE\fPs that represent the definitions of the types
+in the .debug_info section.
+.H 3 "dwarf_add_typename()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_typename(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die die,
+char *type_name,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_typename()\fP adds the name of a file-scope
+user-defined type specified by \f(CWtype_name\fP to the section that
+contains the names of file-scope user-defined type.  The object that
+this section belongs to is specified by \f(CWdbg\fP.  The \f(CWDIE\fP
+that represents the definition of the type is specified by \f(CWdie\fP.
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 2 "File-scope Static Variable Names Operations"
+The .debug_varnames section contains the names of file-scope static
+variables in the given object, and also the offsets of the \f(CWDIE\fPs
+that represent the definition of the variables in the .debug_info
+section.
+.H 3 "dwarf_add_varname()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_varname(
+Dwarf_P_Debug dbg,
+Dwarf_P_Die die,
+char *var_name,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_varname()\fP adds the name of a file-scope
+static variable specified by \f(CWvar_name\fP to the section that
+contains the names of file-scope static variables defined by the
+object represented by \f(CWdbg\fP.  The \f(CWDIE\fP that represents
+the definition of the static variable is specified by \f(CWdie\fP.
+It returns a non-zero value on success, and \f(CW0\fP on error.
+.H 2 "Macro Information Creation"
+All strings passed in by the caller are copied by these
+functions, so the space in which the caller provides the strings
+may be ephemeral (on the stack, or immediately reused or whatever)
+without this causing any difficulty.
+.H 3 "dwarf_def_macro()"
+.DS
+\f(CWint dwarf_def_macro(Dwarf_P_Debug dbg,
+	Dwarf_Unsigned lineno,
+	char *name
+	char *value,
+Dwarf_Error *error);\fP
+.DE
+Adds a macro definition.
+The \f(CWname\fP argument should include the parentheses
+and parameter names if this is a function-like macro.
+Neither string should contain extraneous whitespace.
+\f(CWdwarf_def_macro()\fP adds the mandated space after the
+name and before the value  in the
+output DWARF section(but does not change the
+strings pointed to by the arguments).
+If this is a definition before any files are read,
+\f(CWlineno\fP should be 0.
+Returns \f(CWDW_DLV_ERROR\fP
+and sets \f(CWerror\fP
+if there is an error.
+Returns \f(CWDW_DLV_OK\fP if the call was successful.
+.H 3 "dwarf_undef_macro()"
+.DS
+\f(CWint dwarf_undef_macro(Dwarf_P_Debug dbg,
+	Dwarf_Unsigned lineno,
+	char *name,
+Dwarf_Error *error);\fP
+.DE
+Adds a macro un-definition note.
+If this is a definition before any files are read,
+\f(CWlineno\fP should be 0.
+Returns \f(CWDW_DLV_ERROR\fP
+and sets \f(CWerror\fP
+if there is an error.
+Returns \f(CWDW_DLV_OK\fP if the call was successful.
+.H 3 "dwarf_start_macro_file()"
+.DS
+\f(CWint dwarf_start_macro_file(Dwarf_P_Debug dbg,
+	Dwarf_Unsigned lineno,
+Dwarf_Unsigned fileindex,
+Dwarf_Error *error);\fP
+.DE
+\f(CWfileindex\fP is an index in the .debug_line header:
+the index of
+the file name.
+See the function \f(CWdwarf_add_file_decl()\fP.
+The \f(CWlineno\fP should be 0 if this file is
+the file of the compilation unit source itself
+(which, of course, is not a #include in any
+file).
+Returns \f(CWDW_DLV_ERROR\fP
+and sets \f(CWerror\fP
+if there is an error.
+Returns \f(CWDW_DLV_OK\fP if the call was successful.
+.H 3 "dwarf_end_macro_file()"
+.DS
+\f(CWint dwarf_end_macro_file(Dwarf_P_Debug dbg,
+Dwarf_Error *error);\fP
+.DE
+Returns \f(CWDW_DLV_ERROR\fP
+and sets \f(CWerror\fP
+if there is an error.
+Returns \f(CWDW_DLV_OK\fP if the call was successful.
+.H 3 "dwarf_vendor_ext()"
+.DS
+\f(CWint dwarf_vendor_ext(Dwarf_P_Debug dbg,
+Dwarf_Unsigned constant,
+char *         string,
+Dwarf_Error*   error); \fP
+.DE
+The meaning of the \f(CWconstant\fP and the\f(CWstring\fP
+in the macro info section
+are undefined by DWARF itself, but the string must be
+an ordinary null terminated string.
+This call is not an extension to DWARF.
+It simply enables storing
+macro information as specified in the DWARF document.
+Returns \f(CWDW_DLV_ERROR\fP
+and sets \f(CWerror\fP
+if there is an error.
+Returns \f(CWDW_DLV_OK\fP if the call was successful.
+.H 2 "Low Level (.debug_frame) operations"
+These functions operate on the .debug_frame section.  Refer to
+\f(CWlibdwarf.h\fP for the register names and register assignment
+mapping.  Both of these are necessarily machine dependent.
+.H 3 "dwarf_new_fde()"
+.DS
+\f(CWDwarf_P_Fde dwarf_new_fde(
+Dwarf_P_Debug dbg,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_new_fde()\fP returns a new \f(CWDwarf_P_Fde\fP
+descriptor that should be used to build a complete \f(CWFDE\fP.
+Subsequent calls to routines that build up the \f(CWFDE\fP should use
+the same \f(CWDwarf_P_Fde\fP descriptor.
+It returns a valid \f(CWDwarf_P_Fde\fP descriptor on success, and
+\f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_frame_cie()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_frame_cie(
+Dwarf_P_Debug dbg,
+char *augmenter,
+Dwarf_Small code_align,
+Dwarf_Small data_align,
+Dwarf_Small ret_addr_reg,
+Dwarf_Ptr init_bytes,
+Dwarf_Unsigned init_bytes_len,
+Dwarf_Error *error);\fP
+.DE
+The function
+\f(CWdwarf_add_frame_cie()\fP
+creates a \f(CWCIE\fP,
+and returns an index to it, that should be used to refer to this
+\f(CWCIE\fP.
+\f(CWCIE\fPs are used by \f(CWFDE\fPs to setup
+initial values for frames.
+The augmentation string for the \f(CWCIE\fP
+is specified by \f(CWaugmenter\fP.
+The code alignment factor,
+data alignment factor, and the return address register for the
+\f(CWCIE\fP are specified by \f(CWcode_align\fP, \f(CWdata_align\fP,
+and \f(CWret_addr_reg\fP respectively.
+\f(CWinit_bytes\fP points
+to the bytes that represent the instructions for the \f(CWCIE\fP
+being created, and \f(CWinit_bytes_len\fP specifies the number
+of bytes of instructions.
+There is no convenient way to generate the  \f(CWinit_bytes\fP
+stream.
+One just
+has to calculate it by hand or separately
+generate something with the
+correct sequence and use dwarfdump -v and elfdump -h  and some
+kind of hex dumper to see the bytes.
+This is a serious inconvenience!
+It returns an index to the \f(CWCIE\fP just created on success.
+On error it returns \f(CWDW_DLV_NOCOUNT\fP.
+.H 3 "dwarf_add_frame_fde()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_frame_fde(
+Dwarf_P_Debug dbg,
+Dwarf_P_Fde fde,
+Dwarf_P_Die die,
+Dwarf_Unsigned cie,
+Dwarf_Addr virt_addr,
+Dwarf_Unsigned  code_len,
+Dwarf_Unsigned sym_idx,
+Dwarf_Error* error)\fP
+.DE
+The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP
+specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the
+object represented by the given \f(CWdbg\fP.
+\f(CWdie\fP specifies
+the \f(CWDIE\fP that represents the function whose frame information
+is specified by the given \f(CWfde\fP.
+\f(CWcie\fP specifies the
+index of the \f(CWCIE\fP that should be used to setup the initial
+conditions for the given frame.
+It returns an index to the given \f(CWfde\fP.
+.H 3 "dwarf_add_frame_fde_b()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_frame_fde_b(
+Dwarf_P_Debug dbg,
+Dwarf_P_Fde fde,
+Dwarf_P_Die die,
+Dwarf_Unsigned cie,
+Dwarf_Addr virt_addr,
+Dwarf_Unsigned  code_len,
+Dwarf_Unsigned sym_idx,
+	Dwarf_Unsigned sym_idx_of_end,
+	Dwarf_Addr     offset_from_end_sym,
+Dwarf_Error* error)\fP
+.DE
+This function is like
+\f(CWdwarf_add_frame_fde()\fP
+except that
+\f(CWdwarf_add_frame_fde_b()\fP
+has new arguments to allow use
+with
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP.
+The function \f(CWdwarf_add_frame_fde_b()\fP
+adds the
+\f(CWFDE\fP
+specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the
+object represented by the given \f(CWdbg\fP.
+\f(CWdie\fP specifies
+the \f(CWDIE\fP that represents the function whose frame information
+is specified by the given \f(CWfde\fP.
+\f(CWcie\fP specifies the
+index of the \f(CWCIE\fP that should be used to setup the initial
+conditions for the given frame.
+\f(CWvirt_addr\fP represents the
+relocatable address at which the code for the given function begins,
+and \f(CWsym_idx\fP gives the index of the relocatable symbol to
+be used to relocate this address (\f(CWvirt_addr\fP that is).
+\f(CWcode_len\fP specifies the size in bytes of the machine instructions
+for the given function.
+If \f(CWsym_idx_of_end\fP is zero
+(may  be
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+or
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+):
+.sp
+.in +2
+\f(CWvirt_addr\fP represents the
+relocatable address at which the code for the given function begins,
+and \f(CWsym_idx\fP gives the index of the relocatable symbol to
+be used to relocate this address (\f(CWvirt_addr\fP that is).
+\f(CWcode_len\fP
+specifies the size in bytes of the machine instructions
+for the given function.
+\f(CWsym_idx_of_end\fP
+and
+\f(CWoffset_from_end_sym\fP
+are unused.
+.in -2
+.sp
+If \f(CWsym_idx_of_end\fP is non-zero
+(must be \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP to be useful):
+.sp
+.in +2
+\f(CWvirt_addr\fP
+is the offset from the symbol specified by
+\f(CWsym_idx\fP .
+\f(CWoffset_from_end_sym\fP
+is the offset from the symbol specified by
+\f(CWsym_idx_of_end\fP.
+\f(CWcode_len\fP is ignored.
+This begin-end pair will be show up in the
+relocation array returned by
+\f(CWdwarf_get_relocation_info() \fP
+as a
+\f(CWdwarf_drt_first_of_length_pair\fP
+and
+\f(CWdwarf_drt_second_of_length_pair\fP
+pair of relocation records.
+The consuming application will turn that pair into
+something conceptually identical to
+.sp
+.nf
+.in +4
+.word end_symbol + begin - \\
+( start_symbol + offset_from_end)
+.in -4
+.fi
+.sp
+The reason offsets are allowed on the begin and end symbols
+is to allow the caller to re-use existing labels
+when the labels are available
+and the corresponding offset is known
+(economizing on the number of labels in use).
+The  'offset_from_end - begin_address'
+will actually be in the binary stream, not the relocation
+record, so the app processing the relocation array
+must read that stream value into (for example)
+net_offset and actually emit something like
+.sp
+.nf
+.in +4
+.word end_symbol - start_symbol + net_offset
+.in -4
+.fi
+.sp
+.in -2
+It returns an index to the given \f(CWfde\fP.
+On error, it returns \f(CWDW_DLV_NOCOUNT\fP.
+.H 3 "dwarf_add_frame_info_b()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_frame_info_b(
+Dwarf_P_Debug   dbg,
+Dwarf_P_Fde     fde,
+Dwarf_P_Die     die,
+Dwarf_Unsigned  cie,
+Dwarf_Addr      virt_addr,
+Dwarf_Unsigned  code_len,
+Dwarf_Unsigned  sym_idx,
+	Dwarf_Unsigned  end_symbol_index,
+Dwarf_Addr      offset_from_end_symbol,
+	Dwarf_Signed    offset_into_exception_tables,
+	Dwarf_Unsigned  exception_table_symbol,
+Dwarf_Error*    error)\fP
+.DE
+The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP
+specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the
+object represented by the given \f(CWdbg\fP.
+\f(CWdie\fP specifies
+the \f(CWDIE\fP that represents the function whose frame information
+is specified by the given \f(CWfde\fP.
+\f(CWcie\fP specifies the
+index of the \f(CWCIE\fP that should be used to setup the initial
+conditions for the given frame.
+\f(CWoffset_into_exception_tables\fP specifies the
+offset into \f(CW.MIPS.eh_region\fP elf section where the exception tables
+for this function begins.
+\f(CWexception_table_symbol\fP  gives the index of
+the relocatable symbol to be used to relocate this offset.
+If
+\f(CWend_symbol_index is not zero\fP
+we are using two symbols to create a length
+(must be \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP to be useful)
+.sp
+.in +2
+\f(CWvirt_addr\fP
+is the offset from the symbol specified by
+\f(CWsym_idx\fP .
+\f(CWoffset_from_end_symbol\fP
+is the offset from the symbol specified by
+\f(CWend_symbol_index\fP.
+\f(CWcode_len\fP is ignored.
+This begin-end pair will be show up in the
+relocation array returned by
+\f(CWdwarf_get_relocation_info() \fP
+as a
+\f(CWdwarf_drt_first_of_length_pair\fP
+and
+\f(CWdwarf_drt_second_of_length_pair\fP
+pair of relocation records.
+The consuming application will turn that pair into
+something conceptually identical to
+.sp
+.nf
+.in +4
+.word end_symbol + offset_from_end_symbol - \\
+( start_symbol + virt_addr)
+.in -4
+.fi
+.sp
+The reason offsets are allowed on the begin and end symbols
+is to allow the caller to re-use existing labels
+when the labels are available
+and the corresponding offset is known
+(economizing on the number of labels in use).
+The  'offset_from_end - begin_address'
+will actually be in the binary stream, not the relocation
+record, so the app processing the relocation array
+must read that stream value into (for example)
+net_offset and actually emit something like
+.sp
+.nf
+.in +4
+.word end_symbol - start_symbol + net_offset
+.in -4
+.fi
+.sp
+.in -2
+If
+\f(CWend_symbol_index\fP is zero
+we must be given a code_len value
+(either
+\f(CWDW_DLC_STREAM_RELOCATIONS\fP
+or
+\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP
+):
+.sp
+.in +2
+The relocatable start address of the range is
+specified by \f(CWvirt_addr\fP, and the length of the address
+range is specified by \f(CWcode_len\fP.
+The relocatable symbol to be
+used to relocate the start of the address range is specified by
+\f(CWsymbol_index\fP, which is normally
+the index of the symbol in the Elf
+symbol table.
+The
+\f(CWoffset_from_end_symbol\fP
+is ignored.
+.in -2
+It returns an index to the given \f(CWfde\fP.
+On error, it returns \f(CWDW_DLV_NOCOUNT\fP.
+.H 3 "dwarf_add_frame_info()"
+.DS
+\f(CWDwarf_Unsigned dwarf_add_frame_info(
+Dwarf_P_Debug dbg,
+Dwarf_P_Fde fde,
+Dwarf_P_Die die,
+Dwarf_Unsigned cie,
+Dwarf_Addr virt_addr,
+Dwarf_Unsigned  code_len,
+Dwarf_Unsigned sym_idx,
+	Dwarf_Signed offset_into_exception_tables,
+	Dwarf_Unsigned exception_table_symbol,
+Dwarf_Error* error)\fP
+.DE
+The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP
+specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the
+object represented by the given \f(CWdbg\fP.  \f(CWdie\fP specifies
+the \f(CWDIE\fP that represents the function whose frame information
+is specified by the given \f(CWfde\fP.  \f(CWcie\fP specifies the
+index of the \f(CWCIE\fP that should be used to setup the initial
+conditions for the given frame.  \f(CWvirt_addr\fP represents the
+relocatable address at which the code for the given function begins,
+and \f(CWsym_idx\fP gives the index of the relocatable symbol to
+be used to relocate this address (\f(CWvirt_addr\fP that is).
+\f(CWcode_len\fP specifies the size in bytes of the machine instructions
+for the given function. \f(CWoffset_into_exception_tables\fP specifies the
+offset into \f(CW.MIPS.eh_region\fP elf section where the exception tables
+for this function begins. \f(CWexception_table_symbol\fP  gives the index of
+the relocatable symbol to be used to relocate this offset.
+It returns an index to the given \f(CWfde\fP.
+.H 3 "dwarf_fde_cfa_offset()"
+.DS
+\f(CWDwarf_P_Fde dwarf_fde_cfa_offset(
+Dwarf_P_Fde fde,
+Dwarf_Unsigned reg,
+Dwarf_Signed offset,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_fde_cfa_offset()\fP appends a \f(CWDW_CFA_offset\fP
+operation to the \f(CWFDE\fP, specified by \f(CWfde\fP,  being constructed.
+The first operand of the \f(CWDW_CFA_offset\fP operation is specified by
+\f(CWreg\P.  The register specified should not exceed 6 bits.  The second
+operand of the \f(CWDW_CFA_offset\fP operation is specified by \f(CWoffset\fP.
+It returns the given \f(CWfde\fP on success.
+It returns \f(CWDW_DLV_BADADDR\fP on error.
+.H 3 "dwarf_add_fde_inst()"
+.DS
+\f(CWDwarf_P_Fde dwarf_add_fde_inst(
+Dwarf_P_Fde fde,
+Dwarf_Small op,
+Dwarf_Unsigned val1,
+Dwarf_Unsigned val2,
+Dwarf_Error *error)\fP
+.DE
+The function \f(CWdwarf_add_fde_inst()\fP adds the operation specified
+by \f(CWop\fP to the \f(CWFDE\fP specified by \f(CWfde\fP.  Upto two
+operands can be specified in \f(CWval1\fP, and \f(CWval2\fP.  Based on
+the operand specified \f(CWLibdwarf\fP decides how many operands are
+meaningful for the operand.  It also converts the operands to the
+appropriate datatypes (they are passed to \f(CWdwarf_add_fde_inst\fP
+as \f(CWDwarf_Unsigned\fP).
+It returns the given \f(CWfde\fP on success, and \f(CWDW_DLV_BADADDR\fP
+on error.
+.S
+.TC 1 1 4
+.CS