dwarf_object_init —
allocate a DWARF debug descriptor with
application-specific file access methods
DWARF Access Library (libdwarf, -ldwarf)
#include
<libdwarf.h>
int
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 content.
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.
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 access object
methods.
- methods
- This structure contains pointers to the functions
implementing the access methods, as described below.
-
-
- Dwarf_Obj_Access_Methods
- This structure specifies the functions implementing
low-level access.
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
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 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
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 object.
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 NULL.
-
-
- [
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)