Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
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.
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);
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)
NetBSD 10.99 December 21, 2014 NetBSD 10.99