---
name: "dwarf_elf_init"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/dwarf_elf_init"
---

# dwarf\_elf\_init(3)

allocate a DWARF debug descriptor

## NAME

**dwarf\_init**, **dwarf\_elf\_init** – allocate a DWARF debug descriptor

## LIBRARY

library “libdwarf”

## 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)](/elf_begin/3.md) or [elf\_memory(3)](/elf_memory/3.md).

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)](/dwarf/3.md) 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**().

## IMPLEMENTATION NOTES

The current implementation does not support access modes DW\_DLC\_RDWR and DW\_DLC\_WRITE.

## 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.

## 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/3.md), [dwarf\_errmsg(3)](/dwarf_errmsg/3.md), [dwarf\_finish(3)](/dwarf_finish/3.md), [dwarf\_get\_elf(3)](/dwarf_get_elf/3.md), [elf\_begin(3)](/elf_begin/3.md), [elf\_memory(3)](/elf_memory/3.md)