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.\"
|
114.It Vt Dwarf_P_Expr 115A descriptor for a location expression. 116.It Vt Dwarf_Ptr 117A virtual address used by an application. 118.It Vt Dwarf_Signed 119A 64-bit wide signed numeric type. 120.It Vt Dwarf_Small 121An 8-bit wide unsigned numeric type. 122.It Vt Dwarf_Type 123A descriptor representing a user-specified type. 124.It Vt Dwarf_Unsigned 125A 64-bit wide unsigned numeric type. 126.It Vt Dwarf_Var 127A descriptor representing a static variable. 128.It Vt Dwarf_Weak 129A descriptor representing a weak name. 130.El 131.Ss Error Handling 132.Pp 133Library functions that encounter an error will return with a value 134other than 135.Dv DW_DLV_OK . 136.Pp 137The 138.Lb libdwarf 139allows applications to specify three levels of error handling: 140.Bl -enum -compact 141.It 142Most library functions take a parameter of type 143.Vt Dwarf_Error 144that specifies a location to store an error descriptor in 145case of an error. 146If an error occurs during the execution on an API, and if this 147parameter is non-NULL, then an error descriptor is written to the 148location specified. 149.It 150Otherwise, if the error parameter was NULL, but if an error handler 151was defined for the debug context in use using 152.Xr dwarf_init 3 153or 154.Xr dwarf_seterrhand 3 , 155then the library will invoke the specified error handler with an error 156descriptor as argument. 157.It 158Otherwise, if a library wide error handler was specified using 159.Xr dwarf_seterrhand 3 , 160it is called. 161.El 162.Pp 163Error descriptors may be used with 164.Xr dwarf_errmsg 3 165or 166.Xr dwarf_errno 3 . 167.Sh The DWARF Consumer API 168The DWARF consumer API permits applications to read DWARF information in 169an object file. 170.Pp 171The major functional groups of functions in the consumer API are listed 172below. 173.Pp 174.Bl -tag -compact -width "CCCC" 175.It Abbreviations 176.Bl -tag -compact 177.It Fn dwarf_get_abbrev 178Retrieve abbreviation information at a given offset. 179.It Fn dwarf_get_abbrev_children_flag 180Check if an abbreviation has child elements. 181.It Fn dwarf_get_abbrev_code 182Retrieve the abbreviation code for an abbreviation entry descriptor. 183.It Fn dwarf_get_abbrev_entry 184Retrieve abbreviation information for an abbreviation entry 185descriptor. 186.It Fn dwarf_get_abbrev_tag 187Retrieve the tag for an abbreviation entry. 188.El 189.It Addresses 190.Bl -tag -compact 191.It Fn dwarf_get_address_size 192Return the number of bytes needed to represent an address. 193.It Fn dwarf_get_arange 194Search for an address range descriptor covering an address. 195.It Fn dwarf_get_arange_cu_header_offset 196Retrieve the offsets associated with an address range descriptor. 197.It Fn dwarf_get_arange_info 198Extract address range information from a descriptor. 199.It Fn dwarf_get_aranges 200Retrieve program address space mappings. 201.It Fn dwarf_get_cu_die_offset 202Retrieve the offset associated with a compilation unit for an address 203range descriptor. 204.It Fn dwarf_get_ranges , Fn dwarf_get_ranges_a 205Retrieve information about non-contiguous address ranges for 206a debugging information entry. 207.El 208.It Attributes 209.Bl -tag -compact 210.It Fn dwarf_arrayorder 211Retrieve the value of a 212.Dv DW_AT_ordering 213attribute. 214.It Fn dwarf_attr 215Retrieve an attribute descriptor. 216.It Fn dwarf_attrlist 217Retrieve attribute descriptors for a debugging information entry. 218.It Fn dwarf_attroffset 219Retrieve the section-relative offset of an attribute descriptor. 220.It Fn dwarf_attrval_flag 221Retrieve a 222.Dv DW_AT_FORM_flag 223value. 224.It Fn dwarf_attrval_signed 225Retrieve an attribute's value as a signed integral quantity. 226.It Fn dwarf_attrval_string 227Retrieve an attribute's value as a NUL-terminated string. 228.It Fn dwarf_attrval_unsigned 229Retrieve an attribute's value as an unsigned integral quantity. 230.It Fn dwarf_bitoffset , 231Retrieve the value of a 232.Dv DW_AT_bit_offset 233attribute. 234.It Fn dwarf_bitsize , 235Retrieve the value of a 236.Dv DW_AT_bit_size 237attribute. 238.It Fn dwarf_bytesize 239Retrieve the value of a 240.Dv DW_AT_byte_size 241attribute. 242.It Fn dwarf_formaddr 243Return the value of an 244.Dv ADDRESS Ns - Ns 245class attribute. 246.It Fn dwarf_formblock 247Return the value of a 248.Dv BLOCK Ns - Ns 249class attribute 250.It Fn dwarf_formexprloc 251Return information about a location expression. 252.It Fn dwarf_formflag 253Retrieve information about a 254.Dv BOOLEAN Ns - Ns 255class attribute. 256.It Fn dwarf_formref , Fn dwarf_global_formref 257Retrieve offsets for 258.Dv REFERENCE Ns - Ns 259class attributes. 260.It Fn dwarf_formsdata , Fn dwarf_formudata 261Retrieve the value of a 262.Dv CONSTANT Ns - Ns 263class attribute. 264.It Fn dwarf_formsig8 265Return the type signature for a DWARF type. 266.It Fn dwarf_formstring 267Retrieve information about a 268.Dv STRING Ns - Ns 269class attribute. 270.It Fn dwarf_get_form_class 271Retrieve the form class for an attribute. 272.It Fn dwarf_hasattr 273Check for the presence of an attribute. 274.It Fn dwarf_hasform 275Check if an attribute has the given form. 276.It Fn dwarf_whatattr 277Retrieve the attribute code for an attribute. 278.It Fn dwarf_whatform , Fn dwarf_whatform_direct 279Retrieve 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 284Retrieve the index for a CIE descriptor. 285.It Fn dwarf_get_cie_info 286Retrieve information from a CIE descriptor. 287.It Fn dwarf_get_cie_of_fde 288Retrieve a CIE descriptor. 289.It Fn dwarf_get_fde_at_pc 290Retrieve an FDE descriptor for an address. 291.It Fn dwarf_get_fde_info_for_all_regs 292Retrieve register rule row. 293.It Fn dwarf_get_fde_info_for_all_regs3 294Retrieve register rule row (revised API). 295.It Fn dwarf_get_fde_info_for_cfa_reg3 296Retrieve a CFA register rule. 297.It Fn dwarf_get_fde_info_for_reg 298Retrieve a register rule. 299.It Fn dwarf_get_fde_info_for_reg3 300Retrieve a register rule (revised API). 301.It Fn dwarf_get_fde_instr_bytes 302Retrieve instructions from an FDE descriptor. 303.It Fn dwarf_get_fde_list , Fn dwarf_get_fde_list_eh 304Retrieve frame information. 305.It Fn dwarf_get_fde_n 306Retrieve an FDE descriptor. 307.It Fn dwarf_get_fde_range 308Retrieve range information from an FDE descriptor. 309.El 310.It Compilation Units 311.Bl -tag -compact 312.It Xo 313.Fn dwarf_get_cu_die_offset_given_cu_header_offset , 314.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 315.Xc 316Retrieve the offset of the debugging information entry for a 317compilation or type unit. 318.It Xo 319.Fn dwarf_next_cu_header , 320.Fn dwarf_next_cu_header_b , 321.Fn dwarf_next_cu_header_c 322.Xc 323Step through compilation units in a debug context. 324.El 325.It Debugging Information Entries 326.Bl -tag -compact 327.It Fn dwarf_child 328Returns the child of a debugging information entry. 329.It Fn dwarf_die_abbrev_code 330Returns the abbreviation code for a debugging information entry. 331.It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range 332Retrieve offsets and lengths for a compilation unit. 333.It Fn dwarf_diename 334Returns the 335.Dv DW_AT_name 336attribute for a debugging information entry. 337.It Fn dwarf_dieoffset 338Retrieves the offset for a debugging information entry. 339.It Fn dwarf_get_die_infotypes_flag 340Indicate the originating section for a debugging information entry. 341.It Fn dwarf_highpc , Fn dwarf_highpc_b 342Return the highest PC value for a debugging information entry. 343.It Fn dwarf_lowpc 344Return the lowest PC value for a debugging information entry. 345.It Fn dwarf_offdie , Fn dwarf_offdie_b 346Retrieve a debugging information entry given an offset. 347.It Fn dwarf_siblingof , Fn dwarf_siblingof_b 348Retrieve the sibling descriptor for a debugging information entry. 349.It Fn dwarf_srclang 350Retrieve the source language attribute for a debugging information 351entry. 352.It Fn dwarf_tag 353Retrieve the tag for a debugging information entry. 354.El 355.It Functions 356.Bl -tag -compact 357.It Fn dwarf_func_cu_offset 358Retrieves the offset for the compilation unit for a function. 359.It Fn dwarf_func_die_offset 360Retrieves the offset for the debugging information entry for a 361function. 362.It Fn dwarf_funcname 363Retrieves the name of a function. 364.It Fn dwarf_func_name_offsets 365Retrieve both the name and offsets for a function. 366.It Fn dwarf_get_funcs 367Retrieve information about static functions. 368.El 369.It Globals 370.Bl -tag -compact 371.It Fn dwarf_get_globals 372Retrieve a list of globals. 373.It Fn dwarf_global_cu_offset 374Return the offset for compilation unit for a global. 375.It Fn dwarf_global_die_offset 376Return the offset for the debugging information entry for a global. 377.It Fn dwarf_global_name_offsets 378Return the name and offsets for a global. 379.It Fn dwarf_globname 380Return the name for a global. 381.El 382.It Initialization and Finalization 383Functions 384.Fn dwarf_elf_init 385and 386.Fn dwarf_init 387may be used for initialization. 388The function 389.Fn dwarf_finish 390may be used to release resources. 391.Pp 392The functions 393.Fn dwarf_object_init 394and 395.Fn dwarf_object_finish 396allow an application to specify alternate low-level file access 397routines. 398.It Line Numbers 399.Bl -tag -compact 400.It Fn dwarf_lineaddr 401Retrieve the program address for a source line. 402.It Fn dwarf_linebeginstatement 403Check if a source line corresponds to the beginning of a statement. 404.It Fn dwarf_lineblock 405Check if a source line corresponds to the start of a basic block. 406.It Fn dwarf_lineendsequence 407Check if the source line corresponds to the end of a sequence of 408instructions. 409.It Fn dwarf_lineno 410Retrieve the line number for a line descriptor. 411.It Fn dwarf_lineoff 412Retrieve the column number for a line descriptor. 413.It Fn dwarf_linesrc 414Retrieve the source file for a line descriptor. 415.It Fn dwarf_line_srcfileno 416Retrieve the index of the source file for a line descriptor. 417.It Fn dwarf_srcfiles 418Retrieve source files for a compilation unit. 419.It Fn dwarf_srclines 420Return line number information for a compilation unit. 421.El 422.It Location Lists 423.Bl -tag -compact 424.It Fn dwarf_get_loclist_entry 425Retrieve a location list entry. 426.It Fn dwarf_loclist , Fn dwarf_loclist_n 427Retrieve location expressions. 428.It Xo 429.Fn dwarf_loclist_from_expr , 430.Fn dwarf_loclist_from_expr_a , 431.Fn dwarf_loclist_from_expr_b 432.Xc 433Translate a location expression into a location descriptor. 434.El 435.It Error Handling 436.Bl -tag -compact 437.It Fn dwarf_errmsg 438Retrieve a human-readable error message. 439.It Fn dwarf_errno 440Retrieve an error number from an error descriptor. 441.It Fn dwarf_seterrarg 442Set the argument passed to a callback error handler. 443.It Fn dwarf_seterrhand 444Set the callback handler to be called in case of an error. 445.El 446.It Frame Handling 447.Bl -tag -compact 448.It Fn dwarf_expand_frame_instructions 449Translate frame instruction bytes. 450.It Fn dwarf_set_frame_cfa_value 451Set the CFA parameter for the internal register rule table. 452.It Fn dwarf_set_frame_rule_initial_value 453Set the initial value of the register rules in the internal register 454rule table. 455.It Fn dwarf_set_frame_rule_table_size 456Set the maximum number of columns in the register rule table. 457.It Fn dwarf_set_frame_same_value 458Set the register number representing the 459.Dq "same value" 460rule. 461.It Fn dwarf_set_frame_undefined_value 462Set the register number representing the 463.Dq "undefined" 464rule. 465.El 466.It Macros 467.Bl -tag -compact 468.It Fn dwarf_find_macro_value_start 469Return the macro value part of a macro string. 470.It Fn dwarf_get_macro_details 471Retrieve macro information. 472.El 473.It Memory Management 474In the DWARF consumer API, the rules for memory management differ 475between functions. 476In some cases, the memory areas returned to the application by the 477library are freed by calling specific API functions. 478In others, the deallocation function 479.Fn dwarf_dealloc 480suffices. 481The individual manual pages for the API's functions document the 482specific memory management rules to be followed. 483.Pp 484The function 485.Fn dwarf_dealloc 486is used to mark memory arenas as unused. 487Additionally, the following functions release specific types of 488DWARF resources: 489.Fn dwarf_fde_cie_list_dealloc , 490.Fn dwarf_funcs_dealloc , 491.Fn dwarf_globals_dealloc , 492.Fn dwarf_pubtypes_dealloc , 493.Fn dwarf_ranges_dealloc , 494.Fn dwarf_srclines_dealloc , 495.Fn dwarf_types_dealloc , 496.Fn dwarf_vars_dealloc , 497and 498.Fn dwarf_weaks_dealloc . 499.It Symbol Constants 500The following functions may be used to return symbolic names 501for DWARF constants: 502.Fn dwarf_get_ACCESS_name , 503.Fn dwarf_get_AT_name , 504.Fn dwarf_get_ATE_name , 505.Fn dwarf_get_CC_name , 506.Fn dwarf_get_CFA_name , 507.Fn dwarf_get_CHILDREN_name , 508.Fn dwarf_get_DS_name , 509.Fn dwarf_get_DSC_name , 510.Fn dwarf_get_EH_name , 511.Fn dwarf_get_END_name , 512.Fn dwarf_get_FORM_name , 513.Fn dwarf_get_ID_name , 514.Fn dwarf_get_INL_name , 515.Fn dwarf_get_LANG_name , 516.Fn dwarf_get_LNE_name , 517.Fn dwarf_get_LNS_name , 518.Fn dwarf_get_MACINFO_name , 519.Fn dwarf_get_OP_name , 520.Fn dwarf_get_ORD_name , 521.Fn dwarf_get_TAG_name , 522.Fn dwarf_get_VIRTUALITY_name , 523and 524.Fn dwarf_get_VIS_name . 525.It Types 526.Bl -tag -compact 527.It Fn dwarf_get_pubtypes , Fn dwarf_get_types 528Retrieve descriptors for user-defined types. 529.It Fn dwarf_next_types_section 530Step through 531.Dq \&.debug_types 532sections in a debug context. 533.It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset 534Return the offset for the compilation unit for a type. 535.It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset 536Return the offset for the debugging information entry for a type. 537.It Fn dwarf_pubtypename , Fn dwarf_typename 538Retrieve the name of a type. 539.It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets 540Retrieve the name and offsets for a type. 541.El 542.It Variables 543.Bl -tag -compact 544.It Fn dwarf_get_vars 545Retrieve descriptors for static variables. 546.It Fn dwarf_var_cu_offset 547Return the offset for the compilation unit for a variable. 548.It Fn dwarf_var_die_offset 549Return the offset for the debugging information entry for a variable. 550.It Fn dwarf_varname 551Retrieve the name of a variable. 552.It Fn dwarf_var_name_offsets 553Retrieve the name and offsets for a variable. 554.El 555.It Weak Symbols 556.Bl -tag -compact 557.It Fn dwarf_get_weaks 558Retrieve information about weak symbols. 559.It Fn dwarf_weak_cu_offset 560Return the offset for the compilation unit for a weak symbol. 561.It Fn dwarf_weak_die_offset 562Return the offset for the debugging information entry for a weak symbol. 563.It Fn dwarf_weakname 564Retrieve the name of a weak symbol. 565.It Fn dwarf_weak_name_offsets 566Retrieve the name and offsets for a weak symbol. 567.El 568.It Miscellaneous 569.Bl -tag -compact 570.It Fn dwarf_get_elf 571Retrieve the ELF descriptor for a debug context, see 572.Xr elf 3 . 573.It Fn dwarf_get_str 574Retrieve a NUL-terminated string from the DWARF string section. 575.It Fn dwarf_set_reloc_application 576Control whether relocations are to be handled by 577.Lb libdwarf . 578.El 579.El 580.Sh The DWARF Producer API 581The DWARF producer API permits applications to add DWARF information to 582an object file. 583.Pp 584The major functional groups of functions in the producer API are listed 585below. 586.Bl -tag -width "CCCC" 587.It Attribute Management 588The following functions are used to attach attributes to a debugging 589information entry: 590.Fn dwarf_add_AT_comp_dir , 591.Fn dwarf_add_AT_const_value_signedint , 592.Fn dwarf_add_AT_const_value_string , 593.Fn dwarf_add_AT_const_value_unsignedint , 594.Fn dwarf_add_AT_dataref , 595.Fn dwarf_add_AT_flag , 596.Fn dwarf_add_AT_location_expr , 597.Fn dwarf_add_AT_name , 598.Fn dwarf_add_AT_producer , 599.Fn dwarf_add_AT_ref_address , 600.Fn dwarf_add_AT_reference , 601.Fn dwarf_add_AT_signed_const , 602.Fn dwarf_add_AT_string , 603.Fn dwarf_add_AT_targ_address , 604.Fn dwarf_add_AT_targ_address_b 605and 606.Fn dwarf_add_AT_unsigned_const . 607.It Debugging Information Entry Management 608.Bl -tag -compact 609.It Fn dwarf_add_die_to_debug 610Set the root debugging information entry for a DWARF producer instance. 611.It Fn dwarf_die_link 612Links debugging information entries. 613.It Fn dwarf_new_die 614Allocate a new debugging information entry. 615.El 616.It Initialization and Finalization 617The functions 618.Fn dwarf_producer_init 619and 620.Fn dwarf_producer_init_b 621are used to initialize a producer instance. 622.Pp 623When done, applications release resources using the function 624.Fn dwarf_producer_finish . 625.It Relocations and Sections 626.Bl -tag -compact 627.It Fn dwarf_get_relocation_info 628Retrieve a relocation array from a producer instance. 629.It Fn dwarf_get_relocation_info_count 630Return the number of relocation arrays for a producer instance. 631.It Fn dwarf_get_section_bytes 632Retrieve the ELF byte stream for a section. 633.It Fn dwarf_reset_section_bytes 634Reset internal state for a producer instance. 635.It Fn dwarf_transform_to_disk_form 636Prepare byte streams for writing out. 637.El 638.It Macros 639.Bl -tag -compact 640.It Fn dwarf_def_macro 641Add a macro definition. 642.It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file 643Record macro file related information. 644.It Fn dwarf_undef_macro 645Note the removal of a macro definition. 646.It Fn dwarf_vendor_ext 647Enables storing macro information as specified in the DWARF standard. 648.El 649.It Symbols, Expressions, Addresses and Offsets 650.Bl -tag -compact 651.It Fn dwarf_add_arange , Fn dwarf_add_arange_b 652Add address range information. 653.It Fn dwarf_add_directory_decl 654Add information about an include directory to a producer instance. 655.It Fn dwarf_add_fde_inst 656Add an operation to a frame descriptor entry. 657.It Fn dwarf_add_file_decl 658Add information about a source file to a producer instance. 659.It Fn dwarf_add_frame_cie 660Add call information to a frame descriptor. 661.It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b 662Link a frame descriptor to a producer instance. 663.It Fn dwarf_add_funcname 664Add information about a function to a producer instance. 665.It Fn dwarf_add_line_entry 666Record mapping information between machine addresses and a source line. 667.It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b 668Add a 669.Dv DW_OP_addr 670opcode to a location expression. 671.It Fn dwarf_add_expr_gen 672Add an operator to a location expression. 673.It Fn dwarf_add_pubname 674Add information about a global name to a producer instance. 675.It Fn dwarf_add_typename 676Add information about a type to a producer instance. 677.It Fn dwarf_add_varname 678Add information about a static variable to a producer instance. 679.It Fn dwarf_add_weakname 680Add information about a weak symbol to a producer instance. 681.It Fn dwarf_expr_current_offset 682Retrieve the current size of a location expression. 683.It Fn dwarf_expr_into_block 684Convert a location expression into a byte stream. 685.It Fn dwarf_fde_cfa_offset 686Append a 687.Dv DW_CFA_offset 688operation to a frame descriptor. 689.It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address 690Note address ranges for source lines. 691.It Fn dwarf_new_expr 692Allocate a location expression descriptor. 693.It Fn dwarf_new_fde 694Allocate a frame descriptor. 695.El 696.It Miscellaneous 697The function 698.Fn dwarf_producer_set_isa 699sets the instruction set architecture for the producer instance. 700.El 701.Sh COMPATIBILITY 702This implementation is believed to be source compatible with the 703SGI/GNU DWARF(3) library, version 20110113. 704.Pp 705Known differences with the SGI/GNU library include: 706.Bl -bullet -compact 707.It 708The memory management scheme used differs, in a backward-compatible 709way. 710See 711.Sx Memory Management 712above, for coding guidelines for portable applications. 713.It 714There is provision for setting a library-wide error handler in 715addition to the per-debug context handlers supported by the SGI/GNU 716API, see the subsection 717.Sx Error Handling 718above. 719.El 720.Ss Extensions 721The following APIs are extensions specific to this implementation: 722.Bl -bullet -compact 723.It 724.Fn dwarf_attroffset 725.It 726.Fn dwarf_next_types_section 727.It 728.Fn dwarf_producer_set_isa 729.El 730.Sh SEE ALSO 731.Xr elf 3 732.Sh STANDARDS 733The DWARF standard is defined by 734.Rs 735.%T "The DWARF Debugging Information Format" 736.%V "Version 4" 737.%O "http://www.dwarfstd.org/" 738.Re 739.Sh HISTORY 740The DWARF(3) API originated at Silicon Graphics Inc. 741.Pp 742A BSD-licensed implementation of a subset of the API was written by 743.An John Birrell Aq Mt jb@FreeBSD.org 744for the FreeBSD project. 745The implementation was subsequently revised and completed by 746.An Kai Wang Aq Mt kaiwang27@users.sourceforge.net . 747.Pp 748Manual pages for this implementation were written by 749.An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net 750and 751.An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .
|