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 3195 2015-05-12 17:22:19Z emaste $
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, corresponding to an
115 type supported by the underlying operating system.
117 A descriptor for a location expression.
119 A virtual address used by an application.
121 A 64-bit wide signed numeric type.
123 An 8-bit wide unsigned numeric type.
125 A descriptor representing a user-specified type.
126 .It Vt Dwarf_Unsigned
127 A 64-bit wide unsigned numeric type.
129 A descriptor representing a static variable.
131 A descriptor representing a weak name.
135 Library functions that encounter an error will return with a value
141 allows applications to specify three levels of error handling:
144 Most library functions take a parameter of type
146 that specifies a location to store an error descriptor in
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
152 Otherwise, if the error parameter was NULL, but if an error handler
153 was defined for the debug context in use using
156 .Xr dwarf_seterrhand 3 ,
157 then the library will invoke the specified error handler with an error
158 descriptor as argument.
160 Otherwise, if a library wide error handler was specified using
161 .Xr dwarf_seterrhand 3 ,
165 Error descriptors may be used with
169 .Sh The DWARF Consumer API
170 The DWARF consumer API permits applications to read DWARF information in
173 The major functional groups of functions in the consumer API are listed
176 .Bl -tag -compact -width "CCCC"
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
188 .It Fn dwarf_get_abbrev_tag
189 Retrieve the tag for an abbreviation entry.
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
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.
212 .It Fn dwarf_arrayorder
213 Retrieve the value of a
217 Retrieve an attribute descriptor.
218 .It Fn dwarf_attrlist
219 Retrieve attribute descriptors for a debugging information entry.
220 .It Fn dwarf_attroffset
221 Retrieve the section-relative offset of an attribute descriptor.
222 .It Fn dwarf_attrval_flag
226 .It Fn dwarf_attrval_signed
227 Retrieve an attribute's value as a signed integral quantity.
228 .It Fn dwarf_attrval_string
229 Retrieve an attribute's value as a NUL-terminated string.
230 .It Fn dwarf_attrval_unsigned
231 Retrieve an attribute's value as an unsigned integral quantity.
232 .It Fn dwarf_bitoffset ,
233 Retrieve the value of a
236 .It Fn dwarf_bitsize ,
237 Retrieve the value of a
240 .It Fn dwarf_bytesize
241 Retrieve the value of a
244 .It Fn dwarf_formaddr
245 Return the value of an
248 .It Fn dwarf_formblock
249 Return the value of a
252 .It Fn dwarf_formexprloc
253 Return information about a location expression.
254 .It Fn dwarf_formflag
255 Retrieve information about a
258 .It Fn dwarf_formref , Fn dwarf_global_formref
260 .Dv REFERENCE Ns - Ns
262 .It Fn dwarf_formsdata , Fn dwarf_formudata
263 Retrieve the value of a
266 .It Fn dwarf_formsig8
267 Return the type signature for a DWARF type.
268 .It Fn dwarf_formstring
269 Retrieve information about a
272 .It Fn dwarf_get_form_class
273 Retrieve the form class for an attribute.
275 Check for the presence of an attribute.
277 Check if an attribute has the given form.
278 .It Fn dwarf_whatattr
279 Retrieve the attribute code for an attribute.
280 .It Fn dwarf_whatform , Fn dwarf_whatform_direct
281 Retrieve the form of an attribute.
283 .It Call Information Entries and Frame Descriptor Entries
285 .It Fn dwarf_get_cie_index
286 Retrieve the index for a CIE descriptor.
287 .It Fn dwarf_get_cie_info
288 Retrieve information from a CIE descriptor.
289 .It Fn dwarf_get_cie_of_fde
290 Retrieve a CIE descriptor.
291 .It Fn dwarf_get_fde_at_pc
292 Retrieve an FDE descriptor for an address.
293 .It Fn dwarf_get_fde_info_for_all_regs
294 Retrieve register rule row.
295 .It Fn dwarf_get_fde_info_for_all_regs3
296 Retrieve register rule row (revised API).
297 .It Fn dwarf_get_fde_info_for_cfa_reg3
298 Retrieve a CFA register rule.
299 .It Fn dwarf_get_fde_info_for_reg
300 Retrieve a register rule.
301 .It Fn dwarf_get_fde_info_for_reg3
302 Retrieve a register rule (revised API).
303 .It Fn dwarf_get_fde_instr_bytes
304 Retrieve instructions from an FDE descriptor.
305 .It Fn dwarf_get_fde_list , Fn dwarf_get_fde_list_eh
306 Retrieve frame information.
307 .It Fn dwarf_get_fde_n
308 Retrieve an FDE descriptor.
309 .It Fn dwarf_get_fde_range
310 Retrieve range information from an FDE descriptor.
312 .It Compilation Units
315 .Fn dwarf_get_cu_die_offset_given_cu_header_offset ,
316 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
318 Retrieve the offset of the debugging information entry for a
319 compilation or type unit.
321 .Fn dwarf_next_cu_header ,
322 .Fn dwarf_next_cu_header_b ,
323 .Fn dwarf_next_cu_header_c
325 Step through compilation units in a debug context.
327 .It Debugging Information Entries
330 Returns the child of a debugging information entry.
331 .It Fn dwarf_die_abbrev_code
332 Returns the abbreviation code for a debugging information entry.
333 .It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range
334 Retrieve offsets and lengths for a compilation unit.
338 attribute for a debugging information entry.
339 .It Fn dwarf_dieoffset
340 Retrieves the offset for a debugging information entry.
341 .It Fn dwarf_get_die_infotypes_flag
342 Indicate the originating section for a debugging information entry.
343 .It Fn dwarf_highpc , Fn dwarf_highpc_b
344 Return the highest PC value for a debugging information entry.
346 Return the lowest PC value for a debugging information entry.
347 .It Fn dwarf_offdie , Fn dwarf_offdie_b
348 Retrieve a debugging information entry given an offset.
349 .It Fn dwarf_siblingof , Fn dwarf_siblingof_b
350 Retrieve the sibling descriptor for a debugging information entry.
352 Retrieve the source language attribute for a debugging information
355 Retrieve the tag for a debugging information entry.
359 .It Fn dwarf_func_cu_offset
360 Retrieves the offset for the compilation unit for a function.
361 .It Fn dwarf_func_die_offset
362 Retrieves the offset for the debugging information entry for a
364 .It Fn dwarf_funcname
365 Retrieves the name of a function.
366 .It Fn dwarf_func_name_offsets
367 Retrieve both the name and offsets for a function.
368 .It Fn dwarf_get_funcs
369 Retrieve information about static functions.
373 .It Fn dwarf_get_globals
374 Retrieve a list of globals.
375 .It Fn dwarf_global_cu_offset
376 Return the offset for compilation unit for a global.
377 .It Fn dwarf_global_die_offset
378 Return the offset for the debugging information entry for a global.
379 .It Fn dwarf_global_name_offsets
380 Return the name and offsets for a global.
381 .It Fn dwarf_globname
382 Return the name for a global.
384 .It Initialization and Finalization
389 may be used for initialization.
392 may be used to release resources.
395 .Fn dwarf_object_init
397 .Fn dwarf_object_finish
398 allow an application to specify alternate low-level file access
402 .It Fn dwarf_lineaddr
403 Retrieve the program address for a source line.
404 .It Fn dwarf_linebeginstatement
405 Check if a source line corresponds to the beginning of a statement.
406 .It Fn dwarf_lineblock
407 Check if a source line corresponds to the start of a basic block.
408 .It Fn dwarf_lineendsequence
409 Check if the source line corresponds to the end of a sequence of
412 Retrieve the line number for a line descriptor.
414 Retrieve the column number for a line descriptor.
416 Retrieve the source file for a line descriptor.
417 .It Fn dwarf_line_srcfileno
418 Retrieve the index of the source file for a line descriptor.
419 .It Fn dwarf_srcfiles
420 Retrieve source files for a compilation unit.
421 .It Fn dwarf_srclines
422 Return line number information for a compilation unit.
426 .It Fn dwarf_get_loclist_entry
427 Retrieve a location list entry.
428 .It Fn dwarf_loclist , Fn dwarf_loclist_n
429 Retrieve location expressions.
431 .Fn dwarf_loclist_from_expr ,
432 .Fn dwarf_loclist_from_expr_a ,
433 .Fn dwarf_loclist_from_expr_b
435 Translate a location expression into a location descriptor.
440 Retrieve a human-readable error message.
442 Retrieve an error number from an error descriptor.
443 .It Fn dwarf_seterrarg
444 Set the argument passed to a callback error handler.
445 .It Fn dwarf_seterrhand
446 Set the callback handler to be called in case of an error.
450 .It Fn dwarf_expand_frame_instructions
451 Translate frame instruction bytes.
452 .It Fn dwarf_set_frame_cfa_value
453 Set the CFA parameter for the internal register rule table.
454 .It Fn dwarf_set_frame_rule_initial_value
455 Set the initial value of the register rules in the internal register
457 .It Fn dwarf_set_frame_rule_table_size
458 Set the maximum number of columns in the register rule table.
459 .It Fn dwarf_set_frame_same_value
460 Set the register number representing the
463 .It Fn dwarf_set_frame_undefined_value
464 Set the register number representing the
470 .It Fn dwarf_find_macro_value_start
471 Return the macro value part of a macro string.
472 .It Fn dwarf_get_macro_details
473 Retrieve macro information.
475 .It Memory Management
476 In the DWARF consumer API, the rules for memory management differ
478 In some cases, the memory areas returned to the application by the
479 library are freed by calling specific API functions.
480 In others, the deallocation function
483 The individual manual pages for the API's functions document the
484 specific memory management rules to be followed.
488 is used to mark memory arenas as unused.
489 Additionally, the following functions release specific types of
491 .Fn dwarf_fde_cie_list_dealloc ,
492 .Fn dwarf_funcs_dealloc ,
493 .Fn dwarf_globals_dealloc ,
494 .Fn dwarf_pubtypes_dealloc ,
495 .Fn dwarf_ranges_dealloc ,
496 .Fn dwarf_srclines_dealloc ,
497 .Fn dwarf_types_dealloc ,
498 .Fn dwarf_vars_dealloc ,
500 .Fn dwarf_weaks_dealloc .
502 The following functions may be used to return symbolic names
504 .Fn dwarf_get_ACCESS_name ,
505 .Fn dwarf_get_AT_name ,
506 .Fn dwarf_get_ATE_name ,
507 .Fn dwarf_get_CC_name ,
508 .Fn dwarf_get_CFA_name ,
509 .Fn dwarf_get_CHILDREN_name ,
510 .Fn dwarf_get_DS_name ,
511 .Fn dwarf_get_DSC_name ,
512 .Fn dwarf_get_EH_name ,
513 .Fn dwarf_get_END_name ,
514 .Fn dwarf_get_FORM_name ,
515 .Fn dwarf_get_ID_name ,
516 .Fn dwarf_get_INL_name ,
517 .Fn dwarf_get_LANG_name ,
518 .Fn dwarf_get_LNE_name ,
519 .Fn dwarf_get_LNS_name ,
520 .Fn dwarf_get_MACINFO_name ,
521 .Fn dwarf_get_OP_name ,
522 .Fn dwarf_get_ORD_name ,
523 .Fn dwarf_get_TAG_name ,
524 .Fn dwarf_get_VIRTUALITY_name ,
526 .Fn dwarf_get_VIS_name .
529 .It Fn dwarf_get_pubtypes , Fn dwarf_get_types
530 Retrieve descriptors for user-defined types.
531 .It Fn dwarf_next_types_section
534 sections in a debug context.
535 .It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset
536 Return the offset for the compilation unit for a type.
537 .It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset
538 Return the offset for the debugging information entry for a type.
539 .It Fn dwarf_pubtypename , Fn dwarf_typename
540 Retrieve the name of a type.
541 .It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets
542 Retrieve the name and offsets for a type.
546 .It Fn dwarf_get_vars
547 Retrieve descriptors for static variables.
548 .It Fn dwarf_var_cu_offset
549 Return the offset for the compilation unit for a variable.
550 .It Fn dwarf_var_die_offset
551 Return the offset for the debugging information entry for a variable.
553 Retrieve the name of a variable.
554 .It Fn dwarf_var_name_offsets
555 Retrieve the name and offsets for a variable.
559 .It Fn dwarf_get_weaks
560 Retrieve information about weak symbols.
561 .It Fn dwarf_weak_cu_offset
562 Return the offset for the compilation unit for a weak symbol.
563 .It Fn dwarf_weak_die_offset
564 Return the offset for the debugging information entry for a weak symbol.
565 .It Fn dwarf_weakname
566 Retrieve the name of a weak symbol.
567 .It Fn dwarf_weak_name_offsets
568 Retrieve the name and offsets for a weak symbol.
573 Retrieve the ELF descriptor for a debug context, see
576 Retrieve a NUL-terminated string from the DWARF string section.
577 .It Fn dwarf_set_reloc_application
578 Control whether relocations are to be handled by
582 .Sh The DWARF Producer API
583 The DWARF producer API permits applications to add DWARF information to
586 The major functional groups of functions in the producer API are listed
588 .Bl -tag -width "CCCC"
589 .It Attribute Management
590 The following functions are used to attach attributes to a debugging
592 .Fn dwarf_add_AT_comp_dir ,
593 .Fn dwarf_add_AT_const_value_signedint ,
594 .Fn dwarf_add_AT_const_value_string ,
595 .Fn dwarf_add_AT_const_value_unsignedint ,
596 .Fn dwarf_add_AT_dataref ,
597 .Fn dwarf_add_AT_flag ,
598 .Fn dwarf_add_AT_location_expr ,
599 .Fn dwarf_add_AT_name ,
600 .Fn dwarf_add_AT_producer ,
601 .Fn dwarf_add_AT_ref_address ,
602 .Fn dwarf_add_AT_reference ,
603 .Fn dwarf_add_AT_signed_const ,
604 .Fn dwarf_add_AT_string ,
605 .Fn dwarf_add_AT_targ_address ,
606 .Fn dwarf_add_AT_targ_address_b
608 .Fn dwarf_add_AT_unsigned_const .
609 .It Debugging Information Entry Management
611 .It Fn dwarf_add_die_to_debug
612 Set the root debugging information entry for a DWARF producer instance.
613 .It Fn dwarf_die_link
614 Links debugging information entries.
616 Allocate a new debugging information entry.
618 .It Initialization and Finalization
620 .Fn dwarf_producer_init
622 .Fn dwarf_producer_init_b
623 are used to initialize a producer instance.
625 When done, applications release resources using the function
626 .Fn dwarf_producer_finish .
627 .It Relocations and Sections
629 .It Fn dwarf_get_relocation_info
630 Retrieve a relocation array from a producer instance.
631 .It Fn dwarf_get_relocation_info_count
632 Return the number of relocation arrays for a producer instance.
633 .It Fn dwarf_get_section_bytes
634 Retrieve the ELF byte stream for a section.
635 .It Fn dwarf_reset_section_bytes
636 Reset internal state for a producer instance.
637 .It Fn dwarf_transform_to_disk_form
638 Prepare byte streams for writing out.
642 .It Fn dwarf_def_macro
643 Add a macro definition.
644 .It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file
645 Record macro file related information.
646 .It Fn dwarf_undef_macro
647 Note the removal of a macro definition.
648 .It Fn dwarf_vendor_ext
649 Enables storing macro information as specified in the DWARF standard.
651 .It Symbols, Expressions, Addresses and Offsets
653 .It Fn dwarf_add_arange , Fn dwarf_add_arange_b
654 Add address range information.
655 .It Fn dwarf_add_directory_decl
656 Add information about an include directory to a producer instance.
657 .It Fn dwarf_add_fde_inst
658 Add an operation to a frame descriptor entry.
659 .It Fn dwarf_add_file_decl
660 Add information about a source file to a producer instance.
661 .It Fn dwarf_add_frame_cie
662 Add call information to a frame descriptor.
663 .It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b
664 Link a frame descriptor to a producer instance.
665 .It Fn dwarf_add_funcname
666 Add information about a function to a producer instance.
667 .It Fn dwarf_add_line_entry
668 Record mapping information between machine addresses and a source line.
669 .It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b
672 opcode to a location expression.
673 .It Fn dwarf_add_expr_gen
674 Add an operator to a location expression.
675 .It Fn dwarf_add_pubname
676 Add information about a global name to a producer instance.
677 .It Fn dwarf_add_typename
678 Add information about a type to a producer instance.
679 .It Fn dwarf_add_varname
680 Add information about a static variable to a producer instance.
681 .It Fn dwarf_add_weakname
682 Add information about a weak symbol to a producer instance.
683 .It Fn dwarf_expr_current_offset
684 Retrieve the current size of a location expression.
685 .It Fn dwarf_expr_into_block
686 Convert a location expression into a byte stream.
687 .It Fn dwarf_fde_cfa_offset
690 operation to a frame descriptor.
691 .It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address
692 Note address ranges for source lines.
693 .It Fn dwarf_new_expr
694 Allocate a location expression descriptor.
696 Allocate a frame descriptor.
700 .Fn dwarf_producer_set_isa
701 sets the instruction set architecture for the producer instance.
704 This implementation is believed to be source compatible with the
705 SGI/GNU DWARF(3) library, version 20110113.
707 Known differences with the SGI/GNU library include:
710 The memory management scheme used differs, in a backward-compatible
713 .Sx Memory Management
714 above, for coding guidelines for portable applications.
716 There is provision for setting a library-wide error handler in
717 addition to the per-debug context handlers supported by the SGI/GNU
718 API, see the subsection
723 The following APIs are extensions specific to this implementation:
728 .Fn dwarf_next_types_section
730 .Fn dwarf_producer_set_isa
735 The DWARF standard is defined by
737 .%T "The DWARF Debugging Information Format"
739 .%O "http://www.dwarfstd.org/"
742 The DWARF(3) API originated at Silicon Graphics Inc.
744 A BSD-licensed implementation of a subset of the API was written by
745 .An John Birrell Aq Mt jb@FreeBSD.org
746 for the FreeBSD project.
747 The implementation was subsequently revised and completed by
748 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .
750 Manual pages for this implementation were written by
751 .An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net
753 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .