I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


DWARF_CHILD(3)             Library Functions Manual             DWARF_CHILD(3)

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.

   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() 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)

NetBSD 7.1.2                   November 9, 2011                   NetBSD 7.1.2