NAME

dwarf_child, dwarf_siblingof, dwarf_offdie — 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_siblingof(Dwarf_Debug dbg, 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);

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_offdie() retrieves the debugging information entry descriptor at global offset offset in the “.debug_info” section of the object associated with argument dbg. The returned descriptor is written to the location pointed to by argument ret_die.

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() and dwarf_siblingof(), the descriptor denoted by argument die did not have a child or sibling. For function dwarf_offdie(), there was no debugging information entry at the offset specified by argument offset.

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.

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; 
if (dwarf_child(die, &die0, &de) != DW_DLV_OK) 
	errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de)); 
 
/* Get the rest of children. */ 
do { 
	die = die0; 
	if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR) 
		errx(EXIT_FAILURE, "dwarf_siblingof: %s", 
		    dwarf_errmsg(de)); 
} while (die0 != NULL);

SEE ALSO

dwarf(3), dwarf_errmsg(3), dwarf_next_cu_header(3)