---
name: "dwarf_expand_frame_instructions"
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_expand_frame_instructions"
---

# dwarf\_expand\_frame\_instructions(3)

expand frame instructions

## NAME

**dwarf\_expand\_frame\_instructions** – expand frame instructions

## LIBRARY

library “libdwarf”

## SYNOPSIS

**#include \<libdwarf.h\>**

*int*\

**dwarf\_expand\_frame\_instructions**(*Dwarf\_Cie cie*, *Dwarf\_Ptr instructions*, *Dwarf\_Unsigned len*, *Dwarf\_Frame\_Op \*\*ret\_ops*, *Dwarf\_Signed \*ret\_opcnt*, *Dwarf\_Error \*error*);

## DESCRIPTION

Function **dwarf\_expand\_frame\_instructions**() translates DWARF frame instruction bytes into an array of *Dwarf\_Frame\_Op* descriptors.

Argument *cie* should reference the CIE descriptor associated with the instructions to be translated.

Arugment *instructions* should point to an array of frame instruction bytes, as returned by the functions [dwarf\_get\_cie\_info(3)](/dwarf_get_cie_info/3.md) or [dwarf\_get\_fde\_instr\_bytes(3)](/dwarf_get_fde_instr_bytes/3.md).

Argument *len* should specify the number of the frame instruction bytes to be translated.

Argument *ret\_ops* should point to a location that will be set to a pointer to an array of translated *Dwarf\_Frame\_Op* descriptors.

Argument *ret\_opcnt* should point to a location that will hold the total number of the returned descriptors.

If argument *err* is not NULL, it will be used to store error information in case of an error.

### Memory Management

The memory area used for the descriptor array returned in argument *ret\_ops* is allocated by library “libdwarf”. Application code should use function [dwarf\_dealloc(3)](/dwarf_dealloc/3.md) with type DW\_DLA\_FRAME\_BLOCK to free the memory area when the descriptor array is no longer needed.

## RETURN VALUES

Function **dwarf\_expand\_frame\_instructions**() returns DW\_DLV\_OK when it succeeds. In case of an error, it returns DW\_DLV\_ERROR and sets the argument *err*.

## EXAMPLES

To retrieve and expand the frame instructions for a given FDE descriptor, use:

```
Dwarf_Dbg dbg;
Dwarf_Cie cie;
Dwarf_Fde fde;
Dwarf_Ptr fde_inst;
Dwarf_Unsigned fde_instlen;
Dwarf_Frame_Op *ops;
Dwarf_Signed opcnt;
Dwarf_Error de;
/* ... assuming `dbg` references a valid DWARF debugging context,
  `fde` references a valid FDE descriptor and `cie` holds the CIE
  descriptor associated with the FDE descriptor ... */
if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen,
    &de) != DW_DLV_OK)
	errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s",
	    dwarf_errmsg(de));
if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen,
    &ops, &opcnt, &de) != DW_DLV_OK)
	errx(EXIT_FAILURE,
	    "dwarf_expand_frame_instructions failed: %s",
	    dwarf_errmsg(de));
for (i = 0; i < opcnt; i++) {
	/* ... use ops[i] ... */
}
/* Free the memory area when no longer needed. */
dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK);
```

## ERRORS

Function **dwarf\_expand\_frame\_instructions**() can fail with:

- \[DW\_DLE\_ARGUMENT\]

  One of the arguments *cie*, *instructions*, *ret\_ops* or *ret\_opcnt* was NULL.

- \[DW\_DLE\_ARGUMENT\]

  Argument *len* was 0.

- \[DW\_DLE\_MEMORY\]

  An out of memory condition was encountered during the execution of this function.

- \[DW\_DLE\_FRAME\_INSTR\_EXEC\_ERROR\]

  An unknown instruction was found in the instruction bytes provided in argument *instructions*.

## SEE ALSO

[dwarf(3)](/dwarf/3.md), dwarf\_frame\_instructions\_dealloc(3), [dwarf\_get\_cie\_index(3)](/dwarf_get_cie_index/3.md), [dwarf\_get\_cie\_info(3)](/dwarf_get_cie_info/3.md), [dwarf\_get\_cie\_of\_fde(3)](/dwarf_get_cie_of_fde/3.md), [dwarf\_get\_fde\_at\_pc(3)](/dwarf_get_fde_at_pc/3.md), [dwarf\_get\_fde\_info\_for\_all\_regs(3)](/dwarf_get_fde_info_for_all_regs/3.md), [dwarf\_get\_fde\_info\_for\_all\_regs3(3)](/dwarf_get_fde_info_for_all_regs3/3.md), [dwarf\_get\_fde\_info\_for\_cfa\_reg3(3)](/dwarf_get_fde_info_for_cfa_reg3/3.md), [dwarf\_get\_fde\_info\_for\_reg(3)](/dwarf_get_fde_info_for_reg/3.md), [dwarf\_get\_fde\_info\_for\_reg3(3)](/dwarf_get_fde_info_for_reg3/3.md), [dwarf\_get\_fde\_instr\_bytes(3)](/dwarf_get_fde_instr_bytes/3.md), [dwarf\_get\_fde\_list(3)](/dwarf_get_fde_list/3.md), [dwarf\_get\_fde\_list\_eh(3)](/dwarf_get_fde_list_eh/3.md), [dwarf\_get\_fde\_n(3)](/dwarf_get_fde_n/3.md)