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 3644 2018-10-15 19:55:01Z jkoshy $
31 .Nd access debugging information in object files
39 provides functions that allow an application to read and write debugging
40 information in object files.
41 The format of debugging information accessible through this API
42 is defined by the DWARF standard, see
50 A consumer API set allows applications to read existing debug information
52 The functions that comprise the DWARF consumer API are described in
54 .Sx "DWARF Consumer API"
57 A producer API set that allows applications to add debug information
59 The functions that comprise the DWARF producer API are described in
61 .Sx "DWARF Producer API"
65 Each function referenced below is further described in its own manual page.
67 The DWARF library uses the following prefixes:
69 .Bl -tag -width ".Li Dwarf_*" -compact
71 Used for error numbers and constants.
77 Used for functions and macros that make up the API.
80 The DWARF(3) API uses the following data types:
82 .Bl -tag -width ".Vt Dwarf_Unsigned" -compact
84 Describes DWARF abbreviations.
86 A program address in the target object.
88 Describes address ranges.
89 .It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute
90 Describes attributes of debugging information entries.
92 Used for boolean states.
93 .It Vt Dwarf_Cie , Vt Dwarf_P_Cie
94 Describes call information that is common to several frames.
95 .It Vt Dwarf_Debug , Vt Dwarf_P_Debug
96 An opaque type describing a debug context.
97 .It Vt Dwarf_Die , Vt Dwarf_P_Die
98 A debugging information entry.
99 .It Vt Dwarf_Fde , Vt Dwarf_P_Fde
102 A descriptor representing a function.
104 A descriptor representing a global name.
106 A 16-bit wide unsigned numeric type.
108 A pointer to an error handling function.
110 A descriptor for a source line.
112 An unsigned file offset.
114 A descriptor for a location expression.
116 A virtual address used by an application.
118 A 64-bit wide signed numeric type.
120 An 8-bit wide unsigned numeric type.
122 A descriptor representing a user-specified type.
123 .It Vt Dwarf_Unsigned
124 A 64-bit wide unsigned numeric type.
126 A descriptor representing a static variable.
128 A descriptor representing a weak name.
131 Library functions that encounter an error will return with a value
137 allows applications to specify three levels of error handling:
140 Most library functions take a parameter of type
142 that specifies a location to store an error descriptor in
144 If an error occurs during the execution on an API, and if this
145 parameter is non-NULL, then an error descriptor is written to the
148 Otherwise, if the error parameter was NULL, but if an error handler
149 was defined for the debug context in use using
152 .Xr dwarf_seterrhand 3 ,
153 then the library will invoke the specified error handler with an error
154 descriptor as argument.
156 Otherwise, if a library wide error handler was specified using
157 .Xr dwarf_seterrhand 3 ,
161 Error descriptors may be used with
165 .Sh The DWARF Consumer API
166 The DWARF consumer API permits applications to read DWARF information in
169 The major functional groups of functions in the consumer API are listed
172 .Bl -tag -compact -width "CCCC"
174 .Bl -tag -compact -width indent
175 .It Fn dwarf_get_abbrev
176 Retrieve abbreviation information at a given offset.
177 .It Fn dwarf_get_abbrev_children_flag
178 Check if an abbreviation has child elements.
179 .It Fn dwarf_get_abbrev_code
180 Retrieve the abbreviation code for an abbreviation entry descriptor.
181 .It Fn dwarf_get_abbrev_entry
182 Retrieve abbreviation information for an abbreviation entry
184 .It Fn dwarf_get_abbrev_tag
185 Retrieve the tag for an abbreviation entry.
188 .Bl -tag -compact -width indent
189 .It Fn dwarf_get_address_size
190 Return the number of bytes needed to represent an address.
191 .It Fn dwarf_get_arange
192 Search for an address range descriptor covering an address.
193 .It Fn dwarf_get_arange_cu_header_offset
194 Retrieve the offsets associated with an address range descriptor.
195 .It Fn dwarf_get_arange_info
196 Extract address range information from a descriptor.
197 .It Fn dwarf_get_aranges
198 Retrieve program address space mappings.
199 .It Fn dwarf_get_cu_die_offset
200 Retrieve the offset associated with a compilation unit for an address
202 .It Fn dwarf_get_ranges , Fn dwarf_get_ranges_a
203 Retrieve information about non-contiguous address ranges for
204 a debugging information entry.
207 .Bl -tag -compact -width indent
208 .It Fn dwarf_arrayorder
209 Retrieve the value of a
213 Retrieve an attribute descriptor.
214 .It Fn dwarf_attrlist
215 Retrieve attribute descriptors for a debugging information entry.
216 .It Fn dwarf_attroffset
217 Retrieve the section-relative offset of an attribute descriptor.
218 .It Fn dwarf_attrval_flag
222 .It Fn dwarf_attrval_signed
223 Retrieve an attribute's value as a signed integral quantity.
224 .It Fn dwarf_attrval_string
225 Retrieve an attribute's value as a NUL-terminated string.
226 .It Fn dwarf_attrval_unsigned
227 Retrieve an attribute's value as an unsigned integral quantity.
228 .It Fn dwarf_bitoffset ,
229 Retrieve the value of a
232 .It Fn dwarf_bitsize ,
233 Retrieve the value of a
236 .It Fn dwarf_bytesize
237 Retrieve the value of a
240 .It Fn dwarf_formaddr
241 Return the value of an
244 .It Fn dwarf_formblock
245 Return the value of a
248 .It Fn dwarf_formexprloc
249 Return information about a location expression.
250 .It Fn dwarf_formflag
251 Retrieve information about a
254 .It Fn dwarf_formref , Fn dwarf_global_formref
256 .Dv REFERENCE Ns - Ns
258 .It Fn dwarf_formsdata , Fn dwarf_formudata
259 Retrieve the value of a
262 .It Fn dwarf_formsig8
263 Return the type signature for a DWARF type.
264 .It Fn dwarf_formstring
265 Retrieve information about a
268 .It Fn dwarf_get_form_class
269 Retrieve the form class for an attribute.
271 Check for the presence of an attribute.
273 Check if an attribute has the given form.
274 .It Fn dwarf_whatattr
275 Retrieve the attribute code for an attribute.
276 .It Fn dwarf_whatform , Fn dwarf_whatform_direct
277 Retrieve the form of an attribute.
279 .It Call Information Entries and Frame Descriptor Entries
280 .Bl -tag -compact -width indent
281 .It Fn dwarf_get_cie_index
282 Retrieve the index for a CIE descriptor.
283 .It Fn dwarf_get_cie_info
284 Retrieve information from a CIE descriptor.
285 .It Fn dwarf_get_cie_of_fde
286 Retrieve a CIE descriptor.
287 .It Fn dwarf_get_fde_at_pc
288 Retrieve an FDE descriptor for an address.
289 .It Fn dwarf_get_fde_info_for_all_regs
290 Retrieve register rule row.
291 .It Fn dwarf_get_fde_info_for_all_regs3
292 Retrieve register rule row (revised API).
293 .It Fn dwarf_get_fde_info_for_cfa_reg3
294 Retrieve a CFA register rule.
295 .It Fn dwarf_get_fde_info_for_reg
296 Retrieve a register rule.
297 .It Fn dwarf_get_fde_info_for_reg3
298 Retrieve a register rule (revised API).
299 .It Fn dwarf_get_fde_instr_bytes
300 Retrieve instructions from an FDE descriptor.
301 .It Fn dwarf_get_fde_list , Fn dwarf_get_fde_list_eh
302 Retrieve frame information.
303 .It Fn dwarf_get_fde_n
304 Retrieve an FDE descriptor.
305 .It Fn dwarf_get_fde_range
306 Retrieve range information from an FDE descriptor.
308 .It Compilation Units
309 .Bl -tag -compact -width indent
311 .Fn dwarf_get_cu_die_offset_given_cu_header_offset ,
312 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
314 Retrieve the offset of the debugging information entry for a
315 compilation or type unit.
317 .Fn dwarf_next_cu_header ,
318 .Fn dwarf_next_cu_header_b ,
319 .Fn dwarf_next_cu_header_c
321 Step through compilation units in a debug context.
323 .It Debugging Information Entries
324 .Bl -tag -compact -width indent
326 Returns the child of a debugging information entry.
327 .It Fn dwarf_die_abbrev_code
328 Returns the abbreviation code for a debugging information entry.
329 .It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range
330 Retrieve offsets and lengths for a compilation unit.
334 attribute for a debugging information entry.
335 .It Fn dwarf_dieoffset
336 Retrieves the offset for a debugging information entry.
337 .It Fn dwarf_get_die_infotypes_flag
338 Indicate the originating section for a debugging information entry.
339 .It Fn dwarf_highpc , Fn dwarf_highpc_b
340 Return the highest PC value for a debugging information entry.
342 Return the lowest PC value for a debugging information entry.
343 .It Fn dwarf_offdie , Fn dwarf_offdie_b
344 Retrieve a debugging information entry given an offset.
345 .It Fn dwarf_siblingof , Fn dwarf_siblingof_b
346 Retrieve the sibling descriptor for a debugging information entry.
348 Retrieve the source language attribute for a debugging information
351 Retrieve the tag for a debugging information entry.
354 .Bl -tag -compact -width indent
355 .It Fn dwarf_func_cu_offset
356 Retrieves the offset for the compilation unit for a function.
357 .It Fn dwarf_func_die_offset
358 Retrieves the offset for the debugging information entry for a
360 .It Fn dwarf_funcname
361 Retrieves the name of a function.
362 .It Fn dwarf_func_name_offsets
363 Retrieve both the name and offsets for a function.
364 .It Fn dwarf_get_funcs
365 Retrieve information about static functions.
368 .Bl -tag -compact -width indent
369 .It Fn dwarf_get_globals
370 Retrieve a list of globals.
371 .It Fn dwarf_global_cu_offset
372 Return the offset for compilation unit for a global.
373 .It Fn dwarf_global_die_offset
374 Return the offset for the debugging information entry for a global.
375 .It Fn dwarf_global_name_offsets
376 Return the name and offsets for a global.
377 .It Fn dwarf_globname
378 Return the name for a global.
380 .It Initialization and Finalization
385 may be used for initialization.
388 may be used to release resources.
391 .Fn dwarf_object_init
393 .Fn dwarf_object_finish
394 allow an application to specify alternate low-level file access
397 .Bl -tag -compact -width indent
398 .It Fn dwarf_lineaddr
399 Retrieve the program address for a source line.
400 .It Fn dwarf_linebeginstatement
401 Check if a source line corresponds to the beginning of a statement.
402 .It Fn dwarf_lineblock
403 Check if a source line corresponds to the start of a basic block.
404 .It Fn dwarf_lineendsequence
405 Check if the source line corresponds to the end of a sequence of
408 Retrieve the line number for a line descriptor.
410 Retrieve the column number for a line descriptor.
412 Retrieve the source file for a line descriptor.
413 .It Fn dwarf_line_srcfileno
414 Retrieve the index of the source file for a line descriptor.
415 .It Fn dwarf_srcfiles
416 Retrieve source files for a compilation unit.
417 .It Fn dwarf_srclines
418 Return line number information for a compilation unit.
421 .Bl -tag -compact -width indent
422 .It Fn dwarf_get_loclist_entry
423 Retrieve a location list entry.
424 .It Fn dwarf_loclist , Fn dwarf_loclist_n
425 Retrieve location expressions.
427 .Fn dwarf_loclist_from_expr ,
428 .Fn dwarf_loclist_from_expr_a ,
429 .Fn dwarf_loclist_from_expr_b
431 Translate a location expression into a location descriptor.
434 .Bl -tag -compact -width indent
436 Retrieve a human-readable error message.
438 Retrieve an error number from an error descriptor.
439 .It Fn dwarf_seterrarg
440 Set the argument passed to a callback error handler.
441 .It Fn dwarf_seterrhand
442 Set the callback handler to be called in case of an error.
445 .Bl -tag -compact -width indent
446 .It Fn dwarf_expand_frame_instructions
447 Translate frame instruction bytes.
448 .It Fn dwarf_set_frame_cfa_value
449 Set the CFA parameter for the internal register rule table.
450 .It Fn dwarf_set_frame_rule_initial_value
451 Set the initial value of the register rules in the internal register
453 .It Fn dwarf_set_frame_rule_table_size
454 Set the maximum number of columns in the register rule table.
455 .It Fn dwarf_set_frame_same_value
456 Set the register number representing the
459 .It Fn dwarf_set_frame_undefined_value
460 Set the register number representing the
465 .Bl -tag -compact -width indent
466 .It Fn dwarf_find_macro_value_start
467 Return the macro value part of a macro string.
468 .It Fn dwarf_get_macro_details
469 Retrieve macro information.
471 .It Memory Management
472 In the DWARF consumer API, the rules for memory management differ
474 In some cases, the memory areas returned to the application by the
475 library are freed by calling specific API functions.
476 In others, the deallocation function
479 The individual manual pages for the API's functions document the
480 specific memory management rules to be followed.
484 is used to mark memory arenas as unused.
485 Additionally, the following functions release specific types of
487 .Fn dwarf_fde_cie_list_dealloc ,
488 .Fn dwarf_funcs_dealloc ,
489 .Fn dwarf_globals_dealloc ,
490 .Fn dwarf_pubtypes_dealloc ,
491 .Fn dwarf_ranges_dealloc ,
492 .Fn dwarf_srclines_dealloc ,
493 .Fn dwarf_types_dealloc ,
494 .Fn dwarf_vars_dealloc ,
496 .Fn dwarf_weaks_dealloc .
498 The following functions may be used to return symbolic names
500 .Fn dwarf_get_ACCESS_name ,
501 .Fn dwarf_get_AT_name ,
502 .Fn dwarf_get_ATE_name ,
503 .Fn dwarf_get_CC_name ,
504 .Fn dwarf_get_CFA_name ,
505 .Fn dwarf_get_CHILDREN_name ,
506 .Fn dwarf_get_DS_name ,
507 .Fn dwarf_get_DSC_name ,
508 .Fn dwarf_get_EH_name ,
509 .Fn dwarf_get_END_name ,
510 .Fn dwarf_get_FORM_name ,
511 .Fn dwarf_get_ID_name ,
512 .Fn dwarf_get_INL_name ,
513 .Fn dwarf_get_LANG_name ,
514 .Fn dwarf_get_LNE_name ,
515 .Fn dwarf_get_LNS_name ,
516 .Fn dwarf_get_MACINFO_name ,
517 .Fn dwarf_get_OP_name ,
518 .Fn dwarf_get_ORD_name ,
519 .Fn dwarf_get_TAG_name ,
520 .Fn dwarf_get_VIRTUALITY_name ,
522 .Fn dwarf_get_VIS_name .
524 .Bl -tag -compact -width indent
525 .It Fn dwarf_get_pubtypes , Fn dwarf_get_types
526 Retrieve descriptors for user-defined types.
527 .It Fn dwarf_next_types_section
530 sections in a debug context.
531 .It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset
532 Return the offset for the compilation unit for a type.
533 .It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset
534 Return the offset for the debugging information entry for a type.
535 .It Fn dwarf_pubtypename , Fn dwarf_typename
536 Retrieve the name of a type.
537 .It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets
538 Retrieve the name and offsets for a type.
541 .Bl -tag -compact -width indent
542 .It Fn dwarf_get_vars
543 Retrieve descriptors for static variables.
544 .It Fn dwarf_var_cu_offset
545 Return the offset for the compilation unit for a variable.
546 .It Fn dwarf_var_die_offset
547 Return the offset for the debugging information entry for a variable.
549 Retrieve the name of a variable.
550 .It Fn dwarf_var_name_offsets
551 Retrieve the name and offsets for a variable.
554 .Bl -tag -compact -width indent
555 .It Fn dwarf_get_weaks
556 Retrieve information about weak symbols.
557 .It Fn dwarf_weak_cu_offset
558 Return the offset for the compilation unit for a weak symbol.
559 .It Fn dwarf_weak_die_offset
560 Return the offset for the debugging information entry for a weak symbol.
561 .It Fn dwarf_weakname
562 Retrieve the name of a weak symbol.
563 .It Fn dwarf_weak_name_offsets
564 Retrieve the name and offsets for a weak symbol.
567 .Bl -tag -compact -width indent
569 Retrieve the ELF descriptor for a debug context, see
572 Retrieve a NUL-terminated string from the DWARF string section.
573 .It Fn dwarf_set_reloc_application
574 Control whether relocations are to be handled by
578 .Sh The DWARF Producer API
579 The DWARF producer API permits applications to add DWARF information to
582 The major functional groups of functions in the producer API are listed
584 .Bl -tag -width "CCCC"
585 .It Attribute Management
586 The following functions are used to attach attributes to a debugging
588 .Fn dwarf_add_AT_comp_dir ,
589 .Fn dwarf_add_AT_const_value_signedint ,
590 .Fn dwarf_add_AT_const_value_string ,
591 .Fn dwarf_add_AT_const_value_unsignedint ,
592 .Fn dwarf_add_AT_dataref ,
593 .Fn dwarf_add_AT_flag ,
594 .Fn dwarf_add_AT_location_expr ,
595 .Fn dwarf_add_AT_name ,
596 .Fn dwarf_add_AT_producer ,
597 .Fn dwarf_add_AT_ref_address ,
598 .Fn dwarf_add_AT_reference ,
599 .Fn dwarf_add_AT_signed_const ,
600 .Fn dwarf_add_AT_string ,
601 .Fn dwarf_add_AT_targ_address ,
602 .Fn dwarf_add_AT_targ_address_b
604 .Fn dwarf_add_AT_unsigned_const .
605 .It Debugging Information Entry Management
606 .Bl -tag -compact -width indent
607 .It Fn dwarf_add_die_to_debug
608 Set the root debugging information entry for a DWARF producer instance.
609 .It Fn dwarf_die_link
610 Links debugging information entries.
612 Allocate a new debugging information entry.
614 .It Initialization and Finalization
616 .Fn dwarf_producer_init
618 .Fn dwarf_producer_init_b
619 are used to initialize a producer instance.
621 When done, applications release resources using the function
622 .Fn dwarf_producer_finish .
623 .It Relocations and Sections
624 .Bl -tag -compact -width indent
625 .It Fn dwarf_get_relocation_info
626 Retrieve a relocation array from a producer instance.
627 .It Fn dwarf_get_relocation_info_count
628 Return the number of relocation arrays for a producer instance.
629 .It Fn dwarf_get_section_bytes
630 Retrieve the ELF byte stream for a section.
631 .It Fn dwarf_reset_section_bytes
632 Reset internal state for a producer instance.
633 .It Fn dwarf_transform_to_disk_form
634 Prepare byte streams for writing out.
637 .Bl -tag -compact -width indent
638 .It Fn dwarf_def_macro
639 Add a macro definition.
640 .It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file
641 Record macro file related information.
642 .It Fn dwarf_undef_macro
643 Note the removal of a macro definition.
644 .It Fn dwarf_vendor_ext
645 Enables storing macro information as specified in the DWARF standard.
647 .It Symbols, Expressions, Addresses and Offsets
648 .Bl -tag -compact -width indent
649 .It Fn dwarf_add_arange , Fn dwarf_add_arange_b
650 Add address range information.
651 .It Fn dwarf_add_directory_decl
652 Add information about an include directory to a producer instance.
653 .It Fn dwarf_add_fde_inst
654 Add an operation to a frame descriptor entry.
655 .It Fn dwarf_add_file_decl
656 Add information about a source file to a producer instance.
657 .It Fn dwarf_add_frame_cie
658 Add call information to a frame descriptor.
659 .It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b
660 Link a frame descriptor to a producer instance.
661 .It Fn dwarf_add_funcname
662 Add information about a function to a producer instance.
663 .It Fn dwarf_add_line_entry
664 Record mapping information between machine addresses and a source line.
665 .It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b
668 opcode to a location expression.
669 .It Fn dwarf_add_expr_gen
670 Add an operator to a location expression.
671 .It Fn dwarf_add_pubname
672 Add information about a global name to a producer instance.
673 .It Fn dwarf_add_typename
674 Add information about a type to a producer instance.
675 .It Fn dwarf_add_varname
676 Add information about a static variable to a producer instance.
677 .It Fn dwarf_add_weakname
678 Add information about a weak symbol to a producer instance.
679 .It Fn dwarf_expr_current_offset
680 Retrieve the current size of a location expression.
681 .It Fn dwarf_expr_into_block
682 Convert a location expression into a byte stream.
683 .It Fn dwarf_fde_cfa_offset
686 operation to a frame descriptor.
687 .It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address
688 Note address ranges for source lines.
689 .It Fn dwarf_new_expr
690 Allocate a location expression descriptor.
692 Allocate a frame descriptor.
696 .Fn dwarf_producer_set_isa
697 sets the instruction set architecture for the producer instance.
700 This implementation is believed to be source compatible with the
701 SGI/GNU DWARF(3) library, version 20110113.
703 Known differences with the SGI/GNU library include:
706 The memory management scheme used differs, in a backward-compatible
709 .Sx Memory Management
710 above, for coding guidelines for portable applications.
712 There is provision for setting a library-wide error handler in
713 addition to the per-debug context handlers supported by the SGI/GNU
714 API, see the subsection
719 The following APIs are extensions specific to this implementation:
724 .Fn dwarf_next_types_section
726 .Fn dwarf_producer_set_isa
731 The DWARF standard is defined by
733 .%T "The DWARF Debugging Information Format"
735 .%O "http://www.dwarfstd.org/"
738 The DWARF(3) API originated at Silicon Graphics Inc.
740 A BSD-licensed implementation of a subset of the API was written by
741 .An John Birrell Aq Mt jb@FreeBSD.org
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 .