libdwarf: Stack Frame Access

libdwarf

Loading...
Searching...
No Matches
Typedefs | Functions
Stack Frame Access

## Typedefs
typedef int(* | dwarf_iterate_fde_callback_function_type) (Dwarf_Regtable3 *dw_reg_table, Dwarf_Addr dw_row_pc, Dwarf_Bool dw_has_more_rows, Dwarf_Addr dw_subsequent_pc, void *dw_user_data)

## Functions
DW_API int | dwarf_get_fde_list (Dwarf_Debug dw_dbg, Dwarf_Cie **dw_cie_data, Dwarf_Signed *dw_cie_element_count, Dwarf_Fde **dw_fde_data, Dwarf_Signed *dw_fde_element_count, Dwarf_Error *dw_error)
| Get lists of .debug_frame FDEs and CIEs.
DW_API int | dwarf_get_fde_list_eh (Dwarf_Debug dw_dbg, Dwarf_Cie **dw_cie_data, Dwarf_Signed *dw_cie_element_count, Dwarf_Fde **dw_fde_data, Dwarf_Signed *dw_fde_element_count, Dwarf_Error *dw_error)
| Get lists of .eh_frame FDEs and CIEs.
DW_API void | dwarf_dealloc_fde_cie_list (Dwarf_Debug dw_dbg, Dwarf_Cie *dw_cie_data, Dwarf_Signed dw_cie_element_count, Dwarf_Fde *dw_fde_data, Dwarf_Signed dw_fde_element_count)
| Release storage associated with FDE and CIE arrays.
DW_API int | dwarf_get_fde_range (Dwarf_Fde dw_fde, Dwarf_Addr *dw_low_pc, Dwarf_Unsigned *dw_func_length, Dwarf_Small **dw_fde_bytes, Dwarf_Unsigned *dw_fde_byte_length, Dwarf_Off *dw_cie_offset, Dwarf_Signed *dw_cie_index, Dwarf_Off *dw_fde_offset, Dwarf_Error *dw_error)
| Return the FDE data for a single FDE.
DW_API int | dwarf_get_fde_exception_info (Dwarf_Fde dw_fde, Dwarf_Signed *dw_offset_into_exception_tables, Dwarf_Error *dw_error)
| IRIX only access to C++ destructor tables.
DW_API int | dwarf_get_cie_of_fde (Dwarf_Fde dw_fde, Dwarf_Cie *dw_cie_returned, Dwarf_Error *dw_error)
| Given FDE get CIE.
DW_API int | dwarf_get_cie_info_b (Dwarf_Cie dw_cie, Dwarf_Unsigned *dw_bytes_in_cie, Dwarf_Small *dw_version, char **dw_augmenter, Dwarf_Unsigned *dw_code_alignment_factor, Dwarf_Signed *dw_data_alignment_factor, Dwarf_Half *dw_return_address_register_rule, Dwarf_Small **dw_initial_instructions, Dwarf_Unsigned *dw_initial_instructions_length, Dwarf_Half *dw_offset_size, Dwarf_Error *dw_error)
| Given a CIE get access to its content.
DW_API int | dwarf_get_cie_index (Dwarf_Cie dw_cie, Dwarf_Signed *dw_index, Dwarf_Error *dw_error)
| Return CIE index given CIE.
DW_API int | dwarf_get_fde_instr_bytes (Dwarf_Fde dw_fde, Dwarf_Small **dw_outinstrs, Dwarf_Unsigned *dw_outlen, Dwarf_Error *dw_error)
| Return length and pointer to access frame instructions.
DW_API int | dwarf_iterate_fde_all_regs3 (Dwarf_Fde dw_fde, Dwarf_Regtable3 *dw_reg_table, dwarf_iterate_fde_callback_function_type dw_callback, void *dw_callback_user_data, Dwarf_Error *dw_error)
| Iterate all rows for a given FDE. Iinvokes a provided callback function for each row. Iteration continues until all rows have been visited.
DW_API int | dwarf_get_fde_info_for_all_regs3_b (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Regtable3 *dw_reg_table, Dwarf_Addr *dw_row_pc, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
| Return information on frame registers at a given pc value.
DW_API int | dwarf_get_fde_info_for_all_regs3 (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Regtable3 *dw_reg_table, Dwarf_Addr *dw_row_pc, Dwarf_Error *dw_error)
| Return information on frame registers at a given pc value.
DW_API int | dwarf_get_fde_info_for_reg3_c (Dwarf_Fde dw_fde, Dwarf_Half dw_table_column, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Signed *dw_offset, Dwarf_Block *dw_block_content, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
| Return details about a particular pc and register.
DW_API int | dwarf_get_fde_info_for_reg3_b (Dwarf_Fde dw_fde, Dwarf_Half dw_table_column, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Unsigned *dw_offset, Dwarf_Block *dw_block_content, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
| Return details about a particular pc and register.
DW_API int | dwarf_get_fde_info_for_cfa_reg3_c (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Signed *dw_offset, Dwarf_Block *dw_block, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
| Get the value of the CFA for a particular pc value.
DW_API int | dwarf_get_fde_info_for_cfa_reg3_b (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Unsigned *dw_offset, Dwarf_Block *dw_block, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
| Get the value of the CFA for a particular pc value.
DW_API int | dwarf_get_fde_for_die (Dwarf_Debug dw_dbg, Dwarf_Die dw_subr_die, Dwarf_Fde *dw_returned_fde, Dwarf_Error *dw_error)
| Get the fde given DW_AT_MIPS_fde in a DIE.
DW_API int | dwarf_get_fde_n (Dwarf_Fde *dw_fde_data, Dwarf_Unsigned dw_fde_index, Dwarf_Fde *dw_returned_fde, Dwarf_Error *dw_error)
| Retrieve an FDE from an FDE table.
DW_API int | dwarf_get_fde_at_pc (Dwarf_Fde *dw_fde_data, Dwarf_Addr dw_pc_of_interest, Dwarf_Fde *dw_returned_fde, Dwarf_Addr *dw_lopc, Dwarf_Addr *dw_hipc, Dwarf_Error *dw_error)
| Retrieve an FDE given a pc.
DW_API int | dwarf_get_cie_augmentation_data (Dwarf_Cie dw_cie, Dwarf_Small **dw_augdata, Dwarf_Unsigned *dw_augdata_len, Dwarf_Error *dw_error)
| Return .eh_frame CIE augmentation data.
DW_API int | dwarf_get_fde_augmentation_data (Dwarf_Fde dw_fde, Dwarf_Small **dw_augdata, Dwarf_Unsigned *dw_augdata_len, Dwarf_Error *dw_error)
| Return .eh_frame FDE augmentation data.
DW_API int | dwarf_expand_frame_instructions (Dwarf_Cie dw_cie, Dwarf_Small *dw_instructionspointer, Dwarf_Unsigned dw_length_in_bytes, Dwarf_Frame_Instr_Head *dw_head, Dwarf_Unsigned *dw_instr_count, Dwarf_Error *dw_error)
| Expands CIE or FDE instructions for detailed examination. Called for CIE initial instructions and FDE instructions. Call dwarf_get_fde_instr_bytes() or dwarf_get_cie_info_b() to get the initial instruction bytes and instructions byte count you wish to expand.
DW_API int | dwarf_get_frame_instruction (Dwarf_Frame_Instr_Head dw_head, Dwarf_Unsigned dw_instr_index, Dwarf_Unsigned *dw_instr_offset_in_instrs, Dwarf_Small *dw_cfa_operation, const char **dw_fields_description, Dwarf_Unsigned *dw_u0, Dwarf_Unsigned *dw_u1, Dwarf_Signed *dw_s0, Dwarf_Signed *dw_s1, Dwarf_Unsigned *dw_code_alignment_factor, Dwarf_Signed *dw_data_alignment_factor, Dwarf_Block *dw_expression_block, Dwarf_Error *dw_error)
| Return information about a single instruction Fields_description means a sequence of up to three letters including u,s,r,c,d,b, terminated by NUL byte. It is a string but we test individual bytes instead of using string compares. Do not free any of the returned values.
DW_API int | dwarf_get_frame_instruction_a (Dwarf_Frame_Instr_Head dw_, Dwarf_Unsigned dw_instr_index, Dwarf_Unsigned *dw_instr_offset_in_instrs, Dwarf_Small *dw_cfa_operation, const char **dw_fields_description, Dwarf_Unsigned *dw_u0, Dwarf_Unsigned *dw_u1, Dwarf_Unsigned *dw_u2, Dwarf_Signed *dw_s0, Dwarf_Signed *dw_s1, Dwarf_Unsigned *dw_code_alignment_factor, Dwarf_Signed *dw_data_alignment_factor, Dwarf_Block *dw_expression_block, Dwarf_Error *dw_error)
| Expands CIE or FDE instructions for detailed examination. Called for CIE initial instructions and FDE instructions. This is the same as dwarf_get_frame_instruction() except that it adds a dw_u2 field which contains an address-space identifier if the letter `a` appears in dw_fields_description. The dw_u2 field is non-standard and only applies to Heterogeneous Debugging frame instructions defined by LLVM (DW_CFA_LLVM_def_aspace_cfa and DW_CFA_LLVM_def_aspace_cfa_sf).
DW_API void | dwarf_dealloc_frame_instr_head (Dwarf_Frame_Instr_Head dw_head)
| Deallocates the frame instruction data in dw_head.
DW_API int | dwarf_fde_section_offset (Dwarf_Debug dw_dbg, Dwarf_Fde dw_in_fde, Dwarf_Off *dw_fde_off, Dwarf_Off *dw_cie_off, Dwarf_Error *dw_error)
| Return FDE and CIE offsets from debugging info.
DW_API int | dwarf_cie_section_offset (Dwarf_Debug dw_dbg, Dwarf_Cie dw_in_cie, Dwarf_Off *dw_cie_off, Dwarf_Error *dw_error)
| Use to print CIE offsets from debugging info.
DW_API Dwarf_Half | dwarf_set_frame_rule_table_size (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
| Frame Rule Table Size Invariants for setting frame registers .
DW_API Dwarf_Half | dwarf_set_frame_rule_initial_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
| Frame Rule Initial Value.
DW_API Dwarf_Half | dwarf_set_frame_cfa_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
| Frame CFA Column Invariants for setting frame registers .
DW_API Dwarf_Half | dwarf_set_frame_same_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
| Frame Same Value Default Invariants for setting frame registers .
DW_API Dwarf_Half | dwarf_set_frame_undefined_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
| Frame Undefined Value Default Invariants for setting frame registers .

## Detailed Description

Use to access DWARF2-5 .debug_frame and GNU .eh_frame sections. Does not evaluate frame instructions, but provides detailed data so it is possible do that yourself.

## Typedef Documentation

## ◆ dwarf_iterate_fde_callback_function_type

typedef int(* dwarf_iterate_fde_callback_function_type) (Dwarf_Regtable3 *dw_reg_table, Dwarf_Addr dw_row_pc, Dwarf_Bool dw_has_more_rows, Dwarf_Addr dw_subsequent_pc, void *dw_user_data)

Used as a function pointer to a user-written callback function. This provides the register table for a row address. See dwarf_iterate_fde_all_regs3().

Parameters

  dw_reg_table | The register table for address data.
  dw_row_pc | The address for the row the callback is reportinf.
  dw_has_more_rows | If non-zero means there are more rows in the current FDE.
  dw_subsequent_pc | The pc address of the next row in the current FDE.
  dw_user_data | Passes your callback a pointer to space you allocated

Returns
  Return DW_DLV_OK if the data is valid. If a serious error of some kind return DW_DLV_ERROR.

## Function Documentation

## ◆ dwarf_cie_section_offset()

DW_API int dwarf_cie_section_offset | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Cie | dw_in_cie,
|  | Dwarf_Off * | dw_cie_off,
|  | Dwarf_Error * | dw_error )

Use to print CIE offsets from debugging info.

Parameters

  dw_dbg | The Dwarf_Debug of interest
  dw_in_cie | Pass in the CIE of interest.
  dw_cie_off | On success returns the section offset of the CIE.
  dw_error | Error return details

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_dealloc_fde_cie_list()

DW_API void dwarf_dealloc_fde_cie_list | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Cie * | dw_cie_data,
|  | Dwarf_Signed | dw_cie_element_count,
|  | Dwarf_Fde * | dw_fde_data,
|  | Dwarf_Signed | dw_fde_element_count )

Release storage associated with FDE and CIE arrays.

Applies to .eh_frame and .debug_frame lists.

Parameters

  dw_dbg | The Dwarf_Debug used in the list setup.
  dw_cie_data | As returned from the list setup call.
  dw_cie_element_count |
  dw_fde_data | As returned from the list setup call.
  dw_fde_element_count | As returned from the list setup call.

On return the pointers passed in dw_cie_data and dw_fde_data should be zeroed by the caller as they are then stale pointers.

## ◆ dwarf_dealloc_frame_instr_head()

DW_API void dwarf_dealloc_frame_instr_head | ( | Dwarf_Frame_Instr_Head | dw_head | ) |

Deallocates the frame instruction data in dw_head.

Parameters

  dw_head | A head pointer. Frees all data created by dwarf_expand_frame_instructions() and makes the head pointer stale. The caller should set to NULL.

## ◆ dwarf_expand_frame_instructions()

DW_API int dwarf_expand_frame_instructions | ( | Dwarf_Cie | dw_cie,
|  | Dwarf_Small * | dw_instructionspointer,
|  | Dwarf_Unsigned | dw_length_in_bytes,
|  | Dwarf_Frame_Instr_Head * | dw_head,
|  | Dwarf_Unsigned * | dw_instr_count,
|  | Dwarf_Error * | dw_error )

Expands CIE or FDE instructions for detailed examination. Called for CIE initial instructions and FDE instructions. Call dwarf_get_fde_instr_bytes() or dwarf_get_cie_info_b() to get the initial instruction bytes and instructions byte count you wish to expand.

Combined with dwarf_get_frame_instruction() or dwarf_get_frame_instruction_a() (the second is like the first but adds an argument for LLVM address space numbers) it enables detailed access to frame instruction fields for evaluation or printing.

Free allocated memory with dwarf_dealloc_frame_instr_head().

See also
  Using dwarf_expand_frame_instructions

Parameters

  dw_cie | The cie relevant to the instructions.
  dw_instructionspointer | points to the instructions
  dw_length_in_bytes | byte length of the instruction sequence.
  dw_head | The address of an allocated dw_head
  dw_instr_count | Returns the number of instructions in the byte stream
  dw_error | Error return details

Returns
  On success returns DW_DLV_OK

## ◆ dwarf_fde_section_offset()

DW_API int dwarf_fde_section_offset | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Fde | dw_in_fde,
|  | Dwarf_Off * | dw_fde_off,
|  | Dwarf_Off * | dw_cie_off,
|  | Dwarf_Error * | dw_error )

Return FDE and CIE offsets from debugging info.

Parameters

  dw_dbg | The Dwarf_Debug of interest
  dw_in_fde | Pass in the FDE of interest.
  dw_fde_off | On success returns the section offset of the FDE.
  dw_cie_off | On success returns the section offset of the CIE.
  dw_error | Error return details

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_cie_augmentation_data()

DW_API int dwarf_get_cie_augmentation_data | ( | Dwarf_Cie | dw_cie,
|  | Dwarf_Small ** | dw_augdata,
|  | Dwarf_Unsigned * | dw_augdata_len,
|  | Dwarf_Error * | dw_error )

Return .eh_frame CIE augmentation data.

GNU .eh_frame CIE augmentation information. See Linux Standard Base Core Specification version 3.0 .

See also
  https://gcc.gnu.org/legacy-ml/gcc/2003-12/msg01168.html

Parameters

  dw_cie | The CIE of interest.
  dw_augdata | On success returns a pointer to the augmentation data.
  dw_augdata_len | On success returns the length in bytes of the augmentation data.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc. If the augmentation data length is zero it returns DW_DLV_NO_ENTRY.

## ◆ dwarf_get_cie_index()

DW_API int dwarf_get_cie_index | ( | Dwarf_Cie | dw_cie,
|  | Dwarf_Signed * | dw_index,
|  | Dwarf_Error * | dw_error )

Return CIE index given CIE.

Parameters

  dw_cie | Pass in the CIE of interest.
  dw_index | On success, returns the index (the position of the CIE in the CIE pointer array).
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_cie_info_b()

DW_API int dwarf_get_cie_info_b | ( | Dwarf_Cie | dw_cie,
|  | Dwarf_Unsigned * | dw_bytes_in_cie,
|  | Dwarf_Small * | dw_version,
|  | char ** | dw_augmenter,
|  | Dwarf_Unsigned * | dw_code_alignment_factor,
|  | Dwarf_Signed * | dw_data_alignment_factor,
|  | Dwarf_Half * | dw_return_address_register_rule,
|  | Dwarf_Small ** | dw_initial_instructions,
|  | Dwarf_Unsigned * | dw_initial_instructions_length,
|  | Dwarf_Half * | dw_offset_size,
|  | Dwarf_Error * | dw_error )

Given a CIE get access to its content.

Parameters

  dw_cie | Pass in the CIE of interest.
  dw_bytes_in_cie | On success, returns the length of the CIE in bytes.
  dw_version | On success, returns the CIE version number.
  dw_augmenter | On success, returns a pointer to the augmentation string (which could be the empty string).
  dw_code_alignment_factor | On success, returns a the code_alignment_factor used to interpret CIE/FDE operations.
  dw_data_alignment_factor | On success, returns a the data_alignment_factor used to interpret CIE/FDE operations.
  dw_return_address_register_rule | On success, returns a register number of the return address register.
  dw_initial_instructions | On success, returns a pointer to the bytes of initial_instructions in the CIE.
  dw_initial_instructions_length | On success, returns the length in bytes of the initial_instructions.
  dw_offset_size | On success, returns the offset_size within this CIE.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_cie_of_fde()

DW_API int dwarf_get_cie_of_fde | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Cie * | dw_cie_returned,
|  | Dwarf_Error * | dw_error )

Given FDE get CIE.

Parameters

  dw_fde | The FDE of interest.
  dw_cie_returned | On success returns a pointer to the applicable CIE.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_fde_at_pc()

DW_API int dwarf_get_fde_at_pc | ( | Dwarf_Fde * | dw_fde_data,
|  | Dwarf_Addr | dw_pc_of_interest,
|  | Dwarf_Fde * | dw_returned_fde,
|  | Dwarf_Addr * | dw_lopc,
|  | Dwarf_Addr * | dw_hipc,
|  | Dwarf_Error * | dw_error )

Retrieve an FDE given a pc.

Using binary search this finds the FDE that contains this dw_pc_of_interest That works because libdwarf ensures the array of FDEs is sorted by the low-pc

See also
  dwarf_get_fde_list

Parameters

  dw_fde_data | Pass in a pointer an array of fde pointers.
  dw_pc_of_interest | The pc value of interest.
  dw_returned_fde | On success a pointer to the applicable FDE is set through the pointer.
  dw_lopc | On success a pointer to the low pc in dw_returned_fde is set through the pointer.
  dw_hipc | On success a pointer to the high pc (one past the actual last byte address) in dw_returned_fde is set through the pointer.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK if the dw_pc_of_interest found in some FDE in the array. If no FDE is found containing dw_pc_of_interest DW_DLV_NO_ENTRY is returned.

## ◆ dwarf_get_fde_augmentation_data()

DW_API int dwarf_get_fde_augmentation_data | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Small ** | dw_augdata,
|  | Dwarf_Unsigned * | dw_augdata_len,
|  | Dwarf_Error * | dw_error )

Return .eh_frame FDE augmentation data.

GNU .eh_frame FDE augmentation information. See Linux Standard Base Core Specification version 3.0 .

See also
  https://gcc.gnu.org/legacy-ml/gcc/2003-12/msg01168.html

Parameters

  dw_fde | The FDE of interest.
  dw_augdata | On success returns a pointer to the augmentation data.
  dw_augdata_len | On success returns the length in bytes of the augmentation data.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc. If the augmentation data length is zero it returns DW_DLV_NO_ENTRY.

## ◆ dwarf_get_fde_exception_info()

DW_API int dwarf_get_fde_exception_info | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Signed * | dw_offset_into_exception_tables,
|  | Dwarf_Error * | dw_error )

IRIX only access to C++ destructor tables.

This applies only to IRIX C++ destructor information which was never documented and is unlikely to be of interest.

## ◆ dwarf_get_fde_for_die()

DW_API int dwarf_get_fde_for_die | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Die | dw_subr_die,
|  | Dwarf_Fde * | dw_returned_fde,
|  | Dwarf_Error * | dw_error )

Get the fde given DW_AT_MIPS_fde in a DIE.

This is essentially useless as only SGI/MIPS compilers from the 1990's had DW_AT_MIPS_fde in DW_TAG_subprogram DIEs and this relies on that attribute to work.

## ◆ dwarf_get_fde_info_for_all_regs3()

DW_API int dwarf_get_fde_info_for_all_regs3 | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Addr | dw_pc_requested,
|  | Dwarf_Regtable3 * | dw_reg_table,
|  | Dwarf_Addr * | dw_row_pc,
|  | Dwarf_Error * | dw_error )

Return information on frame registers at a given pc value.

Identical to dwarf_get_fde_info_for_all_regs3_b() except that this doesn't output dw_has_more_rows and dw_subsequent_pc, so dwarf_get_fde_info_for_all_regs3_b() is a better choice.

If you need to iterate through all rows of the FDE, consider switching to dwarf_get_fde_info_for_all_regs3_b() or dwarf_iterate_fde_all_regs3().

## ◆ dwarf_get_fde_info_for_all_regs3_b()

DW_API int dwarf_get_fde_info_for_all_regs3_b | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Addr | dw_pc_requested,
|  | Dwarf_Regtable3 * | dw_reg_table,
|  | Dwarf_Addr * | dw_row_pc,
|  | Dwarf_Bool * | dw_has_more_rows,
|  | Dwarf_Addr * | dw_subsequent_pc,
|  | Dwarf_Error * | dw_error )

Return information on frame registers at a given pc value.

An FDE at a given pc (code address) This function is new in October 2023 version 0.9.0. See libdwarf.h for the required condition of dw_reg_table pointer passed in.

Parameters

  dw_fde | Pass in the FDE of interest.
  dw_pc_requested | Pass in a pc (code) address inside that FDE.
  dw_reg_table | Pass in the address of a Dwarf_Regtable3 struct which has been initialized with zero bits, and for which the dw_rt3_rules array has been allocated and the initialized with all zero bits. On success, returns a filled in dw_reg_table given the frame state.
  dw_row_pc | On success returns the address of the row of frame data which may be a few counts off of the pc requested.
  dw_has_more_rows | On success returns FALSE if there are no more rows, otherwise returns TRUE.
  dw_subsequent_pc | On success this returns the address of the next pc for which there is a register row, making access to all the rows in sequence much more efficient than just adding 1 to a pc value.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK if the dw_pc_requested is in the FDE passed in and there is some applicable row in the table.

## ◆ dwarf_get_fde_info_for_cfa_reg3_b()

DW_API int dwarf_get_fde_info_for_cfa_reg3_b | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Addr | dw_pc_requested,
|  | Dwarf_Small * | dw_value_type,
|  | Dwarf_Unsigned * | dw_offset_relevant,
|  | Dwarf_Unsigned * | dw_register,
|  | Dwarf_Unsigned * | dw_offset,
|  | Dwarf_Block * | dw_block,
|  | Dwarf_Addr * | dw_row_pc_out,
|  | Dwarf_Bool * | dw_has_more_rows,
|  | Dwarf_Addr * | dw_subsequent_pc,
|  | Dwarf_Error * | dw_error )

Get the value of the CFA for a particular pc value.

See also
  dwarf_get_fde_info_for_cfa_reg3_c

This is the earlier version that returns a dw_offset of type Dwarf_Unsigned, requiring you to cast to Dwarf_Signed to work with the value.

## ◆ dwarf_get_fde_info_for_cfa_reg3_c()

DW_API int dwarf_get_fde_info_for_cfa_reg3_c | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Addr | dw_pc_requested,
|  | Dwarf_Small * | dw_value_type,
|  | Dwarf_Unsigned * | dw_offset_relevant,
|  | Dwarf_Unsigned * | dw_register,
|  | Dwarf_Signed * | dw_offset,
|  | Dwarf_Block * | dw_block,
|  | Dwarf_Addr * | dw_row_pc_out,
|  | Dwarf_Bool * | dw_has_more_rows,
|  | Dwarf_Addr * | dw_subsequent_pc,
|  | Dwarf_Error * | dw_error )

Get the value of the CFA for a particular pc value.

See also
  dwarf_get_fde_info_for_reg3_c() has essentially the same return values as dwarf_get_fde_info_for_reg3_c but it refers to the CFA (which is not part of the register table) so this function has no table column argument.

New in September 2023, release 0.8.0. dwarf_get_fde_info_for_cfa_reg3_c() returns dw_offset as a signed type. dwarf_get_fde_info_for_cfa_reg3_b() returns dw_offset as an unsigned type, requiring the caller to cast to Dwarf_Signed before using the value. Both versions exist and operate properly.

If dw_value_type == DW_EXPR_EXPRESSION or DW_EXPR_VALUE_EXPRESSION dw_offset is not set and the caller must evaluate the expression, which usually depends on runtime frame data which cannot be calculated without a stack frame including register values (etc).

## ◆ dwarf_get_fde_info_for_reg3_b()

DW_API int dwarf_get_fde_info_for_reg3_b | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Half | dw_table_column,
|  | Dwarf_Addr | dw_pc_requested,
|  | Dwarf_Small * | dw_value_type,
|  | Dwarf_Unsigned * | dw_offset_relevant,
|  | Dwarf_Unsigned * | dw_register,
|  | Dwarf_Unsigned * | dw_offset,
|  | Dwarf_Block * | dw_block_content,
|  | Dwarf_Addr * | dw_row_pc_out,
|  | Dwarf_Bool * | dw_has_more_rows,
|  | Dwarf_Addr * | dw_subsequent_pc,
|  | Dwarf_Error * | dw_error )

Return details about a particular pc and register.

Identical to dwarf_get_fde_info_for_reg3_c() except that this returns dw_offset as a Dwarf_Unsigned, which was never appropriate, and required you to cast that value to Dwarf_Signed to use it properly..

Please switch to using dwarf_get_fde_info_for_reg3_c()

## ◆ dwarf_get_fde_info_for_reg3_c()

DW_API int dwarf_get_fde_info_for_reg3_c | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Half | dw_table_column,
|  | Dwarf_Addr | dw_pc_requested,
|  | Dwarf_Small * | dw_value_type,
|  | Dwarf_Unsigned * | dw_offset_relevant,
|  | Dwarf_Unsigned * | dw_register,
|  | Dwarf_Signed * | dw_offset,
|  | Dwarf_Block * | dw_block_content,
|  | Dwarf_Addr * | dw_row_pc_out,
|  | Dwarf_Bool * | dw_has_more_rows,
|  | Dwarf_Addr * | dw_subsequent_pc,
|  | Dwarf_Error * | dw_error )

Return details about a particular pc and register.

It is efficient to iterate across all table_columns (registers) using this function (dwarf_get_fde_info_for_reg3_c()).

Or if one wants the data for all frame rows one could instead call dwarf_iterate_fde_all_regs3() and index into the data it fills in and returns via a callback function you write.

If dw_value_type == DW_EXPR_EXPRESSION or DW_EXPR_VALUE_EXPRESSION dw_offset is not set and the caller must evaluate the expression, which usually depends on runtime frame data which cannot be calculated without a stack frame including registers (etc).

dwarf_get_fde_info_for_reg3_c() is new in libdwarf 0.8.0. It corrects the incorrect type of the dw_offset argument in dwarf_get_fde_info_for_reg3_b(). Both versions operate correctly.

As of libdwarf 2.3.0 the CFA can be requested with dw_table_column. Previously the CFA was unavailable. By default the cfa pseudo register number is DW_FRAME_CFA_COL from dwarf.h.

Parameters

  dw_fde | Pass in the FDE of interest.
  dw_table_column | Pass in the table_column, column numbers in the table are 0 through the number_of_registers-1 and the 'column' of the CFA (by default it is DW_FRAME_CFA_COL, but might have been set by your code using dwarf_set_frame_cfa_value()).
  dw_pc_requested | Pass in the pc of interest within dw_fde.
  dw_value_type | On success returns the value type, a DW_EXPR value. For example DW_EXPR_EXPRESSION
  dw_offset_relevant | On success returns FALSE if the offset value is irrelevant, otherwise TRUE.
  dw_register | On success returns a register number.
  dw_offset | On success returns a signed register offset value when dw_value_type is DW_EXPR_OFFSET or DW_EXPER_VAL_OFFSET.
  dw_block_content | On success returns a pointer to a block. For example, for DW_EXPR_EXPRESSION the block gives access to the expression bytes.
  dw_row_pc_out | On success returns the address of the actual pc for this register at this pc.
  dw_has_more_rows | On success returns FALSE if there are no more rows, otherwise returns TRUE.
  dw_subsequent_pc | On success this returns the address of the next pc for which there is a register row, making access to all the rows in sequence much more efficient than just adding 1 to a pc value.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK if the dw_pc_requested is in the FDE passed in and there is a row for the pc in the table.

## ◆ dwarf_get_fde_instr_bytes()

DW_API int dwarf_get_fde_instr_bytes | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Small ** | dw_outinstrs,
|  | Dwarf_Unsigned * | dw_outlen,
|  | Dwarf_Error * | dw_error )

Return length and pointer to access frame instructions.

See also
  dwarf_expand_frame_instructions
  Using dwarf_expand_frame_instructions

Parameters

  dw_fde | Pass in the FDE of interest.
  dw_outinstrs | On success returns a pointer to the FDE instruction byte stream.
  dw_outlen | On success returns the length of the dw_outinstrs byte stream.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_fde_list()

DW_API int dwarf_get_fde_list | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Cie ** | dw_cie_data,
|  | Dwarf_Signed * | dw_cie_element_count,
|  | Dwarf_Fde ** | dw_fde_data,
|  | Dwarf_Signed * | dw_fde_element_count,
|  | Dwarf_Error * | dw_error )

Get lists of .debug_frame FDEs and CIEs.

See DWARF5 Section 6.4 Call Frame Information, page 171.

see doc/checkexamples.c exampleq()

See also
  Extracting fde, cie lists.

The FDE array returned through dw_fde_data is sorted low-to-high by the lowest-pc in each FDE.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_cie_data | On success returns a pointer to an array of pointers to CIE data.
  dw_cie_element_count | On success returns a count of the number of elements in the dw_cie_data array.
  dw_fde_data | On success returns a pointer to an array of pointers to FDE data.
  dw_fde_element_count | On success returns a count of the number of elements in the dw_fde_data array. On success
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_fde_list_eh()

DW_API int dwarf_get_fde_list_eh | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Cie ** | dw_cie_data,
|  | Dwarf_Signed * | dw_cie_element_count,
|  | Dwarf_Fde ** | dw_fde_data,
|  | Dwarf_Signed * | dw_fde_element_count,
|  | Dwarf_Error * | dw_error )

Get lists of .eh_frame FDEs and CIEs.

The arguments are identical to the previous function, the difference is the section read. The GNU-defined .eh_frame section is very similar to .debug_frame but has unique features that matter when following a stack trace.

See also
  dwarf_get_fde_list

## ◆ dwarf_get_fde_n()

DW_API int dwarf_get_fde_n | ( | Dwarf_Fde * | dw_fde_data,
|  | Dwarf_Unsigned | dw_fde_index,
|  | Dwarf_Fde * | dw_returned_fde,
|  | Dwarf_Error * | dw_error )

Retrieve an FDE from an FDE table.

This is just like indexing into the FDE array but with extra checking of the pointer and index.

See also
  dwarf_get_fde_list

## ◆ dwarf_get_fde_range()

DW_API int dwarf_get_fde_range | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Addr * | dw_low_pc,
|  | Dwarf_Unsigned * | dw_func_length,
|  | Dwarf_Small ** | dw_fde_bytes,
|  | Dwarf_Unsigned * | dw_fde_byte_length,
|  | Dwarf_Off * | dw_cie_offset,
|  | Dwarf_Signed * | dw_cie_index,
|  | Dwarf_Off * | dw_fde_offset,
|  | Dwarf_Error * | dw_error )

Return the FDE data for a single FDE.

Parameters

  dw_fde | The FDE of interest.
  dw_low_pc | On success returns the low pc value for the function involved.
  dw_func_length | On success returns the length of the function code in bytes.
  dw_fde_bytes | On success returns a pointer to the bytes of the FDE.
  dw_fde_byte_length | On success returns the length of the dw_fde_bytes area.
  dw_cie_offset | On success returns the section offset of the associated CIE.
  dw_cie_index | On success returns the CIE index of the associated CIE.
  dw_fde_offset | On success returns the section offset of this FDE.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_frame_instruction()

DW_API int dwarf_get_frame_instruction | ( | Dwarf_Frame_Instr_Head | dw_head,
|  | Dwarf_Unsigned | dw_instr_index,
|  | Dwarf_Unsigned * | dw_instr_offset_in_instrs,
|  | Dwarf_Small * | dw_cfa_operation,
|  | const char ** | dw_fields_description,
|  | Dwarf_Unsigned * | dw_u0,
|  | Dwarf_Unsigned * | dw_u1,
|  | Dwarf_Signed * | dw_s0,
|  | Dwarf_Signed * | dw_s1,
|  | Dwarf_Unsigned * | dw_code_alignment_factor,
|  | Dwarf_Signed * | dw_data_alignment_factor,
|  | Dwarf_Block * | dw_expression_block,
|  | Dwarf_Error * | dw_error )

Return information about a single instruction Fields_description means a sequence of up to three letters including u,s,r,c,d,b, terminated by NUL byte. It is a string but we test individual bytes instead of using string compares. Do not free any of the returned values.

See also
  Using dwarf_expand_frame_instructions

Parameters

  dw_head | A head record
  dw_instr_index | index 0 < i < instr_count
  dw_instr_offset_in_instrs | Returns the byte offset of this instruction within instructions.
  dw_cfa_operation | Returns a DW_CFA opcode.
  dw_fields_description | Returns a string. Do not free.
  dw_u0 | May be set to an unsigned value
  dw_u1 | May be set to an unsigned value
  dw_s0 | May be set to a signed value
  dw_s1 | May be set to a signed value
  dw_code_alignment_factor | May be set by the call
  dw_data_alignment_factor | May be set by the call
  dw_expression_block | Pass in a pointer to a block
  dw_error | If DW_DLV_ERROR and the argument is non-NULL, returns details about the error.

Returns
  On success returns DW_DLV_OK If there is no such instruction with that index it returns DW_DLV_NO_ENTRY On error it returns DW_DLV_ERROR and if dw_error is NULL it pushes back a pointer to a Dwarf_Error to the caller.

Frame expressions have a variety of formats and content. The dw_fields parameter is set to a pointer to a short string with some set of the letters s,u,r,d,c,b,a which enables determining exactly which values the call sets. Some examples: A `s` in fields[0] means s0 is a signed number.

A `b` somewhere in fields means the expression block passed in has been filled in.

A `r` in fields[1] means u1 is set to a register number.

A `d` in fields means data_alignment_factor is set

A `c` in fields means code_alignment_factor is set

An `a` in fields means an LLVM address space value and only exists if calling dwarf_get_frame_instruction_a().

The possible frame instruction formats are:

"" "b" "r" "rb" "rr" "rsd" "rsda" "ru" "rua" "rud"
"sd" "u" "uc"

are the possible frame instruction formats.

## ◆ dwarf_get_frame_instruction_a()

DW_API int dwarf_get_frame_instruction_a | ( | Dwarf_Frame_Instr_Head | dw_,
|  | Dwarf_Unsigned | dw_instr_index,
|  | Dwarf_Unsigned * | dw_instr_offset_in_instrs,
|  | Dwarf_Small * | dw_cfa_operation,
|  | const char ** | dw_fields_description,
|  | Dwarf_Unsigned * | dw_u0,
|  | Dwarf_Unsigned * | dw_u1,
|  | Dwarf_Unsigned * | dw_u2,
|  | Dwarf_Signed * | dw_s0,
|  | Dwarf_Signed * | dw_s1,
|  | Dwarf_Unsigned * | dw_code_alignment_factor,
|  | Dwarf_Signed * | dw_data_alignment_factor,
|  | Dwarf_Block * | dw_expression_block,
|  | Dwarf_Error * | dw_error )

Expands CIE or FDE instructions for detailed examination. Called for CIE initial instructions and FDE instructions. This is the same as dwarf_get_frame_instruction() except that it adds a dw_u2 field which contains an address-space identifier if the letter `a` appears in dw_fields_description. The dw_u2 field is non-standard and only applies to Heterogeneous Debugging frame instructions defined by LLVM (DW_CFA_LLVM_def_aspace_cfa and DW_CFA_LLVM_def_aspace_cfa_sf).

Where multiplication is called for (via dw_code_alignment_factor or dw_data_alignment_factor) to produce an offset there is no need to check for overflow as libdwarf has already verified there is no overflow.

The return values are the same except here we have: an `a` in fields[2] or fields[3] means dw_u2 is an address-space identifier for the LLVM CFA instruction.

## ◆ dwarf_iterate_fde_all_regs3()

DW_API int dwarf_iterate_fde_all_regs3 | ( | Dwarf_Fde | dw_fde,
|  | Dwarf_Regtable3 * | dw_reg_table,
|  | dwarf_iterate_fde_callback_function_type | dw_callback,
|  | void * | dw_callback_user_data,
|  | Dwarf_Error * | dw_error )

Iterate all rows for a given FDE. Iinvokes a provided callback function for each row. Iteration continues until all rows have been visited.

This is much more efficient than repeatedly calling dwarf_get_fde_info_for_all_regs3_b() when you need to extract all rows of an FDE. See dwarfexample/frame2.c for an example of its use.

Parameters

  dw_fde | Pass in the FDE of interest.
  dw_reg_table | Pass in the address of a struct to be filled in and returned via the callback with fde row data for the current row. The struct should be all zeros. The array of struct Dwarf_Regtable_Entry3_s for register rules in the struct must have been allocated and initialized with all zero bits.
  dw_callback | The callback that should b invoked for each row in the FDE. The register table of size @dw_reg_table_size is passed to the callback.
  dw_callback_user_data | User data that is passed to the callback
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK if iterations all succeeded

## ◆ dwarf_set_frame_cfa_value()

DW_API Dwarf_Half dwarf_set_frame_cfa_value | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half | dw_value )

Frame CFA Column Invariants for setting frame registers .

Parameters

  dw_dbg | The Dwarf_Debug of interest. If it is null or invalid, return the value zero immediately.
  dw_value | Pass in the value to record for the library to use.

Returns
  Returns the previous value.

## ◆ dwarf_set_frame_rule_initial_value()

DW_API Dwarf_Half dwarf_set_frame_rule_initial_value | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half | dw_value )

Frame Rule Initial Value.

Invariants for setting frame registers

Parameters

  dw_dbg | The Dwarf_Debug of interest. If it is null or invalid, return the value zero immediately.
  dw_value | Pass in the value to record for the library to use.

Returns
  Returns the previous value.

## ◆ dwarf_set_frame_rule_table_size()

DW_API Dwarf_Half dwarf_set_frame_rule_table_size | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half | dw_value )

Frame Rule Table Size Invariants for setting frame registers .

Parameters

  dw_dbg | The Dwarf_Debug of interest. If it is null or invalid, return the value zero immediately
  dw_value | Pass in the value to record for the library to use. If zero, the Frame Rule Table Size is left unchanged. The library someone arbitrarily does not allow setting the number of register rules (registers) below 188 (DW_FRAME_HIGHEST_NORMAL_REGISTER in dwarf.h) and does not apply any dw_value lower than that.

Returns
  Returns the previous value.

## ◆ dwarf_set_frame_same_value()

DW_API Dwarf_Half dwarf_set_frame_same_value | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half | dw_value )

Frame Same Value Default Invariants for setting frame registers .

Parameters

  dw_dbg | The Dwarf_Debug of interest. If it is null or invalid, return the value zero immediately.
  dw_value | Pass in the value to record for the library to use.

Returns
  Returns the previous value.

## ◆ dwarf_set_frame_undefined_value()

DW_API Dwarf_Half dwarf_set_frame_undefined_value | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half | dw_value )

Frame Undefined Value Default Invariants for setting frame registers .

Parameters

  dw_dbg | The Dwarf_Debug of interest. If it is null or invalid, return the value zero immediately.
  dw_value | Pass in the value to record for the library to use.

Returns
  Returns the previous value.