Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DWARF_OBJECT_INIT(3)	 BSD Library Functions Manual	  DWARF_OBJECT_INIT(3)

NAME
     dwarf_object_init -- allocate a DWARF debug descriptor with application-
     specific file access methods

LIBRARY
     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS
     #include <libdwarf.h>

     int
     dwarf_object_init(Dwarf_Obj_Access_Interface *iface,
	 Dwarf_Handler errhand,	Dwarf_Ptr errarg, Dwarf_Debug *dbg,
	 Dwarf_Error *err);

DESCRIPTION
     The dwarf_object_init() function allocates	and returns a Dwarf_Debug in-
     stance that uses application-supplied access methods to read file con-
     tent.

     The argument iface	should point to	a populated Dwarf_Obj_Access_Interface
     structure.	 The contents of the Dwarf_Obj_Access_Interface	structure are
     described in the section Object Access Functions below.

     The argument errhand should point to 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 schemes
     available.

     The argument errarg will be passed	to the error handler function pointed
     to	by argument errhand.

     The argument dbg should point to a	memory location	that will be set to a
     reference to the returned Dwarf_Debug descriptor.

     The argument err will be used to return a Dwarf_Error descriptor in case
     of	an error.

   Object Access Functions
     The data structures used to specify object	access methods are defined in
     <libdwarf.h>.

     Dwarf_Obj_Access_Interface
	     This structure bundles together a set of file access methods
	     along with	a pointer to application-private state.

		   typedef struct {
			   void	*object;
			   const Dwarf_Obj_Access_Methods *methods;
		   } Dwarf_Obj_Access_Interface;

	     object   This field points	to application-specific	state that
		      will be passed as	the first parameter to the actual ac-
		      cess object methods.
	     methods  This structure contains pointers to the functions	imple-
		      menting the access methods, as described below.

     Dwarf_Obj_Access_Methods
	     This structure specifies the functions implementing low-level ac-
	     cess.

		   typedef struct {
			   int (*get_section_info)(void	*obj, Dwarf_Half index,
			       Dwarf_Obj_Access_Section	*ret, int *error);
			   Dwarf_Endianness (*get_byte_order)(void *obj);
			   Dwarf_Small (*get_length_size)(void *obj);
			   Dwarf_Small (*get_pointer_size)(void	*obj);
			   Dwarf_Unsigned (*get_section_count)(void *obj);
			   int (*load_section)(void *obj, Dwarf_Half ndx,
			       Dwarf_Small **ret_data, int *error);
		   } Dwarf_Obj_Access_Methods;

	     get_byte_order	This function should return the	endianness of
				the DWARF object by returning one of the con-
				stants DW_OBJECT_MSB or	DW_OBJECT_LSB.
	     get_length_size	This function should return the	number of
				bytes needed to	represent a DWARF offset in
				the object being debugged.
	     get_pointer_size	This function should return the	size in	bytes,
				in the object being debugged, of a memory ad-
				dress.
	     get_section_count	This function should return the	number of sec-
				tions in the object being debugged.
	     get_section_info	This function should return information	about
				the section at the index ndx by	filling	in the
				structure of type Dwarf_Obj_Access_Section
				pointed	to by argument ret.  The
				Dwarf_Obj_Access_Section structure is de-
				scribed	below.
	     load_section	This function should load the section speci-
				fied by	argument ndx into memory and place a
				pointer	to the section's data into the loca-
				tion pointed to	by argument ret_data.

	     The argument obj passed to	these functions	will be	set to the
	     pointer value in the object field of the associated
	     Dwarf_Obj_Access_Interface	structure.

	     The argument error	is used	to return an error code	in case	of an
	     error.

     Dwarf_Obj_Access_Section
	     This structure describes the layout of a section in the DWARF ob-
	     ject.

		   typedef struct {
			   Dwarf_Addr addr;
			   Dwarf_Unsigned size;
			   const char *name;
		   } Dwarf_Obj_Access_Section;

	     addr  A pointer to	the start of the section's data.
	     size  The size of the section in bytes.
	     name  A pointer to	a NUL-terminated string	containing the name of
		   the section.

RETURN VALUES
     On	success, the dwarf_object_init() function returns DW_DLV_OK.  In case
     of	an error, the function returns DW_DLV_ERROR and	sets the argument err.

ERRORS
     The dwarf_object_init() function may fail with the	following errors:

     [DW_DLE_ARGUMENT]	       One of the arguments iface or dbg was NULL.

     [DW_DLE_DEBUG_INFO_NULL]  The underlying object did not contain debugging
			       information.

     [DW_DLE_MEMORY]	       An out of memory	condition was encountered dur-
			       ing the execution of the	function.

SEE ALSO
     dwarf(3), dwarf_init(3), dwarf_init_elf(3), dwarf_object_finish(3)

BSD			      September	29, 2011			   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dwarf_object_init&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help