dwarf_init,
dwarf_elf_init —
allocate a DWARF debug descriptor
DWARF Access Library (libdwarf, -ldwarf)
#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);
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.
The
Dwarf_Debug instance returned by these
functions should be freed using
dwarf_finish().
The current implementation does not support access modes
DW_DLC_RDWR
and
DW_DLC_WRITE
.
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.
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));
dwarf(3),
dwarf_errmsg(3),
dwarf_finish(3),
dwarf_get_elf(3),
elf_begin(3),
elf_memory(3)