1 .\" Copyright (c) 2011 Joseph Koshy. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
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.
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
24 .\" $Id: dwarf.3 3295 2016-01-08 22:08:10Z jkoshy $
31 .Nd access debugging information in object files
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
51 A consumer API set allows applications to read existing debug information
53 The functions that comprise the DWARF consumer API are described in
55 .Sx "DWARF Consumer API"
58 A producer API set that allows applications to add debug information
60 The functions that comprise the DWARF producer API are described in
62 .Sx "DWARF Producer API"
66 Each function referenced below is further described in its own manual page.
68 The DWARF library uses the following prefixes:
70 .Bl -tag -width ".Li Dwarf_*" -compact
72 Used for error numbers and constants.
78 Used for functions and macros that make up the API.
81 The DWARF(3) API uses the following data types:
83 .Bl -tag -width ".Vt Dwarf_Unsigned" -compact
85 Describes DWARF abbreviations.
87 A program address in the target object.
89 Describes address ranges.
90 .It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute
91 Describes attributes of debugging information entries.
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
103 A descriptor representing a function.
105 A descriptor representing a global name.
107 A 16-bit wide unsigned numeric type.
109 A pointer to an error handling function.
111 A descriptor for a source line.
113 An unsigned file offset.
115 A descriptor for a location expression.
117 A virtual address used by an application.
119 A 64-bit wide signed numeric type.
121 An 8-bit wide unsigned numeric type.
123 A descriptor representing a user-specified type.
124 .It Vt Dwarf_Unsigned
125 A 64-bit wide unsigned numeric type.
127 A descriptor representing a static variable.
129 A descriptor representing a weak name.
133 Library functions that encounter an error will return with a value
139 allows applications to specify three levels of error handling:
142 Most library functions take a parameter of type
144 that specifies a location to store an error descriptor in
146 If an error occurs during the execution on an API, and if this
147 parameter is non-NULL, then an error descriptor is written to the
150 Otherwise, if the error parameter was NULL, but if an error handler
151 was defined for the debug context in use using
154 .Xr dwarf_seterrhand 3 ,
155 then the library will invoke the specified error handler with an error
156 descriptor as argument.
158 Otherwise, if a library wide error handler was specified using
159 .Xr dwarf_seterrhand 3 ,
163 Error descriptors may be used with
167 .Sh The DWARF Consumer API
168 The DWARF consumer API permits applications to read DWARF information in
171 The major functional groups of functions in the consumer API are listed
174 .Bl -tag -compact -width "CCCC"
177 .It Fn dwarf_get_abbrev
178 Retrieve abbreviation information at a given offset.
179 .It Fn dwarf_get_abbrev_children_flag
180 Check if an abbreviation has child elements.
181 .It Fn dwarf_get_abbrev_code
182 Retrieve the abbreviation code for an abbreviation entry descriptor.
183 .It Fn dwarf_get_abbrev_entry
184 Retrieve abbreviation information for an abbreviation entry
186 .It Fn dwarf_get_abbrev_tag
187 Retrieve the tag for an abbreviation entry.
191 .It Fn dwarf_get_address_size
192 Return the number of bytes needed to represent an address.
193 .It Fn dwarf_get_arange
194 Search for an address range descriptor covering an address.
195 .It Fn dwarf_get_arange_cu_header_offset
196 Retrieve the offsets associated with an address range descriptor.
197 .It Fn dwarf_get_arange_info
198 Extract address range information from a descriptor.
199 .It Fn dwarf_get_aranges
200 Retrieve program address space mappings.
201 .It Fn dwarf_get_cu_die_offset
202 Retrieve the offset associated with a compilation unit for an address
204 .It Fn dwarf_get_ranges , Fn dwarf_get_ranges_a
205 Retrieve information about non-contiguous address ranges for
206 a debugging information entry.
210 .It Fn dwarf_arrayorder
211 Retrieve the value of a
215 Retrieve an attribute descriptor.
216 .It Fn dwarf_attrlist
217 Retrieve attribute descriptors for a debugging information entry.
218 .It Fn dwarf_attroffset
219 Retrieve the section-relative offset of an attribute descriptor.
220 .It Fn dwarf_attrval_flag
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
234 .It Fn dwarf_bitsize ,
235 Retrieve the value of a
238 .It Fn dwarf_bytesize
239 Retrieve the value of a
242 .It Fn dwarf_formaddr
243 Return the value of an
246 .It Fn dwarf_formblock
247 Return the value of a
250 .It Fn dwarf_formexprloc
251 Return information about a location expression.
252 .It Fn dwarf_formflag
253 Retrieve information about a
256 .It Fn dwarf_formref , Fn dwarf_global_formref
258 .Dv REFERENCE Ns - Ns
260 .It Fn dwarf_formsdata , Fn dwarf_formudata
261 Retrieve the value of a
264 .It Fn dwarf_formsig8
265 Return the type signature for a DWARF type.
266 .It Fn dwarf_formstring
267 Retrieve information about a
270 .It Fn dwarf_get_form_class
271 Retrieve the form class for an attribute.
273 Check for the presence of an attribute.
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.
281 .It Call Information Entries and Frame Descriptor Entries
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.
310 .It Compilation Units
313 .Fn dwarf_get_cu_die_offset_given_cu_header_offset ,
314 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
316 Retrieve the offset of the debugging information entry for a
317 compilation or type unit.
319 .Fn dwarf_next_cu_header ,
320 .Fn dwarf_next_cu_header_b ,
321 .Fn dwarf_next_cu_header_c
323 Step through compilation units in a debug context.
325 .It Debugging Information Entries
328 Returns the child of a debugging information entry.
329 .It Fn dwarf_die_abbrev_code
330 Returns the abbreviation code for a debugging information entry.
331 .It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range
332 Retrieve offsets and lengths for a compilation unit.
336 attribute for a debugging information entry.
337 .It Fn dwarf_dieoffset
338 Retrieves the offset for a debugging information entry.
339 .It Fn dwarf_get_die_infotypes_flag
340 Indicate the originating section for a debugging information entry.
341 .It Fn dwarf_highpc , Fn dwarf_highpc_b
342 Return the highest PC value for a debugging information entry.
344 Return the lowest PC value for a debugging information entry.
345 .It Fn dwarf_offdie , Fn dwarf_offdie_b
346 Retrieve a debugging information entry given an offset.
347 .It Fn dwarf_siblingof , Fn dwarf_siblingof_b
348 Retrieve the sibling descriptor for a debugging information entry.
350 Retrieve the source language attribute for a debugging information
353 Retrieve the tag for a debugging information entry.
357 .It Fn dwarf_func_cu_offset
358 Retrieves the offset for the compilation unit for a function.
359 .It Fn dwarf_func_die_offset
360 Retrieves the offset for the debugging information entry for a
362 .It Fn dwarf_funcname
363 Retrieves the name of a function.
364 .It Fn dwarf_func_name_offsets
365 Retrieve both the name and offsets for a function.
366 .It Fn dwarf_get_funcs
367 Retrieve information about static functions.
371 .It Fn dwarf_get_globals
372 Retrieve a list of globals.
373 .It Fn dwarf_global_cu_offset
374 Return the offset for compilation unit for a global.
375 .It Fn dwarf_global_die_offset
376 Return the offset for the debugging information entry for a global.
377 .It Fn dwarf_global_name_offsets
378 Return the name and offsets for a global.
379 .It Fn dwarf_globname
380 Return the name for a global.
382 .It Initialization and Finalization
387 may be used for initialization.
390 may be used to release resources.
393 .Fn dwarf_object_init
395 .Fn dwarf_object_finish
396 allow an application to specify alternate low-level file access
400 .It Fn dwarf_lineaddr
401 Retrieve the program address for a source line.
402 .It Fn dwarf_linebeginstatement
403 Check if a source line corresponds to the beginning of a statement.
404 .It Fn dwarf_lineblock
405 Check if a source line corresponds to the start of a basic block.
406 .It Fn dwarf_lineendsequence
407 Check if the source line corresponds to the end of a sequence of
410 Retrieve the line number for a line descriptor.
412 Retrieve the column number for a line descriptor.
414 Retrieve the source file for a line descriptor.
415 .It Fn dwarf_line_srcfileno
416 Retrieve the index of the source file for a line descriptor.
417 .It Fn dwarf_srcfiles
418 Retrieve source files for a compilation unit.
419 .It Fn dwarf_srclines
420 Return line number information for a compilation unit.
424 .It Fn dwarf_get_loclist_entry
425 Retrieve a location list entry.
426 .It Fn dwarf_loclist , Fn dwarf_loclist_n
427 Retrieve location expressions.
429 .Fn dwarf_loclist_from_expr ,
430 .Fn dwarf_loclist_from_expr_a ,
431 .Fn dwarf_loclist_from_expr_b
433 Translate a location expression into a location descriptor.
438 Retrieve a human-readable error message.
440 Retrieve an error number from an error descriptor.
441 .It Fn dwarf_seterrarg
442 Set the argument passed to a callback error handler.
443 .It Fn dwarf_seterrhand
444 Set the callback handler to be called in case of an error.
448 .It Fn dwarf_expand_frame_instructions
449 Translate frame instruction bytes.
450 .It Fn dwarf_set_frame_cfa_value
451 Set the CFA parameter for the internal register rule table.
452 .It Fn dwarf_set_frame_rule_initial_value
453 Set the initial value of the register rules in the internal register
455 .It Fn dwarf_set_frame_rule_table_size
456 Set the maximum number of columns in the register rule table.
457 .It Fn dwarf_set_frame_same_value
458 Set the register number representing the
461 .It Fn dwarf_set_frame_undefined_value
462 Set the register number representing the
468 .It Fn dwarf_find_macro_value_start
469 Return the macro value part of a macro string.
470 .It Fn dwarf_get_macro_details
471 Retrieve macro information.
473 .It Memory Management
474 In the DWARF consumer API, the rules for memory management differ
476 In some cases, the memory areas returned to the application by the
477 library are freed by calling specific API functions.
478 In others, the deallocation function
481 The individual manual pages for the API's functions document the
482 specific memory management rules to be followed.
486 is used to mark memory arenas as unused.
487 Additionally, the following functions release specific types of
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 ,
498 .Fn dwarf_weaks_dealloc .
500 The following functions may be used to return symbolic names
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 ,
524 .Fn dwarf_get_VIS_name .
527 .It Fn dwarf_get_pubtypes , Fn dwarf_get_types
528 Retrieve descriptors for user-defined types.
529 .It Fn dwarf_next_types_section
532 sections in a debug context.
533 .It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset
534 Return the offset for the compilation unit for a type.
535 .It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset
536 Return the offset for the debugging information entry for a type.
537 .It Fn dwarf_pubtypename , Fn dwarf_typename
538 Retrieve the name of a type.
539 .It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets
540 Retrieve the name and offsets for a type.
544 .It Fn dwarf_get_vars
545 Retrieve descriptors for static variables.
546 .It Fn dwarf_var_cu_offset
547 Return the offset for the compilation unit for a variable.
548 .It Fn dwarf_var_die_offset
549 Return the offset for the debugging information entry for a variable.
551 Retrieve the name of a variable.
552 .It Fn dwarf_var_name_offsets
553 Retrieve the name and offsets for a variable.
557 .It Fn dwarf_get_weaks
558 Retrieve information about weak symbols.
559 .It Fn dwarf_weak_cu_offset
560 Return the offset for the compilation unit for a weak symbol.
561 .It Fn dwarf_weak_die_offset
562 Return the offset for the debugging information entry for a weak symbol.
563 .It Fn dwarf_weakname
564 Retrieve the name of a weak symbol.
565 .It Fn dwarf_weak_name_offsets
566 Retrieve the name and offsets for a weak symbol.
571 Retrieve the ELF descriptor for a debug context, see
574 Retrieve a NUL-terminated string from the DWARF string section.
575 .It Fn dwarf_set_reloc_application
576 Control whether relocations are to be handled by
580 .Sh The DWARF Producer API
581 The DWARF producer API permits applications to add DWARF information to
584 The major functional groups of functions in the producer API are listed
586 .Bl -tag -width "CCCC"
587 .It Attribute Management
588 The following functions are used to attach attributes to a debugging
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
606 .Fn dwarf_add_AT_unsigned_const .
607 .It Debugging Information Entry Management
609 .It Fn dwarf_add_die_to_debug
610 Set the root debugging information entry for a DWARF producer instance.
611 .It Fn dwarf_die_link
612 Links debugging information entries.
614 Allocate a new debugging information entry.
616 .It Initialization and Finalization
618 .Fn dwarf_producer_init
620 .Fn dwarf_producer_init_b
621 are used to initialize a producer instance.
623 When done, applications release resources using the function
624 .Fn dwarf_producer_finish .
625 .It Relocations and Sections
627 .It Fn dwarf_get_relocation_info
628 Retrieve a relocation array from a producer instance.
629 .It Fn dwarf_get_relocation_info_count
630 Return the number of relocation arrays for a producer instance.
631 .It Fn dwarf_get_section_bytes
632 Retrieve the ELF byte stream for a section.
633 .It Fn dwarf_reset_section_bytes
634 Reset internal state for a producer instance.
635 .It Fn dwarf_transform_to_disk_form
636 Prepare byte streams for writing out.
640 .It Fn dwarf_def_macro
641 Add a macro definition.
642 .It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file
643 Record macro file related information.
644 .It Fn dwarf_undef_macro
645 Note the removal of a macro definition.
646 .It Fn dwarf_vendor_ext
647 Enables storing macro information as specified in the DWARF standard.
649 .It Symbols, Expressions, Addresses and Offsets
651 .It Fn dwarf_add_arange , Fn dwarf_add_arange_b
652 Add address range information.
653 .It Fn dwarf_add_directory_decl
654 Add information about an include directory to a producer instance.
655 .It Fn dwarf_add_fde_inst
656 Add an operation to a frame descriptor entry.
657 .It Fn dwarf_add_file_decl
658 Add information about a source file to a producer instance.
659 .It Fn dwarf_add_frame_cie
660 Add call information to a frame descriptor.
661 .It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b
662 Link a frame descriptor to a producer instance.
663 .It Fn dwarf_add_funcname
664 Add information about a function to a producer instance.
665 .It Fn dwarf_add_line_entry
666 Record mapping information between machine addresses and a source line.
667 .It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b
670 opcode to a location expression.
671 .It Fn dwarf_add_expr_gen
672 Add an operator to a location expression.
673 .It Fn dwarf_add_pubname
674 Add information about a global name to a producer instance.
675 .It Fn dwarf_add_typename
676 Add information about a type to a producer instance.
677 .It Fn dwarf_add_varname
678 Add information about a static variable to a producer instance.
679 .It Fn dwarf_add_weakname
680 Add information about a weak symbol to a producer instance.
681 .It Fn dwarf_expr_current_offset
682 Retrieve the current size of a location expression.
683 .It Fn dwarf_expr_into_block
684 Convert a location expression into a byte stream.
685 .It Fn dwarf_fde_cfa_offset
688 operation to a frame descriptor.
689 .It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address
690 Note address ranges for source lines.
691 .It Fn dwarf_new_expr
692 Allocate a location expression descriptor.
694 Allocate a frame descriptor.
698 .Fn dwarf_producer_set_isa
699 sets the instruction set architecture for the producer instance.
702 This implementation is believed to be source compatible with the
703 SGI/GNU DWARF(3) library, version 20110113.
705 Known differences with the SGI/GNU library include:
708 The memory management scheme used differs, in a backward-compatible
711 .Sx Memory Management
712 above, for coding guidelines for portable applications.
714 There is provision for setting a library-wide error handler in
715 addition to the per-debug context handlers supported by the SGI/GNU
716 API, see the subsection
721 The following APIs are extensions specific to this implementation:
726 .Fn dwarf_next_types_section
728 .Fn dwarf_producer_set_isa
733 The DWARF standard is defined by
735 .%T "The DWARF Debugging Information Format"
737 .%O "http://www.dwarfstd.org/"
740 The DWARF(3) API originated at Silicon Graphics Inc.
742 A BSD-licensed implementation of a subset of the API was written by
743 .An John Birrell Aq Mt jb@FreeBSD.org
744 for the FreeBSD project.
745 The implementation was subsequently revised and completed by
746 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .
748 Manual pages for this implementation were written by
749 .An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net
751 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .