---
name: "dwarf_object_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_object_init"
---

# dwarf\_object\_init(3)

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

## NAME

**dwarf\_object\_init** – allocate a DWARF debug descriptor with application-specific file access methods

## LIBRARY

library “libdwarf”

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

## 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 during the execution of the function.

## SEE ALSO

[dwarf(3)](/dwarf/3.md), [dwarf\_init(3)](/dwarf_init/3.md), dwarf\_init\_elf(3), [dwarf\_object\_finish(3)](/dwarf_object_finish/3.md)