1 \."

     2 \." the following line may be removed if the ff ligature works on your machine

     3 .lg 0

     4 \." set up heading formats

     5 .ds HF 3 3 3 3 3 2 2

     6 .ds HP +2 +2 +1 +0 +0

     7 .nr Hs 5

     8 .nr Hb 5

     9 \." ==============================================

    10 \." Put current date in the following at each rev

    11 .ds vE rev 1.66, 04 July 2007

    12 \." ==============================================

    13 \." ==============================================

    14 .ds | |

    15 .ds ~ ~

    16 .ds ' '

    17 .if t .ds Cw \&\f(CW

    18 .if n .ds Cw \fB

    19 .de Cf          \" Place every other arg in Cw font, beginning with first

    20 .if \\n(.$=1 \&\*(Cw\\$1\fP

    21 .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2

    22 .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP

    23 .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4

    24 .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP

    25 .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6

    26 .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP

    27 .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8

    28 .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\

    29 *(Cw

    30 ..

    31 .nr Cl 4

    32 .SA 1

    33 .TL

    34 A Consumer Library Interface to DWARF 

    35 .AF ""

    36 .AU "David Anderson"

    37 .PF "'\*(vE'- \\\\nP -''"

    38 .AS 1

    39 This document describes an interface to a library of functions

    40 .FS 

    41 UNIX is a registered trademark of UNIX System Laboratories, Inc.

    42 in the United States and other countries.

    43 .FE

    44 to access DWARF debugging information entries and DWARF line number

    45 information (and other DWARF2/3 information). 

    46 It does not make recommendations as to how the functions

    47 described in this document should be implemented nor does it

    48 suggest possible optimizations. 

    49 .P

    50 The document is oriented to reading DWARF version 2 

    51 and version 3.

    52 There are certain sections which are SGI-specific (those

    53 are clearly identified in the document).

    54 .P

    55 \*(vE

    56 

    57 .AE

    58 .MT 4

    59 

    60 .H 1 "INTRODUCTION"

    61 This document describes an interface to \fIlibdwarf\fP, a

    62 library of functions to provide access to DWARF debugging information

    63 records, DWARF line number information, DWARF address range and global 

    64 names information, weak names information, DWARF frame description 

    65 information, DWARF static function names, DWARF static variables, and 

    66 DWARF type information.

    67 .P

    68 The document has long mentioned the  

    69 "Unix International Programming Languages Special Interest Group" 

    70 (PLSIG), under whose auspices the

    71 DWARF committtee was formed around 1991.

    72 "Unix International"  

    73 was disbanded in the 1990's and no longer exists.

    74 .P

    75 The DWARF committee published DWARF2 July 27, 1993.

    76 .P

    77 In the mid 1990's this document and the library it describes

    78 (which the committee never endorsed, having decided

    79 not to endorse or approve any particular library interface)

    80 was made available on the internet by Silcon Graphics, Inc.

    81 .P

    82 In 2005 the DWARF committee began an affiliation with FreeStandards.org.

    83 In 2007 FreeStandards.org merged with The Linux Foundation.

    84 The DWARF committee dropped its affiliation with FreeStandards.org

    85 in 2007 and established the dwarfstd.org website.

    86 See "http://www.dwarfstd.org" for current

    87 information on standardization activities 

    88 and a copy of the standard.

    89 .H 2 "Copyright"

    90 Copyright 1993-2006 Silicon Graphics, Inc.

    91 

    92 Copyright 2007 David Anderson. 

    93 

    94 Permission is hereby granted to 

    95 copy or republish or use any or all of this document without

    96 restriction except that when publishing more than a small amount

    97 of the document

    98 please acknowledge Silicon Graphics, Inc and David Anderson.

    99 

   100 This document is distributed in the hope that it would be useful, but

   101 WITHOUT ANY WARRANTY; without even the implied warranty of

   102 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

   103 .P

   104 

   105 .H 2 "Purpose and Scope"

   106 The purpose of this document is to document a library of functions 

   107 to access DWARF debugging information. There is no effort made in 

   108 this document to address the creation of these records as those

   109 issues are addressed separately 

   110 (see "A Producer Library Interface to DWARF").

   111 

   112 .P

   113 Additionally, the focus of this document is the functional interface,

   114 and as such, implementation as well as optimization issues are

   115 intentionally ignored.

   116 

   117 

   118 .H 2 "Document History"

   119 .P

   120 A document was written about 1991 which had similar

   121 layout and interfaces. 

   122 Written by people from Hal Corporation,

   123 That document described a library for reading DWARF1.

   124 The authors distributed paper copies to the committee

   125 with the clearly expressed intent to propose the document as

   126 a supported interface definition.

   127 The committee decided not to pursue a library definition.

   128 .P

   129 SGI wrote the document you are now reading in 1993

   130 with a similar layout and content and organization, but 

   131 it was complete document rewrite with the intent to read DWARF2

   132 (the DWARF version then in existence).

   133 The intent was (and is) to also cover

   134 future revisions of DWARF.

   135 All the function interfaces were changed 

   136 in 1994 to uniformly

   137 return a simple integer success-code (see DW_DLV_OK etc), 

   138 generally following

   139 the recomendations in the chapter titled "Candy Machine Interfaces"

   140 of "Writing Solid Code", a book by

   141 Steve Maguire (published by Microsoft Press).

   142 .H 2 "Definitions"

   143 DWARF debugging information entries (DIEs) are the segments of information 

   144 placed in the \f(CW.debug_*\fP sections by compilers, assemblers, and 

   145 linkage editors that, in conjunction with line number entries, are 

   146 necessary for symbolic source-level debugging.  

   147 Refer to the latest

   148 "\fIDWARF Debugging Information Format\fP" from www.dwarfstd.org for a more 

   149 complete description of these entries.

   150 

   151 .P

   152 This document adopts all the terms and definitions in "\fIDWARF Debugging 

   153 Information Format\fP" versions 2 and 3.  

   154 It originally focused on the implementation at

   155 Silicon Graphics, Inc., but now

   156 attempts to be more generally useful.

   157 

   158 .H 2 "Overview"

   159 The remaining sections of this document describe the proposed interface

   160 to \f(CWlibdwarf\fP, first by describing the purpose of additional types

   161 defined by the interface, followed by descriptions of the available 

   162 operations.  This document assumes you are thoroughly familiar with the 

   163 information contained in the \fIDWARF Debugging Information Format\fP 

   164 document. 

   165 .P

   166 We separate the functions into several categories to emphasize that not 

   167 all consumers want to use all the functions.  We call the categories 

   168 Debugger, Internal-level, High-level, and Miscellaneous not because one is more 

   169 important than another but as a way of making the rather large set of 

   170 function calls easier to understand.

   171 .P

   172 Unless otherwise specified, all functions and structures should be

   173 taken as being designed for Debugger consumers.

   174 .P

   175 The Debugger Interface of this library is intended to be used by debuggers. 

   176 The interface is low-level (close to dwarf) but suppresses irrelevant detail.

   177 A debugger will want to absorb all of some sections at startup and will 

   178 want to see little or nothing of some sections except at need.  And even 

   179 then will probably want to absorb only the information in a single compilation 

   180 unit at a time.  A debugger does not care about

   181 implementation details of the library.

   182 .P

   183 The Internal-level Interface is for a DWARF prettyprinter and checker.  

   184 A 

   185 thorough prettyprinter will want to know all kinds of internal things 

   186 (like actual FORM numbers and actual offsets) so it can check for 

   187 appropriate structure in the DWARF data and print (on request) all 

   188 that internal information for human users and libdwarf authors and 

   189 compiler-writers.  

   190 Calls in this interface provide data a debugger 

   191 does not care about.

   192 .P

   193 The High-level Interface is for higher level access

   194 (it's not really a high level interface!).  

   195 Programs such as 

   196 disassemblers will want to be able to display relevant information 

   197 about functions and line numbers without having to invest too much 

   198 effort in looking at DWARF.

   199 .P

   200 The miscellaneous interface is just what is left over: the error handler 

   201 functions.

   202 .P

   203 The following is a brief mention of the changes in this libdwarf from 

   204 the libdwarf draft for DWARF Version 1 and recent changes.

   205 .H 2 "Items Changed"

   206 .P

   207 Added support for various DWARF3 features, but primarily

   208 a new frame-information interface tailorable at run-time

   209 to more than a single ABI.

   210 See dwarf_set_frame_rule_inital_value() and dwarf_set_frame_rule_table_size().

   211 See also dwarf_get_fde_info_for_reg3() and

   212 dwarf_get_fde_info_for_cfa_reg3().  (April 2006)

   213 .P

   214 Added support for DWARF3 .debug_pubtypes section.

   215 Corrected various leaks (revising dealloc() calls, adding

   216 new functions) and corrected dwarf_formstring() documentation.

   217 .P 

   218 Added dwarf_srclines_dealloc() as the previous deallocation

   219 method documented for data returned by

   220 dwarf_srclines() was incapable of freeing

   221 all the allocated storage (14 July 2005).

   222 .P

   223 dwarf_nextglob(), dwarf_globname(), and dwarf_globdie() were all changed 

   224 to operate on the items in the .debug_pubnames section.

   225 .P

   226 All functions were modified to return solely an error code.

   227 Data is returned through pointer arguments.

   228 This makes writing safe and correct library-using-code far easier.

   229 For justification for this approach, see the book by

   230 Steve Maguire titled "Writing Solid Code" at your bookstore.

   231 

   232 

   233 .H 2 "Items Removed"

   234 .P

   235 Dwarf_Type

   236 was removed since types are no longer special.

   237 .P

   238 dwarf_typeof()

   239 was removed since types are no longer special.

   240 .P

   241 Dwarf_Ellist

   242 was removed since element lists no longer are a special format.

   243 .P

   244 Dwarf_Bounds

   245 was removed since bounds have been generalized.

   246 .P

   247 dwarf_nextdie()

   248 was replaced by dwarf_next_cu_header() to reflect the

   249 real way DWARF is organized.

   250 The dwarf_nextdie() was only useful for getting to compilation

   251 unit beginnings, so it does not seem harmful to remove it in favor

   252 of a more direct function.

   253 .P

   254 dwarf_childcnt() is removed on grounds

   255 that no good use was apparent.

   256 .P

   257 dwarf_prevline() and dwarf_nextline() were removed on grounds this

   258 is better left to a debugger to do.

   259 Similarly, dwarf_dieline() was removed.

   260 .P

   261 dwarf_is1stline() was removed as it was not meaningful for the

   262 revised DWARF line operations.

   263 .P

   264 Any libdwarf implementation might well decide to support all the

   265 removed functionality and to retain the DWARF Version 1 meanings

   266 of that functionality.  

   267 This would be difficult because the

   268 original libdwarf draft

   269 specification used traditional C library interfaces which

   270 confuse the values returned by successful calls with

   271 exceptional conditions like failures and 'no more data' indications.

   272 

   273 .H 2 "Revision History"

   274 .VL 15

   275 .LI "March 93"

   276 Work on DWARF2 SGI draft begins

   277 .LI "June 94"

   278 The function returns are changed to return an error/success code

   279 only.

   280 .LI "April 2006:

   281 Support for DWARF3 consumer operations is close to completion.

   282 .LE

   283 

   284 .H 1 "Types Definitions"

   285 

   286 .H 2 "General Description"

   287 The \fIlibdwarf.h\fP header file contains typedefs and preprocessor 

   288 definitions of types and symbolic names used to reference objects 

   289 of \fIlibdwarf\fP. The types defined by typedefs contained in 

   290 \fIlibdwarf.h\fP all use the convention of adding \f(CWDwarf_\fP 

   291 as a prefix and can be placed in three categories: 

   292 

   293 .BL

   294 .LI

   295 Scalar types : The scalar types defined in \fIlibdwarf.h\fP are

   296 defined primarily for notational convenience and identification.

   297 Depending on the individual definition, they are interpreted as a 

   298 value, a pointer, or as a flag.

   299 .LI

   300 Aggregate types : Some values can not be represented by a single 

   301 scalar type; they must be represented by a collection of, or as a 

   302 union of, scalar and/or aggregate types. 

   303 .LI

   304 Opaque types : The complete definition of these types is intentionally

   305 omitted; their use is as handles for query operations, which will yield

   306 either an instance of another opaque type to be used in another query, or 

   307 an instance of a scalar or aggregate type, which is the actual result.

   308 .P

   309 

   310 .H 2 "Scalar Types"

   311 The following are the defined by \fIlibdwarf.h\fP:

   312 

   313 .DS

   314 \f(CW

   315 typedef int                Dwarf_Bool;

   316 typedef unsigned long long Dwarf_Off;

   317 typedef unsigned long long Dwarf_Unsigned;

   318 typedef unsigned short     Dwarf_Half;

   319 typedef unsigned char      Dwarf_Small;

   320 typedef signed long long   Dwarf_Signed;

   321 typedef unsigned long long Dwarf_Addr;

   322 typedef void 		   *Dwarf_Ptr;

   323 typedef void   (*Dwarf_Handler)(Dwarf_Error *error, Dwarf_Ptr errarg);

   324 .DE

   325 

   326 .nr aX \n(Fg+1

   327 Dwarf_Ptr is an address for use by the host program calling the library,

   328 not for representing pc-values/addresses within the target object file.

   329 Dwarf_Addr is for pc-values within the target object file.  The sample 

   330 scalar type assignments above are for a \fIlibdwarf.h\fP that can read 

   331 and write

   332 32-bit or 64-bit binaries on a 32-bit or 64-bit host machine.

   333 The types must be  defined appropriately

   334 for each implementation of libdwarf.

   335 A description of these scalar types in the SGI/MIPS

   336 environment is given in Figure \n(aX.

   337 

   338 .DS

   339 .TS

   340 center box, tab(:);

   341 lfB lfB lfB lfB

   342 l c c l.

   343 NAME:SIZE:ALIGNMENT:PURPOSE

   344 _

   345 Dwarf_Bool:4:4:Boolean states

   346 Dwarf_Off:8:8:Unsigned file offset

   347 Dwarf_Unsigned:8:8:Unsigned large integer

   348 Dwarf_Half:2:2:Unsigned medium integer

   349 Dwarf_Small:1:1:Unsigned small integer

   350 Dwarf_Signed:8:8:Signed large integer

   351 Dwarf_Addr:8:8:Program address

   352 :::(target program)

   353 Dwarf_Ptr:4|8:4|8:Dwarf section pointer 

   354 :::(host program)

   355 Dwarf_Handler:4|8:4|8:Pointer to

   356 :::error handler function 

   357 .TE

   358 .FG "Scalar Types"

   359 .DE

   360 

   361 .H 2 "Aggregate Types"

   362 The following aggregate types are defined by 

   363 \fIlibdwarf.h\fP:

   364 \f(CWDwarf_Loc\fP,

   365 \f(CWDwarf_Locdesc\fP,

   366 \f(CWDwarf_Block\fP, 

   367 \f(CWDwarf_Frame_Op\fP. 

   368 \f(CWDwarf_Regtable\fP. 

   369 \f(CWDwarf_Regtable3\fP. 

   370 While most of \f(CWlibdwarf\fP acts on or returns simple values or

   371 opaque pointer types, this small set of structures seems useful.

   372 

   373 .H 3 "Location Record"

   374 The \f(CWDwarf_Loc\fP type identifies a single atom of a location description

   375 or a location expression.

   376 

   377 .DS

   378 \f(CWtypedef struct {

   379         Dwarf_Small        lr_atom;

   380         Dwarf_Unsigned     lr_number;

   381         Dwarf_Unsigned     lr_number2;

   382         Dwarf_Unsigned     lr_offset;  

   383 } Dwarf_Loc;\fP

   384 .DE

   385 

   386 The \f(CWlr_atom\fP identifies the atom corresponding to the \f(CWDW_OP_*\fP 

   387 definition in \fIdwarf.h\fP and it represents the operation to be performed 

   388 in order to locate the item in question.

   389 

   390 .P

   391 The \f(CWlr_number\fP field is the operand to be used in the calculation

   392 specified by the \f(CWlr_atom\fP field; not all atoms use this field.

   393 Some atom operations imply signed numbers so it is necessary to cast 

   394 this to a \f(CWDwarf_Signed\fP type for those operations.

   395 

   396 .P

   397 The \f(CWlr_number2\fP field is the second operand specified by the 

   398 \f(CWlr_atom\fP field; only \f(CWDW_OP_BREGX\fP has this field.  Some 

   399 atom operations imply signed numbers so it may be necessary to cast 

   400 this to a \f(CWDwarf_Signed\fP type for those operations.

   401 

   402 .P

   403 The \f(CWlr_offset\fP field is the byte offset (within the block the 

   404 location record came from) of the atom specified by the \f(CWlr_atom\fP 

   405 field.  This is set on all atoms.  This is useful for operations 

   406 \f(CWDW_OP_SKIP\fP and \f(CWDW_OP_BRA\fP.

   407 

   408 .H 3 "Location Description"

   409 The \f(CWDwarf_Locdesc\fP type represents an ordered list of 

   410 \f(CWDwarf_Loc\fP records used in the calculation to locate 

   411 an item.  Note that in many cases, the location can only be 

   412 calculated at runtime of the associated program.

   413 

   414 .DS

   415 \f(CWtypedef struct {

   416         Dwarf_Addr        ld_lopc;

   417         Dwarf_Addr        ld_hipc;

   418         Dwarf_Unsigned    ld_cents;

   419         Dwarf_Loc*        ld_s;

   420 } Dwarf_Locdesc;\fP

   421 .DE

   422 

   423 The \f(CWld_lopc\fP and \f(CWld_hipc\fP fields provide an address range for

   424 which this location descriptor is valid.  Both of these fields are set to

   425 \fIzero\fP if the location descriptor is valid throughout the scope of the

   426 item it is associated with.  These addresses are virtual memory addresses, 

   427 not offsets-from-something.  The virtual memory addresses do not account 

   428 for dso movement (none of the pc values from libdwarf do that, it is up to 

   429 the consumer to do that).

   430 

   431 .P

   432 The \f(CWld_cents\fP field contains a count of the number of \f(CWDwarf_Loc\fP 

   433 entries pointed to by the \f(CWld_s\fP field.

   434 

   435 .P

   436 The \f(CWld_s\fP field points to an array of \f(CWDwarf_Loc\fP records. 

   437 

   438 .H 3 "Data Block"

   439 .SP

   440 The \f(CWDwarf_Block\fP type is used to contain the value of an attribute

   441 whose form is either \f(CWDW_FORM_block1\fP, \f(CWDW_FORM_block2\fP, 

   442 \f(CWDW_FORM_block4\fP, \f(CWDW_FORM_block8\fP, or \f(CWDW_FORM_block\fP.

   443 Its intended use is to deliver the value for an attribute of any of these 

   444 forms.

   445 

   446 .DS

   447 \f(CWtypedef struct {

   448         Dwarf_Unsigned     bl_len;

   449         Dwarf_Ptr          bl_data;

   450 } Dwarf_Block;\fP

   451 .DE

   452 

   453 .P

   454 The \f(CWbl_len\fP field contains the length in bytes of the data pointed

   455 to by the \f(CWbl_data\fP field. 

   456 

   457 .P

   458 The \f(CWbl_data\fP field contains a pointer to the uninterpreted data.

   459 Since we use  a \f(CWDwarf_Ptr\fP here one must copy the pointer to some 

   460 other type (typically an \f(CWunsigned char *\fP) so one can add increments 

   461 to index through the data.  The data pointed to by \f(CWbl_data\fP is not 

   462 necessarily at any useful alignment.

   463 

   464 .H 3 "Frame Operation Codes: DWARF 2"

   465 This interface is adequate for DWARF2 but not for DWARF3.

   466 A separate interface usable for DWARF3 and for DWARF2 is described below.

   467 .P

   468 The DWARF2 \f(CWDwarf_Frame_Op\fP type is used to contain the data of a single

   469 instruction of an instruction-sequence of low-level information from the 

   470 section containing frame information.  This is ordinarily used by 

   471 Internal-level Consumers trying to print everything in detail.

   472 

   473 .DS

   474 \f(CWtypedef struct {

   475 	Dwarf_Small  fp_base_op;

   476 	Dwarf_Small  fp_extended_op;

   477 	Dwarf_Half   fp_register;

   478 	Dwarf_Signed fp_offset;

   479 	Dwarf_Offset fp_instr_offset;

   480 } Dwarf_Frame_Op;

   481 .DE

   482 

   483 \f(CWfp_base_op\fP is the 2-bit basic op code.  \f(CWfp_extended_op\fP is 

   484 the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an 

   485 extended op code) and is zero otherwise.

   486 .P

   487 \f(CWfp_register\fP 

   488 is any (or the first) register value as defined

   489 in the \f(CWCall Frame Instruction Encodings\fP figure

   490 in the \f(CWdwarf\fP document.

   491 If not used with the Op it is 0.

   492 .P

   493 \f(CWfp_offset\fP

   494 is the address, delta, offset, or second register as defined

   495 in the \f(CWCall Frame Instruction Encodings\fP figure

   496 in the \f(CWdwarf\fP document.

   497 If this is an \f(CWaddress\fP then the value should be cast to

   498 \f(CW(Dwarf_Addr)\fP before being used.

   499 In any implementation this field *must* be as large as the

   500 larger of Dwarf_Signed and Dwarf_Addr for this to work properly.

   501 If not used with the op it is 0.

   502 .P

   503 \f(CWfp_instr_offset\fP is the byte_offset (within the instruction

   504 stream of the frame instructions) of this operation.  It starts at 0

   505 for a given frame descriptor.

   506 

   507 .H 3 "Frame Regtable: DWARF 2"

   508 This interface is adequate for DWARF2 but not for DWARF3.

   509 A separate interface usable for DWARF3 and for DWARF2 is described below.

   510 .P

   511 The \f(CWDwarf_Regtable\fP type is used to contain the 

   512 register-restore information for all registers at a given

   513 PC value.

   514 Normally used by debuggers.

   515 .DS

   516 /* DW_REG_TABLE_SIZE must reflect the number of registers

   517  *(DW_FRAME_LAST_REG_NUM) as defined in dwarf.h

   518  */

   519 #define DW_REG_TABLE_SIZE  <fill in size here, 66 for MIPS/IRIX>

   520 \f(CWtypedef struct {

   521     struct {

   522         Dwarf_Small         dw_offset_relevant;

   523         Dwarf_Half          dw_regnum;

   524         Dwarf_Addr          dw_offset;

   525     }                       rules[DW_REG_TABLE_SIZE];

   526 } Dwarf_Regtable;\fP

   527 .DE

   528 .P

   529 The array is indexed by register number.

   530 The field values for each index are described next.

   531 For clarity we describe the field values for index rules[M]

   532 (M being any legal array element index).

   533 .P

   534 \f(CWdw_offset_relevant\fP is non-zero to indicate the \f(CWdw_offset\fP

   535 field is meaningful. If zero then the \f(CWdw_offset\fP is zero

   536 and should be ignored.

   537 .P

   538 \f(CWdw_regnum \fPis the register number\fP applicable.

   539 If \f(CWdw_offset_relevant\fP is zero, then this is the register

   540 number of the register containing the value for register M.

   541 If \f(CWdw_offset_relevant\fP is non-zero, then this is

   542 the register number of the register to use as a base (M may be

   543 DW_FRAME_CFA_COL, for example) and the \f(CWdw_offset\fP

   544 value applies.  The value of register M is therefore

   545 the value of register \f(CWdw_regnum\vP .

   546 .P

   547 \f(CWdw_offset\fP should be ignored if \f(CWdw_offset_relevant\fP is zero.

   548 If \f(CWdw_offset_relevant\fP is non-zero, then 

   549 the consumer code should add the value to

   550 the value of the register \f(CWdw_regnum\fP to produce the

   551 value.  

   552 

   553 .H 3 "Frame Operation Codes: DWARF 3 (and DWARF2)"

   554 This interface is adequate for DWARF3 and for DWARF2.

   555 It is new in libdwarf in April 2006.

   556 .P

   557 The DWARF2 \f(CWDwarf_Frame_Op3\fP type is used to contain the data of a single

   558 instruction of an instruction-sequence of low-level information from the 

   559 section containing frame information.  This is ordinarily used by 

   560 Internal-level Consumers trying to print everything in detail.

   561 

   562 .DS

   563 \f(CWtypedef struct {

   564         Dwarf_Small     fp_base_op;

   565         Dwarf_Small     fp_extended_op;

   566         Dwarf_Half      fp_register;

   567 

   568         /* Value may be signed, depends on op.

   569            Any applicable data_alignment_factor has

   570            not been applied, this is the  raw offset. */

   571         Dwarf_Unsigned  fp_offset_or_block_len;

   572         Dwarf_Small     *fp_expr_block;

   573 

   574         Dwarf_Off       fp_instr_offset;

   575 } Dwarf_Frame_Op3;\fP

   576 .DE

   577 

   578 \f(CWfp_base_op\fP is the 2-bit basic op code.  \f(CWfp_extended_op\fP is 

   579 the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an 

   580 extended op code) and is zero otherwise.

   581 .P

   582 \f(CWfp_register\fP 

   583 is any (or the first) register value as defined

   584 in the \f(CWCall Frame Instruction Encodings\fP figure

   585 in the \f(CWdwarf\fP document.

   586 If not used with the Op it is 0.

   587 .P

   588 \f(CWfp_offset_or_block_len\fP

   589 is the address, delta, offset, or second register as defined

   590 in the \f(CWCall Frame Instruction Encodings\fP figure

   591 in the \f(CWdwarf\fP document. Or (depending on the op, it

   592 may be the length of the dwarf-expression block pointed to

   593 by \f(CWfp_expr_block\fP.

   594 If this is an \f(CWaddress\fP then the value should be cast to

   595 \f(CW(Dwarf_Addr)\fP before being used.

   596 In any implementation this field *must* be as large as the

   597 larger of Dwarf_Signed and Dwarf_Addr for this to work properly.

   598 If not used with the op it is 0.

   599 .P

   600 \f(CWfp_expr_block\fP (if applicable to the op)

   601 points to a dwarf-expression block whch is \f(CWfp_offset_or_block_len\fP

   602 bytes long.

   603 .P

   604 \f(CWfp_instr_offset\fP is the byte_offset (within the instruction

   605 stream of the frame instructions) of this operation.  It starts at 0

   606 for a given frame descriptor.

   607 

   608 .H 3 "Frame Regtable: DWARF 3"

   609 This interface is adequate for DWARF3 and for DWARF2.

   610 It is new in libdwarf as of April 2006.

   611 .P

   612 The \f(CWDwarf_Regtable3\fP type is used to contain the 

   613 register-restore information for all registers at a given

   614 PC value.

   615 Normally used by debuggers.

   616 .DS

   617 \f(CWtypedef struct Dwarf_Regtable_Entry3_s {

   618         Dwarf_Small         dw_offset_relevant;

   619         Dwarf_Small         dw_value_type;

   620         Dwarf_Half          dw_regnum;

   621         Dwarf_Unsigned      dw_offset_or_block_len;

   622         Dwarf_Ptr           dw_block_ptr;

   623 }Dwarf_Regtable_Entry3;

   624 

   625 typedef struct Dwarf_Regtable3_s {

   626     struct Dwarf_Regtable_Entry3_s   rt3_cfa_rule;

   627 

   628     Dwarf_Half                       rt3_reg_table_size;

   629     struct Dwarf_Regtable_Entry3_s * rt3_rules;

   630 } Dwarf_Regtable3;\fP

   631 

   632 .DE

   633 .P

   634 The array is indexed by register number.

   635 The field values for each index are described next.

   636 For clarity we describe the field values for index rules[M]

   637 (M being any legal array element index).

   638 (DW_FRAME_CFA_COL3  DW_FRAME_SAME_VAL, DW_FRAME_UNDEFINED_VAL

   639 are not legal array indexes, nor is any index < 0 or >

   640 rt3_reg_table_size);

   641 The caller  of routines using this

   642 struct must create data space for rt3_reg_table_size entries

   643 of struct Dwarf_Regtable_Entry3_s and arrange that

   644 rt3_rules points to that space and that rt3_reg_table_size

   645 is set correctly.  The caller need not (but may)

   646 initialize the contents of the rt3_cfa_rule or the rt3_rules array.

   647 The following applies to each rt3_rules rule M:

   648 .P

   649 .in +4

   650 \f(CWdw_regnum\fP is the register number applicable.

   651 If \f(CWdw_regnum\fP is DW_FRAME_UNDEFINED_VAL, then the

   652 register I has undefined value.

   653 If \f(CWdw_regnum\fP is DW_FRAME_SAME_VAL, then the

   654 register I has the same value as in the previous frame.

   655 .P

   656 If \f(CWdw_regnum\fP is neither of these two, then the following apply:

   657 .P

   658 .P

   659 \f(CWdw_value_type\fP determines the meaning of the other fields.

   660 It is one of DW_EXPR_OFFSET (0),

   661 DW_EXPR_VAL_OFFSET(1), DW_EXPR_EXPRESSION(2) or 

   662 DW_EXPR_VAL_EXPRESSION(3).

   663 

   664 .P

   665 If \f(CWdw_value_type\fP  is DW_EXPR_OFFSET (0) then

   666 this is as in DWARF2 and the offset(N) rule  or the register(R)

   667 rule

   668 of the DWARF3 and DWARF2 document applies.

   669 The value is either:

   670 .in +4

   671 If \f(CWdw_offset_relevant\fP is non-zero, then \f(CWdw_regnum\fP  

   672 is effectively ignored but must be identical to

   673 DW_FRAME_CFA_COL3 and the \f(CWdw_offset\fP value applies. 

   674 The value of register M is therefore

   675 the value of CFA plus the value

   676 of \f(CWdw_offset\fP.   The result of the calculation

   677 is the address in memory where the value of register M resides.

   678 This is the offset(N) rule of the DWARF2 and DWARF3 documents.

   679 .P

   680 \f(CWdw_offset_relevant\fP is zero it indicates the \f(CWdw_offset\fP

   681 field is not meaningful. 

   682 The value of register M is 

   683 the value currently in register \f(CWdw_regnum\fP (the

   684 value DW_FRAME_CFA_COL3 must not appear, only real registers).

   685 This is the register(R) rule of the DWARF3 spec.

   686 .in -4

   687 

   688 .P

   689 If \f(CWdw_value_type\fP  is DW_EXPR_OFFSET (1) then

   690 this is the the val_offset(N) rule of the DWARF3 spec applies.

   691 The calculation is identical to that of DW_EXPR_OFFSET (0) 

   692 but the value is interpreted as the value of register M

   693 (rather than the address where register M's value is stored).

   694 .P

   695 If \f(CWdw_value_type\fP  is DW_EXPR_EXPRESSION (2) then

   696 this is the the expression(E) rule of the DWARF3 document.

   697 .P

   698 .in +4

   699 \f(CWdw_offset_or_block_len\fP is the length in bytes of

   700 the in-memory block  pointed at by \f(CWdw_block_ptr\fP.

   701 \f(CWdw_block_ptr\fP is a DWARF expression.

   702 Evaluate that expression and the result is the address

   703 where the previous value of register M is found.

   704 .in -4

   705 .P

   706 If \f(CWdw_value_type\fP  is DW_EXPR_VAL_EXPRESSION (3) then

   707 this is the the val_expression(E) rule of the DWARF3 spec.

   708 .P

   709 .in +4

   710 \f(CWdw_offset_or_block_len\fP is the length in bytes of

   711 the in-memory block  pointed at by \f(CWdw_block_ptr\fP.

   712 \f(CWdw_block_ptr\fP is a DWARF expression.

   713 Evaluate that expression and the result is the 

   714 previous value of register M.

   715 .in -4

   716 .P

   717 The rule \f(CWrt3_cfa_rule\fP is the current value of

   718 the CFA. It is interpreted exactly like

   719 any register M rule (as described just above) except that 

   720 \f(CWdw_regnum\fP cannot be CW_FRAME_CFA_REG3 or

   721 DW_FRAME_UNDEFINED_VAL or DW_FRAME_SAME_VAL but must

   722 be a real register number.

   723 .in -4

   724 

   725 

   726 

   727 .H 3 "Macro Details Record"

   728 The \f(CWDwarf_Macro_Details\fP type gives information about

   729 a single entry in the .debug.macinfo section.

   730 .DS

   731 \f(CWstruct Dwarf_Macro_Details_s {

   732   Dwarf_Off    dmd_offset;

   733   Dwarf_Small  dmd_type;  

   734   Dwarf_Signed dmd_lineno;

   735   Dwarf_Signed dmd_fileindex;

   736   char *       dmd_macro;

   737 };

   738 typedef struct Dwarf_Macro_Details_s Dwarf_Macro_Details;

   739 .DE

   740 .P

   741 \f(CWdmd_offset\fP is the byte offset, within the .debug_macinfo

   742 section, of this macro information.

   743 .P

   744 \f(CWdmd_type\fP is the type code of this macro info entry

   745 (or 0, the type code indicating that this is the end of

   746 macro information entries for a compilation unit.

   747 See \f(CWDW_MACINFO_define\fP, etc in the DWARF document.

   748 .P

   749 \f(CWdmd_lineno\fP is the line number where this entry was found,

   750 or 0 if there is no applicable line number.

   751 .P

   752 \f(CWdmd_fileindex\fP is the file index of the file involved.

   753 This is only guaranteed meaningful on a \f(CWDW_MACINFO_start_file\fP

   754 \f(CWdmd_type\fP.  Set to -1 if unknown (see the functional

   755 interface for more details).

   756 .P

   757 \f(CWdmd_macro\fP is the applicable string.

   758 For a \f(CWDW_MACINFO_define\fP

   759 this is the macro name and value.

   760 For a

   761 \f(CWDW_MACINFO_undef\fP, or

   762 this is the macro name.

   763 For a

   764 \f(CWDW_MACINFO_vendor_ext\fP

   765 this is the vendor-defined string value.

   766 For other \f(CWdmd_type\fPs this is 0.

   767 

   768 .H 2 "Opaque Types"

   769 The opaque types declared in \fIlibdwarf.h\fP are used as descriptors

   770 for queries against DWARF information stored in various debugging 

   771 sections.  Each time an instance of an opaque type is returned as a 

   772 result of a \fIlibdwarf\fP operation (\f(CWDwarf_Debug\fP excepted), 

   773 it should be free'd, using \f(CWdwarf_dealloc()\fP when it is no longer 

   774 of use (read the following documentation for details, as in at least

   775 one case there is a special routine provided for deallocation

   776 and \f(CWdwarf_dealloc()\fP is not directly called: 

   777 see \f(CWdwarf_srclines()\fP).

   778 Some functions return a number of instances of an opaque type 

   779 in a block, by means of a pointer to the block and a count of the number

   780 of opaque descriptors in the block:

   781 see the function description for deallocation rules for such functions.

   782 The list of opaque types defined 

   783 in \fIlibdwarf.h\fP that are pertinent to the Consumer Library, and their 

   784 intended use is described below.

   785 

   786 .DS

   787 \f(CWtypedef struct Dwarf_Debug_s* Dwarf_Debug;\fP

   788 .DE

   789 An instance of the \f(CWDwarf_Debug\fP type is created as a result of a 

   790 successful call to \f(CWdwarf_init()\fP, or \f(CWdwarf_elf_init()\fP, 

   791 and is used as a descriptor for subsequent access to most \f(CWlibdwarf\fP

   792 functions on that object.  The storage pointed to by this descriptor 

   793 should be not be free'd, using the \f(CWdwarf_dealloc()\fP function.

   794 Instead free it with \f(CWdwarf_finish()\fP.

   795 .P

   796 

   797 .DS

   798 \f(CWtypedef struct Dwarf_Die_s* Dwarf_Die;\fP

   799 .DE

   800 An instance of a \f(CWDwarf_Die\fP type is returned from a successful 

   801 call to the \f(CWdwarf_siblingof()\fP, \f(CWdwarf_child\fP, or 

   802 \f(CWdwarf_offdie()\fP function, and is used as a descriptor for queries 

   803 about information related to that DIE.  The storage pointed to by this 

   804 descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the allocation 

   805 type \f(CWDW_DLA_DIE\fP when no longer needed.

   806 

   807 .DS

   808 \f(CWtypedef struct Dwarf_Line_s* Dwarf_Line;\fP

   809 .DE

   810 Instances of \f(CWDwarf_Line\fP type are returned from a successful call 

   811 to the \f(CWdwarf_srclines()\fP function, and are used as descriptors for 

   812 queries about source lines.  The storage pointed to by these descriptors

   813 should be individually free'd, using \f(CWdwarf_dealloc()\fP with the 

   814 allocation type \f(CWDW_DLA_LINE\fP when no longer needed.

   815 

   816 .DS

   817 \f(CWtypedef struct Dwarf_Global_s* Dwarf_Global;\fP

   818 .DE

   819 Instances of \f(CWDwarf_Global\fP type are returned from a successful 

   820 call to the \f(CWdwarf_get_globals()\fP function, and are used as 

   821 descriptors for queries about global names (pubnames).

   822 

   823 .DS

   824 \f(CWtypedef struct Dwarf_Weak_s* Dwarf_Weak;\fP

   825 .DE

   826 Instances of \f(CWDwarf_Weak\fP type are returned from a successful call 

   827 to the 

   828 SGI-specific \f(CWdwarf_get_weaks()\fP

   829 function, and are used as descriptors for 

   830 queries about weak names.  The storage pointed to by these descriptors 

   831 should be individually free'd, using \f(CWdwarf_dealloc()\fP with the 

   832 allocation type 

   833 \f(CWDW_DLA_WEAK_CONTEXT\fP 

   834 (or

   835 \f(CWDW_DLA_WEAK\fP, an older name, supported for compatibility)

   836 when no longer needed.

   837 

   838 .DS

   839 \f(CWtypedef struct Dwarf_Func_s* Dwarf_Func;\fP

   840 .DE

   841 Instances of \f(CWDwarf_Func\fP type are returned from a successful

   842 call to the 

   843 SGI-specific \f(CWdwarf_get_funcs()\fP

   844 function, and are used as 

   845 descriptors for queries about static function names.  

   846 

   847 .DS

   848 \f(CWtypedef struct Dwarf_Type_s* Dwarf_Type;\fP

   849 .DE

   850 Instances of \f(CWDwarf_Type\fP type are returned from a successful call 

   851 to the 

   852 SGI-specific \f(CWdwarf_get_types()\fP

   853 function, and are used as descriptors for 

   854 queries about user defined types.  

   855 

   856 .DS

   857 \f(CWtypedef struct Dwarf_Var_s* Dwarf_Var;\fP

   858 .DE

   859 Instances of \f(CWDwarf_Var\fP type are returned from a successful call 

   860 to the SGI-specific \f(CWdwarf_get_vars()\fP

   861 function, and are used as descriptors for 

   862 queries about static variables.  

   863 

   864 .DS

   865 \f(CWtypedef struct Dwarf_Error_s* Dwarf_Error;\fP

   866 .DE

   867 This descriptor points to a structure that provides detailed information

   868 about errors detected by \f(CWlibdwarf\fP.  Users typically provide a

   869 location for \f(CWlibdwarf\fP to store this descriptor for the user to

   870 obtain more information about the error.  The storage pointed to by this

   871 descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the 

   872 allocation type \f(CWDW_DLA_ERROR\fP when no longer needed.

   873 

   874 .DS

   875 \f(CWtypedef struct Dwarf_Attribute_s* Dwarf_Attribute;\fP

   876 .DE

   877 Instances of \f(CWDwarf_Attribute\fP type are returned from a successful 

   878 call to the \f(CWdwarf_attrlist()\fP, or \f(CWdwarf_attr()\fP functions, 

   879 and are used as descriptors for queries about attribute values.  The storage 

   880 pointed to by this descriptor should be individually free'd, using 

   881 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ATTR\fP when 

   882 no longer needed.

   883 

   884 .DS

   885 \f(CWtypedef struct Dwarf_Abbrev_s* Dwarf_Abbrev;\fP

   886 .DE

   887 An instance of a \f(CWDwarf_Abbrev\fP type is returned from a successful 

   888 call to \f(CWdwarf_get_abbrev()\fP, and is used as a descriptor for queries 

   889 about abbreviations in the .debug_abbrev section.  The storage pointed to 

   890 by this descriptor should be free'd, using \f(CWdwarf_dealloc()\fP with the

   891 allocation type \f(CWDW_DLA_ABBREV\fP when no longer needed.

   892 

   893 .DS

   894 \f(CWtypedef struct Dwarf_Fde_s* Dwarf_Fde;\fP

   895 .DE

   896 Instances of \f(CWDwarf_Fde\fP type are returned from a successful call 

   897 to the \f(CWdwarf_get_fde_list()\fP, \f(CWdwarf_get_fde_for_die()\fP, or

   898 \f(CWdwarf_get_fde_at_pc()\fP functions, and are used as descriptors for 

   899 queries about frames descriptors.

   900 

   901 .DS

   902 \f(CWtypedef struct Dwarf_Cie_s* Dwarf_Cie;\fP

   903 .DE

   904 Instances of \f(CWDwarf_Cie\fP type are returned from a successful call 

   905 to the \f(CWdwarf_get_fde_list()\fP function, and are used as descriptors 

   906 for queries about information that is common to several frames.

   907 

   908 .DS

   909 \f(CWtypedef struct Dwarf_Arange_s* Dwarf_Arange;\fP

   910 .DE

   911 Instances of \f(CWDwarf_Arange\fP type are returned from successful calls 

   912 to the \f(CWdwarf_get_aranges()\fP, or \f(CWdwarf_get_arange()\fP functions, 

   913 and are used as descriptors for queries about address ranges.  The storage 

   914 pointed to by this descriptor should be individually free'd, using 

   915 \f(CWdwarf_dealloc()\fP with the allocation type \f(CWDW_DLA_ARANGE\fP when 

   916 no longer needed.

   917 

   918 .H 1 "Error Handling"

   919 The method for detection and disposition of error conditions that arise 

   920 during access of debugging information via \fIlibdwarf\fP is consistent

   921 across all \fIlibdwarf\fP functions that are capable of producing an

   922 error.  This section describes the method used by \fIlibdwarf\fP in

   923 notifying client programs of error conditions. 

   924 

   925 .P

   926 Most functions within \fIlibdwarf\fP accept as an argument a pointer to 

   927 a \f(CWDwarf_Error\fP descriptor where a \f(CWDwarf_Error\fP descriptor 

   928 is stored if an error is detected by the function.  Routines in the client 

   929 program that provide this argument can query the \f(CWDwarf_Error\fP 

   930 descriptor to determine the nature of the error and perform appropriate 

   931 processing. 

   932 

   933 .P

   934 A client program can also specify a function to be invoked upon detection 

   935 of an error at the time the library is initialized (see \f(CWdwarf_init()\fP). 

   936 When a \fIlibdwarf\fP routine detects an error, this function is called

   937 with two arguments: a code indicating the nature of the error and a pointer

   938 provided by the client at initialization (again see \f(CWdwarf_init()\fP).

   939 This pointer argument can be used to relay information between the error 

   940 handler and other routines of the client program.  A client program can 

   941 specify or change both the error handling function and the pointer argument 

   942 after initialization using \f(CWdwarf_seterrhand()\fP and 

   943 \f(CWdwarf_seterrarg()\fP.

   944 

   945 .P

   946 In the case where \fIlibdwarf\fP functions are not provided a pointer

   947 to a \f(CWDwarf_Error\fP descriptor, and no error handling function was 

   948 provided at initialization, \fIlibdwarf\fP functions terminate execution 

   949 by calling \f(CWabort(3C)\fP.

   950 

   951 .P

   952 The following lists the processing steps taken upon detection of an

   953 error:

   954 .AL 1

   955 .LI

   956 Check the \f(CWerror\fP argument; if not a \fINULL\fP pointer, allocate

   957 and initialize a \f(CWDwarf_Error\fP descriptor with information describing

   958 the error, place this descriptor in the area pointed to by \f(CWerror\fP,

   959 and return a value indicating an error condition.

   960 .LI

   961 If an \f(CWerrhand\fP argument was provided to \f(CWdwarf_init()\fP

   962 at initialization, call \f(CWerrhand()\fP passing it the error descriptor

   963 and the value of the \f(CWerrarg\fP argument provided to \f(CWdwarf_init()\fP. 

   964 If the error handling function returns, return a value indicating an 

   965 error condition.

   966 .LI

   967 Terminate program execution by calling \f(CWabort(3C)\fP.

   968 .LE

   969 .SP

   970 

   971 In all cases, it is clear from the value returned from a function 

   972 that an error occurred in executing the function, since

   973 DW_DLV_ERROR is returned.

   974 .P

   975 As can be seen from the above steps, the client program can provide

   976 an error handler at initialization, and still provide an \f(CWerror\fP

   977 argument to \fIlibdwarf\fP functions when it is not desired to have

   978 the error handler invoked.

   979 

   980 .P

   981 If a \f(CWlibdwarf\fP function is called with invalid arguments, the 

   982 behaviour is undefined.  In particular, supplying a \f(CWNULL\fP pointer 

   983 to a \f(CWlibdwarf\fP function (except where explicitly permitted), 

   984 or pointers to invalid addresses or uninitialized data causes undefined 

   985 behaviour; the return value in such cases is undefined, and the function 

   986 may fail to invoke the caller supplied error handler or to return a 

   987 meaningful error number.  Implementations also may abort execution for 

   988 such cases.

   989 

   990 .P

   991 .H 2 "Returned values in the functional interface"

   992 Values returned by \f(CWlibdwarf\fP functions to indicate 

   993 success and errors

   994 .nr aX \n(Fg+1

   995 are enumerated in Figure \n(aX.

   996 The \f(CWDW_DLV_NO_ENTRY\fP

   997 case is useful for functions 

   998 need to indicate that while there was no data to return

   999 there was no error either.

  1000 For example, \f(CWdwarf_siblingof()\fP

  1001 may return \f(CWDW_DLV_NO_ENTRY\fP to indicate that that there was

  1002 no sibling to return.

  1003 .DS

  1004 .TS

  1005 center box, tab(:);

  1006 lfB cfB lfB 

  1007 l c l.

  1008 SYMBOLIC NAME:VALUE:MEANING

  1009 _

  1010 DW_DLV_ERROR:1:Error

  1011 DW_DLV_OK:0:Successful call

  1012 DW_DLV_NO_ENTRY:-1:No applicable value

  1013 .TE

  1014 .FG "Error Indications"

  1015 .DE

  1016 .P

  1017 Each function in the interface that returns a value returns one

  1018 of the integers in the above figure.

  1019 .P

  1020 If \f(CWDW_DLV_ERROR\fP is returned and a pointer to a \f(CWDwarf_Error\fP

  1021 pointer is passed to the function, then a Dwarf_Error handle is returned

  1022 thru the pointer. No other pointer value in the interface returns a value.

  1023 After the \f(CWDwarf_Error\fP is no longer of interest,

  1024 a  \f(CWdwarf_dealloc(dbg,dw_err,DW_DLA_ERROR)\fP on the error

  1025 pointer is appropriate to free any space used by the error information.

  1026 .P

  1027 If \f(CWDW_DLV_NO_ENTRY\fP is returned no pointer value in the

  1028 interface returns a value.

  1029 .P

  1030 If \f(CWDW_DLV_OK\fP is returned  the \f(CWDwarf_Error\fP pointer, if

  1031 supplied, is not touched, but any other values to be returned

  1032 through pointers are returned.

  1033 In this case calls (depending on the exact function

  1034 returning the error) to \f(CWdwarf_dealloc()\fP may be appropriate

  1035 once the particular pointer returned is no longer of interest.

  1036 .P

  1037 Pointers passed to allow values to be returned thru them are 

  1038 uniformly the last pointers

  1039 in each argument list.

  1040 .P

  1041 All the interface functions are defined from the point of view of

  1042 the writer-of-the-library (as is traditional for UN*X library

  1043 documentation), not from the point of view of the user of the library.

  1044 The caller might code:

  1045 .P

  1046 .DS

  1047 Dwarf_Line line;

  1048 Dwarf_Signed ret_loff;

  1049 Dwarf_Error  err;

  1050 int retval = dwarf_lineoff(line,&ret_loff,&err); 

  1051 .DE

  1052 for the function defined as

  1053 .P

  1054 .DS

  1055 int dwarf_lineoff(Dwarf_Line line,Dwarf_Signed *return_lineoff,

  1056   Dwarf_Error* err);

  1057 .DE

  1058 and this document refers to the function as 

  1059 returning the value thru *err or *return_lineoff or 

  1060 uses the phrase "returns in

  1061 the location pointed to by err".

  1062 Sometimes other similar phrases are used.

  1063 

  1064 .H 1 "Memory Management"

  1065 Several of the functions that comprise \fIlibdwarf\fP return pointers 

  1066 (opaque descriptors) to structures that have been dynamically allocated 

  1067 by the library.  To aid in the management of dynamic memory, the function 

  1068 \f(CWdwarf_dealloc()\fP is provided to free storage allocated as a result 

  1069 of a call to a \fIlibdwarf\fP function.  This section describes the strategy 

  1070 that should be taken by a client program in managing dynamic storage.

  1071 

  1072 .H 2 "Read-only Properties"

  1073 All pointers (opaque descriptors) returned by or as a result of a 

  1074 \fIlibdwarf Consumer Library\fP 

  1075 call should be assumed to point to read-only memory.  

  1076 The results are undefined for \fIlibdwarf\fP  clients that attempt 

  1077 to write to a region pointed to by a value returned by a 

  1078 \fIlibdwarf Consumer Library\fP 

  1079 call.

  1080 

  1081 .H 2 "Storage Deallocation"

  1082 See the section "Returned values in the functional interface",

  1083 above, for the general rules where 

  1084 calls to \f(CWdwarf_dealloc()\fP

  1085 is appropriate.

  1086 .P

  1087 In some cases the pointers returned by a \fIlibdwarf\fP call are pointers

  1088 to data which is not free-able.  

  1089 The library knows from the allocation type

  1090 provided to it whether the space is freeable or not and will not free 

  1091 inappropriately when \f(CWdwarf_dealloc()\fP is called.  

  1092 So it is vital

  1093 that \f(CWdwarf_dealloc()\fP be called with the proper allocation type.

  1094 .P

  1095 For most storage allocated by \fIlibdwarf\fP, the client can free the

  1096 storage for reuse by calling \f(CWdwarf_dealloc()\fP, providing it with 

  1097 the \f(CWDwarf_Debug\fP descriptor specifying the object for which the

  1098 storage was allocated, a pointer to the area to be free-ed, and an 

  1099 identifier that specifies what the pointer points to (the allocation

  1100 type).  For example, to free a \f(CWDwarf_Die die\fP belonging the the

  1101 object represented by \f(CWDwarf_Debug dbg\fP, allocated by a call to 

  1102 \f(CWdwarf_siblingof()\fP, the call to \f(CWdwarf_dealloc()\fP would be:

  1103 .DS

  1104     \f(CWdwarf_dealloc(dbg, die, DW_DLA_DIE);\fP

  1105 .DE

  1106 

  1107 To free storage allocated in the form of a list of pointers (opaque 

  1108 descriptors), each member of the list should be deallocated, followed 

  1109 by deallocation of the actual list itself.  The following code fragment 

  1110 uses an invocation of \f(CWdwarf_attrlist()\fP as an example to illustrate 

  1111 a technique that can be used to free storage from any \fIlibdwarf\fP 

  1112 routine that returns a list:

  1113 .DS

  1114 \f(CWDwarf_Unsigned atcnt;

  1115 Dwarf_Attribute *atlist;

  1116 int errv;

  1117 

  1118 errv = dwarf_attrlist(somedie, &atlist,&atcnt, &error);

  1119 if (errv == DW_DLV_OK) {

  1120 

  1121         for (i = 0; i < atcnt; ++i) {

  1122                 /* use atlist[i] */

  1123                 dwarf_dealloc(dbg, atlist[i], DW_DLA_ATTR);

  1124         }

  1125         dwarf_dealloc(dbg, atlist, DW_DLA_LIST);

  1126 }\fP

  1127 .DE

  1128 

  1129 The \f(CWDwarf_Debug\fP returned from \f(CWdwarf_init()\fP 

  1130 or \f(CWdwarf_elf_init()\fP 

  1131 cannot be free'd using \f(CWdwarf_dealloc()\fP.

  1132 The function \f(CWdwarf_finish()\fP will deallocate all dynamic storage

  1133 associated with an instance of a \f(CWDwarf_Debug\fP type.  In particular,

  1134 it will deallocate all dynamically allocated space associated with the

  1135 \f(CWDwarf_Debug\fP descriptor, and finally make the descriptor invalid.