FreeBSD manual

download PDF document: dwarf_offdie_b.3.pdf

DWARF_CHILD(3) FreeBSD Library Functions Manual DWARF_CHILD(3) NAME dwarf_child, dwarf_offdie, dwarf_offdie_b, dwarf_siblingof, dwarf_siblingof_b - retrieve DWARF Debugging Information Entry descriptors LIBRARY DWARF Access Library (libdwarf, -ldwarf) SYNOPSIS #include <libdwarf.h> int dwarf_child(Dwarf_Die die, Dwarf_Die *ret_die, Dwarf_Error *err); int dwarf_offdie(Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Die *ret_die, Dwarf_Error *err); int dwarf_offdie_b(Dwarf_Debug dbg, Dwarf_Off offset, Dwarf_Bool is_info, Dwarf_Die *ret_die, Dwarf_Error *err); int dwarf_siblingof(Dwarf_Debug dbg, Dwarf_Die die, Dwarf_Die *ret_die, Dwarf_Error *err); int dwarf_siblingof_b(Dwarf_Debug dbg, Dwarf_Die die, Dwarf_Die *ret_die, Dwarf_Bool is_info, Dwarf_Error *err); DESCRIPTION These functions are used to retrieve and traverse DWARF Debugging Information Entry (DIE) descriptors associated with a compilation unit. These descriptors are arranged in the form of a tree, traversable using "child" and "sibling" links; see dwarf(3) for more information. DWARF Debugging Information Entry descriptors are represented by the Dwarf_Die opaque type. Function dwarf_child() retrieves the child of descriptor denoted by argument die, and stores it in the location pointed to by argument ret_die. Function dwarf_siblingof() retrieves the sibling of the descriptor denoted by argument die, and stores it in the location pointed to by argument ret_die. If argument die is NULL, the first debugging information entry descriptor for the current compilation unit will be returned. This function and function dwarf_child() may be used together to traverse the tree of debugging information entry descriptors for a compilation unit. Function dwarf_siblingof_b() is identical to the function dwarf_siblingof() except that it can retrieve the sibling descriptor from either the current compilation unit or type unit. If argument is_info is non-zero, the function behaves identically to function dwarf_siblingof(). If argument is_info is zero, the descriptor referred by argument die should be associated with a debugging information entry in the type unit. The function will store the sibling of the descriptor in the location to the location pointed to by argument ret_die. Function dwarf_offdie_b() is identical to the function dwarf_offdie() except that it can retrieve the debugging information entry descriptor at global offset offset from either of the ".debug_info" and ".debug_types" sections of the object associated with argument dbg. If argument is_info is non-zero, the function will retrieve the debugging information entry from the ".debug_info" section, otherwise the function will retrieve the debugging information entry from the ".debug_types" section. The returned descriptor is written to the location pointed to by argument ret_die. Memory Management The memory area used for the Dwarf_Die descriptor returned in argument ret_die is allocated by the DWARF Access Library (libdwarf, -ldwarf). Application code should use function dwarf_dealloc() with the allocation type DW_DLA_DIE to free the memory area when the Dwarf_Die descriptor is no longer needed. RETURN VALUES These functions return the following values: [DW_DLV_OK] The call succeeded. [DW_DLV_ERROR] The requested operation failed. Additional information about the error encountered will be recorded in argument err, if it is not NULL. [DW_DLV_NO_ENTRY] For functions dwarf_child(), dwarf_siblingof() and dwarf_siblingof_b(), the descriptor denoted by argument die did not have a child or sibling. For functions dwarf_offdie() and dwarf_offdie_b(), there was no debugging information entry at the offset specified by argument offset. EXAMPLES To retrieve the first DWARF Debugging Information Entry descriptor for the first compilation unit associated with a Dwarf_Debug instance, and to traverse all its children, use: Dwarf_Debug dbg; Dwarf_Die die, die0; Dwarf_Error de; ... allocate dbg using dwarf_init() etc ... if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) != DW_DLV_OK) errx(EXIT_FAILURE, "dwarf_next_cu_header: %s", dwarf_errmsg(de)); /* Get the first DIE for the current compilation unit. */ die = NULL; if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK) errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de)); /* Get the first child of this DIE. */ die = die0; errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de)); } while (die0 != NULL); ERRORS These functions may fail with the following errors: [DW_DLE_ARGUMENT] Arguments dbg, die or ret_die were NULL. [DW_DLE_DIE_NO_CU_CONTEXT] Argument dbg was not associated with a compilation unit. [DW_DLE_NO_ENTRY] The descriptor denoted by argument die had no child or sibling, or there was no DWARF debugging information entry at the offset specified by argument offset. SEE ALSO dwarf(3), dwarf_errmsg(3), dwarf_get_die_infotypes_flag(3), dwarf_next_cu_header(3) FreeBSD 14.0-RELEASE-p6 December 21, 2014 FreeBSD 14.0-RELEASE-p6