| blob | d8e6cea45c9cb840b6b8c34b65398f302961280f |
1 .\" $NetBSD: dwarf.3,v 1.2 2014/03/09 16:58:03 christos Exp $
2 .\"
3 .\" Copyright (c) 2011 Joseph Koshy. All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\"
14 .\" This software is provided by Joseph Koshy ``as is'' and
15 .\" any express or implied warranties, including, but not limited to, the
16 .\" implied warranties of merchantability and fitness for a particular purpose
17 .\" are disclaimed. in no event shall Joseph Koshy be liable
18 .\" for any direct, indirect, incidental, special, exemplary, or consequential
19 .\" damages (including, but not limited to, procurement of substitute goods
20 .\" or services; loss of use, data, or profits; or business interruption)
21 .\" however caused and on any theory of liability, whether in contract, strict
22 .\" liability, or tort (including negligence or otherwise) arising in any way
23 .\" out of the use of this software, even if advised of the possibility of
24 .\" such damage.
25 .\"
26 .\" Id: dwarf.3 2075 2011-10-27 03:47:28Z jkoshy
27 .\"
28 .Dd September 17, 2011
29 .Os
30 .Dt DWARF 3
31 .Sh NAME
32 .Nm dwarf
33 .Nd access debugging information in object files
34 .Sh LIBRARY
35 .Lb libdwarf
36 .Sh SYNOPSIS
37 .In libdwarf.h
38 .Sh DESCRIPTION
39 .Pp
40 The
41 .Lb libdwarf
42 provides functions that allow an application to read and write debugging
43 information in object files.
44 The format of debugging information accessible through this API
45 is defined by the DWARF standard, see
46 .Xr dwarf 4 .
47 .Pp
48 The
49 .Xr DWARF 3
50 API has two parts:
51 .Bl -bullet
52 .It
53 A consumer API set allows applications to read existing debug information
54 in a program object.
55 The functions that comprise the DWARF consumer API are described in
56 the section
57 .Sx "DWARF Consumer API"
58 below.
59 .It
60 A producer API set that allows applications to add debug information
61 to a program object.
62 The functions that comprise the DWARF producer API are described in
63 the section
64 .Sx "DWARF Producer API"
65 below.
66 .El
67 .Pp
68 Each function referenced below is further described in its own manual page.
69 .Ss Namespace use
70 The DWARF library uses the following prefixes:
71 .Pp
72 .Bl -tag -width ".Li Dwarf_*" -compact
73 .It Li DWARF_*
74 Used for error numbers and constants.
75 .It Li DW_*
76 Used for constants.
77 .It Li Dwarf_*
78 Used for types.
79 .It Li dwarf_*
80 Used for functions and macros that make up the API.
81 .El
82 .Ss Data Types
83 The DWARF(3) API uses the following data types:
84 .Pp
85 .Bl -tag -width ".Vt Dwarf_Unsigned" -compact
86 .It Vt Dwarf_Abbrev
87 Describes DWARF abbreviations.
88 .It Vt Dwarf_Addr
89 A program address in the target object.
90 .It Vt Dwarf_Arange
91 Describes address ranges.
92 .It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute
93 Describes attributes of debugging information entries.
94 .It Vt Dwarf_Bool
95 Used for boolean states.
96 .It Vt Dwarf_Cie , Vt Dwarf_P_Cie
97 Describes call information that is common to several frames.
98 .It Vt Dwarf_Debug , Vt Dwarf_P_Debug
99 An opaque type describing a debug context.
100 .It Vt Dwarf_Die , Vt Dwarf_P_Die
101 A debugging information entry.
102 .It Vt Dwarf_Fde , Vt Dwarf_P_Fde
103 A frame descriptor.
104 .It Vt Dwarf_Func
105 A descriptor representing a function.
106 .It Vt Dwarf_Global
107 A descriptor representing a global name.
108 .It Vt Dwarf_Half
109 A 16-bit wide unsigned numeric type.
110 .It Vt Dwarf_Handler
111 A pointer to an error handling function.
112 .It Vt Dwarf_Line
113 A descriptor for a source line.
114 .It Vt Dwarf_Off
115 An unsigned file offset, corresponding to an
116 .Vt off_t
117 type supported by the underlying operating system.
118 .It Vt Dwarf_P_Expr
119 A descriptor for a location expression.
120 .It Vt Dwarf_Ptr
121 A virtual address used by an application.
122 .It Vt Dwarf_Signed
123 A 64-bit wide signed numeric type.
124 .It Vt Dwarf_Small
125 An 8-bit wide unsigned numeric type.
126 .It Vt Dwarf_Type
127 A descriptor representing a user-specified type.
128 .It Vt Dwarf_Unsigned
129 A 64-bit wide unsigned numeric type.
130 .It Vt Dwarf_Var
131 A descriptor representing a static variable.
132 .It Vt Dwarf_Weak
133 A descriptor representing a weak name.
134 .El
135 .Ss Error Handling
136 .Pp
137 Library functions that encounter an error will return with a value
138 other than
139 .Dv DW_DLV_OK .
140 .Pp
141 The
142 .Lb libdwarf
143 allows applications to specify three levels of error handling:
144 .Bl -enum -compact
145 .It
146 Most library functions take a parameter of type
147 .Vt Dwarf_Error
148 that specifies a location to store an error descriptor in
149 case of an error.
150 If an error occurs during the execution on an API, and if this
151 parameter is non-NULL, then an error descriptor is written to the
152 location specified.
153 .It
154 Otherwise, if the error parameter was NULL, but if an error handler
155 was defined for the debug context in use using
156 .Xr dwarf_init 3
157 or
158 .Xr dwarf_seterrhand 3 ,
159 then the library will invoke the specified error handler with an error
160 descriptor as argument.
161 .It
162 Otherwise, if a library wide error handler was specified using
163 .Xr dwarf_seterrhand 3 ,
164 it is called.
165 .El
166 .Pp
167 Error descriptors may be used with
168 .Xr dwarf_errmsg 3
169 or
170 .Xr dwarf_errno 3 .
171 .Sh The DWARF Consumer API
172 The DWARF consumer API permits applications to read DWARF information in
173 an object file.
174 .Pp
175 The major functional groups of functions in the consumer API are listed
176 below.
177 .Pp
178 .Bl -tag -compact -width "CCCC"
179 .It Abbreviations
180 .Bl -tag -compact
181 .It Fn dwarf_get_abbrev
182 Retrieve abbreviation information at a given offset.
183 .It Fn dwarf_get_abbrev_children_flag
184 Check if an abbreviation has child elements.
185 .It Fn dwarf_get_abbrev_code
186 Retrieve the abbreviation code for an abbreviation entry descriptor.
187 .It Fn dwarf_get_abbrev_entry
188 Retrieve abbreviation information for an abbreviation entry
189 descriptor.
190 .It Fn dwarf_get_abbrev_tag
191 Retrieve the tag for an abbreviation entry.
192 .El
193 .It Addresses
194 .Bl -tag -compact
195 .It Fn dwarf_get_address_size
196 Return the number of bytes needed to represent an address.
197 .It Fn dwarf_get_arange
198 Search for an address range descriptor covering an address.
199 .It Fn dwarf_get_arange_cu_header_offset
200 Retrieve the offsets associated with an address range descriptor.
201 .It Fn dwarf_get_arange_info
202 Extract address range information from a descriptor.
203 .It Fn dwarf_get_aranges
204 Retrieve program address space mappings.
205 .It Fn dwarf_get_cu_die_offset
206 Retrieve the offset associated with a compilation unit for an address
207 range descriptor.
208 .It Fn dwarf_get_ranges , Fn dwarf_get_ranges_a
209 Retrieve information about non-contiguous address ranges for
210 a debugging information entry.
211 .El
212 .It Attributes
213 .Bl -tag -compact
214 .It Fn dwarf_arrayorder
215 Retrieve the value of a
216 .Dv DW_AT_ordering
217 attribute.
218 .It Fn dwarf_attr
219 Retrieve an attribute descriptor.
220 .It Fn dwarf_attrlist
221 Retrieve attribute descriptors for a debugging information entry.
222 .It Fn dwarf_attrval_flag
223 Retrieve a
224 .Dv DW_AT_FORM_flag
225 value.
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
234 .Dv DW_AT_bit_offset
235 attribute.
236 .It Fn dwarf_bitsize ,
237 Retrieve the value of a
238 .Dv DW_AT_bit_size
239 attribute.
240 .It Fn dwarf_bytesize
241 Retrieve the value of a
242 .Dv DW_AT_byte_size
243 attribute.
244 .It Fn dwarf_formaddr
245 Return the value of an
246 .Dv ADDRESS Ns - Ns
247 class attribute.
248 .It Fn dwarf_formblock
249 Return the value of a
250 .Dv BLOCK Ns - Ns
251 class attribute
252 .It Fn dwarf_formexprloc
253 Return information about a location expression.
254 .It Fn dwarf_formflag
255 Retrieve information about a
256 .Dv BOOLEAN Ns - Ns
257 class attribute.
258 .It Fn dwarf_formref , Fn dwarf_global_formref
259 Retrieve offsets for
260 .Dv REFERENCE Ns - Ns
261 class attributes.
262 .It Fn dwarf_formsdata , Fn dwarf_formudata
263 Retrieve the value of a
264 .Dv CONSTANT Ns - Ns
265 class attribute.
266 .It Fn dwarf_formsig8
267 Return the type signature for a DWARF type.
268 .It Fn dwarf_formstring
269 Retrieve information about a
270 .Dv STRING Ns - Ns
271 class attribute.
272 .It Fn dwarf_get_form_class
273 Retrieve the form class for an attribute.
274 .It Fn dwarf_hasattr
275 Check for the presence of an attribute.
276 .It Fn dwarf_hasform
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.
282 .El
283 .It Call Information Entries and Frame Descriptor Entries
284 .Bl -tag -compact
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.
311 .El
312 .It Compilation Units
313 .Bl -tag -compact
314 .It Fn dwarf_get_cu_die_offset_given_cu_header_offset
315 Retrieve the offset of the debugging information entry for a
316 compilation unit.
317 .It Fn dwarf_next_cu_header , Fn dwarf_next_cu_header_b
318 Step through compilation units in a debug context.
319 .El
320 .It Debugging Information Entries
321 .Bl -tag -compact
322 .It Fn dwarf_child
323 Returns the child of a debugging information entry.
324 .It Fn dwarf_die_abbrev_code
325 Returns the abbreviation code for a debugging information entry.
326 .It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range
327 Retrieve offsets and lengths for a compilation unit.
328 .It Fn dwarf_diename
329 Returns the
330 .Dv DW_AT_name
331 attribute for a debugging information entry.
332 .It Fn dwarf_dieoffset
333 Retrieves the offset for a debugging information entry.
334 .It Fn dwarf_highpc
335 Return the highest PC value for a debugging information entry.
336 .It Fn dwarf_lowpc
337 Return the lowest PC value for a debugging information entry.
338 .It Fn dwarf_offdie
339 Retrieve a debugging information entry given an offset.
340 .It Fn dwarf_siblingof
341 Retrieve the sibling descriptor for a debugging information entry.
342 .It Fn dwarf_srclang
343 Retrive the source language attribute for a debugging information
344 entry.
345 .It Fn dwarf_tag
346 Retrieve the tag for a debugging information entry.
347 .El
348 .It Functions
349 .Bl -tag -compact
350 .It Fn dwarf_func_cu_offset
351 Retrieves the offset for the compilation unit for a function.
352 .It Fn dwarf_func_die_offset
353 Retrieves the offset for the debugging information entry for a
354 function.
355 .It Fn dwarf_funcname
356 Retrieves the name of a function.
357 .It Fn dwarf_func_name_offsets
358 Retrieve both the name and offsets for a function.
359 .It Fn dwarf_get_funcs
360 Retrieve information about static functions.
361 .El
362 .It Globals
363 .Bl -tag -compact
364 .It Fn dwarf_get_globals
365 Retrieve a list of globals.
366 .It Fn dwarf_global_cu_offset
367 Return the offset for compilation unit for a global.
368 .It Fn dwarf_global_die_offset
369 Return the offset for the debugging information entry for a global.
370 .It Fn dwarf_global_name_offsets
371 Return the name and offsets for a global.
372 .It Fn dwarf_globname
373 Return the name for a global.
374 .El
375 .It Initialization and Finalization
376 Functions
377 .Fn dwarf_elf_init
378 and
379 .Fn dwarf_init
380 may be used for initialization.
381 The function
382 .Fn dwarf_finish
383 may be used to release resources.
384 .Pp
385 The functions
386 .Fn dwarf_object_init
387 and
388 .Fn dwarf_object_finish
389 allow an application to specify alternate low-level file access
390 routines.
391 .It Line Numbers
392 .Bl -tag -compact
393 .It Fn dwarf_lineaddr
394 Retrieve the program address for a source line.
395 .It Fn dwarf_linebeginstatement
396 Check if a source line corresponds to the beginning of a statement.
397 .It Fn dwarf_lineblock
398 Check if a source line corresponds to the start of a basic block.
399 .It Fn dwarf_lineendsequence
400 Check if the source line corresponds to the end of a sequence of
401 instructions.
402 .It Fn dwarf_lineno
403 Retrieve the line number for a line descriptor.
404 .It Fn dwarf_lineoff
405 Retrieve the column number for a line descriptor.
406 .It Fn dwarf_linesrc
407 Retrieve the source file for a line descriptor.
408 .It Fn dwarf_line_srcfileno
409 Retrieve the index of the source file for a line descriptor.
410 .It Fn dwarf_srcfiles
411 Retrieve source files for a compilation unit.
412 .It Fn dwarf_srclines
413 Return line number information for a compilation unit.
414 .El
415 .It Location Lists
416 .Bl -tag -compact
417 .It Fn dwarf_get_loclist_entry
418 Retrieve a location list entry.
419 .It Fn dwarf_loclist , Fn dwarf_loclist_n
420 Retrieve location expressions.
421 .It Fn dwarf_loclist_from_expr , Fn dwarf_loclist_from_expr_a
422 Translate a location expression into a location descriptor.
423 .El
424 .It Error Handling
425 .Bl -tag -compact
426 .It Fn dwarf_errmsg
427 Retrieve a human-readable error message.
428 .It Fn dwarf_errno
429 Retrieve an error number from an error descriptor.
430 .It Fn dwarf_seterrarg
431 Set the argument passed to a callback error handler.
432 .It Fn dwarf_seterrhand
433 Set the callback handler to be called in case of an error.
434 .El
435 .It Frame Handling
436 .Bl -tag -compact
437 .It Fn dwarf_expand_frame_instructions
438 Translate frame instruction bytes.
439 .It Fn dwarf_set_frame_cfa_value
440 Set the CFA parameter for the internal register rule table.
441 .It Fn dwarf_set_frame_rule_initial_value
442 Set the initial value of the register rules in the internal register
443 rule table.
444 .It Fn dwarf_set_frame_rule_table_size
445 Set the maximum number of columns in the register rule table.
446 .It Fn dwarf_set_frame_same_value
447 Set the register number representing the
448 .Dq "same value"
449 rule.
450 .It Fn dwarf_set_frame_undefined_value
451 Set the register number representing the
452 .Dq "undefined"
453 rule.
454 .El
455 .It Macros
456 .Bl -tag -compact
457 .It Fn dwarf_find_macro_value_start
458 Return the macro value part of a macro string.
459 .It Fn dwarf_get_macro_details
460 Retrieve macro information.
461 .El
462 .It Memory Management
463 In the DWARF consumer API, the rules for memory management differ
464 between functions.
465 In some cases, the memory areas returned to the application by the
466 library are freed by calling specific API functions.
467 In others, the deallocation function
468 .Fn dwarf_dealloc
469 suffices.
470 The individual manual pages for the API's functions document the
471 specific memory management rules to be followed.
472 .Pp
473 The function
474 .Fn dwarf_dealloc
475 is used to mark memory arenas as unused.
476 Additionally, the following functions release specific types of
477 DWARF resources:
478 .Fn dwarf_fde_cie_list_dealloc ,
479 .Fn dwarf_funcs_dealloc ,
480 .Fn dwarf_globals_dealloc ,
481 .Fn dwarf_pubtypes_dealloc ,
482 .Fn dwarf_ranges_dealloc ,
483 .Fn dwarf_srclines_dealloc ,
484 .Fn dwarf_types_dealloc ,
485 .Fn dwarf_vars_dealloc ,
486 and
487 .Fn dwarf_weaks_dealloc .
488 .It Symbol Constants
489 The following functions may be used to return symbolic names
490 for DWARF constants:
491 .Fn dwarf_get_ACCESS_name ,
492 .Fn dwarf_get_AT_name ,
493 .Fn dwarf_get_ATE_name ,
494 .Fn dwarf_get_CC_name ,
495 .Fn dwarf_get_CFA_name ,
496 .Fn dwarf_get_CHILDREN_name ,
497 .Fn dwarf_get_DS_name ,
498 .Fn dwarf_get_DSC_name ,
499 .Fn dwarf_get_EH_name ,
500 .Fn dwarf_get_END_name ,
501 .Fn dwarf_get_FORM_name ,
502 .Fn dwarf_get_ID_name ,
503 .Fn dwarf_get_INL_name ,
504 .Fn dwarf_get_LANG_name ,
505 .Fn dwarf_get_LNE_name ,
506 .Fn dwarf_get_LNS_name ,
507 .Fn dwarf_get_MACINFO_name ,
508 .Fn dwarf_get_OP_name ,
509 .Fn dwarf_get_ORD_name ,
510 .Fn dwarf_get_TAG_name ,
511 .Fn dwarf_get_VIRTUALITY_name ,
512 and
513 .Fn dwarf_get_VIS_name .
514 .It Types
515 .Bl -tag -compact
516 .It Fn dwarf_get_pubtypes , Fn dwarf_get_types
517 Retrieve descriptors for user-defined types.
518 .It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset
519 Return the offset for the compilation unit for a type.
520 .It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset
521 Return the offset for the debugging information entry for a type.
522 .It Fn dwarf_pubtypename , Fn dwarf_typename
523 Retrieve the name of a type.
524 .It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets
525 Retrieve the name and offsets for a type.
526 .El
527 .It Variables
528 .Bl -tag -compact
529 .It Fn dwarf_get_vars
530 Retrieve descriptors for static variables.
531 .It Fn dwarf_var_cu_offset
532 Return the offset for the compilation unit for a variable.
533 .It Fn dwarf_var_die_offset
534 Return the offset for the debugging information entry for a variable.
535 .It Fn dwarf_varname
536 Retrieve the name of a variable.
537 .It Fn dwarf_var_name_offsets
538 Retrieve the name and offsets for a variable.
539 .El
540 .It Weak Symbols
541 .Bl -tag -compact
542 .It Fn dwarf_get_weaks
543 Retrieve information about weak symbols.
544 .It Fn dwarf_weak_cu_offset
545 Return the offset for the compilation unit for a weak symbol.
546 .It Fn dwarf_weak_die_offset
547 Return the offset for the debugging information entry for a weak symbol.
548 .It Fn dwarf_weakname
549 Retrieve the name of a weak symbol.
550 .It Fn dwarf_weak_name_offsets
551 Retrieve the name and offsets for a weak symbol.
552 .El
553 .It Miscellaneous
554 .Bl -tag -compact
555 .It Fn dwarf_get_elf
556 Retrieve the ELF descriptor for a debug context, see
557 .Xr elf 3 .
558 .It Fn dwarf_get_str
559 Retrieve a NUL-terminated string from the DWARF string section.
560 .It Fn dwarf_set_reloc_application
561 Control whether relocations are to be handled by
562 .Lb libdwarf .
563 .El
564 .El
565 .Sh The DWARF Producer API
566 The DWARF producer API permits applications to add DWARF information to
567 an object file.
568 .Pp
569 The major functional groups of functions in the producer API are listed
570 below.
571 .Bl -tag -width "CCCC"
572 .It Attribute Management
573 The following functions are used to attach attributes to a debugging
574 information entry:
575 .Fn dwarf_add_AT_comp_dir ,
576 .Fn dwarf_add_AT_const_value_signedint ,
577 .Fn dwarf_add_AT_const_value_string ,
578 .Fn dwarf_add_AT_const_value_unsignedint ,
579 .Fn dwarf_add_AT_dataref ,
580 .Fn dwarf_add_AT_flag ,
581 .Fn dwarf_add_AT_location_expr ,
582 .Fn dwarf_add_AT_name ,
583 .Fn dwarf_add_AT_producer ,
584 .Fn dwarf_add_AT_ref_address ,
585 .Fn dwarf_add_AT_reference ,
586 .Fn dwarf_add_AT_signed_const ,
587 .Fn dwarf_add_AT_string ,
588 .Fn dwarf_add_AT_targ_address ,
589 .Fn dwarf_add_AT_targ_address_b
590 and
591 .Fn dwarf_add_AT_unsigned_const .
592 .It Debugging Information Entry Management
593 .Bl -tag -compact
594 .It Fn dwarf_add_die_to_debug
595 Set the root debugging information entry for a DWARF producer instance.
596 .It Fn dwarf_die_link
597 Links debugging information entries.
598 .It Fn dwarf_new_die
599 Allocate a new debugging information entry.
600 .El
601 .It Initialization and Finalization
602 The functions
603 .Fn dwarf_producer_init
604 and
605 .Fn dwarf_producer_init_b
606 are used to initialize a producer instance.
607 .Pp
608 When done, applications release resources using the function
609 .Fn dwarf_producer_finish .
610 .It Relocations and Sections
611 .Bl -tag -compact
612 .It Fn dwarf_get_relocation_info
613 Retrieve a relocation array from a producer instance.
614 .It Fn dwarf_get_relocation_info_count
615 Return the number of relocation arrays for a producer instance.
616 .It Fn dwarf_get_section_bytes
617 Retrieve the ELF byte stream for a section.
618 .It Fn dwarf_reset_section_bytes
619 Reset internal state for a producer instance.
620 .It Fn dwarf_transform_to_disk_form
621 Prepare byte streams for writing out.
622 .El
623 .It Macros
624 .Bl -tag -compact
625 .It Fn dwarf_def_macro
626 Add a macro definition.
627 .It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file
628 Record macro file related information.
629 .It Fn dwarf_undef_macro
630 Note the removal of a macro definition.
631 .It Fn dwarf_vendor_ext
632 Enables storing macro information as specified in the DWARF standard.
633 .El
634 .It Symbols, Expressions, Addresses and Offsets
635 .Bl -tag -compact
636 .It Fn dwarf_add_arange , Fn dwarf_add_arange_b
637 Add address range information.
638 .It Fn dwarf_add_directory_decl
639 Add information about an include directory to a producer instance.
640 .It Fn dwarf_add_fde_inst
641 Add an operation to a frame descriptor entry.
642 .It Fn dwarf_add_file_decl
643 Add information about a source file to a producer instance.
644 .It Fn dwarf_add_frame_cie
645 Add call information to a frame descriptor.
646 .It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b
647 Link a frame descriptor to a producer instance.
648 .It Fn dwarf_add_funcname
649 Add information about a function to a producer instance.
650 .It Fn dwarf_add_line_entry
651 Record mapping information between machine addresses and a source line.
652 .It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b
653 Add a
654 .Dv DW_OP_addr
655 opcode to a location expression.
656 .It Fn dwarf_add_expr_gen
657 Add an operator to a location expression.
658 .It Fn dwarf_add_pubname
659 Add information about a global name to a producer instance.
660 .It Fn dwarf_add_typename
661 Add information about a type to a producer instance.
662 .It Fn dwarf_add_varname
663 Add information about a static variable to a producer instance.
664 .It Fn dwarf_add_weakname
665 Add information about a weak symbol to a producer instance.
666 .It Fn dwarf_expr_current_offset
667 Retrieve the current size of a location expression.
668 .It Fn dwarf_expr_into_block
669 Convert a location expression into a byte stream.
670 .It Fn dwarf_fde_cfa_offset
671 Append a
672 .Dv DW_CFA_offset
673 operation to a frame descriptor.
674 .It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address
675 Note address ranges for source lines.
676 .It Fn dwarf_new_expr
677 Allocate a location expression descriptor.
678 .It Fn dwarf_new_fde
679 Allocate a frame descriptor.
680 .El
681 .It Miscellaneous
682 The function
683 .Fn dwarf_producer_set_isa
684 sets the instruction set architecture for the producer instance.
685 .El
686 .Sh COMPATIBILITY
687 This implementation is believed to be source compatible with the
688 SGI/GNU DWARF(3) library, version 20110113.
689 .Pp
690 Known differences with the SGI/GNU library include:
691 .Bl -bullet -compact
692 .It
693 The memory management scheme used differs, in a backward-compatible
694 way.
695 See
696 .Sx Memory Management
697 above, for coding guidelines for portable applications.
698 .It
699 There is provision for setting a library-wide error handler in
700 addition to the per-debug context handlers supported by the SGI/GNU
701 API, see the subsection
702 .Sx Error Handling
703 above.
704 .It
705 The following API is an extension:
706 .Fn dwarf_producer_set_isa .
707 .El
708 .Sh SEE ALSO
709 .Xr elf 3
710 .Sh STANDARDS
711 The DWARF standard is defined by
712 .Rs
713 .%T "The DWARF Debugging Information Format"
714 .%V "Version 4"
715 .%O "http://www.dwarfstd.org/"
716 .Re
717 .Sh HISTORY
718 The DWARF(3) API originated at Silicon Graphics Inc.
719 .Pp
720 A BSD-licensed implementation of a subset of the API was written by
721 .An "John Birrell" Aq jb@FreeBSD.org
722 for the FreeBSD project.
723 The implementation was subsequently revised and completed by
724 .An "Kai Wang" Aq kaiwang27@users.sourceforge.net .
725 .Pp
726 Manual pages for this implementation were written by
727 .An "Joseph Koshy" Aq jkoshy@users.sourceforge.net
728 and
729 .An "Kai Wang" Aq kaiwang27@users.sourceforge.net .