contrib/elftoolchain/libdwarf/dwarf.3

   1 .\" Copyright (c) 2011 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Joseph Koshy ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $Id: dwarf.3 2075 2011-10-27 03:47:28Z jkoshy $
  25 .\"
  26 .Dd September 17, 2011
  27 .Os
  28 .Dt DWARF 3
  29 .Sh NAME
  30 .Nm dwarf
  31 .Nd access debugging information in object files
  32 .Sh LIBRARY
  33 .Lb libdwarf
  34 .Sh SYNOPSIS
  35 .In libdwarf.h
  36 .Sh DESCRIPTION
  37 .Pp
  38 The
  39 .Lb libdwarf
  40 provides functions that allow an application to read and write debugging
  41 information in object files.
  42 The format of debugging information accessible through this API
  43 is defined by the DWARF standard, see
  44 .Xr dwarf 4 .
  45 .Pp
  46 The
  47 .Xr DWARF 3
  48 API has two parts:
  49 .Bl -bullet
  50 .It
  51 A consumer API set allows applications to read existing debug information
  52 in a program object.
  53 The functions that comprise the DWARF consumer API are described in
  54 the section
  55 .Sx "DWARF Consumer API"
  56 below.
  57 .It
  58 A producer API set that allows applications to add debug information
  59 to a program object.
  60 The functions that comprise the DWARF producer API are described in
  61 the section
  62 .Sx "DWARF Producer API"
  63 below.
  64 .El
  65 .Pp
  66 Each function referenced below is further described in its own manual page.
  67 .Ss Namespace use
  68 The DWARF library uses the following prefixes:
  69 .Pp
  70 .Bl -tag -width ".Li Dwarf_*" -compact
  71 .It Li DWARF_*
  72 Used for error numbers and constants.
  73 .It Li DW_*
  74 Used for constants.
  75 .It Li Dwarf_*
  76 Used for types.
  77 .It Li dwarf_*
  78 Used for functions and macros that make up the API.
  79 .El
  80 .Ss Data Types
  81 The DWARF(3) API uses the following data types:
  82 .Pp
  83 .Bl -tag -width ".Vt Dwarf_Unsigned" -compact
  84 .It Vt Dwarf_Abbrev
  85 Describes DWARF abbreviations.
  86 .It Vt Dwarf_Addr
  87 A program address in the target object.
  88 .It Vt Dwarf_Arange
  89 Describes address ranges.
  90 .It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute
  91 Describes attributes of debugging information entries.
  92 .It Vt Dwarf_Bool
  93 Used for boolean states.
  94 .It Vt Dwarf_Cie , Vt Dwarf_P_Cie
  95 Describes call information that is common to several frames.
  96 .It Vt Dwarf_Debug , Vt Dwarf_P_Debug
  97 An opaque type describing a debug context.
  98 .It Vt Dwarf_Die , Vt Dwarf_P_Die
  99 A debugging information entry.
 100 .It Vt Dwarf_Fde , Vt Dwarf_P_Fde
 101 A frame descriptor.
 102 .It Vt Dwarf_Func
 103 A descriptor representing a function.
 104 .It Vt Dwarf_Global
 105 A descriptor representing a global name.
 106 .It Vt Dwarf_Half
 107 A 16-bit wide unsigned numeric type.
 108 .It Vt Dwarf_Handler
 109 A pointer to an error handling function.
 110 .It Vt Dwarf_Line
 111 A descriptor for a source line.
 112 .It Vt Dwarf_Off
 113 An unsigned file offset, corresponding to an
 114 .Vt off_t
 115 type supported by the underlying operating system.
 116 .It Vt Dwarf_P_Expr
 117 A descriptor for a location expression.
 118 .It Vt Dwarf_Ptr
 119 A virtual address used by an application.
 120 .It Vt Dwarf_Signed
 121 A 64-bit wide signed numeric type.
 122 .It Vt Dwarf_Small
 123 An 8-bit wide unsigned numeric type.
 124 .It Vt Dwarf_Type
 125 A descriptor representing a user-specified type.
 126 .It Vt Dwarf_Unsigned
 127 A 64-bit wide unsigned numeric type.
 128 .It Vt Dwarf_Var
 129 A descriptor representing a static variable.
 130 .It Vt Dwarf_Weak
 131 A descriptor representing a weak name.
 132 .El
 133 .Ss Error Handling
 134 .Pp
 135 Library functions that encounter an error will return with a value
 136 other than
 137 .Dv DW_DLV_OK .
 138 .Pp
 139 The
 140 .Lb libdwarf
 141 allows applications to specify three levels of error handling:
 142 .Bl -enum -compact
 143 .It
 144 Most library functions take a parameter of type
 145 .Vt Dwarf_Error
 146 that specifies a location to store an error descriptor in
 147 case of an error.
 148 If an error occurs during the execution on an API, and if this
 149 parameter is non-NULL, then an error descriptor is written to the
 150 location specified.
 151 .It
 152 Otherwise, if the error parameter was NULL, but if an error handler
 153 was defined for the debug context in use using
 154 .Xr dwarf_init 3
 155 or
 156 .Xr dwarf_seterrhand 3 ,
 157 then the library will invoke the specified error handler with an error
 158 descriptor as argument.
 159 .It
 160 Otherwise, if a library wide error handler was specified using
 161 .Xr dwarf_seterrhand 3 ,
 162 it is called.
 163 .El
 164 .Pp
 165 Error descriptors may be used with
 166 .Xr dwarf_errmsg 3
 167 or
 168 .Xr dwarf_errno 3 .
 169 .Sh The DWARF Consumer API
 170 The DWARF consumer API permits applications to read DWARF information in
 171 an object file.
 172 .Pp
 173 The major functional groups of functions in the consumer API are listed
 174 below.
 175 .Pp
 176 .Bl -tag -compact -width "CCCC"
 177 .It Abbreviations
 178 .Bl -tag -compact
 179 .It Fn dwarf_get_abbrev
 180 Retrieve abbreviation information at a given offset.
 181 .It Fn dwarf_get_abbrev_children_flag
 182 Check if an abbreviation has child elements.
 183 .It Fn dwarf_get_abbrev_code
 184 Retrieve the abbreviation code for an abbreviation entry descriptor.
 185 .It Fn dwarf_get_abbrev_entry
 186 Retrieve abbreviation information for an abbreviation entry
 187 descriptor.
 188 .It Fn dwarf_get_abbrev_tag
 189 Retrieve the tag for an abbreviation entry.
 190 .El
 191 .It Addresses
 192 .Bl -tag -compact
 193 .It Fn dwarf_get_address_size
 194 Return the number of bytes needed to represent an address.
 195 .It Fn dwarf_get_arange
 196 Search for an address range descriptor covering an address.
 197 .It Fn dwarf_get_arange_cu_header_offset
 198 Retrieve the offsets associated with an address range descriptor.
 199 .It Fn dwarf_get_arange_info
 200 Extract address range information from a descriptor.
 201 .It Fn dwarf_get_aranges
 202 Retrieve program address space mappings.
 203 .It Fn dwarf_get_cu_die_offset
 204 Retrieve the offset associated with a compilation unit for an address
 205 range descriptor.
 206 .It Fn dwarf_get_ranges , Fn dwarf_get_ranges_a
 207 Retrieve information about non-contiguous address ranges for
 208 a debugging information entry.
 209 .El
 210 .It Attributes
 211 .Bl -tag -compact
 212 .It Fn dwarf_arrayorder
 213 Retrieve the value of a
 214 .Dv DW_AT_ordering
 215 attribute.
 216 .It Fn dwarf_attr
 217 Retrieve an attribute descriptor.
 218 .It Fn dwarf_attrlist
 219 Retrieve attribute descriptors for a debugging information entry.
 220 .It Fn dwarf_attrval_flag
 221 Retrieve a
 222 .Dv DW_AT_FORM_flag
 223 value.
 224 .It Fn dwarf_attrval_signed
 225 Retrieve an attribute's value as a signed integral quantity.
 226 .It Fn dwarf_attrval_string
 227 Retrieve an attribute's value as a NUL-terminated string.
 228 .It Fn dwarf_attrval_unsigned
 229 Retrieve an attribute's value as an unsigned integral quantity.
 230 .It Fn dwarf_bitoffset ,
 231 Retrieve the value of a
 232 .Dv DW_AT_bit_offset
 233 attribute.
 234 .It Fn dwarf_bitsize ,
 235 Retrieve the value of a
 236 .Dv DW_AT_bit_size
 237 attribute.
 238 .It Fn dwarf_bytesize
 239 Retrieve the value of a
 240 .Dv DW_AT_byte_size
 241 attribute.
 242 .It Fn dwarf_formaddr
 243 Return the value of an
 244 .Dv ADDRESS Ns - Ns
 245 class attribute.
 246 .It Fn dwarf_formblock
 247 Return the value of a
 248 .Dv BLOCK Ns - Ns
 249 class attribute
 250 .It Fn dwarf_formexprloc
 251 Return information about a location expression.
 252 .It Fn dwarf_formflag
 253 Retrieve information about a
 254 .Dv BOOLEAN Ns - Ns
 255 class attribute.
 256 .It Fn dwarf_formref , Fn dwarf_global_formref
 257 Retrieve offsets for
 258 .Dv REFERENCE Ns - Ns
 259 class attributes.
 260 .It Fn dwarf_formsdata , Fn dwarf_formudata
 261 Retrieve the value of a
 262 .Dv CONSTANT Ns - Ns
 263 class attribute.
 264 .It Fn dwarf_formsig8
 265 Return the type signature for a DWARF type.
 266 .It Fn dwarf_formstring
 267 Retrieve information about a
 268 .Dv STRING Ns - Ns
 269 class attribute.
 270 .It Fn dwarf_get_form_class
 271 Retrieve the form class for an attribute.
 272 .It Fn dwarf_hasattr
 273 Check for the presence of an attribute.
 274 .It Fn dwarf_hasform
 275 Check if an attribute has the given form.
 276 .It Fn dwarf_whatattr
 277 Retrieve the attribute code for an attribute.
 278 .It Fn dwarf_whatform , Fn dwarf_whatform_direct
 279 Retrieve the form of an attribute.
 280 .El
 281 .It Call Information Entries and Frame Descriptor Entries
 282 .Bl -tag -compact
 283 .It Fn dwarf_get_cie_index
 284 Retrieve the index for a CIE descriptor.
 285 .It Fn dwarf_get_cie_info
 286 Retrieve information from a CIE descriptor.
 287 .It Fn dwarf_get_cie_of_fde
 288 Retrieve a CIE descriptor.
 289 .It Fn dwarf_get_fde_at_pc
 290 Retrieve an FDE descriptor for an address.
 291 .It Fn dwarf_get_fde_info_for_all_regs
 292 Retrieve register rule row.
 293 .It Fn dwarf_get_fde_info_for_all_regs3
 294 Retrieve register rule row (revised API).
 295 .It Fn dwarf_get_fde_info_for_cfa_reg3
 296 Retrieve a CFA register rule.
 297 .It Fn dwarf_get_fde_info_for_reg
 298 Retrieve a register rule.
 299 .It Fn dwarf_get_fde_info_for_reg3
 300 Retrieve a register rule (revised API).
 301 .It Fn dwarf_get_fde_instr_bytes
 302 Retrieve instructions from an FDE descriptor.
 303 .It Fn dwarf_get_fde_list , Fn dwarf_get_fde_list_eh
 304 Retrieve frame information.
 305 .It Fn dwarf_get_fde_n
 306 Retrieve an FDE descriptor.
 307 .It Fn dwarf_get_fde_range
 308 Retrieve range information from an FDE descriptor.
 309 .El
 310 .It Compilation Units
 311 .Bl -tag -compact
 312 .It Fn dwarf_get_cu_die_offset_given_cu_header_offset
 313 Retrieve the offset of the debugging information entry for a
 314 compilation unit.
 315 .It Fn dwarf_next_cu_header , Fn dwarf_next_cu_header_b
 316 Step through compilation units in a debug context.
 317 .El
 318 .It Debugging Information Entries
 319 .Bl -tag -compact
 320 .It Fn dwarf_child
 321 Returns the child of a debugging information entry.
 322 .It Fn dwarf_die_abbrev_code
 323 Returns the abbreviation code for a debugging information entry.
 324 .It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range
 325 Retrieve offsets and lengths for a compilation unit.
 326 .It Fn dwarf_diename
 327 Returns the
 328 .Dv DW_AT_name
 329 attribute for a debugging information entry.
 330 .It Fn dwarf_dieoffset
 331 Retrieves the offset for a debugging information entry.
 332 .It Fn dwarf_highpc
 333 Return the highest PC value for a debugging information entry.
 334 .It Fn dwarf_lowpc
 335 Return the lowest PC value for a debugging information entry.
 336 .It Fn dwarf_offdie
 337 Retrieve a debugging information entry given an offset.
 338 .It Fn dwarf_siblingof
 339 Retrieve the sibling descriptor for a debugging information entry.
 340 .It Fn dwarf_srclang
 341 Retrive the source language attribute for a debugging information
 342 entry.
 343 .It Fn dwarf_tag
 344 Retrieve the tag for a debugging information entry.
 345 .El
 346 .It Functions
 347 .Bl -tag -compact
 348 .It Fn dwarf_func_cu_offset
 349 Retrieves the offset for the compilation unit for a function.
 350 .It Fn dwarf_func_die_offset
 351 Retrieves the offset for the debugging information entry for a
 352 function.
 353 .It Fn dwarf_funcname
 354 Retrieves the name of a function.
 355 .It Fn dwarf_func_name_offsets
 356 Retrieve both the name and offsets for a function.
 357 .It Fn dwarf_get_funcs
 358 Retrieve information about static functions.
 359 .El
 360 .It Globals
 361 .Bl -tag -compact
 362 .It Fn dwarf_get_globals
 363 Retrieve a list of globals.
 364 .It Fn dwarf_global_cu_offset
 365 Return the offset for compilation unit for a global.
 366 .It Fn dwarf_global_die_offset
 367 Return the offset for the debugging information entry for a global.
 368 .It Fn dwarf_global_name_offsets
 369 Return the name and offsets for a global.
 370 .It Fn dwarf_globname
 371 Return the name for a global.
 372 .El
 373 .It Initialization and Finalization
 374 Functions
 375 .Fn dwarf_elf_init
 376 and
 377 .Fn dwarf_init
 378 may be used for initialization.
 379 The function
 380 .Fn dwarf_finish
 381 may be used to release resources.
 382 .Pp
 383 The functions
 384 .Fn dwarf_object_init
 385 and
 386 .Fn dwarf_object_finish
 387 allow an application to specify alternate low-level file access
 388 routines.
 389 .It Line Numbers
 390 .Bl -tag -compact
 391 .It Fn dwarf_lineaddr
 392 Retrieve the program address for a source line.
 393 .It Fn dwarf_linebeginstatement
 394 Check if a source line corresponds to the beginning of a statement.
 395 .It Fn dwarf_lineblock
 396 Check if a source line corresponds to the start of a basic block.
 397 .It Fn dwarf_lineendsequence
 398 Check if the source line corresponds to the end of a sequence of
 399 instructions.
 400 .It Fn dwarf_lineno
 401 Retrieve the line number for a line descriptor.
 402 .It Fn dwarf_lineoff
 403 Retrieve the column number for a line descriptor.
 404 .It Fn dwarf_linesrc
 405 Retrieve the source file for a line descriptor.
 406 .It Fn dwarf_line_srcfileno
 407 Retrieve the index of the source file for a line descriptor.
 408 .It Fn dwarf_srcfiles
 409 Retrieve source files for a compilation unit.
 410 .It Fn dwarf_srclines
 411 Return line number information for a compilation unit.
 412 .El
 413 .It Location Lists
 414 .Bl -tag -compact
 415 .It Fn dwarf_get_loclist_entry
 416 Retrieve a location list entry.
 417 .It Fn dwarf_loclist , Fn dwarf_loclist_n
 418 Retrieve location expressions.
 419 .It Fn dwarf_loclist_from_expr , Fn dwarf_loclist_from_expr_a
 420 Translate a location expression into a location descriptor.
 421 .El
 422 .It Error Handling
 423 .Bl -tag -compact
 424 .It Fn dwarf_errmsg
 425 Retrieve a human-readable error message.
 426 .It Fn dwarf_errno
 427 Retrieve an error number from an error descriptor.
 428 .It Fn dwarf_seterrarg
 429 Set the argument passed to a callback error handler.
 430 .It Fn dwarf_seterrhand
 431 Set the callback handler to be called in case of an error.
 432 .El
 433 .It Frame Handling
 434 .Bl -tag -compact
 435 .It Fn dwarf_expand_frame_instructions
 436 Translate frame instruction bytes.
 437 .It Fn dwarf_set_frame_cfa_value
 438 Set the CFA parameter for the internal register rule table.
 439 .It Fn dwarf_set_frame_rule_initial_value
 440 Set the initial value of the register rules in the internal register
 441 rule table.
 442 .It Fn dwarf_set_frame_rule_table_size
 443 Set the maximum number of columns in the register rule table.
 444 .It Fn dwarf_set_frame_same_value
 445 Set the register number representing the
 446 .Dq "same value"
 447 rule.
 448 .It Fn dwarf_set_frame_undefined_value
 449 Set the register number representing the
 450 .Dq "undefined"
 451 rule.
 452 .El
 453 .It Macros
 454 .Bl -tag -compact
 455 .It Fn dwarf_find_macro_value_start
 456 Return the macro value part of a macro string.
 457 .It Fn dwarf_get_macro_details
 458 Retrieve macro information.
 459 .El
 460 .It Memory Management
 461 In the DWARF consumer API, the rules for memory management differ
 462 between functions.
 463 In some cases, the memory areas returned to the application by the
 464 library are freed by calling specific API functions.
 465 In others, the deallocation function
 466 .Fn dwarf_dealloc
 467 suffices.
 468 The individual manual pages for the API's functions document the
 469 specific memory management rules to be followed.
 470 .Pp
 471 The function
 472 .Fn dwarf_dealloc
 473 is used to mark memory arenas as unused.
 474 Additionally, the following functions release specific types of
 475 DWARF resources:
 476 .Fn dwarf_fde_cie_list_dealloc ,
 477 .Fn dwarf_funcs_dealloc ,
 478 .Fn dwarf_globals_dealloc ,
 479 .Fn dwarf_pubtypes_dealloc ,
 480 .Fn dwarf_ranges_dealloc ,
 481 .Fn dwarf_srclines_dealloc ,
 482 .Fn dwarf_types_dealloc ,
 483 .Fn dwarf_vars_dealloc ,
 484 and
 485 .Fn dwarf_weaks_dealloc .
 486 .It Symbol Constants
 487 The following functions may be used to return symbolic names
 488 for DWARF constants:
 489 .Fn dwarf_get_ACCESS_name ,
 490 .Fn dwarf_get_AT_name ,
 491 .Fn dwarf_get_ATE_name ,
 492 .Fn dwarf_get_CC_name ,
 493 .Fn dwarf_get_CFA_name ,
 494 .Fn dwarf_get_CHILDREN_name ,
 495 .Fn dwarf_get_DS_name ,
 496 .Fn dwarf_get_DSC_name ,
 497 .Fn dwarf_get_EH_name ,
 498 .Fn dwarf_get_END_name ,
 499 .Fn dwarf_get_FORM_name ,
 500 .Fn dwarf_get_ID_name ,
 501 .Fn dwarf_get_INL_name ,
 502 .Fn dwarf_get_LANG_name ,
 503 .Fn dwarf_get_LNE_name ,
 504 .Fn dwarf_get_LNS_name ,
 505 .Fn dwarf_get_MACINFO_name ,
 506 .Fn dwarf_get_OP_name ,
 507 .Fn dwarf_get_ORD_name ,
 508 .Fn dwarf_get_TAG_name ,
 509 .Fn dwarf_get_VIRTUALITY_name ,
 510 and
 511 .Fn dwarf_get_VIS_name .
 512 .It Types
 513 .Bl -tag -compact
 514 .It Fn dwarf_get_pubtypes , Fn dwarf_get_types
 515 Retrieve descriptors for user-defined types.
 516 .It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset
 517 Return the offset for the compilation unit for a type.
 518 .It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset
 519 Return the offset for the debugging information entry for a type.
 520 .It Fn dwarf_pubtypename , Fn dwarf_typename
 521 Retrieve the name of a type.
 522 .It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets
 523 Retrieve the name and offsets for a type.
 524 .El
 525 .It Variables
 526 .Bl -tag -compact
 527 .It Fn dwarf_get_vars
 528 Retrieve descriptors for static variables.
 529 .It Fn dwarf_var_cu_offset
 530 Return the offset for the compilation unit for a variable.
 531 .It Fn dwarf_var_die_offset
 532 Return the offset for the debugging information entry for a variable.
 533 .It Fn dwarf_varname
 534 Retrieve the name of a variable.
 535 .It Fn dwarf_var_name_offsets
 536 Retrieve the name and offsets for a variable.
 537 .El
 538 .It Weak Symbols
 539 .Bl -tag -compact
 540 .It Fn dwarf_get_weaks
 541 Retrieve information about weak symbols.
 542 .It Fn dwarf_weak_cu_offset
 543 Return the offset for the compilation unit for a weak symbol.
 544 .It Fn dwarf_weak_die_offset
 545 Return the offset for the debugging information entry for a weak symbol.
 546 .It Fn dwarf_weakname
 547 Retrieve the name of a weak symbol.
 548 .It Fn dwarf_weak_name_offsets
 549 Retrieve the name and offsets for a weak symbol.
 550 .El
 551 .It Miscellaneous
 552 .Bl -tag -compact
 553 .It Fn dwarf_get_elf
 554 Retrieve the ELF descriptor for a debug context, see
 555 .Xr elf 3 .
 556 .It Fn dwarf_get_str
 557 Retrieve a NUL-terminated string from the DWARF string section.
 558 .It Fn dwarf_set_reloc_application
 559 Control whether relocations are to be handled by
 560 .Lb libdwarf .
 561 .El
 562 .El
 563 .Sh The DWARF Producer API
 564 The DWARF producer API permits applications to add DWARF information to
 565 an object file.
 566 .Pp
 567 The major functional groups of functions in the producer API are listed
 568 below.
 569 .Bl -tag -width "CCCC"
 570 .It Attribute Management
 571 The following functions are used to attach attributes to a debugging
 572 information entry:
 573 .Fn dwarf_add_AT_comp_dir ,
 574 .Fn dwarf_add_AT_const_value_signedint ,
 575 .Fn dwarf_add_AT_const_value_string ,
 576 .Fn dwarf_add_AT_const_value_unsignedint ,
 577 .Fn dwarf_add_AT_dataref ,
 578 .Fn dwarf_add_AT_flag ,
 579 .Fn dwarf_add_AT_location_expr ,
 580 .Fn dwarf_add_AT_name ,
 581 .Fn dwarf_add_AT_producer ,
 582 .Fn dwarf_add_AT_ref_address ,
 583 .Fn dwarf_add_AT_reference ,
 584 .Fn dwarf_add_AT_signed_const ,
 585 .Fn dwarf_add_AT_string ,
 586 .Fn dwarf_add_AT_targ_address ,
 587 .Fn dwarf_add_AT_targ_address_b
 588 and
 589 .Fn dwarf_add_AT_unsigned_const .
 590 .It Debugging Information Entry Management
 591 .Bl -tag -compact
 592 .It Fn dwarf_add_die_to_debug
 593 Set the root debugging information entry for a DWARF producer instance.
 594 .It Fn dwarf_die_link
 595 Links debugging information entries.
 596 .It Fn dwarf_new_die
 597 Allocate a new debugging information entry.
 598 .El
 599 .It Initialization and Finalization
 600 The functions
 601 .Fn dwarf_producer_init
 602 and
 603 .Fn dwarf_producer_init_b
 604 are used to initialize a producer instance.
 605 .Pp
 606 When done, applications release resources using the function
 607 .Fn dwarf_producer_finish .
 608 .It Relocations and Sections
 609 .Bl -tag -compact
 610 .It Fn dwarf_get_relocation_info
 611 Retrieve a relocation array from a producer instance.
 612 .It Fn dwarf_get_relocation_info_count
 613 Return the number of relocation arrays for a producer instance.
 614 .It Fn dwarf_get_section_bytes
 615 Retrieve the ELF byte stream for a section.
 616 .It Fn dwarf_reset_section_bytes
 617 Reset internal state for a producer instance.
 618 .It Fn dwarf_transform_to_disk_form
 619 Prepare byte streams for writing out.
 620 .El
 621 .It Macros
 622 .Bl -tag -compact
 623 .It Fn dwarf_def_macro
 624 Add a macro definition.
 625 .It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file
 626 Record macro file related information.
 627 .It Fn dwarf_undef_macro
 628 Note the removal of a macro definition.
 629 .It Fn dwarf_vendor_ext
 630 Enables storing macro information as specified in the DWARF standard.
 631 .El
 632 .It Symbols, Expressions, Addresses and Offsets
 633 .Bl -tag -compact
 634 .It Fn dwarf_add_arange , Fn dwarf_add_arange_b
 635 Add address range information.
 636 .It Fn dwarf_add_directory_decl
 637 Add information about an include directory to a producer instance.
 638 .It Fn dwarf_add_fde_inst
 639 Add an operation to a frame descriptor entry.
 640 .It Fn dwarf_add_file_decl
 641 Add information about a source file to a producer instance.
 642 .It Fn dwarf_add_frame_cie
 643 Add call information to a frame descriptor.
 644 .It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b
 645 Link a frame descriptor to a producer instance.
 646 .It Fn dwarf_add_funcname
 647 Add information about a function to a producer instance.
 648 .It Fn dwarf_add_line_entry
 649 Record mapping information between machine addresses and a source line.
 650 .It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b
 651 Add a
 652 .Dv DW_OP_addr
 653 opcode to a location expression.
 654 .It Fn dwarf_add_expr_gen
 655 Add an operator to a location expression.
 656 .It Fn dwarf_add_pubname
 657 Add information about a global name to a producer instance.
 658 .It Fn dwarf_add_typename
 659 Add information about a type to a producer instance.
 660 .It Fn dwarf_add_varname
 661 Add information about a static variable to a producer instance.
 662 .It Fn dwarf_add_weakname
 663 Add information about a weak symbol to a producer instance.
 664 .It Fn dwarf_expr_current_offset
 665 Retrieve the current size of a location expression.
 666 .It Fn dwarf_expr_into_block
 667 Convert a location expression into a byte stream.
 668 .It Fn dwarf_fde_cfa_offset
 669 Append a
 670 .Dv DW_CFA_offset
 671 operation to a frame descriptor.
 672 .It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address
 673 Note address ranges for source lines.
 674 .It Fn dwarf_new_expr
 675 Allocate a location expression descriptor.
 676 .It Fn dwarf_new_fde
 677 Allocate a frame descriptor.
 678 .El
 679 .It Miscellaneous
 680 The function
 681 .Fn dwarf_producer_set_isa
 682 sets the instruction set architecture for the producer instance.
 683 .El
 684 .Sh COMPATIBILITY
 685 This implementation is believed to be source compatible with the
 686 SGI/GNU DWARF(3) library, version 20110113.
 687 .Pp
 688 Known differences with the SGI/GNU library include:
 689 .Bl -bullet -compact
 690 .It
 691 The memory management scheme used differs, in a backward-compatible
 692 way.
 693 See
 694 .Sx Memory Management
 695 above, for coding guidelines for portable applications.
 696 .It
 697 There is provision for setting a library-wide error handler in
 698 addition to the per-debug context handlers supported by the SGI/GNU
 699 API, see the subsection
 700 .Sx Error Handling
 701 above.
 702 .It
 703 The following API is an extension:
 704 .Fn dwarf_producer_set_isa .
 705 .El
 706 .Sh SEE ALSO
 707 .Xr elf 3
 708 .Sh STANDARDS
 709 The DWARF standard is defined by
 710 .Rs
 711 .%T "The DWARF Debugging Information Format"
 712 .%V "Version 4"
 713 .%O "http://www.dwarfstd.org/"
 714 .Re
 715 .Sh HISTORY
 716 The DWARF(3) API originated at Silicon Graphics Inc.
 717 .Pp
 718 A BSD-licensed implementation of a subset of the API was written by
 719 .An "John Birrell" Aq jb@FreeBSD.org
 720 for the FreeBSD project.
 721 The implementation was subsequently revised and completed by
 722 .An "Kai Wang" Aq kaiwang27@users.sourceforge.net .
 723 .Pp
 724 Manual pages for this implementation were written by
 725 .An "Joseph Koshy" Aq jkoshy@users.sourceforge.net
 726 and
 727 .An "Kai Wang" Aq kaiwang27@users.sourceforge.net .