dwarf_object_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_INIT(3)						   BSD Library Functions Manual 					     DWARF_INIT(3)

NAME

     dwarf_init, dwarf_elf_init -- allocate a DWARF debug descriptor

LIBRARY

     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS

     #include <libdwarf.h>

     int
     dwarf_init(int fd, int mode, Dwarf_Handler errhand, Dwarf_Ptr errarg, Dwarf_Debug *ret, Dwarf_Error *err);

     in
     dwarf_elf_init(Elf *elf, int mode, Dwarf_Handler errhand, Dwarf_Ptr errarg, Dwarf_Debug *ret, Dwarf_Error *err);

DESCRIPTION

     These functions allocate and return a Dwarf_Debug instance for the object denoted by argument fd or elf.  This instance would be used for
     subsequent access to debugging information in the object by other functions in the DWARF(3) library.

     For function dwarf_init(), argument fd denotes an open file descriptor referencing a compilation object.  Function dwarf_init() implicitly
     allocates an Elf descriptor for argument fd.

     For function dwarf_elf_init(), argument elf denotes a descriptor returned by elf_begin(3) or elf_memory(3).

     Argument mode specifies the access mode desired.  It should be at least as permissive as the mode with which the file descriptor fd or the
     ELF descriptor elf was created with.  Legal values for argument mode are:

     DW_DLC_RDWR   Permit reading and writing of DWARF information.
     DW_DLC_READ   Operate in read-only mode.
     DW_DLC_WRITE  Permit writing of DWARF information.

     Argument errhand denotes a function to be called in case of an error.  If this argument is NULL then a default error handling scheme is used.
     See dwarf(3) for a description of the error handling scheme used by the DWARF(3) library.

     Argument errarg is passed to the error handler function denoted by argument errhand when it is invoked.

     Argument ret points to the memory location that will hold a Dwarf_Debug reference on a successful call these functions.

     Argument err references a memory location that would hold a Dwarf_Error descriptor in case of an error.

   Memory Management
     The Dwarf_Debug instance returned by these functions should be freed using dwarf_finish().

RETURN VALUES

     These functions return the following values:

     [DW_DLV_OK]	This return value indicates a successful return.

     [DW_DLV_ERROR]	The operation failed.

     [DW_DLV_NO_ENTRY]	The object specified by arguments fd or elf did not contain debug information.

IMPLEMENTATION NOTES

     The current implementation does not support access modes DW_DLC_RDWR and DW_DLC_WRITE.

EXAMPLES

     To initialize a Dwarf_Debug instance from a open file descriptor referencing an ELF object, and with the default error handler, use:

	   Dwarf_Error err;
	   Dwarf_Debug dbg;

	   if (dwarf_init(fd, DW_DLC_READ, NULL, NULL, &dbg, &err) !=
	       DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_init: %s", dwarf_errmsg(err));

SEE ALSO

     dwarf(3), dwarf_errmsg(3), dwarf_finish(3), dwarf_get_elf(3), elf_begin(3), elf_memory(3)

BSD
								 November 9, 2011							       BSD