Updated: 2021/Apr/14

DWARF_OBJECT_INIT(3)       Library Functions Manual       DWARF_OBJECT_INIT(3)

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

     DWARF Access Library (libdwarf, -ldwarf)

     #include <libdwarf.h>

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

     The dwarf_object_init() function allocates and returns a Dwarf_Debug
     instance that uses application-supplied access methods to read file

     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

     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

             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
                          access object methods.
             methods      This structure contains pointers to the functions
                          implementing the access methods, as described below.

             This structure specifies the functions implementing low-level

                   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 constants DW_OBJECT_MSB or
             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 address.
             get_section_count      This function should return the number of
                                    sections 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
                                    described below.
             load_section           This function should load the section
                                    specified by argument ndx into memory and
                                    place a pointer to the section's data into
                                    the location pointed to by argument

             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

             This structure describes the layout of a section in the DWARF

                   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.

     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.

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

     [DW_DLE_ARGUMENT]              One of the arguments iface or dbg was

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

     [DW_DLE_MEMORY]                An out of memory condition was encountered
                                    during the execution of the function.

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

NetBSD 9.99                   September 29, 2011                   NetBSD 9.99