dwarf_finish(3) [freebsd man page]

DWARF_FINISH(3) 					   BSD Library Functions Manual 					   DWARF_FINISH(3)

NAME

     dwarf_finish, dwarf_object_finish -- free resources associated with a debug descriptor

LIBRARY

     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS

     #include <libdwarf.h>

     int
     dwarf_finish(Dwarf_Debug dbg, Dwarf_Error *err);

     int
     dwarf_object_finish(Dwarf_Debug dbg, Dwarf_Error *err);

DESCRIPTION

     The dwarf_finish() and dwarf_object_finish() functions are used to release the resources associated with a debug descriptor allocated by a
     prior call to dwarf_init(3) and dwarf_object_init(3) respectively.

     Argument dbg denotes a valid Dwarf_Debug instance.  Argument err will be used to record error information in case of an error.

     After a call to dwarf_finish() or dwarf_object_finish(), the argument dbg will be invalid and should not be used further.

     For Dwarf_Debug descriptors opened using dwarf_init(3), the application would need to explicitly release the Elf instance associated with the
     descriptor by first retrieving the instance using dwarf_get_elf(3) and closing it using elf_end(3).

RETURN VALUES

     These functions return DW_DLV_OK if successful.  In case of an error, the functions return DW_DLV_ERROR and record additional information in
     argument err.

EXAMPLES

     To deallocate a Dwarf_Debug instance allocated using dwarf_elf_init(3) use:

	   Dwarf_Debug dbg;
	   Dwarf_Error de;

	   if (dwarf_finish(dbg, &de) != DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_finish: %s", dwarf_errmsg(de));

     To deallocate a Dwarf_Debug instance allocated using dwarf_object_init(3) use:

	   Dwarf_Debug dbg;
	   Dwarf_Error de;

	   if (dwarf_object_finish(dbg, &de) != DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_object_finish: %s",
		       dwarf_errmsg(de));

     To deallocate a Dwarf_Debug instance allocated using dwarf_init(3) use:

	   Dwarf_Debug dbg;
	   Dward_Error de;
	   Elf *e;

	   if (dwarf_get_elf(dbg, &e, &de) != DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_get_elf: %s", dwarf_errmsg(&de));

	   if (dwarf_finish(dbg, &de) != DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_finish: %s", dwarf_errmsg(de));

	   (void) elf_end(e);

SEE ALSO

     elf_end(3), dwarf_elf_init(3), dwarf_get_elf(3), dwarf_init(3), dwarf_object_init(3)

BSD
								 November 9, 2011							       BSD

DWARF_CHILD(3)						   BSD 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 argu-
     ment 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 compila-
     tion 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 descrip-
     tor 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)

BSD
								 December 21, 2014							       BSD