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 3295 2016-01-08 22:08:10Z jkoshy $
25.\"
26.Dd December 21, 2014
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
38The
39.Lb libdwarf
40provides functions that allow an application to read and write debugging
41information in object files.
42The format of debugging information accessible through this API
43is defined by the DWARF standard, see
44.Xr dwarf 4 .
45.Pp
46The
47.Xr DWARF 3
48API has two parts:
49.Bl -bullet
50.It
51A consumer API set allows applications to read existing debug information
52in a program object.
53The functions that comprise the DWARF consumer API are described in
54the section
55.Sx "DWARF Consumer API"
56below.
57.It
58A producer API set that allows applications to add debug information
59to a program object.
60The functions that comprise the DWARF producer API are described in
61the section
62.Sx "DWARF Producer API"
63below.
64.El
65.Pp
66Each function referenced below is further described in its own manual page.
67.Ss Namespace use
68The DWARF library uses the following prefixes:
69.Pp
70.Bl -tag -width ".Li Dwarf_*" -compact
71.It Li DWARF_*
72Used for error numbers and constants.
73.It Li DW_*
74Used for constants.
75.It Li Dwarf_*
76Used for types.
77.It Li dwarf_*
78Used for functions and macros that make up the API.
79.El
80.Ss Data Types
81The DWARF(3) API uses the following data types:
82.Pp
83.Bl -tag -width ".Vt Dwarf_Unsigned" -compact
84.It Vt Dwarf_Abbrev
85Describes DWARF abbreviations.
86.It Vt Dwarf_Addr
87A program address in the target object.
88.It Vt Dwarf_Arange
89Describes address ranges.
90.It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute
91Describes attributes of debugging information entries.
92.It Vt Dwarf_Bool
93Used for boolean states.
94.It Vt Dwarf_Cie , Vt Dwarf_P_Cie
95Describes call information that is common to several frames.
96.It Vt Dwarf_Debug , Vt Dwarf_P_Debug
97An opaque type describing a debug context.
98.It Vt Dwarf_Die , Vt Dwarf_P_Die
99A debugging information entry.
100.It Vt Dwarf_Fde , Vt Dwarf_P_Fde
101A frame descriptor.
102.It Vt Dwarf_Func
103A descriptor representing a function.
104.It Vt Dwarf_Global
105A descriptor representing a global name.
106.It Vt Dwarf_Half
107A 16-bit wide unsigned numeric type.
108.It Vt Dwarf_Handler
109A pointer to an error handling function.
110.It Vt Dwarf_Line
111A descriptor for a source line.
112.It Vt Dwarf_Off
113An unsigned file offset.
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 .
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 3295 2016-01-08 22:08:10Z jkoshy $
25.\"
26.Dd December 21, 2014
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
38The
39.Lb libdwarf
40provides functions that allow an application to read and write debugging
41information in object files.
42The format of debugging information accessible through this API
43is defined by the DWARF standard, see
44.Xr dwarf 4 .
45.Pp
46The
47.Xr DWARF 3
48API has two parts:
49.Bl -bullet
50.It
51A consumer API set allows applications to read existing debug information
52in a program object.
53The functions that comprise the DWARF consumer API are described in
54the section
55.Sx "DWARF Consumer API"
56below.
57.It
58A producer API set that allows applications to add debug information
59to a program object.
60The functions that comprise the DWARF producer API are described in
61the section
62.Sx "DWARF Producer API"
63below.
64.El
65.Pp
66Each function referenced below is further described in its own manual page.
67.Ss Namespace use
68The DWARF library uses the following prefixes:
69.Pp
70.Bl -tag -width ".Li Dwarf_*" -compact
71.It Li DWARF_*
72Used for error numbers and constants.
73.It Li DW_*
74Used for constants.
75.It Li Dwarf_*
76Used for types.
77.It Li dwarf_*
78Used for functions and macros that make up the API.
79.El
80.Ss Data Types
81The DWARF(3) API uses the following data types:
82.Pp
83.Bl -tag -width ".Vt Dwarf_Unsigned" -compact
84.It Vt Dwarf_Abbrev
85Describes DWARF abbreviations.
86.It Vt Dwarf_Addr
87A program address in the target object.
88.It Vt Dwarf_Arange
89Describes address ranges.
90.It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute
91Describes attributes of debugging information entries.
92.It Vt Dwarf_Bool
93Used for boolean states.
94.It Vt Dwarf_Cie , Vt Dwarf_P_Cie
95Describes call information that is common to several frames.
96.It Vt Dwarf_Debug , Vt Dwarf_P_Debug
97An opaque type describing a debug context.
98.It Vt Dwarf_Die , Vt Dwarf_P_Die
99A debugging information entry.
100.It Vt Dwarf_Fde , Vt Dwarf_P_Fde
101A frame descriptor.
102.It Vt Dwarf_Func
103A descriptor representing a function.
104.It Vt Dwarf_Global
105A descriptor representing a global name.
106.It Vt Dwarf_Half
107A 16-bit wide unsigned numeric type.
108.It Vt Dwarf_Handler
109A pointer to an error handling function.
110.It Vt Dwarf_Line
111A descriptor for a source line.
112.It Vt Dwarf_Off
113An unsigned file offset.
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 .