DWARF_CHILD(3)

DWARF_CHILD(3) | 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 pointed to by argument ret_die. If argument is_info is zero and argument die is `NULL`, the first debugging information entry descriptor for the current type unit will be returned.

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.

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.

# 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_get_die_infotypes_flag.3, dwarf_next_cu_header(3)

December 21, 2014 | NetBSD 9.5